theokit 0.30.0 → 0.30.2

package/dist/chunk-63BUBV5L.js

@@ -0,0 +1,64 @@
+// src/server/define/define-agent-tool.ts
+import { z } from "zod";
+var TOOL_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+function isZodObject(schema) {
+  let current = schema;
+  for (let depth = 0; depth < 10; depth++) {
+    if (current instanceof z.ZodObject) return true;
+    const z4 = current.def;
+    if (z4?.type === "object") return true;
+    const z3 = current._def;
+    if (z3?.typeName === "ZodObject") return true;
+    const next = z4?.innerType ?? z4?.in ?? z3?.schema ?? z3?.innerType;
+    if (next !== void 0) {
+      current = next;
+      continue;
+    }
+    return false;
+  }
+  return false;
+}
+function defineAgentTool(spec) {
+  if (!TOOL_NAME_REGEX.test(spec.name)) {
+    throw new Error(
+      `defineAgentTool: name must match ${TOOL_NAME_REGEX.source}. Got: ${JSON.stringify(spec.name)}`
+    );
+  }
+  if (!isZodObject(spec.inputSchema)) {
+    throw new Error("defineAgentTool: inputSchema must be a ZodObject (z.object({...}))");
+  }
+  if (spec.description.length === 0) {
+    console.warn(
+      `defineAgentTool(${JSON.stringify(spec.name)}): empty description degrades LLM tool selection \u2014 provide a one-sentence summary.`
+    );
+  }
+  const { $schema: _$schema, ...inputSchema } = z.toJSONSchema(spec.inputSchema);
+  return {
+    name: spec.name,
+    description: spec.description,
+    inputSchema,
+    handler: async (input, ctx) => {
+      const parsed = spec.inputSchema.parse(input);
+      const result = await spec.handler(parsed, ctx);
+      if (spec.toModelOutput) return spec.toModelOutput(result);
+      if (typeof result !== "string") {
+        throw new Error(
+          `defineAgentTool(${JSON.stringify(spec.name)}): handler returned a non-string; provide toModelOutput to map it to a string for the model.`
+        );
+      }
+      return result;
+    },
+    // M18 — carry the per-target formatters for the app (ignored by the SDK wire).
+    ...spec.transform !== void 0 ? { transform: spec.transform } : {}
+  };
+}
+function applyTransform(tool, result, target) {
+  const fn = tool.transform?.[target];
+  return fn ? fn(result) : result;
+}
+
+export {
+  defineAgentTool,
+  applyTransform
+};
+//# sourceMappingURL=chunk-63BUBV5L.js.map

package/dist/chunk-63BUBV5L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/define/define-agent-tool.ts"],"sourcesContent":["import { z } from 'zod'\n\n/**\n * Item #4 — `defineAgentTool`\n *\n * Sugar over the `@theokit/sdk` `CustomTool` contract. Takes a Zod schema +\n * handler and produces a structurally-compatible `CustomTool` that\n * `Agent.create({ tools: [...] })` accepts.\n *\n * Uses Zod v4's native `z.toJSONSchema()` to convert the input schema to\n * JSON Schema for LLM providers.\n *\n * Handler error propagation:\n *   `defineAgentTool` parses the input via the Zod schema BEFORE calling the\n *   user handler. Invalid input throws a `ZodError`, which the SDK's tool-\n *   dispatcher treats as a tool failure and surfaces to the model as a tool\n *   error (the SDK owns the wire; ADR D3).\n */\n\n/**\n * Local mirror of the SDK's `CustomTool` interface. We don't `import type`\n * from `@theokit/sdk` because the SDK is an optional peer (consumers who\n * never call `defineAgentTool` shouldn't need it installed). The shape is\n * the wire contract; any structurally-matching object is accepted by\n * `Agent.create({ tools })`.\n *\n * @public\n */\nexport interface CustomTool {\n  name: string\n  description: string\n  inputSchema: Record<string, unknown>\n  handler: (\n    input: Record<string, unknown>,\n    ctx?: { signal?: AbortSignal; context?: unknown },\n  ) => string | Promise<string>\n  /** M18 — optional per-target formatters for the app's UI/transcript (ignored by the SDK wire). */\n  transform?: ToolTransform\n}\n\n/**\n * M18 — per-target formatters. `display` shapes the rich handler result for the UI; `transcript`\n * shapes it for a saved transcript. Applied by {@link applyTransform}, never by the model wire.\n */\nexport interface ToolTransform<R = unknown> {\n  display?: (result: R) => unknown\n  transcript?: (result: R) => unknown\n}\n\n/**\n * Spec accepted by {@link defineAgentTool}. `inputSchema` is a Zod 3 schema\n * rooted in `z.object(...)`. The `handler` argument type is inferred via\n * `z.infer<T>`.\n *\n * @public\n */\nexport interface DefineAgentToolSpec<T extends z.ZodType, R = string> {\n  /** Tool name surfaced to the LLM. Must match `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`. */\n  name: string\n  /** Description surfaced to the LLM. Required — drives tool-selection accuracy. */\n  description: string\n  /** Zod schema describing the input. Must be `z.object(...)` at the root. */\n  inputSchema: T\n  /**\n   * Handler invoked with the parsed input and, optionally, the run `ctx` (M7). `ctx.context`\n   * is the object supplied once at the agent level (`defineAgent({ context })`) or per-run —\n   * read it for shared config like `projectRoot` instead of baking it into the factory.\n   * `ctx.signal` is the abort signal. Optional so existing one-arg handlers keep working.\n   *\n   * M18 — the handler may return RICH data `R` (not just a string) when `toModelOutput` is\n   * provided to map it to the model-visible string.\n   */\n  handler: (\n    input: z.infer<T>,\n    ctx?: { signal?: AbortSignal; context?: unknown },\n  ) => R | Promise<R>\n  /**\n   * M18 — map the rich handler result `R` to the string the model sees. Required (in practice)\n   * when `handler` returns a non-string; absent ⇒ the handler must return a string.\n   */\n  toModelOutput?: (result: R) => string\n  /** M18 — per-target formatters (`display` / `transcript`) for the app, applied by {@link applyTransform}. */\n  transform?: ToolTransform<R>\n}\n\nconst TOOL_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/\n\nfunction isZodObject(schema: z.ZodType): boolean {\n  // Refinements (`.refine`), transforms (`.transform`), and defaults wrap the\n  // underlying schema — walk the chain until we hit a ZodObject (or give up).\n  // Supports both zod 4 (`instanceof z.ZodObject`, `def.type === 'object'`,\n  // wrappers via `def.innerType` / pipe via `def.in`) and zod 3\n  // (`_def.typeName === 'ZodObject'`, wrappers via `_def.schema`/`_def.innerType`).\n  let current: unknown = schema\n  for (let depth = 0; depth < 10; depth++) {\n    if (current instanceof z.ZodObject) return true\n    const z4 = (current as { def?: { type?: string; innerType?: unknown; in?: unknown } }).def\n    if (z4?.type === 'object') return true\n    const z3 = (current as { _def?: { typeName?: string; schema?: unknown; innerType?: unknown } })\n      ._def\n    if (z3?.typeName === 'ZodObject') return true\n    const next = z4?.innerType ?? z4?.in ?? z3?.schema ?? z3?.innerType\n    if (next !== undefined) {\n      current = next\n      continue\n    }\n    return false\n  }\n  return false\n}\n\n/**\n * Build a {@link CustomTool} from a Zod 3 schema + handler.\n *\n * Behavior:\n * - Validates `name` matches the LLM tool-name regex.\n * - Requires `inputSchema` to be a `ZodObject` (Anthropic + SDK contract).\n * - Warns (not throws) if `description` is empty — empty descriptions\n *   degrade LLM tool selection.\n * - Converts the Zod schema to JSON Schema 7 inline (no `$ref`s — LLMs handle\n *   inline schemas more reliably).\n * - Strips the top-level `$schema` field (Anthropic rejects schemas with\n *   `$schema` at root in some provider modes).\n * - Wraps the handler to parse the input via the Zod schema BEFORE invoking\n *   the user code — bad LLM-supplied input throws `ZodError`, which the SDK\n *   converts to `tool_result(isError)`.\n *\n * @public\n */\nexport function defineAgentTool<T extends z.ZodType, R = string>(\n  spec: DefineAgentToolSpec<T, R>,\n): CustomTool {\n  if (!TOOL_NAME_REGEX.test(spec.name)) {\n    throw new Error(\n      `defineAgentTool: name must match ${TOOL_NAME_REGEX.source}. Got: ${JSON.stringify(spec.name)}`,\n    )\n  }\n  if (!isZodObject(spec.inputSchema)) {\n    throw new Error('defineAgentTool: inputSchema must be a ZodObject (z.object({...}))')\n  }\n  if (spec.description.length === 0) {\n    console.warn(\n      `defineAgentTool(${JSON.stringify(spec.name)}): empty description degrades LLM tool selection — provide a one-sentence summary.`,\n    )\n  }\n\n  // Zod v4 native JSON Schema conversion — replaces zod-to-json-schema dep.\n  // Strip $schema (Anthropic + some providers reject it).\n  const { $schema: _$schema, ...inputSchema } = z.toJSONSchema(spec.inputSchema) as Record<\n    string,\n    unknown\n  > & {\n    $schema?: unknown\n  }\n\n  return {\n    name: spec.name,\n    description: spec.description,\n    inputSchema,\n    handler: async (\n      input: Record<string, unknown>,\n      ctx?: { signal?: AbortSignal; context?: unknown },\n    ): Promise<string> => {\n      const parsed = spec.inputSchema.parse(input)\n      // M7 — forward the run ctx so the handler can read `ctx.context` (e.g. projectRoot).\n      const result = await spec.handler(parsed, ctx)\n      // M18 — shape the (possibly rich) result into the model-visible string.\n      if (spec.toModelOutput) return spec.toModelOutput(result)\n      if (typeof result !== 'string') {\n        throw new Error(\n          `defineAgentTool(${JSON.stringify(spec.name)}): handler returned a non-string; provide toModelOutput to map it to a string for the model.`,\n        )\n      }\n      return result\n    },\n    // M18 — carry the per-target formatters for the app (ignored by the SDK wire).\n    ...(spec.transform !== undefined ? { transform: spec.transform as ToolTransform } : {}),\n  }\n}\n\n/**\n * M18 — apply a tool's `transform` for a target (`display` / `transcript`). Returns the formatted\n * value, or the raw `result` when the tool declares no transform for that target.\n */\nexport function applyTransform(\n  tool: CustomTool,\n  result: unknown,\n  target: 'display' | 'transcript',\n): unknown {\n  const fn = tool.transform?.[target]\n  return fn ? fn(result) : result\n}\n"],"mappings":";AAAA,SAAS,SAAS;AAqFlB,IAAM,kBAAkB;AAExB,SAAS,YAAY,QAA4B;AAM/C,MAAI,UAAmB;AACvB,WAAS,QAAQ,GAAG,QAAQ,IAAI,SAAS;AACvC,QAAI,mBAAmB,EAAE,UAAW,QAAO;AAC3C,UAAM,KAAM,QAA2E;AACvF,QAAI,IAAI,SAAS,SAAU,QAAO;AAClC,UAAM,KAAM,QACT;AACH,QAAI,IAAI,aAAa,YAAa,QAAO;AACzC,UAAM,OAAO,IAAI,aAAa,IAAI,MAAM,IAAI,UAAU,IAAI;AAC1D,QAAI,SAAS,QAAW;AACtB,gBAAU;AACV;AAAA,IACF;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAoBO,SAAS,gBACd,MACY;AACZ,MAAI,CAAC,gBAAgB,KAAK,KAAK,IAAI,GAAG;AACpC,UAAM,IAAI;AAAA,MACR,oCAAoC,gBAAgB,MAAM,UAAU,KAAK,UAAU,KAAK,IAAI,CAAC;AAAA,IAC/F;AAAA,EACF;AACA,MAAI,CAAC,YAAY,KAAK,WAAW,GAAG;AAClC,UAAM,IAAI,MAAM,oEAAoE;AAAA,EACtF;AACA,MAAI,KAAK,YAAY,WAAW,GAAG;AACjC,YAAQ;AAAA,MACN,mBAAmB,KAAK,UAAU,KAAK,IAAI,CAAC;AAAA,IAC9C;AAAA,EACF;AAIA,QAAM,EAAE,SAAS,UAAU,GAAG,YAAY,IAAI,EAAE,aAAa,KAAK,WAAW;AAO7E,SAAO;AAAA,IACL,MAAM,KAAK;AAAA,IACX,aAAa,KAAK;AAAA,IAClB;AAAA,IACA,SAAS,OACP,OACA,QACoB;AACpB,YAAM,SAAS,KAAK,YAAY,MAAM,KAAK;AAE3C,YAAM,SAAS,MAAM,KAAK,QAAQ,QAAQ,GAAG;AAE7C,UAAI,KAAK,cAAe,QAAO,KAAK,cAAc,MAAM;AACxD,UAAI,OAAO,WAAW,UAAU;AAC9B,cAAM,IAAI;AAAA,UACR,mBAAmB,KAAK,UAAU,KAAK,IAAI,CAAC;AAAA,QAC9C;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA;AAAA,IAEA,GAAI,KAAK,cAAc,SAAY,EAAE,WAAW,KAAK,UAA2B,IAAI,CAAC;AAAA,EACvF;AACF;AAMO,SAAS,eACd,MACA,QACA,QACS;AACT,QAAM,KAAK,KAAK,YAAY,MAAM;AAClC,SAAO,KAAK,GAAG,MAAM,IAAI;AAC3B;","names":[]}

package/dist/{chunk-EHUT4FMG.js → chunk-HAOPVC47.js}

@@ -1,20 +1,30 @@
-import {
-  broadcastToDevtools
-} from "./chunk-7BIM27LV.js";
 import {
   buildServicesProxyConfig,
   servicesConfigSchema
 } from "./chunk-D7ZH7DTG.js";
 import {
-  extractAppResources,
-  handleMcpJsonRpc,
-  isMcpPath,
+  broadcastToDevtools
+} from "./chunk-7BIM27LV.js";
+import {
   loadEnv,
   resolveTransformer
-} from "./chunk-UYFZ6DDW.js";
+} from "./chunk-4MTCKE5I.js";
+import {
+  BATCH_PATH,
+  TRACE_HEADER,
+  createCorsHandler,
+  executeAction,
+  executeRoute,
+  extractTraceId,
+  handleBatchRequest,
+  sendError
+} from "./chunk-TGTNRUH3.js";
 import {
   findSuggestion
 } from "./chunk-5QW7IQQU.js";
+import {
+  logRequest
+} from "./chunk-WFNLNIJX.js";
 import {
   createPluginRunnerFromConfig
 } from "./chunk-IAJ2JVEH.js";
@@ -38,28 +48,20 @@ import {
   handleCspReport,
   handleCsrfReadiness
 } from "./chunk-JBCHWRKF.js";
+import {
+  validateCsrfRequest
+} from "./chunk-TSLSIRBR.js";
+import {
+  extractAppResources,
+  handleMcpJsonRpc,
+  isMcpPath
+} from "./chunk-HZ6USUHC.js";
 import {
   generateNonce
 } from "./chunk-C3ZZ56YZ.js";
 import {
   importUserModule
 } from "./chunk-7MQOHNHE.js";
-import {
-  BATCH_PATH,
-  TRACE_HEADER,
-  createCorsHandler,
-  executeAction,
-  executeRoute,
-  extractTraceId,
-  handleBatchRequest,
-  sendError
-} from "./chunk-TGTNRUH3.js";
-import {
-  logRequest
-} from "./chunk-WFNLNIJX.js";
-import {
-  validateCsrfRequest
-} from "./chunk-TSLSIRBR.js";
 
 // src/vite-plugin/index.ts
 import { existsSync as existsSync9 } from "fs";
@@ -3342,19 +3344,19 @@ async function theoPluginAsync(rootOrOptions) {
       })
     );
   }
-  const { appTypedClientPlugin } = await import("./app-typed-client-EXHUWPOI.js");
+  const { appTypedClientPlugin } = await import("./app-typed-client-4PAUHTO6.js");
   const appClientPlugin = appTypedClientPlugin({
     cwd: projectRoot,
     serverDir: serverDirAbs,
     distDir: resolve9(projectRoot, ".theokit")
   });
-  const { actionsVirtualModule } = await import("./actions-virtual-module-PBLLMJY4.js");
+  const { actionsVirtualModule } = await import("./actions-virtual-module-XHVLBFNN.js");
   const actionsPlugin = actionsVirtualModule({
     serverDir: serverDirAbs,
     distDir: resolve9(projectRoot, ".theokit")
   });
   const { agentsTypedClientPlugin } = await import("./agents-typed-client-MAAILRI6.js");
-  const { generateManifest } = await import("./internal-api-JIR3HRKF.js");
+  const { generateManifest } = await import("./internal-api-QSP2HCUU.js");
   const agentsClientPlugin = agentsTypedClientPlugin({
     projectRoot,
     agentsDir: agentsDirName,
@@ -3537,4 +3539,4 @@ export {
   theoPluginAsync,
   theoPlugin
 };
-//# sourceMappingURL=chunk-EHUT4FMG.js.map
+//# sourceMappingURL=chunk-HAOPVC47.js.map