theokit 0.30.0 → 0.30.2

package/dist/server/agent/index.d.ts

@@ -0,0 +1,387 @@
+import { z } from 'zod';
+import { C as CustomTool } from '../../define-agent-tool-ChaGymol.js';
+import { AcpTransport, HumanInTheLoopOptions, HitlDecision, streamAgentUIMessages } from '@theokit/agents';
+import { CustomTool as CustomTool$1 } from '@theokit/sdk';
+import { V as VerifyFn } from '../../webhook-types-CNUZY7o1.js';
+import { UIMessageChunk } from 'ai';
+
+/**
+ * M26 (ADR-0041) — `createWorkflowTool`: wrap an SDK `Workflow` as a `CustomTool`.
+ *
+ * THIN adapter. `packages/workflows/` stays G13-forbidden — the workflow ENGINE is the SDK's
+ * (`Workflow.create(...).run(input)`). This exposes an already-built `Workflow` to an agent as one
+ * callable tool: it validates the tool input, delegates to `workflow.run(input)`, and shapes the
+ * result for the model. It calls no LLM, dispatches no tool, and runs no orchestration of its own —
+ * the SDK owns all of that (sdk-runtime.md / G2).
+ */
+
+/**
+ * Structural stand-in for the SDK `Workflow` (the adapter never imports the SDK type — keeps the
+ * SDK an optional peer). Any object with a `run(input)` resolving to `{ status, output }` matches.
+ */
+interface WorkflowLike {
+    run(input: unknown): Promise<{
+        status: string;
+        output: unknown;
+        runId?: string;
+    }>;
+}
+/** Config for {@link createWorkflowTool}. `inputSchema` defaults to an open object. */
+interface WorkflowToolConfig {
+    /** Tool name surfaced to the LLM. */
+    name: string;
+    /** Tool description surfaced to the LLM. */
+    description: string;
+    /** Zod schema for the workflow input (defaults to `z.object({}).passthrough()`). */
+    inputSchema?: z.ZodType;
+}
+/**
+ * Wrap an SDK `Workflow` as a {@link CustomTool}. Fails fast if `workflow` does not expose a
+ * `run()` method (the SDK Workflow contract), so a mis-wired call is caught at definition time, not
+ * at the first invocation (error-handling.md).
+ */
+declare function createWorkflowTool(workflow: WorkflowLike, config: WorkflowToolConfig): CustomTool;
+
+/** Stdio transport backed by a spawned subprocess (the default for {@link createACPTool}). */
+declare class NodeAcpTransport implements AcpTransport {
+    private readonly proc;
+    constructor(command: string, args?: string[], cwd?: string);
+    send(line: string): void;
+    subscribe(onData: (chunk: string) => void): void;
+    close(): void;
+}
+interface AcpToolConfig {
+    /** Executable for the coding agent (e.g. `claude`, `amp`, `codex`). */
+    command: string;
+    /** Command-line arguments. */
+    args?: string[];
+    /** Working directory for the spawned agent. */
+    cwd?: string;
+    /** Tool name the model calls. */
+    name: string;
+    /** Tool description surfaced to the model. */
+    description: string;
+    /**
+     * REQUIRED — decide file/shell permission requests from the coding agent. Security by default:
+     * there is NO default-allow. Return `{ granted: boolean }` (may be async).
+     */
+    onPermissionRequest: (params: unknown) => {
+        granted: boolean;
+    } | Promise<{
+        granted: boolean;
+    }>;
+    /** Injected transport factory (defaults to spawning via {@link NodeAcpTransport}) — for tests. */
+    transportFactory?: (config: AcpToolConfig) => AcpTransport;
+}
+/** Wrap a coding agent as a `CustomTool`. Fails fast if `onPermissionRequest` is missing. */
+declare function createACPTool(config: AcpToolConfig): CustomTool$1;
+
+/**
+ * M28 (ADR-0041) — `createVendorAgentTool`: expose a third-party agent SDK (Claude Agent SDK,
+ * OpenAI, Cursor) behind a uniform `CustomTool`, mirroring the M17 ACP pattern.
+ *
+ * The vendor RUNTIME stays theirs — TheoKit only wires. The vendor client is INJECTED (the real
+ * vendor SDK client in prod, a fake in tests), so no vendor dependency enters core; vendor-specific
+ * client packages belong under `@theokit/agent-*`, never here. This calls no LLM of its own and runs
+ * no loop — it delegates each prompt to `client.query(...)` (sdk-runtime.md / G2). Resume is threaded
+ * via the vendor's own session id.
+ */
+
+/**
+ * Structural contract a vendor agent client must satisfy (the adapter never imports a vendor type).
+ * `query` runs one turn; `resumeSessionId` continues a prior vendor session; the returned
+ * `sessionId` identifies the session to resume next.
+ */
+interface VendorAgentClient {
+    query(prompt: string, opts?: {
+        resumeSessionId?: string;
+    }): Promise<{
+        text: string;
+        sessionId?: string;
+    }>;
+}
+/** Config for {@link createVendorAgentTool}. */
+interface VendorAgentToolConfig {
+    /** Vendor label (e.g. `claude`, `openai`, `cursor`). Drives the default tool name. */
+    vendor: string;
+    /** The injected vendor client (real SDK client in prod, a fake in tests). */
+    client: VendorAgentClient;
+    /** Tool name the model calls (defaults to `<vendor>_agent`). */
+    name?: string;
+    /** Tool description surfaced to the model (defaults to a one-line delegate hint). */
+    description?: string;
+    /**
+     * Side-channel callback invoked with the vendor session id after each turn — lets the app capture
+     * it for a later resume WITHOUT leaking session bookkeeping into the model's view of the result.
+     */
+    onSession?: (sessionId: string) => void;
+}
+/**
+ * Wrap a vendor agent SDK as a {@link CustomTool}. Fails fast if `vendor` is empty or the client
+ * does not expose `query()` (error-handling.md) — a mis-wired call is caught at definition time.
+ */
+declare function createVendorAgentTool(config: VendorAgentToolConfig): CustomTool;
+
+/**
+ * M29 (ADR-0041) — `createCodeMode`: expose a set of tools to agent-authored code run inside an
+ * ISOLATION boundary, so the agent composes tools programmatically instead of one call at a time.
+ *
+ * Security posture (the whole point of this feature):
+ *  - The isolation boundary (`sandbox`) is **injected**, never hand-rolled here (Top-risk 1). The app
+ *    supplies a vetted sandbox — isolated-vm, QuickJS-WASM, or a locked-down worker. TheoKit core
+ *    ships no VM and adds no sandbox dependency (same posture as the injected deploy adapter / the
+ *    M17 transport). `node:vm` is NOT a security boundary and MUST NOT be used as the sandbox.
+ *  - TheoKit owns the **restricted API** (only the declared tools are reachable from the code — no
+ *    `fs`, `process`, `require`, or network unless a declared, permission-gated tool provides it) and
+ *    the **mandatory permission gate**: every tool call from the code passes `onPermissionRequest`
+ *    first, and there is NO default-allow (mirrors M17 `onPermissionRequest`).
+ *
+ * Threat model (summary): a malicious model could author code that (a) calls a dangerous tool, or
+ * (b) tries to reach a host capability. (a) is stopped by the permission gate (deny → the API call
+ * throws). (b) is stopped by the injected sandbox (the restricted API is the ONLY surface the code
+ * sees). If the app injects a weak sandbox, (b) is on the app — hence the vetted-sandbox requirement.
+ */
+
+/** The restricted API handed to sandboxed code: declared tool names → permission-gated callables. */
+type CodeModeApi = Record<string, (args: unknown) => Promise<unknown>>;
+/** The injected isolation boundary. The app supplies a vetted implementation. */
+interface Sandbox {
+    /** Run `code` with access to ONLY `api` (the restricted tool surface). Resolve the code's result. */
+    run(code: string, api: CodeModeApi): Promise<unknown>;
+}
+/** A permission decision for one tool call from sandboxed code. */
+interface CodeModePermission {
+    granted: boolean;
+    /** Optional reason surfaced to the model on denial. */
+    reason?: string;
+}
+interface CodeModeConfig {
+    /** The tools reachable from the code (the restricted API). */
+    tools: CustomTool[];
+    /** The injected isolation boundary (vetted sandbox — NEVER node:vm). */
+    sandbox: Sandbox;
+    /**
+     * REQUIRED — decide each tool call the code attempts. Security by default: NO default-allow.
+     * Return `{ granted }` (may be async). Mirrors M17 `onPermissionRequest`.
+     */
+    onPermissionRequest: (req: {
+        tool: string;
+        args: unknown;
+    }) => CodeModePermission | Promise<CodeModePermission>;
+    /** Tool name the model calls (default `run_code`). */
+    name?: string;
+    /** Tool description surfaced to the model. */
+    description?: string;
+}
+/** Thrown when the permission gate denies a tool call from sandboxed code. */
+declare class CodeModePermissionDeniedError extends Error {
+    constructor(tool: string, reason?: string);
+}
+/**
+ * Build a code-mode tool + its generated model instructions (M40 / ADR-0049). Fails fast if
+ * `onPermissionRequest` or `sandbox` is missing (security by default). `tool` takes `{ code }`,
+ * assembles the permission-gated restricted API from `tools`, runs the code in the injected sandbox,
+ * and returns the code's result. `instructions` (add it to the agent's system prompt) teaches the
+ * model the sandboxed-code contract + the available `api.<name>(input)` calls.
+ */
+declare function createCodeMode(config: CodeModeConfig): {
+    tool: CustomTool;
+    instructions: string;
+};
+
+/**
+ * M27 (ADR-0041) — channel webhook routes: `POST /api/agents/<name>/channels/<platform>/webhook`.
+ *
+ * Auto-generates a per-platform inbound webhook endpoint that VALIDATES the platform signature
+ * (reusing the existing webhook `VerifyFn` providers — Slack/Telegram/Discord — never a hand-rolled
+ * scheme) and hands the parsed payload to an injected `onMessage` seam. The seam is where an app
+ * wires the SDK gateway package (`@theokit/gateway-*`) that translates the payload into an agent
+ * turn — TheoKit provides the route + signature gate, NOT the gateway's parsing (G2 / it does not
+ * reimplement the gateway).
+ */
+
+/** Parsed `{ agent, platform }` from a channel webhook path, or `null` when it doesn't match. */
+declare function parseChannelPath(urlPath: string): {
+    agent: string;
+    platform: string;
+} | null;
+/** True when `urlPath` targets a channel webhook (dev/prod routing branches on this). */
+declare function isChannelPath(urlPath: string): boolean;
+/** The inbound message handed to the app after signature validation passes. */
+interface ChannelMessage {
+    agent: string;
+    platform: string;
+    /** The parsed JSON payload from the platform (the gateway translates this to an agent turn). */
+    payload: unknown;
+}
+interface ChannelWebhookConfig {
+    /** Per-platform signature validators (e.g. `{ slack: slack({...}), telegram: telegram({...}) }`). */
+    validators: Record<string, VerifyFn>;
+    /** Handoff seam — wire the SDK gateway / agent here. Invoked only after signature validation. */
+    onMessage: (message: ChannelMessage) => void | Promise<void>;
+}
+/**
+ * Handle one channel webhook request. Returns:
+ *   404 UNKNOWN_PLATFORM — no validator configured for `<platform>`
+ *   400 BAD_REQUEST      — path is not a channel webhook, or the body is not JSON
+ *   401 INVALID_SIGNATURE — the platform signature check failed (negative case)
+ *   200 { ok: true }     — validated + handed to `onMessage`
+ */
+declare function handleChannelWebhook(request: Request, urlPath: string, config: ChannelWebhookConfig): Promise<Response>;
+
+/**
+ * M35 (multi-surface) — the in-process agent-turn seam (Model A).
+ *
+ * The FRAMEWORK-owned sibling of the HTTP `mountAgent` and the stdout `runAgentInTerminal`: it runs a
+ * compiled agent with the SAME `compileAgentModule` + SAME `streamAgentUIMessages` (G2 — reuses the
+ * SDK runtime, reimplements nothing), but returns the raw `UIMessageChunk` generator so ANY consumer
+ * drives it directly — the Ink TUI (M35), a Tauri window (M36), or a test — in a SINGLE process with
+ * NO HTTP loopback, NO port, and NO CSRF (there is no network boundary to defend).
+ *
+ * The ONLY difference from the HTTP mount is HITL resolution: the mount pauses the run and resolves
+ * the approval via a SECOND HTTP request to `/approve/:id` (the approval registry). In-process there
+ * is no second request — the caller resolves the approval INLINE via `awaitApproval` (e.g. the Ink
+ * TUI's y/n prompt). The gated-tool map is `compiled.hitl` verbatim, so the pause semantics are
+ * byte-identical to the HTTP path; only the resolver differs. Parity with the mount is by
+ * construction: both compile the module, resolve function-form skills, and call `streamAgentUIMessages`
+ * with the same `{ message, sessionId, hitl }`.
+ *
+ * Consumers WILL still receive `tool-approval-request` chunks from the returned generator — they are
+ * INFORMATIONAL (render them or ignore them). The authoritative human gate is `awaitApproval`, which
+ * the SDK awaits BEFORE the gated tool runs; the chunk is not the gate.
+ */
+
+/** An inline approval request handed to the caller's `awaitApproval` (the Ink/Tauri prompt). */
+interface InProcessApprovalRequest {
+    approvalId: string;
+    toolName: string;
+    opts: HumanInTheLoopOptions;
+}
+/** Resolve one gated-tool approval inline (approve/deny, or a structured {@link HitlDecision}). */
+type InProcessAwaitApproval = (req: InProcessApprovalRequest) => Promise<boolean | HitlDecision>;
+interface StreamAgentTurnInProcessInput {
+    message: string;
+    /** Resume key; a fresh id per run when omitted. */
+    sessionId?: string;
+    /**
+     * Inline HITL resolver — required IFF the agent has `@HumanInTheLoop`-gated tools. Omitting it for a
+     * gated agent is a fail-fast error, never a silent bypass (Rule 8, the #99 lesson).
+     */
+    awaitApproval?: InProcessAwaitApproval;
+    /** Labels a fail-fast `AgentDefinitionError` (the file path). */
+    source?: string;
+    /** Abort signal forwarded to the SDK stream (client disconnect / window close). */
+    signal?: AbortSignal;
+}
+/** Injectable stream fn (defaults to the real SDK bridge) — lets tests drive a deterministic stream. */
+interface StreamAgentTurnDeps {
+    stream: typeof streamAgentUIMessages;
+}
+/**
+ * Thrown when a gated agent is run in-process without an `awaitApproval` resolver. Refusing loudly is
+ * the correct posture: silently running a `@HumanInTheLoop`-gated tool with no human gate is exactly
+ * the #99 class of bug. Typed so callers can catch it distinctly.
+ */
+declare class InProcessApprovalRequiredError extends Error {
+    constructor(toolNames: readonly string[]);
+}
+/**
+ * Run a compiled agent in-process and return its `UIMessageChunk` stream. `apiKey` is resolved by the
+ * caller (same contract as the HTTP mount). Validation + compile happen SYNCHRONOUSLY (so a gated
+ * agent without a resolver throws at call time, not lazily on first iteration); the returned value is
+ * the SDK's `streamAgentUIMessages` generator.
+ */
+declare function streamAgentTurnInProcess(mod: unknown, apiKey: string, input: StreamAgentTurnInProcessInput, deps?: StreamAgentTurnDeps): AsyncGenerator<UIMessageChunk>;
+
+/**
+ * M30 (ADR-0041) — MCP Apps: `ui://` HTML resources for the MCP server (M16).
+ *
+ * A tool can declare a `ui://` HTML resource; the MCP server advertises it via `resources/list` and
+ * serves the HTML via `resources/read`. The client renders it in a SANDBOXED iframe (see
+ * `mcp-app-host.ts`). Pure data transforms here — no LLM, no runtime (ADR-0040 § D2 home concern).
+ *
+ * Security: only the `ui://` scheme is accepted (an app UI resource), never `http(s)://` — the HTML
+ * is rendered sandboxed on the client, and the scheme gate keeps a tool from smuggling a remote URL
+ * into the app surface.
+ */
+/** A declared `ui://` app resource. */
+interface AppResource {
+    uri: string;
+    name: string;
+    mimeType: 'text/html';
+    html: string;
+    description?: string;
+}
+/** Input to {@link defineAppResource}. */
+interface AppResourceInput {
+    /** MUST start with `ui://`. */
+    uri: string;
+    name: string;
+    html: string;
+    description?: string;
+}
+/** An MCP `resources/list` descriptor (no HTML body — that comes from `resources/read`). */
+interface McpResourceDescriptor {
+    uri: string;
+    name: string;
+    mimeType: 'text/html';
+    description?: string;
+}
+/** An MCP `resources/read` result. */
+interface McpResourceContents {
+    contents: {
+        uri: string;
+        mimeType: 'text/html';
+        text: string;
+    }[];
+}
+/**
+ * Declare a `ui://` HTML app resource. Fails fast if the uri is not a `ui://` scheme or the HTML is
+ * empty (error-handling.md) — a misconfigured resource is caught at definition time.
+ */
+declare function defineAppResource(input: AppResourceInput): AppResource;
+/** Map app resources to MCP `resources/list` descriptors (the HTML body is omitted from the list). */
+declare function buildResourceDescriptors(resources: readonly AppResource[]): McpResourceDescriptor[];
+/** Serve the HTML for `uri` as an MCP `resources/read` result, or `null` when unknown. */
+declare function readAppResource(resources: readonly AppResource[], uri: string): McpResourceContents | null;
+/**
+ * M30 wiring — extract the App resources an agent module declares via a named `appResources` export
+ * (`export const appResources = [defineAppResource(...)]`). Returns only the well-formed entries; a
+ * module without the export (or with a malformed one) yields `[]`. This is how per-agent `ui://`
+ * resources reach the MCP server's `resources/list` + `resources/read` without a runtime dependency
+ * from `@theokit/agents` on this theo-side type (the module exports them; the serving path reads them).
+ */
+declare function extractAppResources(mod: unknown): AppResource[];
+
+/**
+ * MCP stdio transport (M16 follow-up) — expose a TheoKit agent as an MCP server over stdin/stdout,
+ * the sibling of the M16 HTTP route (`POST /api/agents/<name>/mcp`). A desktop MCP client (e.g.
+ * Claude Desktop) spawns `theokit mcp <agent>` and speaks newline-delimited JSON-RPC over the pipe.
+ *
+ * This is a TRANSPORT over the framework's OWN {@link handleMcpJsonRpc} — it reuses the exact handler
+ * the HTTP route uses; it calls no LLM, spawns no MCP client, and reimplements no runtime (G2 /
+ * sdk-runtime.md). Distinct from the SDK's MCP CLIENT stdio (which spawns external MCP servers via
+ * `mcpServers` command/args) — that stays SDK-side. Here TheoKit is the SERVER. The framework-side
+ * placement of this server-exposure transport is recorded in ADR-0042 (refining ADR-0040's M16 note).
+ */
+
+/**
+ * Handle one newline-delimited JSON-RPC line. Returns the response line to write to stdout, or
+ * `null` for a blank line (nothing to emit). A malformed JSON line yields a `-32700` (Parse error)
+ * envelope — never throws, so the stdio loop never dies on bad input.
+ */
+declare function handleMcpStdioLine(line: string, mod: unknown, name: string, appResources?: readonly AppResource[]): Promise<string | null>;
+/** A minimal readable line source (an async iterable of lines) + a writable sink. */
+interface StdioStreams {
+    /** Async iterable of newline-delimited input lines (e.g. `readline.createInterface({ input })`). */
+    lines: AsyncIterable<string>;
+    /** Write a response line (the caller appends no newline). */
+    write: (line: string) => void;
+}
+/**
+ * Drive the MCP stdio server loop: for each input line, dispatch via {@link handleMcpStdioLine} and
+ * write the response line (with a trailing `\n`). Returns when the input stream ends (EOF).
+ */
+declare function serveMcpStdio(mod: unknown, name: string, appResources: readonly AppResource[], streams: StdioStreams): Promise<void>;
+
+export { type AcpToolConfig, type AppResource, type AppResourceInput, type ChannelMessage, type ChannelWebhookConfig, type CodeModeApi, type CodeModeConfig, type CodeModePermission, CodeModePermissionDeniedError, type InProcessApprovalRequest, InProcessApprovalRequiredError, type InProcessAwaitApproval, type McpResourceContents, type McpResourceDescriptor, NodeAcpTransport, type Sandbox, type StdioStreams, type StreamAgentTurnDeps, type StreamAgentTurnInProcessInput, type VendorAgentClient, type VendorAgentToolConfig, type WorkflowLike, type WorkflowToolConfig, buildResourceDescriptors, createACPTool, createCodeMode, createVendorAgentTool, createWorkflowTool, defineAppResource, extractAppResources, handleChannelWebhook, handleMcpStdioLine, isChannelPath, parseChannelPath, readAppResource, serveMcpStdio, streamAgentTurnInProcess };

package/dist/server/agent/index.js

@@ -0,0 +1,43 @@
+import {
+  CodeModePermissionDeniedError,
+  InProcessApprovalRequiredError,
+  NodeAcpTransport,
+  createACPTool,
+  createCodeMode,
+  createVendorAgentTool,
+  createWorkflowTool,
+  handleChannelWebhook,
+  handleMcpStdioLine,
+  isChannelPath,
+  parseChannelPath,
+  serveMcpStdio,
+  streamAgentTurnInProcess
+} from "../../chunk-SPFMJAFW.js";
+import {
+  buildResourceDescriptors,
+  defineAppResource,
+  extractAppResources,
+  readAppResource
+} from "../../chunk-HZ6USUHC.js";
+import "../../chunk-63BUBV5L.js";
+import "../../chunk-DGUM43GV.js";
+export {
+  CodeModePermissionDeniedError,
+  InProcessApprovalRequiredError,
+  NodeAcpTransport,
+  buildResourceDescriptors,
+  createACPTool,
+  createCodeMode,
+  createVendorAgentTool,
+  createWorkflowTool,
+  defineAppResource,
+  extractAppResources,
+  handleChannelWebhook,
+  handleMcpStdioLine,
+  isChannelPath,
+  parseChannelPath,
+  readAppResource,
+  serveMcpStdio,
+  streamAgentTurnInProcess
+};
+//# sourceMappingURL=index.js.map

package/dist/server/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/server/auth/index.js

@@ -24,10 +24,10 @@ import {
   verifyOAuthState,
   verifyTotp
 } from "../../chunk-SJIRP73B.js";
+import "../../chunk-ZJQ4O76G.js";
 import {
   generateNonce
 } from "../../chunk-C3ZZ56YZ.js";
-import "../../chunk-ZJQ4O76G.js";
 import "../../chunk-DGUM43GV.js";
 export {
   AuthRequiredError,

package/dist/server/define/index.d.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import { W as WebSocketHandler, b as WebSocketLike } from '../../define-websocket-CPQcQK9h.js';
 export { a as WebSocketHandlerWeb } from '../../define-websocket-CPQcQK9h.js';
+import { T as ToolTransform, C as CustomTool } from '../../define-agent-tool-ChaGymol.js';
+export { D as DefineAgentToolSpec, a as applyTransform } from '../../define-agent-tool-ChaGymol.js';
 import { f as OnRequestHook, i as PreHandlerHook, g as OnResponseHook, O as OnErrorHook, T as TheoPlugin } from '../../plugin-types-L49QYMb5.js';
 import { UIMessageChunk } from 'ai';
 import { IncomingMessage } from 'node:http';
@@ -95,91 +97,6 @@ interface ActionConfig<TInput extends z.ZodType, TCtx = unknown> {
 
 type MiddlewareHandler = (request: Request, next: (request: Request) => Promise<Response>) => Response | Promise<Response>;
 
-/**
- * Item #4 — `defineAgentTool`
- *
- * Sugar over the `@theokit/sdk` `CustomTool` contract. Takes a Zod schema +
- * handler and produces a structurally-compatible `CustomTool` that
- * `Agent.create({ tools: [...] })` accepts.
- *
- * Uses Zod v4's native `z.toJSONSchema()` to convert the input schema to
- * JSON Schema for LLM providers.
- *
- * Handler error propagation:
- *   `defineAgentTool` parses the input via the Zod schema BEFORE calling the
- *   user handler. Invalid input throws a `ZodError`, which the SDK's tool-
- *   dispatcher treats as a tool failure and surfaces to the model as a tool
- *   error (the SDK owns the wire; ADR D3).
- */
-/**
- * Local mirror of the SDK's `CustomTool` interface. We don't `import type`
- * from `@theokit/sdk` because the SDK is an optional peer (consumers who
- * never call `defineAgentTool` shouldn't need it installed). The shape is
- * the wire contract; any structurally-matching object is accepted by
- * `Agent.create({ tools })`.
- *
- * @public
- */
-interface CustomTool {
-    name: string;
-    description: string;
-    inputSchema: Record<string, unknown>;
-    handler: (input: Record<string, unknown>, ctx?: {
-        signal?: AbortSignal;
-        context?: unknown;
-    }) => string | Promise<string>;
-    /** M18 — optional per-target formatters for the app's UI/transcript (ignored by the SDK wire). */
-    transform?: ToolTransform;
-}
-/**
- * M18 — per-target formatters. `display` shapes the rich handler result for the UI; `transcript`
- * shapes it for a saved transcript. Applied by {@link applyTransform}, never by the model wire.
- */
-interface ToolTransform<R = unknown> {
-    display?: (result: R) => unknown;
-    transcript?: (result: R) => unknown;
-}
-/**
- * Spec accepted by {@link defineAgentTool}. `inputSchema` is a Zod 3 schema
- * rooted in `z.object(...)`. The `handler` argument type is inferred via
- * `z.infer<T>`.
- *
- * @public
- */
-interface DefineAgentToolSpec<T extends z.ZodType, R = string> {
-    /** Tool name surfaced to the LLM. Must match `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`. */
-    name: string;
-    /** Description surfaced to the LLM. Required — drives tool-selection accuracy. */
-    description: string;
-    /** Zod schema describing the input. Must be `z.object(...)` at the root. */
-    inputSchema: T;
-    /**
-     * Handler invoked with the parsed input and, optionally, the run `ctx` (M7). `ctx.context`
-     * is the object supplied once at the agent level (`defineAgent({ context })`) or per-run —
-     * read it for shared config like `projectRoot` instead of baking it into the factory.
-     * `ctx.signal` is the abort signal. Optional so existing one-arg handlers keep working.
-     *
-     * M18 — the handler may return RICH data `R` (not just a string) when `toModelOutput` is
-     * provided to map it to the model-visible string.
-     */
-    handler: (input: z.infer<T>, ctx?: {
-        signal?: AbortSignal;
-        context?: unknown;
-    }) => R | Promise<R>;
-    /**
-     * M18 — map the rich handler result `R` to the string the model sees. Required (in practice)
-     * when `handler` returns a non-string; absent ⇒ the handler must return a string.
-     */
-    toModelOutput?: (result: R) => string;
-    /** M18 — per-target formatters (`display` / `transcript`) for the app, applied by {@link applyTransform}. */
-    transform?: ToolTransform<R>;
-}
-/**
- * M18 — apply a tool's `transform` for a target (`display` / `transcript`). Returns the formatted
- * value, or the raw `result` when the tool declares no transform for that target.
- */
-declare function applyTransform(tool: CustomTool, result: unknown, target: 'display' | 'transcript'): unknown;
-
 /**
  * M31 Phase 3 — `route()`, the fluent builder that replaces `defineRoute({...})`.
  *
@@ -492,4 +409,4 @@ interface WebChannelHandler<TMessage = unknown> {
  */
 declare function defineWebChannel<TMessage = unknown>(handler: WebChannelHandler<TMessage>): WebChannelHandler<TMessage>;
 
-export { type ActionAccept, type ActionBuilder, type ActionConfig, type ChannelHandler, type CustomTool, type DefineAgentToolSpec, type MiddlewareBuilder, type MiddlewareHandler, type PluginBuilder, type RouteBuilder, type RouteConfig, type ToolBuilder, type ToolTransform, type WebChannelHandler, type WebSocketBuilder, WebSocketHandler, WebSocketLike, action, applyTransform, defineChannel, defineWebChannel, middleware, plugin, route, tool, uiMessageStreamResponse, websocket };
+export { type ActionAccept, type ActionBuilder, type ActionConfig, type ChannelHandler, CustomTool, type MiddlewareBuilder, type MiddlewareHandler, type PluginBuilder, type RouteBuilder, type RouteConfig, type ToolBuilder, ToolTransform, type WebChannelHandler, type WebSocketBuilder, WebSocketHandler, WebSocketLike, action, defineChannel, defineWebChannel, middleware, plugin, route, tool, uiMessageStreamResponse, websocket };

package/dist/server/define/index.js

@@ -1,6 +1,5 @@
 import {
   action,
-  applyTransform,
   defineChannel,
   defineWebChannel,
   middleware,
@@ -9,7 +8,7 @@ import {
   tool,
   uiMessageStreamResponse,
   websocket
-} from "../../chunk-DMGVH3VG.js";
+} from "../../chunk-V3X5FWJA.js";
 import {
   HEALTH_PATH,
   READY_PATH,
@@ -17,6 +16,9 @@ import {
   defineReadyRoute,
   serveReservedRoute
 } from "../../chunk-V3LJN2GS.js";
+import {
+  applyTransform
+} from "../../chunk-63BUBV5L.js";
 import "../../chunk-DGUM43GV.js";
 export {
   HEALTH_PATH,