@theokit/sdk-tools 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.29.0
+
+### Minor Changes
+
+- [#859](https://github.com/usetheokit/theokit-sdk/pull/859) [`0b76797`](https://github.com/usetheokit/theokit-sdk/commit/0b767975a8076a82c7834b5b11a032083fd06a51) Thanks [@usetheodev](https://github.com/usetheodev)! - `createGoalTool`, from the `@theokit/sdk-tools/goal` subpath, adds a `goal` tool that keeps one
+  standing goal per session across turns, for an objective that outlives a single turn (a checklist
+  stays with `todolist`). Its actions are `set`, `get`, `complete` and `clear`. `set` replaces an
+  existing goal and returns the previous text; `complete` on a finished goal is refused. Goals are
+  keyed by the run's `ctx.threadId`, so one tool object serves many sessions, and calls without a
+  thread id share one default goal. The goal lives in memory only and does not survive a restart.
+  Goal text is trimmed and capped at 2000 characters by default (`maxGoalChars`); every failure is a
+  typed result (`missing_goal`, `goal_too_long`, `no_goal`, `already_done`, `invalid_action`), never
+  a throw. It ships from its own subpath rather than the package root, so the root bundle stays
+  within its gzip budget.
+
+- [#859](https://github.com/usetheokit/theokit-sdk/pull/859) [`9a4adbf`](https://github.com/usetheokit/theokit-sdk/commit/9a4adbf4d751049d46ccd00dbfba1e3d02f7e0ab) Thanks [@usetheodev](https://github.com/usetheodev)! - `@theokit/sdk-tools/web-search-adapters` adds two providers for `createWebSearchTool`:
+  `createTavilyWebSearchAdapter` (a bearer-key POST; the key comes from `{ apiKey }` or
+  `TAVILY_API_KEY`) and `createSearxngWebSearchAdapter` (a keyless GET against your own instance;
+  the base URL comes from `{ baseUrl }` or `SEARXNG_BASE_URL`, and the instance must have the json
+  format enabled). Both reject on a non-OK status, so the tool reports `search_failed`, and return an
+  empty list for a 200 body without results. They ship from their own subpath so the root bundle
+  stays inside its size budget. The request and response shapes follow each provider's public
+  documentation and were not exercised against a live service.
+
+### Patch Changes
+
+- [#859](https://github.com/usetheokit/theokit-sdk/pull/859) [`9024a16`](https://github.com/usetheokit/theokit-sdk/commit/9024a16627657411c8be0d5e367f665f3e07c9a6) Thanks [@usetheodev](https://github.com/usetheodev)! - Add `structured_output`, a built-in tool that returns the model's object only when it validates against the consumer's zod schema, imported from the subpath `@theokit/sdk-tools/structured-output` (`createStructuredOutputTool({ schema })`). A valid call returns `{ ok: true, output }` with the parsed value; an invalid or non-object call returns the typed `invalid_structured_output` result with up to `maxIssues` `{ path, message }` issues and the full `issue_count`, and never throws. A schema that is not an object, or a `maxIssues` that is not a positive integer, fails at construction. The tool does not end the agent turn: the host stops on `ok: true`.
+
 ## 0.28.0
 
 ### Minor Changes

package/dist/goal.cjs

@@ -0,0 +1,84 @@
+'use strict';
+
+// src/goal.ts
+var DEFAULT_MAX_GOAL_CHARS = 2e3;
+var DEFAULT_SESSION = "__default__";
+function ok(data) {
+  return JSON.stringify({ ok: true, ...data });
+}
+function fail(error) {
+  return JSON.stringify({ ok: false, error });
+}
+function readMaxGoalChars(options) {
+  const max = options?.maxGoalChars ?? DEFAULT_MAX_GOAL_CHARS;
+  if (!Number.isInteger(max) || max <= 0) {
+    throw new RangeError(`createGoalTool: maxGoalChars must be a positive integer, got ${max}`);
+  }
+  return max;
+}
+function createGoalTool(options) {
+  const maxGoalChars = readMaxGoalChars(options);
+  const goals = /* @__PURE__ */ new Map();
+  function handleSet(key, input) {
+    const text = typeof input.goal === "string" ? input.goal.trim() : "";
+    if (text === "") return fail("missing_goal");
+    if (text.length > maxGoalChars) return fail("goal_too_long");
+    const previous = goals.get(key);
+    const goal = { text, status: "active", setAt: Date.now() };
+    goals.set(key, goal);
+    if (previous === void 0) return ok({ goal, replaced: false });
+    return ok({ goal, replaced: true, previous: previous.text });
+  }
+  function handleComplete(key) {
+    const goal = goals.get(key);
+    if (goal === void 0) return fail("no_goal");
+    if (goal.status === "done") return fail("already_done");
+    goal.status = "done";
+    goal.completedAt = Date.now();
+    return ok({ goal });
+  }
+  function handle(input, key) {
+    const fields = typeof input === "object" && input !== null ? input : {};
+    switch (fields.action) {
+      case "set":
+        return handleSet(key, fields);
+      case "get":
+        return ok({ goal: goals.get(key) ?? null });
+      case "complete":
+        return handleComplete(key);
+      case "clear":
+        goals.delete(key);
+        return ok({ goal: null });
+      default:
+        return fail("invalid_action");
+    }
+  }
+  return {
+    name: "goal",
+    description: `Keep ONE standing goal for the current session, read back across turns. Use it when the user states an objective that spans many turns, and check it with 'get' before deciding you are finished; use todolist for the steps toward it. Actions: 'set' (store the goal text, at most ${maxGoalChars} characters after trimming, replacing any existing goal and returning it as previous), 'get' (current goal or null), 'complete' (mark it done), 'clear' (drop it). Returns { ok, goal } with goal = { text, status, setAt, completedAt }; failures are { ok: false, error } with error one of missing_goal, goal_too_long, no_goal, already_done, invalid_action.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["set", "get", "complete", "clear"],
+          description: "The action to perform."
+        },
+        goal: {
+          type: "string",
+          description: "The goal text (required for 'set')."
+        }
+      },
+      required: ["action"]
+    },
+    handler: (input, ctx) => handle(input, ctx?.threadId ?? DEFAULT_SESSION),
+    getGoal: (threadId) => {
+      const goal = goals.get(threadId ?? DEFAULT_SESSION);
+      return goal === void 0 ? null : { ...goal };
+    }
+  };
+}
+
+exports.createGoalTool = createGoalTool;
+//# sourceMappingURL=goal.cjs.map
+//# sourceMappingURL=goal.cjs.map

package/dist/goal.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/goal.ts"],"names":[],"mappings":"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","file":"goal.cjs","sourcesContent":["/**\n * `goal` — one standing goal per session, kept across turns.\n *\n * Actions:\n *   - set(goal)   → set the goal, replacing any existing one (reports `previous`)\n *   - get()       → read the current goal, or null\n *   - complete()  → mark the goal done\n *   - clear()     → drop the goal\n *\n * State is keyed by `ctx.threadId`, as in `todolist` (#119). Calls without a thread id share one\n * default session, so a multi-session host that forgets to thread the id merges its users' goals.\n * The goal lives in memory only and dies with the process.\n */\n\n/** A session's goal: its text, whether it is still active, and when it was set and completed. */\nexport interface GoalState {\n  text: string;\n  status: \"active\" | \"done\";\n  setAt: number;\n  completedAt?: number;\n}\n\n/** Options for {@link createGoalTool}. */\nexport interface CreateGoalToolOptions {\n  /** Longest goal text accepted, after trimming. A positive integer; defaults to 2000. */\n  maxGoalChars?: number;\n}\n\n/**\n * The `goal` tool object. Hand-built like `todolist`: `inputSchema` is a plain JSON Schema value\n * and `handler` is synchronous. `getGoal` is a test seam onto the state the handler mutates.\n */\nexport interface GoalTool {\n  name: string;\n  description: string;\n  inputSchema: unknown;\n  handler: (input: GoalInput, ctx?: { threadId?: string }) => string;\n  /** A session's goal (defaults to the no-threadId session), or null when none is set. */\n  getGoal: (threadId?: string) => GoalState | null;\n}\n\ntype GoalInput =\n  | { action: \"set\"; goal: string }\n  | { action: \"get\" }\n  | { action: \"complete\" }\n  | { action: \"clear\" };\n\nconst DEFAULT_MAX_GOAL_CHARS = 2000;\nconst DEFAULT_SESSION = \"__default__\";\n\nfunction ok(data: Record<string, unknown>): string {\n  return JSON.stringify({ ok: true, ...data });\n}\n\nfunction fail(error: string): string {\n  return JSON.stringify({ ok: false, error });\n}\n\nfunction readMaxGoalChars(options: CreateGoalToolOptions | undefined): number {\n  const max = options?.maxGoalChars ?? DEFAULT_MAX_GOAL_CHARS;\n  if (!Number.isInteger(max) || max <= 0) {\n    throw new RangeError(`createGoalTool: maxGoalChars must be a positive integer, got ${max}`);\n  }\n  return max;\n}\n\n/**\n * Build the `goal` tool: the agent's one standing objective for a session, read back in later turns.\n *\n * Failures are typed, never thrown: `missing_goal`, `goal_too_long`, `no_goal`, `already_done` and\n * `invalid_action`. Only an invalid `maxGoalChars` throws, at construction.\n */\nexport function createGoalTool(options?: CreateGoalToolOptions): GoalTool {\n  const maxGoalChars = readMaxGoalChars(options);\n  const goals = new Map<string, GoalState>();\n\n  function handleSet(key: string, input: Record<string, unknown>): string {\n    const text = typeof input.goal === \"string\" ? input.goal.trim() : \"\";\n    if (text === \"\") return fail(\"missing_goal\");\n    if (text.length > maxGoalChars) return fail(\"goal_too_long\");\n    const previous = goals.get(key);\n    const goal: GoalState = { text, status: \"active\", setAt: Date.now() };\n    goals.set(key, goal);\n    if (previous === undefined) return ok({ goal, replaced: false });\n    return ok({ goal, replaced: true, previous: previous.text });\n  }\n\n  function handleComplete(key: string): string {\n    const goal = goals.get(key);\n    if (goal === undefined) return fail(\"no_goal\");\n    if (goal.status === \"done\") return fail(\"already_done\");\n    goal.status = \"done\";\n    goal.completedAt = Date.now();\n    return ok({ goal });\n  }\n\n  function handle(input: unknown, key: string): string {\n    const fields = (typeof input === \"object\" && input !== null ? input : {}) as Record<\n      string,\n      unknown\n    >;\n    switch (fields.action) {\n      case \"set\":\n        return handleSet(key, fields);\n      case \"get\":\n        return ok({ goal: goals.get(key) ?? null });\n      case \"complete\":\n        return handleComplete(key);\n      case \"clear\":\n        goals.delete(key);\n        return ok({ goal: null });\n      default:\n        return fail(\"invalid_action\");\n    }\n  }\n\n  return {\n    name: \"goal\",\n    description:\n      \"Keep ONE standing goal for the current session, read back across turns. Use it when the user \" +\n      \"states an objective that spans many turns, and check it with 'get' before deciding you are \" +\n      \"finished; use todolist for the steps toward it. Actions: 'set' (store the goal text, at most \" +\n      `${maxGoalChars} characters after trimming, replacing any existing goal and returning it as ` +\n      \"previous), 'get' (current goal or null), 'complete' (mark it done), 'clear' (drop it). Returns \" +\n      \"{ ok, goal } with goal = { text, status, setAt, completedAt }; failures are { ok: false, error } \" +\n      \"with error one of missing_goal, goal_too_long, no_goal, already_done, invalid_action.\",\n    inputSchema: {\n      type: \"object\" as const,\n      properties: {\n        action: {\n          type: \"string\",\n          enum: [\"set\", \"get\", \"complete\", \"clear\"],\n          description: \"The action to perform.\",\n        },\n        goal: {\n          type: \"string\",\n          description: \"The goal text (required for 'set').\",\n        },\n      },\n      required: [\"action\"],\n    },\n    handler: (input: GoalInput, ctx?: { threadId?: string }): string =>\n      handle(input, ctx?.threadId ?? DEFAULT_SESSION),\n    getGoal: (threadId?: string): GoalState | null => {\n      const goal = goals.get(threadId ?? DEFAULT_SESSION);\n      return goal === undefined ? null : { ...goal };\n    },\n  };\n}\n"]}

package/dist/goal.d.cts

@@ -0,0 +1,58 @@
+/**
+ * `goal` — one standing goal per session, kept across turns.
+ *
+ * Actions:
+ *   - set(goal)   → set the goal, replacing any existing one (reports `previous`)
+ *   - get()       → read the current goal, or null
+ *   - complete()  → mark the goal done
+ *   - clear()     → drop the goal
+ *
+ * State is keyed by `ctx.threadId`, as in `todolist` (#119). Calls without a thread id share one
+ * default session, so a multi-session host that forgets to thread the id merges its users' goals.
+ * The goal lives in memory only and dies with the process.
+ */
+/** A session's goal: its text, whether it is still active, and when it was set and completed. */
+interface GoalState {
+    text: string;
+    status: "active" | "done";
+    setAt: number;
+    completedAt?: number;
+}
+/** Options for {@link createGoalTool}. */
+interface CreateGoalToolOptions {
+    /** Longest goal text accepted, after trimming. A positive integer; defaults to 2000. */
+    maxGoalChars?: number;
+}
+/**
+ * The `goal` tool object. Hand-built like `todolist`: `inputSchema` is a plain JSON Schema value
+ * and `handler` is synchronous. `getGoal` is a test seam onto the state the handler mutates.
+ */
+interface GoalTool {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    handler: (input: GoalInput, ctx?: {
+        threadId?: string;
+    }) => string;
+    /** A session's goal (defaults to the no-threadId session), or null when none is set. */
+    getGoal: (threadId?: string) => GoalState | null;
+}
+type GoalInput = {
+    action: "set";
+    goal: string;
+} | {
+    action: "get";
+} | {
+    action: "complete";
+} | {
+    action: "clear";
+};
+/**
+ * Build the `goal` tool: the agent's one standing objective for a session, read back in later turns.
+ *
+ * Failures are typed, never thrown: `missing_goal`, `goal_too_long`, `no_goal`, `already_done` and
+ * `invalid_action`. Only an invalid `maxGoalChars` throws, at construction.
+ */
+declare function createGoalTool(options?: CreateGoalToolOptions): GoalTool;
+
+export { type CreateGoalToolOptions, type GoalState, type GoalTool, createGoalTool };

package/dist/goal.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `goal` — one standing goal per session, kept across turns.
+ *
+ * Actions:
+ *   - set(goal)   → set the goal, replacing any existing one (reports `previous`)
+ *   - get()       → read the current goal, or null
+ *   - complete()  → mark the goal done
+ *   - clear()     → drop the goal
+ *
+ * State is keyed by `ctx.threadId`, as in `todolist` (#119). Calls without a thread id share one
+ * default session, so a multi-session host that forgets to thread the id merges its users' goals.
+ * The goal lives in memory only and dies with the process.
+ */
+/** A session's goal: its text, whether it is still active, and when it was set and completed. */
+interface GoalState {
+    text: string;
+    status: "active" | "done";
+    setAt: number;
+    completedAt?: number;
+}
+/** Options for {@link createGoalTool}. */
+interface CreateGoalToolOptions {
+    /** Longest goal text accepted, after trimming. A positive integer; defaults to 2000. */
+    maxGoalChars?: number;
+}
+/**
+ * The `goal` tool object. Hand-built like `todolist`: `inputSchema` is a plain JSON Schema value
+ * and `handler` is synchronous. `getGoal` is a test seam onto the state the handler mutates.
+ */
+interface GoalTool {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    handler: (input: GoalInput, ctx?: {
+        threadId?: string;
+    }) => string;
+    /** A session's goal (defaults to the no-threadId session), or null when none is set. */
+    getGoal: (threadId?: string) => GoalState | null;
+}
+type GoalInput = {
+    action: "set";
+    goal: string;
+} | {
+    action: "get";
+} | {
+    action: "complete";
+} | {
+    action: "clear";
+};
+/**
+ * Build the `goal` tool: the agent's one standing objective for a session, read back in later turns.
+ *
+ * Failures are typed, never thrown: `missing_goal`, `goal_too_long`, `no_goal`, `already_done` and
+ * `invalid_action`. Only an invalid `maxGoalChars` throws, at construction.
+ */
+declare function createGoalTool(options?: CreateGoalToolOptions): GoalTool;
+
+export { type CreateGoalToolOptions, type GoalState, type GoalTool, createGoalTool };

package/dist/goal.js

@@ -0,0 +1,82 @@
+// src/goal.ts
+var DEFAULT_MAX_GOAL_CHARS = 2e3;
+var DEFAULT_SESSION = "__default__";
+function ok(data) {
+  return JSON.stringify({ ok: true, ...data });
+}
+function fail(error) {
+  return JSON.stringify({ ok: false, error });
+}
+function readMaxGoalChars(options) {
+  const max = options?.maxGoalChars ?? DEFAULT_MAX_GOAL_CHARS;
+  if (!Number.isInteger(max) || max <= 0) {
+    throw new RangeError(`createGoalTool: maxGoalChars must be a positive integer, got ${max}`);
+  }
+  return max;
+}
+function createGoalTool(options) {
+  const maxGoalChars = readMaxGoalChars(options);
+  const goals = /* @__PURE__ */ new Map();
+  function handleSet(key, input) {
+    const text = typeof input.goal === "string" ? input.goal.trim() : "";
+    if (text === "") return fail("missing_goal");
+    if (text.length > maxGoalChars) return fail("goal_too_long");
+    const previous = goals.get(key);
+    const goal = { text, status: "active", setAt: Date.now() };
+    goals.set(key, goal);
+    if (previous === void 0) return ok({ goal, replaced: false });
+    return ok({ goal, replaced: true, previous: previous.text });
+  }
+  function handleComplete(key) {
+    const goal = goals.get(key);
+    if (goal === void 0) return fail("no_goal");
+    if (goal.status === "done") return fail("already_done");
+    goal.status = "done";
+    goal.completedAt = Date.now();
+    return ok({ goal });
+  }
+  function handle(input, key) {
+    const fields = typeof input === "object" && input !== null ? input : {};
+    switch (fields.action) {
+      case "set":
+        return handleSet(key, fields);
+      case "get":
+        return ok({ goal: goals.get(key) ?? null });
+      case "complete":
+        return handleComplete(key);
+      case "clear":
+        goals.delete(key);
+        return ok({ goal: null });
+      default:
+        return fail("invalid_action");
+    }
+  }
+  return {
+    name: "goal",
+    description: `Keep ONE standing goal for the current session, read back across turns. Use it when the user states an objective that spans many turns, and check it with 'get' before deciding you are finished; use todolist for the steps toward it. Actions: 'set' (store the goal text, at most ${maxGoalChars} characters after trimming, replacing any existing goal and returning it as previous), 'get' (current goal or null), 'complete' (mark it done), 'clear' (drop it). Returns { ok, goal } with goal = { text, status, setAt, completedAt }; failures are { ok: false, error } with error one of missing_goal, goal_too_long, no_goal, already_done, invalid_action.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["set", "get", "complete", "clear"],
+          description: "The action to perform."
+        },
+        goal: {
+          type: "string",
+          description: "The goal text (required for 'set')."
+        }
+      },
+      required: ["action"]
+    },
+    handler: (input, ctx) => handle(input, ctx?.threadId ?? DEFAULT_SESSION),
+    getGoal: (threadId) => {
+      const goal = goals.get(threadId ?? DEFAULT_SESSION);
+      return goal === void 0 ? null : { ...goal };
+    }
+  };
+}
+
+export { createGoalTool };
+//# sourceMappingURL=goal.js.map
+//# sourceMappingURL=goal.js.map

package/dist/goal.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/goal.ts"],"names":[],"mappings":"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","file":"goal.js","sourcesContent":["/**\n * `goal` — one standing goal per session, kept across turns.\n *\n * Actions:\n *   - set(goal)   → set the goal, replacing any existing one (reports `previous`)\n *   - get()       → read the current goal, or null\n *   - complete()  → mark the goal done\n *   - clear()     → drop the goal\n *\n * State is keyed by `ctx.threadId`, as in `todolist` (#119). Calls without a thread id share one\n * default session, so a multi-session host that forgets to thread the id merges its users' goals.\n * The goal lives in memory only and dies with the process.\n */\n\n/** A session's goal: its text, whether it is still active, and when it was set and completed. */\nexport interface GoalState {\n  text: string;\n  status: \"active\" | \"done\";\n  setAt: number;\n  completedAt?: number;\n}\n\n/** Options for {@link createGoalTool}. */\nexport interface CreateGoalToolOptions {\n  /** Longest goal text accepted, after trimming. A positive integer; defaults to 2000. */\n  maxGoalChars?: number;\n}\n\n/**\n * The `goal` tool object. Hand-built like `todolist`: `inputSchema` is a plain JSON Schema value\n * and `handler` is synchronous. `getGoal` is a test seam onto the state the handler mutates.\n */\nexport interface GoalTool {\n  name: string;\n  description: string;\n  inputSchema: unknown;\n  handler: (input: GoalInput, ctx?: { threadId?: string }) => string;\n  /** A session's goal (defaults to the no-threadId session), or null when none is set. */\n  getGoal: (threadId?: string) => GoalState | null;\n}\n\ntype GoalInput =\n  | { action: \"set\"; goal: string }\n  | { action: \"get\" }\n  | { action: \"complete\" }\n  | { action: \"clear\" };\n\nconst DEFAULT_MAX_GOAL_CHARS = 2000;\nconst DEFAULT_SESSION = \"__default__\";\n\nfunction ok(data: Record<string, unknown>): string {\n  return JSON.stringify({ ok: true, ...data });\n}\n\nfunction fail(error: string): string {\n  return JSON.stringify({ ok: false, error });\n}\n\nfunction readMaxGoalChars(options: CreateGoalToolOptions | undefined): number {\n  const max = options?.maxGoalChars ?? DEFAULT_MAX_GOAL_CHARS;\n  if (!Number.isInteger(max) || max <= 0) {\n    throw new RangeError(`createGoalTool: maxGoalChars must be a positive integer, got ${max}`);\n  }\n  return max;\n}\n\n/**\n * Build the `goal` tool: the agent's one standing objective for a session, read back in later turns.\n *\n * Failures are typed, never thrown: `missing_goal`, `goal_too_long`, `no_goal`, `already_done` and\n * `invalid_action`. Only an invalid `maxGoalChars` throws, at construction.\n */\nexport function createGoalTool(options?: CreateGoalToolOptions): GoalTool {\n  const maxGoalChars = readMaxGoalChars(options);\n  const goals = new Map<string, GoalState>();\n\n  function handleSet(key: string, input: Record<string, unknown>): string {\n    const text = typeof input.goal === \"string\" ? input.goal.trim() : \"\";\n    if (text === \"\") return fail(\"missing_goal\");\n    if (text.length > maxGoalChars) return fail(\"goal_too_long\");\n    const previous = goals.get(key);\n    const goal: GoalState = { text, status: \"active\", setAt: Date.now() };\n    goals.set(key, goal);\n    if (previous === undefined) return ok({ goal, replaced: false });\n    return ok({ goal, replaced: true, previous: previous.text });\n  }\n\n  function handleComplete(key: string): string {\n    const goal = goals.get(key);\n    if (goal === undefined) return fail(\"no_goal\");\n    if (goal.status === \"done\") return fail(\"already_done\");\n    goal.status = \"done\";\n    goal.completedAt = Date.now();\n    return ok({ goal });\n  }\n\n  function handle(input: unknown, key: string): string {\n    const fields = (typeof input === \"object\" && input !== null ? input : {}) as Record<\n      string,\n      unknown\n    >;\n    switch (fields.action) {\n      case \"set\":\n        return handleSet(key, fields);\n      case \"get\":\n        return ok({ goal: goals.get(key) ?? null });\n      case \"complete\":\n        return handleComplete(key);\n      case \"clear\":\n        goals.delete(key);\n        return ok({ goal: null });\n      default:\n        return fail(\"invalid_action\");\n    }\n  }\n\n  return {\n    name: \"goal\",\n    description:\n      \"Keep ONE standing goal for the current session, read back across turns. Use it when the user \" +\n      \"states an objective that spans many turns, and check it with 'get' before deciding you are \" +\n      \"finished; use todolist for the steps toward it. Actions: 'set' (store the goal text, at most \" +\n      `${maxGoalChars} characters after trimming, replacing any existing goal and returning it as ` +\n      \"previous), 'get' (current goal or null), 'complete' (mark it done), 'clear' (drop it). Returns \" +\n      \"{ ok, goal } with goal = { text, status, setAt, completedAt }; failures are { ok: false, error } \" +\n      \"with error one of missing_goal, goal_too_long, no_goal, already_done, invalid_action.\",\n    inputSchema: {\n      type: \"object\" as const,\n      properties: {\n        action: {\n          type: \"string\",\n          enum: [\"set\", \"get\", \"complete\", \"clear\"],\n          description: \"The action to perform.\",\n        },\n        goal: {\n          type: \"string\",\n          description: \"The goal text (required for 'set').\",\n        },\n      },\n      required: [\"action\"],\n    },\n    handler: (input: GoalInput, ctx?: { threadId?: string }): string =>\n      handle(input, ctx?.threadId ?? DEFAULT_SESSION),\n    getGoal: (threadId?: string): GoalState | null => {\n      const goal = goals.get(threadId ?? DEFAULT_SESSION);\n      return goal === undefined ? null : { ...goal };\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -2,6 +2,8 @@ import { CustomTool, ConfigurationError } from '@theokit/sdk';
 import { FilesystemProvider } from '@theokit/sdk/filesystem';
 import { SandboxProvider } from '@theokit/sdk/sandbox';
 import { InteractiveProvider } from '@theokit/sdk/interactive';
+import { W as WebSearchCallback } from './web-search-CE82zZVl.cjs';
+export { C as CreateWebSearchToolOptions, a as WebSearchResult, c as createWebSearchTool } from './web-search-CE82zZVl.cjs';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -1714,64 +1716,6 @@ interface CreateWebFetchToolOptions {
  */
 declare function createWebFetchTool(opts?: CreateWebFetchToolOptions): CustomTool;
 
-/**
- * `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;
-
 /**
  * Brave Search adapter for `createWebSearchTool` (M3-7).
  *
@@ -1912,4 +1856,4 @@ interface CreateWriteFileToolOptions {
  */
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateTextToSpeechToolOptions, type CreateViewImageToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_MAX_AUDIO_BYTES, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_MAX_TEXT_CHARS, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type SynthesizedAudio, type TextToSpeechCallback, type TextToSpeechResult, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTextToSpeechTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateTextToSpeechToolOptions, type CreateViewImageToolOptions, type CreateWebFetchToolOptions, type CreateWriteFileToolOptions, DEFAULT_MAX_AUDIO_BYTES, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_MAX_TEXT_CHARS, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type SynthesizedAudio, type TextToSpeechCallback, type TextToSpeechResult, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, WebSearchCallback, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTextToSpeechTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, createWebFetchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { CustomTool, ConfigurationError } from '@theokit/sdk';
 import { FilesystemProvider } from '@theokit/sdk/filesystem';
 import { SandboxProvider } from '@theokit/sdk/sandbox';
 import { InteractiveProvider } from '@theokit/sdk/interactive';
+import { W as WebSearchCallback } from './web-search-CE82zZVl.js';
+export { C as CreateWebSearchToolOptions, a as WebSearchResult, c as createWebSearchTool } from './web-search-CE82zZVl.js';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -1714,64 +1716,6 @@ interface CreateWebFetchToolOptions {
  */
 declare function createWebFetchTool(opts?: CreateWebFetchToolOptions): CustomTool;
 
-/**
- * `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;
-
 /**
  * Brave Search adapter for `createWebSearchTool` (M3-7).
  *
@@ -1912,4 +1856,4 @@ interface CreateWriteFileToolOptions {
  */
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateTextToSpeechToolOptions, type CreateViewImageToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_MAX_AUDIO_BYTES, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_MAX_TEXT_CHARS, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type SynthesizedAudio, type TextToSpeechCallback, type TextToSpeechResult, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTextToSpeechTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateTextToSpeechToolOptions, type CreateViewImageToolOptions, type CreateWebFetchToolOptions, type CreateWriteFileToolOptions, DEFAULT_MAX_AUDIO_BYTES, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_MAX_TEXT_CHARS, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type SynthesizedAudio, type TextToSpeechCallback, type TextToSpeechResult, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, WebSearchCallback, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTextToSpeechTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, createWebFetchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };

package/dist/structured-output.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+var sdk = require('@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 = sdk.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))
+  };
+}
+
+exports.createStructuredOutputTool = createStructuredOutputTool;
+//# sourceMappingURL=structured-output.cjs.map
+//# sourceMappingURL=structured-output.cjs.map

package/dist/structured-output.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/structured-output.ts"],"names":["Tool"],"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,GAAOA,SAAK,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.cjs","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"]}