src/lib/agentLoop/toolDefs/toolDefsWeb.ts

// ─── Web & network tools — web_search, read_page, weather, currency, github, fetch, wikipedia, news, translate, npm, stock, browser ───────────────────────────────────────────────────────────
  // P3-4 split da toolDefinitions.ts — DO NOT edit toolDefinitions.ts directly
  // Tools (14): web_search, read_page, get_weather, get_currency, search_github, fetch_url, search_wikipedia, get_news, translate, search_npm, get_stock, clone_url_to_vfs, browser_session_open, browser_session_act

  import type { ChatCompletionTool } from "openai/resources/chat/completions";

  export const WEB_TOOLS: (ChatCompletionTool | undefined)[] = [
      {
      type: "function",
      function: {
        name: "web_search",
        description: "Ricerca web (Brave → Tavily → DDG → HackerNews → StackOverflow). USA SOLO per: notizie di OGGI, eventi live, prezzi/quote in tempo reale, versioni software uscite dopo il 2024. NON USARE MAI per: costanti fisiche (velocità luce, gravità, Planck), matematica, formule, logica, definizioni, storia, geografia, persone famose, fatti stabili che non cambiano — rispondi DIRETTAMENTE da training. REGOLA: se la domanda aveva la stessa risposta 5 anni fa, NON cercare.",
        parameters: { type: "object", properties: { query: { type: "string", description: "Query concisa di massimo 8 parole" }, focus: { type: "string", enum: ["general","technical","code","news"], description: "Opzionale: technical=SO/GitHub, news=notizie recenti" } }, required: ["query"] }
      }
    },
    {
      type: "function",
      function: {
        name: "read_page",
        description: "Leggi il contenuto completo di una pagina web o URL (usa proxy CORS automaticamente). Ottimo per leggere documentazione, articoli, README.",
        parameters: { type: "object", properties: { url: { type: "string", description: "URL completo da leggere" } }, required: ["url"] }
      }
    },
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Meteo attuale e previsioni 4 giorni (Open-Meteo). Usa solo se l'utente chiede esplicitamente meteo/previsioni di una citta' specifica.",
        parameters: { type: "object", properties: { city: { type: "string", description: "Nome città (es. 'Milano', 'New York')" } }, required: ["city"] }
      }
    },
    {
      type: "function",
      function: {
        name: "get_currency",
        description: "Tasso di cambio e conversione valute in tempo reale (exchangerate-api, nessuna API key).",
        parameters: { type: "object", properties: { from: { type: "string", description: "Valuta sorgente (es. EUR)" }, to: { type: "string", description: "Valuta destinazione (es. USD)" }, amount: { type: "number", description: "Importo da convertire (default 1)" } }, required: ["from","to"] }
      }
    },
    {
      type: "function",
      function: {
        name: "search_github",
        description: "Cerca repository GitHub per linguaggio, topic o keyword. Restituisce nome, descrizione, stelle, URL.",
        parameters: { type: "object", properties: { query: { type: "string", description: "Query di ricerca (es. 'react state management')" }, lang: { type: "string", description: "Linguaggio di programmazione (opzionale)" } }, required: ["query"] }
      }
    },
    {
      type: "function",
      function: {
        name: "fetch_url",
        description: "Fetch HTTP di qualsiasi URL o API pubblica (con fallback CORS proxy automatico). Usa per API REST, webhook, dati JSON.",
        parameters: { type: "object", properties: { url: { type: "string", description: "URL da chiamare" }, method: { type: "string", enum: ["GET","POST","PUT","DELETE","PATCH"], description: "Metodo HTTP (default GET)" }, body: { type: "string", description: "Body JSON per POST/PUT" } }, required: ["url"] }
      }
    },
    {
      type: "function",
      function: {
        name: "search_wikipedia",
        description: "Articolo Wikipedia. Usa solo se servono dati enciclopedici precisi (date esatte, numeri, biografia dettagliata) che potresti confondere a memoria.",
        parameters: { type: "object", properties: { query: { type: "string", description: "Termine di ricerca" } }, required: ["query"] }
      }
    },
    {
      type: "function",
      function: {
        name: "get_news",
        description: "Ultime notizie italiane in tempo reale da ANSA, Corriere, Sole24Ore. Usa per eventi recenti, notizie del giorno.",
        parameters: { type: "object", properties: { query: { type: "string", description: "Argomento di interesse (opzionale)" } } }
      }
    },
    {
      type: "function",
      function: {
        name: "translate",
        description: "Traduci testo in qualsiasi lingua via MyMemory (gratis). Usa per traduzioni singole o di paragrafi.",
        parameters: {
          type: "object",
          properties: {
            text: { type: "string", description: "Testo da tradurre (max 500 chars)" },
            to:   { type: "string", description: "Codice lingua destinazione (es. en, it, fr, de, es, pt, ja, zh, ar, ru, ko)" },
            from: { type: "string", description: "Codice lingua sorgente (default: auto-detect)" }
          },
          required: ["text", "to"]
        }
      }
    },
    {
      type: "function",
      function: {
        name: "search_npm",
        description: "Cerca pacchetti nel registro npm. Usa per trovare librerie JavaScript/TypeScript, confrontare alternative, verificare versioni.",
        parameters: { type: "object", properties: { query: { type: "string", description: "Termine di ricerca (es. 'state management react', 'csv parser')" } }, required: ["query"] }
      }
    },
    {
      type: "function",
      function: {
        name: "get_stock",
        description: "Quotazione borsa in tempo reale via Yahoo Finance (gratis). Prezzo attuale, variazione, ultime 5 sedute.",
        parameters: { type: "object", properties: { symbol: { type: "string", description: "Simbolo ticker (es. AAPL, TSLA, MSFT, NVDA, BTC-EUR, ETH-EUR, ENI.MI, UCG.MI)" } }, required: ["symbol"] }
      }
    },
    {
      type: "function",
      function: {
        name: "clone_url_to_vfs",
        description: "Scarica qualsiasi file/risorsa da un URL e lo salva nel VFS. Supporta testo, JSON, immagini, binari. Usa CORS proxy automaticamente.",
        parameters: { type: "object", properties: { url: { type: "string", description: "URL da scaricare" }, save_path: { type: "string", description: "Percorso di destinazione nel VFS (es. /downloads/data.json)" }, format: { type: "string", enum: ["auto","text","binary"], description: "Formato: auto (default), text (forza testo), binary (forza base64)" } }, required: ["url","save_path"] }
      }
    },
  {
    type: "function",
    function: {
      name: "browser_session_open",
      description: "Apre una sessione browser Playwright con stato persistente (cookie, localStorage, autenticazione). La sessione rimane aperta per azioni sequenziali. Usa quando devi navigare siti con login o scraping multi-step.",
      parameters: {
        type: "object",
        properties: {
          url:        { type: "string",  description: "URL iniziale da aprire" },
          session_id: { type: "string",  description: "ID sessione (default: auto-generato — usalo in browser_session_act)" },
          headless:   { type: "boolean", description: "Modalità headless (default: true)" },
          viewport:   { type: "object",  description: "Dimensioni viewport {width, height} (default: 1280x720)" },
        },
        required: ["url"],
      },
    },
  },
  {
    type: "function",
    function: {
      name: "browser_session_act",
      description: "Esegue un'azione in una sessione Playwright aperta con browser_session_open. Azioni: click, type, navigate, screenshot, get_text, select, hover, wait, scroll, evaluate.",
      parameters: {
        type: "object",
        properties: {
          session_id: { type: "string", description: "ID sessione da browser_session_open" },
          action:     { type: "string", enum: ["click","type","navigate","screenshot","get_text","select","hover","wait","scroll","evaluate"], description: "Azione da eseguire" },
          selector:   { type: "string", description: "Selettore CSS o XPath dell'elemento target" },
          value:      { type: "string", description: "Valore per type/select/navigate/evaluate" },
          timeout:    { type: "number", description: "Timeout ms (default: 5000)" },
        },
        required: ["session_id", "action"],
      },
    },
  },
  {
    type: "function",
    function: {
      name: "deep_research",
      description: "Ricerca multi-round approfondita su argomenti complessi (ARL). " +
        "USA per: analisi comparative, report multi-fonte, argomenti tecnici che richiedono " +
        "confronto tra più fonti, ricerche dove web_search singolo è insufficiente. " +
        "Esegue fino a 3 round con raffinamento automatico della query (zero LLM aggiuntivo) " +
        "e navigazione dei link rilevanti. Budget fisso: ≤12 fetch · timeout 22s · safe su iPhone. " +
        "NON usare per domande rapide — usa web_search per query semplici.",
      parameters: {
        type: "object",
        properties: {
          goal: {
            type: "string",
            description: "Obiettivo di ricerca in linguaggio naturale, preciso e dettagliato " +
              "(es. 'Analisi delle prestazioni dei principali LLM open-source nel 2025: " +
              "benchmark, costi, limitazioni free tier')"
          }
        },
        required: ["goal"]
      }
    }
  },

  ];