@sisu-ai/tool-web-search-openai 1.0.0

package/README.md

@@ -0,0 +1,45 @@
+# @sisu-ai/tool-web-search-openai
+
+Web search tool powered by OpenAI's Responses API `web_search` capability.
+
+Install
+```bash
+npm i @sisu-ai/tool-web-search-openai
+```
+
+Environment
+- `OPENAI_API_KEY` or `API_KEY`: API key (required)
+- `OPENAI_RESPONSES_BASE_URL`: Base URL for the Responses API. Defaults to `https://api.openai.com`.
+- `OPENAI_BASE_URL` or `BASE_URL`: Fallback base URL if `OPENAI_RESPONSES_BASE_URL` is not set.
+- `OPENAI_RESPONSES_MODEL`: Model to use (default `gpt-4.1-mini`). If missing, the tool will try to infer from the adapter (`openai:<model>`), then fall back to default.
+- `DEBUG_LLM=1`: Logs a redacted request preview and response summary.
+
+CLI flags (example app)
+- `--openai-api-key`, `--api-key`
+- `--openai-responses-base-url`, `--openai-base-url`, `--base-url`
+- `--openai-responses-model`, `--openai-model`
+
+Precedence
+1) CLI flags (when provided by your app in `ctx.state.openai`, or read by core helpers)
+2) Env vars
+3) Adapter hints/metadata (e.g., `openAIAdapter({ responseModel })` or adapter model name)
+4) Defaults
+
+Usage
+```ts
+import { Agent } from '@sisu-ai/core';
+import { registerTools } from '@sisu-ai/mw-register-tools';
+import { toolCalling } from '@sisu-ai/mw-tool-calling';
+import { openAIAdapter } from '@sisu-ai/adapter-openai';
+import { openAIWebSearch } from '@sisu-ai/tool-web-search-openai';
+
+const model = openAIAdapter({ model: 'gpt-4o-mini' });
+const app = new Agent()
+  .use(registerTools([openAIWebSearch]))
+  .use(toolCalling);
+```
+
+Notes
+- If your main adapter uses a gateway (e.g., OpenRouter) that does not support `/v1/responses`, set `OPENAI_RESPONSES_BASE_URL=https://api.openai.com` so the tool hits the correct endpoint.
+- On provider/tool mismatch, the tool retries once with a safe default model (`gpt-4.1-mini`).
+

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { Tool } from '@sisu-ai/core';
+export interface OpenAIWebSearchArgs {
+    query: string;
+}
+export declare const openAIWebSearch: Tool<OpenAIWebSearchArgs>;
+export default openAIWebSearch;

package/dist/index.js

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+// Uses OpenAI Responses API web_search tool
+export const openAIWebSearch = {
+    name: 'webSearch',
+    description: 'Search the web using OpenAI\'s built-in web search tool.',
+    schema: z.object({ query: z.string() }),
+    handler: async ({ query }, ctx) => {
+        const st = (ctx?.state ?? {});
+        const stOpenAI = (st.openai ?? {});
+        const cliApiKey = stOpenAI.apiKey ?? st.apiKey;
+        const apiKey = cliApiKey || (process.env.OPENAI_API_KEY || process.env.API_KEY);
+        if (!apiKey)
+            throw new Error('Missing OPENAI_API_KEY or API_KEY');
+        const cliRespBase = stOpenAI.responsesBaseUrl ?? st.responsesBaseUrl;
+        const cliBase = stOpenAI.baseUrl ?? st.baseUrl;
+        const envBase = process.env.OPENAI_RESPONSES_BASE_URL || process.env.OPENAI_BASE_URL || process.env.BASE_URL;
+        const baseUrl = ((cliRespBase || cliBase || envBase) ?? 'https://api.openai.com').replace(/\/$/, '');
+        const fromMeta = ctx?.model?.meta?.responseModel || ctx?.model?.responseModel;
+        const fromAdapterName = typeof ctx?.model?.name === 'string' && ctx.model.name.startsWith('openai:')
+            ? ctx.model.name.slice('openai:'.length)
+            : undefined;
+        const cliRespModel = stOpenAI.responsesModel ?? st.responsesModel;
+        const cliModel = stOpenAI.model ?? st.model;
+        let model = cliRespModel || cliModel || process.env.OPENAI_RESPONSES_MODEL || process.env.OPENAI_MODEL || fromMeta || fromAdapterName || 'gpt-4.1-mini';
+        const url = `${baseUrl}/v1/responses`;
+        const body = {
+            model,
+            input: query,
+            tools: [{ type: 'web_search' }],
+            tool_choice: { type: 'web_search' }
+        };
+        const DEBUG = String(process.env.DEBUG_LLM || '').toLowerCase() === 'true' || process.env.DEBUG_LLM === '1';
+        if (DEBUG) {
+            try {
+                // eslint-disable-next-line no-console
+                console.error('[DEBUG_LLM] request', { url, headers: { Authorization: 'Bearer ***', 'Content-Type': 'application/json', Accept: 'application/json' }, body });
+            }
+            catch { }
+        }
+        const doRequest = async (modelToUse) => fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+                'Accept': 'application/json'
+            },
+            body: JSON.stringify({ ...body, model: modelToUse })
+        });
+        let res = await doRequest(model);
+        let raw = await res.text();
+        if (!res.ok) {
+            let details = raw;
+            try {
+                const j = JSON.parse(raw);
+                details = j.error?.message ?? raw;
+            }
+            catch { }
+            if (DEBUG) {
+                // eslint-disable-next-line no-console
+                console.error('[DEBUG_LLM] response_error', { status: res.status, statusText: res.statusText, body: typeof raw === 'string' ? raw.slice(0, 500) : raw });
+            }
+            // Retry once with a safe default model if we suspect model/tool mismatch
+            const msg = String(details).toLowerCase();
+            const shouldRetry = res.status === 400 || msg.includes('tool') || msg.includes('web_search');
+            if (shouldRetry && model !== 'gpt-4.1-mini') {
+                const fallback = 'gpt-4.1-mini';
+                if (DEBUG) {
+                    try {
+                        console.error('[DEBUG_LLM] retrying with fallback model', { from: model, to: fallback });
+                    }
+                    catch { }
+                }
+                model = fallback;
+                res = await doRequest(model);
+                raw = await res.text();
+                if (!res.ok) {
+                    let d2 = raw;
+                    try {
+                        const j2 = JSON.parse(raw);
+                        d2 = j2.error?.message ?? raw;
+                    }
+                    catch { }
+                    throw new Error(`OpenAI web search failed: ${res.status} ${res.statusText} — ${String(d2).slice(0, 500)}`);
+                }
+            }
+            else {
+                throw new Error(`OpenAI web search failed: ${res.status} ${res.statusText} — ${String(details).slice(0, 500)}`);
+            }
+        }
+        const ct = res.headers.get('content-type') || '';
+        if (!ct.toLowerCase().includes('application/json')) {
+            if (DEBUG) {
+                try {
+                    // eslint-disable-next-line no-console
+                    console.error('[DEBUG_LLM] non_json_response', { contentType: ct, snippet: typeof raw === 'string' ? raw.slice(0, 200) : raw });
+                }
+                catch { }
+            }
+            throw new Error(`OpenAI web search returned non-JSON content (content-type: ${ct}). Check OPENAI_BASE_URL/BASE_URL and API key. Snippet: ${String(raw).slice(0, 200)}`);
+        }
+        const json = raw ? JSON.parse(raw) : {};
+        if (DEBUG) {
+            try {
+                // eslint-disable-next-line no-console
+                console.error('[DEBUG_LLM] response_ok', { keys: Object.keys(json ?? {}), outputType: Array.isArray(json?.output) ? 'array' : typeof json?.output });
+            }
+            catch { }
+        }
+        const results = json.output?.find?.((p) => p.type === 'web_search_results')?.web_search_results
+            ?? json.output?.[0]?.content?.find?.((c) => c.type === 'web_search_results')?.web_search_results;
+        return results ?? json;
+    }
+};
+export default openAIWebSearch;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@sisu-ai/tool-web-search-openai",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "@sisu-ai/core": "0.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/finger-gun/sisu",
+    "directory": "packages/tools/web-search-openai"
+  },
+  "homepage": "https://github.com/finger-gun/sisu#readme",
+  "bugs": {
+    "url": "https://github.com/finger-gun/sisu/issues"
+  }
+}