@theokit/sdk-tools 0.28.0 → 0.29.0

package/dist/structured-output.d.cts

@@ -0,0 +1,61 @@
+import { CustomTool } from '@theokit/sdk';
+import { z } from 'zod';
+
+/**
+ * `structured_output` — hands the host the model's object only when it validates against the
+ * consumer's zod schema.
+ *
+ * The model sees the schema as the tool's JSON Schema and calls the tool with its answer. The
+ * handler runs the full zod contract (refinements and transforms included, which the JSON Schema
+ * only approximates) and never throws: a failed parse becomes a typed result the model can act on.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, output }` with `output` the parsed value, defaults and transforms applied
+ *   - `{ ok: false, error: "invalid_structured_output", issue_count, issues }` with at most
+ *     `maxIssues` issues, each `{ path, message }`, and `issue_count` the full count
+ *
+ * The tool does not end the agent turn: `CustomTool` has no terminal flag, so the host stops on
+ * the first `ok: true` result.
+ *
+ * Limits, accepted and stated: "never throws" holds for synchronous schemas whose parsed value is
+ * JSON-serialisable. An async refinement makes `safeParse` throw, and a transform that yields a
+ * BigInt or a cycle makes the serialisation throw; both are the consumer's schema, and the error
+ * surfaces as the tool error the SDK reports for any throwing handler.
+ */
+
+/** Options for {@link createStructuredOutputTool}. `schema` is required and must describe an object. */
+interface CreateStructuredOutputToolOptions {
+    /** The zod schema the model's object must satisfy. Its JSON Schema must have `type: "object"`. */
+    schema: z.ZodType;
+    /** Name exposed to the model. Omitted ⇒ `structured_output`. */
+    name?: string;
+    /** Description exposed to the model. Omitted ⇒ a literal telling the model to retry on issues. */
+    description?: string;
+    /** Most issues returned in one failure. Omitted ⇒ 10. */
+    maxIssues?: number;
+}
+/** One validation issue: the dotted path to the field (empty for the root) and zod's message. */
+interface StructuredOutputIssue {
+    path: string;
+    message: string;
+}
+/** The tool's result, before it is serialised to the JSON string the handler returns. */
+type StructuredOutputResult = {
+    ok: true;
+    output: unknown;
+} | {
+    ok: false;
+    error: "invalid_structured_output";
+    issue_count: number;
+    issues: StructuredOutputIssue[];
+};
+/**
+ * Build a `structured_output` tool over `schema`.
+ *
+ * @throws TypeError when the schema's JSON Schema is not `type: "object"` (provider tool inputs
+ *   must be objects; a top-level union, intersection or recursive `$ref` is refused too);
+ *   RangeError when `maxIssues` is not a positive integer.
+ */
+declare function createStructuredOutputTool(opts: CreateStructuredOutputToolOptions): CustomTool;
+
+export { type CreateStructuredOutputToolOptions, type StructuredOutputIssue, type StructuredOutputResult, createStructuredOutputTool };

package/dist/structured-output.d.ts

@@ -0,0 +1,61 @@
+import { CustomTool } from '@theokit/sdk';
+import { z } from 'zod';
+
+/**
+ * `structured_output` — hands the host the model's object only when it validates against the
+ * consumer's zod schema.
+ *
+ * The model sees the schema as the tool's JSON Schema and calls the tool with its answer. The
+ * handler runs the full zod contract (refinements and transforms included, which the JSON Schema
+ * only approximates) and never throws: a failed parse becomes a typed result the model can act on.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, output }` with `output` the parsed value, defaults and transforms applied
+ *   - `{ ok: false, error: "invalid_structured_output", issue_count, issues }` with at most
+ *     `maxIssues` issues, each `{ path, message }`, and `issue_count` the full count
+ *
+ * The tool does not end the agent turn: `CustomTool` has no terminal flag, so the host stops on
+ * the first `ok: true` result.
+ *
+ * Limits, accepted and stated: "never throws" holds for synchronous schemas whose parsed value is
+ * JSON-serialisable. An async refinement makes `safeParse` throw, and a transform that yields a
+ * BigInt or a cycle makes the serialisation throw; both are the consumer's schema, and the error
+ * surfaces as the tool error the SDK reports for any throwing handler.
+ */
+
+/** Options for {@link createStructuredOutputTool}. `schema` is required and must describe an object. */
+interface CreateStructuredOutputToolOptions {
+    /** The zod schema the model's object must satisfy. Its JSON Schema must have `type: "object"`. */
+    schema: z.ZodType;
+    /** Name exposed to the model. Omitted ⇒ `structured_output`. */
+    name?: string;
+    /** Description exposed to the model. Omitted ⇒ a literal telling the model to retry on issues. */
+    description?: string;
+    /** Most issues returned in one failure. Omitted ⇒ 10. */
+    maxIssues?: number;
+}
+/** One validation issue: the dotted path to the field (empty for the root) and zod's message. */
+interface StructuredOutputIssue {
+    path: string;
+    message: string;
+}
+/** The tool's result, before it is serialised to the JSON string the handler returns. */
+type StructuredOutputResult = {
+    ok: true;
+    output: unknown;
+} | {
+    ok: false;
+    error: "invalid_structured_output";
+    issue_count: number;
+    issues: StructuredOutputIssue[];
+};
+/**
+ * Build a `structured_output` tool over `schema`.
+ *
+ * @throws TypeError when the schema's JSON Schema is not `type: "object"` (provider tool inputs
+ *   must be objects; a top-level union, intersection or recursive `$ref` is refused too);
+ *   RangeError when `maxIssues` is not a positive integer.
+ */
+declare function createStructuredOutputTool(opts: CreateStructuredOutputToolOptions): CustomTool;
+
+export { type CreateStructuredOutputToolOptions, type StructuredOutputIssue, type StructuredOutputResult, createStructuredOutputTool };

package/dist/structured-output.js

@@ -0,0 +1,50 @@
+import { Tool } from '@theokit/sdk';
+
+// src/structured-output.ts
+var DEFAULT_MAX_ISSUES = 10;
+var DEFAULT_DESCRIPTION = "Return your final answer as an object matching this tool's input schema. If the result reports invalid_structured_output, fix the listed issues and call again.";
+function requireMaxIssues(value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError(
+      `createStructuredOutputTool: maxIssues must be a positive integer, got ${value}`
+    );
+  }
+  return value;
+}
+function validate(schema, input, maxIssues) {
+  const parsed = schema.safeParse(input);
+  if (parsed.success) return { ok: true, output: parsed.data };
+  const all = parsed.error.issues;
+  return {
+    ok: false,
+    error: "invalid_structured_output",
+    issue_count: all.length,
+    issues: all.slice(0, maxIssues).map((issue) => ({
+      path: issue.path.map(String).join("."),
+      message: issue.message
+    }))
+  };
+}
+function createStructuredOutputTool(opts) {
+  const maxIssues = requireMaxIssues(opts.maxIssues ?? DEFAULT_MAX_ISSUES);
+  const base = Tool.create({
+    name: opts.name ?? "structured_output",
+    description: opts.description ?? DEFAULT_DESCRIPTION,
+    inputSchema: opts.schema,
+    handler: () => ""
+  });
+  const type = base.inputSchema.type;
+  if (type !== "object") {
+    throw new TypeError(
+      `createStructuredOutputTool: schema must be an object schema, got type ${String(type)}`
+    );
+  }
+  return {
+    ...base,
+    handler: (input) => JSON.stringify(validate(opts.schema, input, maxIssues))
+  };
+}
+
+export { createStructuredOutputTool };
+//# sourceMappingURL=structured-output.js.map
+//# sourceMappingURL=structured-output.js.map

package/dist/structured-output.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/structured-output.ts"],"names":[],"mappings":";;;AA2BA,IAAM,kBAAA,GAAqB,EAAA;AAE3B,IAAM,mBAAA,GACJ,iKAAA;AA+BF,SAAS,iBAAiB,KAAA,EAAuB;AAC/C,EAAA,IAAI,CAAC,MAAA,CAAO,SAAA,CAAU,KAAK,CAAA,IAAK,SAAS,CAAA,EAAG;AAC1C,IAAA,MAAM,IAAI,UAAA;AAAA,MACR,yEAAyE,KAAK,CAAA;AAAA,KAChF;AAAA,EACF;AACA,EAAA,OAAO,KAAA;AACT;AAEA,SAAS,QAAA,CAAS,MAAA,EAAmB,KAAA,EAAgB,SAAA,EAA2C;AAC9F,EAAA,MAAM,MAAA,GAAS,MAAA,CAAO,SAAA,CAAU,KAAK,CAAA;AACrC,EAAA,IAAI,MAAA,CAAO,SAAS,OAAO,EAAE,IAAI,IAAA,EAAM,MAAA,EAAQ,OAAO,IAAA,EAAK;AAC3D,EAAA,MAAM,GAAA,GAAM,OAAO,KAAA,CAAM,MAAA;AACzB,EAAA,OAAO;AAAA,IACL,EAAA,EAAI,KAAA;AAAA,IACJ,KAAA,EAAO,2BAAA;AAAA,IACP,aAAa,GAAA,CAAI,MAAA;AAAA,IACjB,MAAA,EAAQ,IAAI,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA,CAAE,GAAA,CAAI,CAAC,KAAA,MAAW;AAAA,MAC9C,MAAM,KAAA,CAAM,IAAA,CAAK,IAAI,MAAM,CAAA,CAAE,KAAK,GAAG,CAAA;AAAA,MACrC,SAAS,KAAA,CAAM;AAAA,KACjB,CAAE;AAAA,GACJ;AACF;AASO,SAAS,2BAA2B,IAAA,EAAqD;AAC9F,EAAA,MAAM,SAAA,GAAY,gBAAA,CAAiB,IAAA,CAAK,SAAA,IAAa,kBAAkB,CAAA;AACvE,EAAA,MAAM,IAAA,GAAO,KAAK,MAAA,CAAO;AAAA,IACvB,IAAA,EAAM,KAAK,IAAA,IAAQ,mBAAA;AAAA,IACnB,WAAA,EAAa,KAAK,WAAA,IAAe,mBAAA;AAAA,IACjC,aAAa,IAAA,CAAK,MAAA;AAAA,IAClB,SAAS,MAAM;AAAA,GAChB,CAAA;AACD,EAAA,MAAM,IAAA,GAAQ,KAAK,WAAA,CAAmC,IAAA;AACtD,EAAA,IAAI,SAAS,QAAA,EAAU;AACrB,IAAA,MAAM,IAAI,SAAA;AAAA,MACR,CAAA,sEAAA,EAAyE,MAAA,CAAO,IAAI,CAAC,CAAA;AAAA,KACvF;AAAA,EACF;AACA,EAAA,OAAO;AAAA,IACL,GAAG,IAAA;AAAA,IACH,OAAA,EAAS,CAAC,KAAA,KAAmB,IAAA,CAAK,SAAA,CAAU,SAAS,IAAA,CAAK,MAAA,EAAQ,KAAA,EAAO,SAAS,CAAC;AAAA,GACrF;AACF","file":"structured-output.js","sourcesContent":["/**\n * `structured_output` — hands the host the model's object only when it validates against the\n * consumer's zod schema.\n *\n * The model sees the schema as the tool's JSON Schema and calls the tool with its answer. The\n * handler runs the full zod contract (refinements and transforms included, which the JSON Schema\n * only approximates) and never throws: a failed parse becomes a typed result the model can act on.\n *\n * Return shape (always a JSON string):\n *   - `{ ok: true, output }` with `output` the parsed value, defaults and transforms applied\n *   - `{ ok: false, error: \"invalid_structured_output\", issue_count, issues }` with at most\n *     `maxIssues` issues, each `{ path, message }`, and `issue_count` the full count\n *\n * The tool does not end the agent turn: `CustomTool` has no terminal flag, so the host stops on\n * the first `ok: true` result.\n *\n * Limits, accepted and stated: \"never throws\" holds for synchronous schemas whose parsed value is\n * JSON-serialisable. An async refinement makes `safeParse` throw, and a transform that yields a\n * BigInt or a cycle makes the serialisation throw; both are the consumer's schema, and the error\n * surfaces as the tool error the SDK reports for any throwing handler.\n */\n\nimport type { CustomTool } from \"@theokit/sdk\";\nimport { Tool } from \"@theokit/sdk\";\nimport type { z } from \"zod\";\n\n/** Default ceiling on the issues returned to the model. A default, not a measured limit. */\nconst DEFAULT_MAX_ISSUES = 10;\n\nconst DEFAULT_DESCRIPTION =\n  \"Return your final answer as an object matching this tool's input schema. \" +\n  \"If the result reports invalid_structured_output, fix the listed issues and call again.\";\n\n/** Options for {@link createStructuredOutputTool}. `schema` is required and must describe an object. */\nexport interface CreateStructuredOutputToolOptions {\n  /** The zod schema the model's object must satisfy. Its JSON Schema must have `type: \"object\"`. */\n  schema: z.ZodType;\n  /** Name exposed to the model. Omitted ⇒ `structured_output`. */\n  name?: string;\n  /** Description exposed to the model. Omitted ⇒ a literal telling the model to retry on issues. */\n  description?: string;\n  /** Most issues returned in one failure. Omitted ⇒ 10. */\n  maxIssues?: number;\n}\n\n/** One validation issue: the dotted path to the field (empty for the root) and zod's message. */\nexport interface StructuredOutputIssue {\n  path: string;\n  message: string;\n}\n\n/** The tool's result, before it is serialised to the JSON string the handler returns. */\nexport type StructuredOutputResult =\n  | { ok: true; output: unknown }\n  | {\n      ok: false;\n      error: \"invalid_structured_output\";\n      issue_count: number;\n      issues: StructuredOutputIssue[];\n    };\n\nfunction requireMaxIssues(value: number): number {\n  if (!Number.isInteger(value) || value <= 0) {\n    throw new RangeError(\n      `createStructuredOutputTool: maxIssues must be a positive integer, got ${value}`,\n    );\n  }\n  return value;\n}\n\nfunction validate(schema: z.ZodType, input: unknown, maxIssues: number): StructuredOutputResult {\n  const parsed = schema.safeParse(input);\n  if (parsed.success) return { ok: true, output: parsed.data };\n  const all = parsed.error.issues;\n  return {\n    ok: false,\n    error: \"invalid_structured_output\",\n    issue_count: all.length,\n    issues: all.slice(0, maxIssues).map((issue) => ({\n      path: issue.path.map(String).join(\".\"),\n      message: issue.message,\n    })),\n  };\n}\n\n/**\n * Build a `structured_output` tool over `schema`.\n *\n * @throws TypeError when the schema's JSON Schema is not `type: \"object\"` (provider tool inputs\n *   must be objects; a top-level union, intersection or recursive `$ref` is refused too);\n *   RangeError when `maxIssues` is not a positive integer.\n */\nexport function createStructuredOutputTool(opts: CreateStructuredOutputToolOptions): CustomTool {\n  const maxIssues = requireMaxIssues(opts.maxIssues ?? DEFAULT_MAX_ISSUES);\n  const base = Tool.create({\n    name: opts.name ?? \"structured_output\",\n    description: opts.description ?? DEFAULT_DESCRIPTION,\n    inputSchema: opts.schema,\n    handler: () => \"\",\n  });\n  const type = (base.inputSchema as { type?: unknown }).type;\n  if (type !== \"object\") {\n    throw new TypeError(\n      `createStructuredOutputTool: schema must be an object schema, got type ${String(type)}`,\n    );\n  }\n  return {\n    ...base,\n    handler: (input: unknown) => JSON.stringify(validate(opts.schema, input, maxIssues)),\n  };\n}\n"]}

package/dist/web-search-CE82zZVl.d.cts

@@ -0,0 +1,61 @@
+import { CustomTool } from '@theokit/sdk';
+
+/**
+ * `web_search` — built-in tool for coding agents.
+ *
+ * Accepts a search callback via DIP (consumer provides the search
+ * provider). The tool itself is provider-agnostic.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, results: Array<{ title, url, snippet }> }`
+ *   - `{ ok: false, error: 'search_failed' | 'no_provider' }`
+ */
+
+interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/**
+ * The search provider {@link createWebSearchTool} calls.
+ *
+ * `maxResults` is what the caller asked for, not a limit you must enforce — the tool slices the array
+ * itself — but returning far more than asked wastes the round trip that produced them.
+ *
+ * Reject the promise to signal a failed search: the tool turns a rejection into
+ * `{ ok: false, error: "search_failed" }` and never lets it escape into the agent turn. Resolving
+ * with `[]` says something different — that the search ran and found nothing.
+ */
+type WebSearchCallback = (query: string, maxResults: number) => Promise<WebSearchResult[]>;
+/**
+ * Options for {@link createWebSearchTool}. `search` is required: the tool ships no provider of its
+ * own, and the two adapters in this package — {@link createBraveWebSearchAdapter} and
+ * {@link createGenericHttpSearchAdapter} — exist to fill it.
+ */
+interface CreateWebSearchToolOptions {
+    /** M76 — name exposed to the model. Omitted => today's literal (additive). The name is a contract:
+     *  the approval key, what the model sees and what telemetry records. */
+    name?: string;
+    /** M76 — description exposed to the model. Omitted => today's literal (additive). */
+    description?: string;
+    /** Search provider callback — consumer injects the implementation. */
+    search: WebSearchCallback;
+    /** Default max results if not specified by the LLM. */
+    defaultMaxResults?: number;
+}
+/**
+ * Build the `web_search` tool over a caller-supplied provider.
+ *
+ * The tool holds no API key and talks to no service; everything network-facing lives in the `search`
+ * callback, which is why one tool serves Brave, a self-hosted endpoint, or a fixture in a test. Use
+ * it to find pages and `web_fetch` to read one — results carry a snippet, not a body.
+ *
+ * The model's `max_results` (1..20) wins over `defaultMaxResults`, and the list is sliced to it even
+ * when the provider returns more. A rejecting provider yields `{ ok: false, error: "search_failed" }`
+ * with its message attached; a provider resolving `[]` yields `{ ok: true, results: [] }`. The two
+ * are different signals, so an adapter that swallows its own failures — as
+ * {@link createGenericHttpSearchAdapter} deliberately does — reports the first as the second.
+ */
+declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTool;
+
+export { type CreateWebSearchToolOptions as C, type WebSearchCallback as W, type WebSearchResult as a, createWebSearchTool as c };

package/dist/web-search-CE82zZVl.d.ts

@@ -0,0 +1,61 @@
+import { CustomTool } from '@theokit/sdk';
+
+/**
+ * `web_search` — built-in tool for coding agents.
+ *
+ * Accepts a search callback via DIP (consumer provides the search
+ * provider). The tool itself is provider-agnostic.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, results: Array<{ title, url, snippet }> }`
+ *   - `{ ok: false, error: 'search_failed' | 'no_provider' }`
+ */
+
+interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/**
+ * The search provider {@link createWebSearchTool} calls.
+ *
+ * `maxResults` is what the caller asked for, not a limit you must enforce — the tool slices the array
+ * itself — but returning far more than asked wastes the round trip that produced them.
+ *
+ * Reject the promise to signal a failed search: the tool turns a rejection into
+ * `{ ok: false, error: "search_failed" }` and never lets it escape into the agent turn. Resolving
+ * with `[]` says something different — that the search ran and found nothing.
+ */
+type WebSearchCallback = (query: string, maxResults: number) => Promise<WebSearchResult[]>;
+/**
+ * Options for {@link createWebSearchTool}. `search` is required: the tool ships no provider of its
+ * own, and the two adapters in this package — {@link createBraveWebSearchAdapter} and
+ * {@link createGenericHttpSearchAdapter} — exist to fill it.
+ */
+interface CreateWebSearchToolOptions {
+    /** M76 — name exposed to the model. Omitted => today's literal (additive). The name is a contract:
+     *  the approval key, what the model sees and what telemetry records. */
+    name?: string;
+    /** M76 — description exposed to the model. Omitted => today's literal (additive). */
+    description?: string;
+    /** Search provider callback — consumer injects the implementation. */
+    search: WebSearchCallback;
+    /** Default max results if not specified by the LLM. */
+    defaultMaxResults?: number;
+}
+/**
+ * Build the `web_search` tool over a caller-supplied provider.
+ *
+ * The tool holds no API key and talks to no service; everything network-facing lives in the `search`
+ * callback, which is why one tool serves Brave, a self-hosted endpoint, or a fixture in a test. Use
+ * it to find pages and `web_fetch` to read one — results carry a snippet, not a body.
+ *
+ * The model's `max_results` (1..20) wins over `defaultMaxResults`, and the list is sliced to it even
+ * when the provider returns more. A rejecting provider yields `{ ok: false, error: "search_failed" }`
+ * with its message attached; a provider resolving `[]` yields `{ ok: true, results: [] }`. The two
+ * are different signals, so an adapter that swallows its own failures — as
+ * {@link createGenericHttpSearchAdapter} deliberately does — reports the first as the second.
+ */
+declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTool;
+
+export { type CreateWebSearchToolOptions as C, type WebSearchCallback as W, type WebSearchResult as a, createWebSearchTool as c };

package/dist/web-search-adapters.cjs

@@ -0,0 +1,71 @@
+'use strict';
+
+var sdk = require('@theokit/sdk');
+
+// src/web-search-searxng.ts
+function parseBase(raw) {
+  const fail = () => {
+    throw new sdk.ConfigurationError(
+      "SEARXNG_BASE_URL is not set or not a URL (pass { baseUrl } or set the env var).",
+      { code: "no_base_url" }
+    );
+  };
+  if (!raw) return fail();
+  try {
+    const url = new URL(raw);
+    if (!url.pathname.endsWith("/")) url.pathname += "/";
+    return url;
+  } catch {
+    return fail();
+  }
+}
+function createSearxngWebSearchAdapter(opts = {}) {
+  const base = parseBase(opts.baseUrl ?? process.env.SEARXNG_BASE_URL);
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  return async (query, maxResults) => {
+    const url = new URL("search", base);
+    url.searchParams.set("q", query);
+    url.searchParams.set("format", "json");
+    const res = await fetchImpl(url.toString(), { headers: { Accept: "application/json" } });
+    if (!res.ok) throw new Error(`searxng_search_failed: HTTP ${res.status}`);
+    const json = await res.json();
+    const results = Array.isArray(json?.results) ? json.results : [];
+    return results.slice(0, maxResults).map((r) => ({
+      title: String(r?.title ?? ""),
+      url: String(r?.url ?? ""),
+      snippet: String(r?.content ?? "")
+    }));
+  };
+}
+var TAVILY_ENDPOINT = "https://api.tavily.com/search";
+function createTavilyWebSearchAdapter(opts = {}) {
+  const apiKey = opts.apiKey ?? process.env.TAVILY_API_KEY;
+  if (!apiKey) {
+    throw new sdk.ConfigurationError(
+      "TAVILY_API_KEY is not set (pass { apiKey } or set the env var).",
+      { code: "no_api_key" }
+    );
+  }
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const endpoint = new URL(opts.endpoint ?? TAVILY_ENDPOINT).toString();
+  return async (query, maxResults) => {
+    const res = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ query, max_results: maxResults })
+    });
+    if (!res.ok) throw new Error(`tavily_search_failed: HTTP ${res.status}`);
+    const json = await res.json();
+    const results = Array.isArray(json?.results) ? json.results : [];
+    return results.slice(0, maxResults).map((r) => ({
+      title: String(r?.title ?? ""),
+      url: String(r?.url ?? ""),
+      snippet: String(r?.content ?? "")
+    }));
+  };
+}
+
+exports.createSearxngWebSearchAdapter = createSearxngWebSearchAdapter;
+exports.createTavilyWebSearchAdapter = createTavilyWebSearchAdapter;
+//# sourceMappingURL=web-search-adapters.cjs.map
+//# sourceMappingURL=web-search-adapters.cjs.map

package/dist/web-search-adapters.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/web-search-searxng.ts","../src/web-search-tavily.ts"],"names":["ConfigurationError"],"mappings":"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","file":"web-search-adapters.cjs","sourcesContent":["/**\n * SearXNG adapter for `createWebSearchTool`.\n *\n * `createSearxngWebSearchAdapter()` returns a `WebSearchCallback` that queries a self-hosted\n * SearXNG instance (`SEARXNG_BASE_URL`) with `format=json`, which the instance must enable. The\n * call is keyless. A failed request rejects (`searxng_search_failed`) so the tool reports\n * `search_failed`; a 200 body without `results` is an empty search. SearXNG has no count\n * parameter, so the list is sliced here. The base URL is chosen by the consumer, never by the\n * model, so a plain fetch is used (like the Brave adapter's fixed host); `fetchImpl` is injectable\n * for offline tests.\n */\n\nimport { ConfigurationError } from \"@theokit/sdk\";\n\nimport type { WebSearchCallback, WebSearchResult } from \"./web-search.js\";\n\ntype FetchLike = (url: string, init?: RequestInit) => Promise<Response>;\n\n/** Options for {@link createSearxngWebSearchAdapter}. */\nexport interface CreateSearxngWebSearchAdapterOptions {\n  /** Instance base URL. Defaults to `process.env.SEARXNG_BASE_URL`. */\n  baseUrl?: string;\n  /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */\n  fetchImpl?: FetchLike;\n}\n\ninterface SearxngResult {\n  title?: unknown;\n  url?: unknown;\n  content?: unknown;\n}\n\nfunction parseBase(raw: string | undefined): URL {\n  const fail = (): never => {\n    throw new ConfigurationError(\n      \"SEARXNG_BASE_URL is not set or not a URL (pass { baseUrl } or set the env var).\",\n      { code: \"no_base_url\" },\n    );\n  };\n  if (!raw) return fail();\n  try {\n    const url = new URL(raw);\n    if (!url.pathname.endsWith(\"/\")) url.pathname += \"/\";\n    return url;\n  } catch {\n    return fail();\n  }\n}\n\n/**\n * Build a `WebSearchCallback` backed by a SearXNG instance. Throws a typed\n * `ConfigurationError` (\"no_base_url\") at creation when no valid base URL is available.\n */\nexport function createSearxngWebSearchAdapter(\n  opts: CreateSearxngWebSearchAdapterOptions = {},\n): WebSearchCallback {\n  const base = parseBase(opts.baseUrl ?? process.env.SEARXNG_BASE_URL);\n  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;\n\n  return async (query: string, maxResults: number): Promise<WebSearchResult[]> => {\n    const url = new URL(\"search\", base);\n    url.searchParams.set(\"q\", query);\n    url.searchParams.set(\"format\", \"json\");\n    const res = await fetchImpl(url.toString(), { headers: { Accept: \"application/json\" } });\n    if (!res.ok) throw new Error(`searxng_search_failed: HTTP ${res.status}`);\n    const json = (await res.json()) as { results?: unknown } | null;\n    const results: SearxngResult[] = Array.isArray(json?.results) ? json.results : [];\n    return results.slice(0, maxResults).map((r) => ({\n      title: String(r?.title ?? \"\"),\n      url: String(r?.url ?? \"\"),\n      snippet: String(r?.content ?? \"\"),\n    }));\n  };\n}\n","/**\n * Tavily adapter for `createWebSearchTool`.\n *\n * `createTavilyWebSearchAdapter()` returns a `WebSearchCallback` that posts the query to the\n * Tavily Search API with a bearer key (`TAVILY_API_KEY`). The tool is not modified: the adapter\n * plugs into its callback seam like the Brave one. A failed request rejects (`tavily_search_failed`)\n * so the tool reports `search_failed`, and a 200 body without `results` is an empty search. The\n * `fetch` impl is injectable for offline tests; a plain fetch is used because the host is fixed and\n * `screenedFetch` cannot carry the auth header. The message never carries the key.\n */\n\nimport { ConfigurationError } from \"@theokit/sdk\";\n\nimport type { WebSearchCallback, WebSearchResult } from \"./web-search.js\";\n\nconst TAVILY_ENDPOINT = \"https://api.tavily.com/search\";\n\ntype FetchLike = (url: string, init?: RequestInit) => Promise<Response>;\n\n/** Options for {@link createTavilyWebSearchAdapter}. */\nexport interface CreateTavilyWebSearchAdapterOptions {\n  /** Tavily API key. Defaults to `process.env.TAVILY_API_KEY`. */\n  apiKey?: string;\n  /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */\n  fetchImpl?: FetchLike;\n  /** Override the Tavily endpoint (proxy / test). */\n  endpoint?: string;\n}\n\ninterface TavilyResult {\n  title?: unknown;\n  url?: unknown;\n  content?: unknown;\n}\n\n/**\n * Build a `WebSearchCallback` backed by the Tavily Search API. Throws a typed\n * `ConfigurationError` (\"no_api_key\") at creation when no key is available.\n */\nexport function createTavilyWebSearchAdapter(\n  opts: CreateTavilyWebSearchAdapterOptions = {},\n): WebSearchCallback {\n  const apiKey = opts.apiKey ?? process.env.TAVILY_API_KEY;\n  if (!apiKey) {\n    throw new ConfigurationError(\n      \"TAVILY_API_KEY is not set (pass { apiKey } or set the env var).\",\n      { code: \"no_api_key\" },\n    );\n  }\n  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;\n  const endpoint = new URL(opts.endpoint ?? TAVILY_ENDPOINT).toString();\n\n  return async (query: string, maxResults: number): Promise<WebSearchResult[]> => {\n    const res = await fetchImpl(endpoint, {\n      method: \"POST\",\n      headers: { Authorization: `Bearer ${apiKey}`, \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ query, max_results: maxResults }),\n    });\n    if (!res.ok) throw new Error(`tavily_search_failed: HTTP ${res.status}`);\n    const json = (await res.json()) as { results?: unknown } | null;\n    const results: TavilyResult[] = Array.isArray(json?.results) ? json.results : [];\n    return results.slice(0, maxResults).map((r) => ({\n      title: String(r?.title ?? \"\"),\n      url: String(r?.url ?? \"\"),\n      snippet: String(r?.content ?? \"\"),\n    }));\n  };\n}\n"]}

package/dist/web-search-adapters.d.cts

@@ -0,0 +1,57 @@
+import { W as WebSearchCallback } from './web-search-CE82zZVl.cjs';
+import '@theokit/sdk';
+
+/**
+ * SearXNG adapter for `createWebSearchTool`.
+ *
+ * `createSearxngWebSearchAdapter()` returns a `WebSearchCallback` that queries a self-hosted
+ * SearXNG instance (`SEARXNG_BASE_URL`) with `format=json`, which the instance must enable. The
+ * call is keyless. A failed request rejects (`searxng_search_failed`) so the tool reports
+ * `search_failed`; a 200 body without `results` is an empty search. SearXNG has no count
+ * parameter, so the list is sliced here. The base URL is chosen by the consumer, never by the
+ * model, so a plain fetch is used (like the Brave adapter's fixed host); `fetchImpl` is injectable
+ * for offline tests.
+ */
+
+type FetchLike$1 = (url: string, init?: RequestInit) => Promise<Response>;
+/** Options for {@link createSearxngWebSearchAdapter}. */
+interface CreateSearxngWebSearchAdapterOptions {
+    /** Instance base URL. Defaults to `process.env.SEARXNG_BASE_URL`. */
+    baseUrl?: string;
+    /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
+    fetchImpl?: FetchLike$1;
+}
+/**
+ * Build a `WebSearchCallback` backed by a SearXNG instance. Throws a typed
+ * `ConfigurationError` ("no_base_url") at creation when no valid base URL is available.
+ */
+declare function createSearxngWebSearchAdapter(opts?: CreateSearxngWebSearchAdapterOptions): WebSearchCallback;
+
+/**
+ * Tavily adapter for `createWebSearchTool`.
+ *
+ * `createTavilyWebSearchAdapter()` returns a `WebSearchCallback` that posts the query to the
+ * Tavily Search API with a bearer key (`TAVILY_API_KEY`). The tool is not modified: the adapter
+ * plugs into its callback seam like the Brave one. A failed request rejects (`tavily_search_failed`)
+ * so the tool reports `search_failed`, and a 200 body without `results` is an empty search. The
+ * `fetch` impl is injectable for offline tests; a plain fetch is used because the host is fixed and
+ * `screenedFetch` cannot carry the auth header. The message never carries the key.
+ */
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Options for {@link createTavilyWebSearchAdapter}. */
+interface CreateTavilyWebSearchAdapterOptions {
+    /** Tavily API key. Defaults to `process.env.TAVILY_API_KEY`. */
+    apiKey?: string;
+    /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
+    fetchImpl?: FetchLike;
+    /** Override the Tavily endpoint (proxy / test). */
+    endpoint?: string;
+}
+/**
+ * Build a `WebSearchCallback` backed by the Tavily Search API. Throws a typed
+ * `ConfigurationError` ("no_api_key") at creation when no key is available.
+ */
+declare function createTavilyWebSearchAdapter(opts?: CreateTavilyWebSearchAdapterOptions): WebSearchCallback;
+
+export { type CreateSearxngWebSearchAdapterOptions, type CreateTavilyWebSearchAdapterOptions, createSearxngWebSearchAdapter, createTavilyWebSearchAdapter };

package/dist/web-search-adapters.d.ts

@@ -0,0 +1,57 @@
+import { W as WebSearchCallback } from './web-search-CE82zZVl.js';
+import '@theokit/sdk';
+
+/**
+ * SearXNG adapter for `createWebSearchTool`.
+ *
+ * `createSearxngWebSearchAdapter()` returns a `WebSearchCallback` that queries a self-hosted
+ * SearXNG instance (`SEARXNG_BASE_URL`) with `format=json`, which the instance must enable. The
+ * call is keyless. A failed request rejects (`searxng_search_failed`) so the tool reports
+ * `search_failed`; a 200 body without `results` is an empty search. SearXNG has no count
+ * parameter, so the list is sliced here. The base URL is chosen by the consumer, never by the
+ * model, so a plain fetch is used (like the Brave adapter's fixed host); `fetchImpl` is injectable
+ * for offline tests.
+ */
+
+type FetchLike$1 = (url: string, init?: RequestInit) => Promise<Response>;
+/** Options for {@link createSearxngWebSearchAdapter}. */
+interface CreateSearxngWebSearchAdapterOptions {
+    /** Instance base URL. Defaults to `process.env.SEARXNG_BASE_URL`. */
+    baseUrl?: string;
+    /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
+    fetchImpl?: FetchLike$1;
+}
+/**
+ * Build a `WebSearchCallback` backed by a SearXNG instance. Throws a typed
+ * `ConfigurationError` ("no_base_url") at creation when no valid base URL is available.
+ */
+declare function createSearxngWebSearchAdapter(opts?: CreateSearxngWebSearchAdapterOptions): WebSearchCallback;
+
+/**
+ * Tavily adapter for `createWebSearchTool`.
+ *
+ * `createTavilyWebSearchAdapter()` returns a `WebSearchCallback` that posts the query to the
+ * Tavily Search API with a bearer key (`TAVILY_API_KEY`). The tool is not modified: the adapter
+ * plugs into its callback seam like the Brave one. A failed request rejects (`tavily_search_failed`)
+ * so the tool reports `search_failed`, and a 200 body without `results` is an empty search. The
+ * `fetch` impl is injectable for offline tests; a plain fetch is used because the host is fixed and
+ * `screenedFetch` cannot carry the auth header. The message never carries the key.
+ */
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Options for {@link createTavilyWebSearchAdapter}. */
+interface CreateTavilyWebSearchAdapterOptions {
+    /** Tavily API key. Defaults to `process.env.TAVILY_API_KEY`. */
+    apiKey?: string;
+    /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
+    fetchImpl?: FetchLike;
+    /** Override the Tavily endpoint (proxy / test). */
+    endpoint?: string;
+}
+/**
+ * Build a `WebSearchCallback` backed by the Tavily Search API. Throws a typed
+ * `ConfigurationError` ("no_api_key") at creation when no key is available.
+ */
+declare function createTavilyWebSearchAdapter(opts?: CreateTavilyWebSearchAdapterOptions): WebSearchCallback;
+
+export { type CreateSearxngWebSearchAdapterOptions, type CreateTavilyWebSearchAdapterOptions, createSearxngWebSearchAdapter, createTavilyWebSearchAdapter };

package/dist/web-search-adapters.js

@@ -0,0 +1,68 @@
+import { ConfigurationError } from '@theokit/sdk';
+
+// src/web-search-searxng.ts
+function parseBase(raw) {
+  const fail = () => {
+    throw new ConfigurationError(
+      "SEARXNG_BASE_URL is not set or not a URL (pass { baseUrl } or set the env var).",
+      { code: "no_base_url" }
+    );
+  };
+  if (!raw) return fail();
+  try {
+    const url = new URL(raw);
+    if (!url.pathname.endsWith("/")) url.pathname += "/";
+    return url;
+  } catch {
+    return fail();
+  }
+}
+function createSearxngWebSearchAdapter(opts = {}) {
+  const base = parseBase(opts.baseUrl ?? process.env.SEARXNG_BASE_URL);
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  return async (query, maxResults) => {
+    const url = new URL("search", base);
+    url.searchParams.set("q", query);
+    url.searchParams.set("format", "json");
+    const res = await fetchImpl(url.toString(), { headers: { Accept: "application/json" } });
+    if (!res.ok) throw new Error(`searxng_search_failed: HTTP ${res.status}`);
+    const json = await res.json();
+    const results = Array.isArray(json?.results) ? json.results : [];
+    return results.slice(0, maxResults).map((r) => ({
+      title: String(r?.title ?? ""),
+      url: String(r?.url ?? ""),
+      snippet: String(r?.content ?? "")
+    }));
+  };
+}
+var TAVILY_ENDPOINT = "https://api.tavily.com/search";
+function createTavilyWebSearchAdapter(opts = {}) {
+  const apiKey = opts.apiKey ?? process.env.TAVILY_API_KEY;
+  if (!apiKey) {
+    throw new ConfigurationError(
+      "TAVILY_API_KEY is not set (pass { apiKey } or set the env var).",
+      { code: "no_api_key" }
+    );
+  }
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const endpoint = new URL(opts.endpoint ?? TAVILY_ENDPOINT).toString();
+  return async (query, maxResults) => {
+    const res = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ query, max_results: maxResults })
+    });
+    if (!res.ok) throw new Error(`tavily_search_failed: HTTP ${res.status}`);
+    const json = await res.json();
+    const results = Array.isArray(json?.results) ? json.results : [];
+    return results.slice(0, maxResults).map((r) => ({
+      title: String(r?.title ?? ""),
+      url: String(r?.url ?? ""),
+      snippet: String(r?.content ?? "")
+    }));
+  };
+}
+
+export { createSearxngWebSearchAdapter, createTavilyWebSearchAdapter };
+//# sourceMappingURL=web-search-adapters.js.map
+//# sourceMappingURL=web-search-adapters.js.map

package/dist/web-search-adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/web-search-searxng.ts","../src/web-search-tavily.ts"],"names":["ConfigurationError"],"mappings":"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","file":"web-search-adapters.js","sourcesContent":["/**\n * SearXNG adapter for `createWebSearchTool`.\n *\n * `createSearxngWebSearchAdapter()` returns a `WebSearchCallback` that queries a self-hosted\n * SearXNG instance (`SEARXNG_BASE_URL`) with `format=json`, which the instance must enable. The\n * call is keyless. A failed request rejects (`searxng_search_failed`) so the tool reports\n * `search_failed`; a 200 body without `results` is an empty search. SearXNG has no count\n * parameter, so the list is sliced here. The base URL is chosen by the consumer, never by the\n * model, so a plain fetch is used (like the Brave adapter's fixed host); `fetchImpl` is injectable\n * for offline tests.\n */\n\nimport { ConfigurationError } from \"@theokit/sdk\";\n\nimport type { WebSearchCallback, WebSearchResult } from \"./web-search.js\";\n\ntype FetchLike = (url: string, init?: RequestInit) => Promise<Response>;\n\n/** Options for {@link createSearxngWebSearchAdapter}. */\nexport interface CreateSearxngWebSearchAdapterOptions {\n  /** Instance base URL. Defaults to `process.env.SEARXNG_BASE_URL`. */\n  baseUrl?: string;\n  /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */\n  fetchImpl?: FetchLike;\n}\n\ninterface SearxngResult {\n  title?: unknown;\n  url?: unknown;\n  content?: unknown;\n}\n\nfunction parseBase(raw: string | undefined): URL {\n  const fail = (): never => {\n    throw new ConfigurationError(\n      \"SEARXNG_BASE_URL is not set or not a URL (pass { baseUrl } or set the env var).\",\n      { code: \"no_base_url\" },\n    );\n  };\n  if (!raw) return fail();\n  try {\n    const url = new URL(raw);\n    if (!url.pathname.endsWith(\"/\")) url.pathname += \"/\";\n    return url;\n  } catch {\n    return fail();\n  }\n}\n\n/**\n * Build a `WebSearchCallback` backed by a SearXNG instance. Throws a typed\n * `ConfigurationError` (\"no_base_url\") at creation when no valid base URL is available.\n */\nexport function createSearxngWebSearchAdapter(\n  opts: CreateSearxngWebSearchAdapterOptions = {},\n): WebSearchCallback {\n  const base = parseBase(opts.baseUrl ?? process.env.SEARXNG_BASE_URL);\n  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;\n\n  return async (query: string, maxResults: number): Promise<WebSearchResult[]> => {\n    const url = new URL(\"search\", base);\n    url.searchParams.set(\"q\", query);\n    url.searchParams.set(\"format\", \"json\");\n    const res = await fetchImpl(url.toString(), { headers: { Accept: \"application/json\" } });\n    if (!res.ok) throw new Error(`searxng_search_failed: HTTP ${res.status}`);\n    const json = (await res.json()) as { results?: unknown } | null;\n    const results: SearxngResult[] = Array.isArray(json?.results) ? json.results : [];\n    return results.slice(0, maxResults).map((r) => ({\n      title: String(r?.title ?? \"\"),\n      url: String(r?.url ?? \"\"),\n      snippet: String(r?.content ?? \"\"),\n    }));\n  };\n}\n","/**\n * Tavily adapter for `createWebSearchTool`.\n *\n * `createTavilyWebSearchAdapter()` returns a `WebSearchCallback` that posts the query to the\n * Tavily Search API with a bearer key (`TAVILY_API_KEY`). The tool is not modified: the adapter\n * plugs into its callback seam like the Brave one. A failed request rejects (`tavily_search_failed`)\n * so the tool reports `search_failed`, and a 200 body without `results` is an empty search. The\n * `fetch` impl is injectable for offline tests; a plain fetch is used because the host is fixed and\n * `screenedFetch` cannot carry the auth header. The message never carries the key.\n */\n\nimport { ConfigurationError } from \"@theokit/sdk\";\n\nimport type { WebSearchCallback, WebSearchResult } from \"./web-search.js\";\n\nconst TAVILY_ENDPOINT = \"https://api.tavily.com/search\";\n\ntype FetchLike = (url: string, init?: RequestInit) => Promise<Response>;\n\n/** Options for {@link createTavilyWebSearchAdapter}. */\nexport interface CreateTavilyWebSearchAdapterOptions {\n  /** Tavily API key. Defaults to `process.env.TAVILY_API_KEY`. */\n  apiKey?: string;\n  /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */\n  fetchImpl?: FetchLike;\n  /** Override the Tavily endpoint (proxy / test). */\n  endpoint?: string;\n}\n\ninterface TavilyResult {\n  title?: unknown;\n  url?: unknown;\n  content?: unknown;\n}\n\n/**\n * Build a `WebSearchCallback` backed by the Tavily Search API. Throws a typed\n * `ConfigurationError` (\"no_api_key\") at creation when no key is available.\n */\nexport function createTavilyWebSearchAdapter(\n  opts: CreateTavilyWebSearchAdapterOptions = {},\n): WebSearchCallback {\n  const apiKey = opts.apiKey ?? process.env.TAVILY_API_KEY;\n  if (!apiKey) {\n    throw new ConfigurationError(\n      \"TAVILY_API_KEY is not set (pass { apiKey } or set the env var).\",\n      { code: \"no_api_key\" },\n    );\n  }\n  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;\n  const endpoint = new URL(opts.endpoint ?? TAVILY_ENDPOINT).toString();\n\n  return async (query: string, maxResults: number): Promise<WebSearchResult[]> => {\n    const res = await fetchImpl(endpoint, {\n      method: \"POST\",\n      headers: { Authorization: `Bearer ${apiKey}`, \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ query, max_results: maxResults }),\n    });\n    if (!res.ok) throw new Error(`tavily_search_failed: HTTP ${res.status}`);\n    const json = (await res.json()) as { results?: unknown } | null;\n    const results: TavilyResult[] = Array.isArray(json?.results) ? json.results : [];\n    return results.slice(0, maxResults).map((r) => ({\n      title: String(r?.title ?? \"\"),\n      url: String(r?.url ?? \"\"),\n      snippet: String(r?.content ?? \"\"),\n    }));\n  };\n}\n"]}