theokit 0.12.0 → 0.13.0

package/dist/chunk-ZSTZXR2D.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/define/define-route.ts","../src/server/define/define-action.ts","../src/server/define/define-middleware.ts","../src/server/define/define-agent-endpoint.ts","../src/server/define/define-agent-tool.ts","../src/server/define/define-websocket.ts","../src/server/define/define-channel.ts","../src/server/define/define-plugin.ts"],"sourcesContent":["import type { z } from 'zod'\n\n// T2.2 (architecture-cleanup) — RouteConfig type moved to core/contracts/\n// (canonical home per ADR-0001 v3). Re-export preserves the public path\n// `import { type RouteConfig } from 'theokit/server'`.\nexport type { RouteConfig } from '../../core/contracts/route-config.js'\n\nimport type { RouteConfig } from '../../core/contracts/route-config.js'\n\n/**\n * Define a typed HTTP route.\n * Identity function — provides type inference for route handlers.\n */\nexport function defineRoute<\n  TQuery extends z.ZodType = z.ZodUndefined,\n  TBody extends z.ZodType = z.ZodUndefined,\n  TParams extends z.ZodType = z.ZodUndefined,\n  TCtx = unknown,\n  TResponse = unknown,\n>(\n  config: RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>,\n): RouteConfig<TQuery, TBody, TParams, TCtx, TResponse> {\n  return config\n}\n","import type { z } from 'zod'\n\n/**\n * Action wire-protocol accept mode per plan g3-server-actions-and-useaction\n * v1.2 ADR D1. Default behavior (when omitted) is `'json'`. `'form'` opts the\n * action into FormData multipart parsing for progressive-enhancement forms;\n * the runtime in `server/http/action-execute.ts` will coerce FormData entries\n * against the `input` schema via `formDataToObject` (Astro pattern).\n */\nexport type ActionAccept = 'form' | 'json'\n\nexport interface ActionConfig<TInput extends z.ZodType, TCtx = unknown> {\n  /**\n   * Zod input schema. Required: every action declares its input contract via\n   * Zod (architecture rule: zod-is-SSOT). The shape becomes the handler's\n   * typed `input` parameter via `z.infer<TInput>`.\n   */\n  input: TInput\n  /**\n   * Wire-protocol accept mode. Defaults to `'json'` when omitted. Setting\n   * `'form'` switches the runtime to FormData multipart parsing — the input\n   * schema MUST be `z.object(...)` so field-by-field coercion can drive\n   * boolean string / number / array coercion (Astro pattern).\n   */\n  accept?: ActionAccept\n  /**\n   * Opt OUT of CSRF enforcement for this action. Default (omitted) keeps the\n   * multi-header CSRF gate active. Set `false` for endpoints intentionally\n   * callable without the `X-Theo-Action` header (e.g. public webhooks). The\n   * runtime in `server/http/action-execute.ts` reads this flag.\n   */\n  csrf?: false\n  handler: (ctx: { input: z.infer<TInput>; ctx: TCtx }) => unknown\n}\n\n/**\n * Define a typed server action.\n *\n * Identity function — provides type inference for action handlers. The\n * runtime that consumes the config (validation + invocation + serialization)\n * lives in `server/http/action-execute.ts`.\n *\n * Per plan g3-server-actions-and-useaction v1.2 § Phase 1 / T1.2: the new\n * `accept?: 'form' | 'json'` field is the only contract change vs the\n * pre-G3 identity. Existing callsites (`defineAction({input, handler})`)\n * continue to compile — `accept` is opt-in.\n */\nexport function defineAction<TInput extends z.ZodType, TCtx = unknown>(\n  config: ActionConfig<TInput, TCtx>,\n): ActionConfig<TInput, TCtx> {\n  return config\n}\n","export type MiddlewareHandler = (\n  request: Request,\n  next: (request: Request) => Promise<Response>,\n) => Response | Promise<Response>\n\n/**\n * Define a middleware handler.\n * Identity function — provides type annotation for middleware.\n */\nexport function defineMiddleware(handler: MiddlewareHandler): MiddlewareHandler {\n  return handler\n}\n","import type { z } from 'zod'\n\nimport type { AgentEvent } from '../agent/agent-types.js'\n\nimport type { RouteConfig } from './define-route.js'\n\n/**\n * T5.1 — defineAgentEndpoint\n *\n * Sugar over defineRoute (ADR D4). Accepts an async generator that yields\n * AgentEvents and produces a RouteConfig whose handler returns a Response\n * streaming Server-Sent Events (SSE).\n *\n * Wire format: `data: <JSON>\\n\\n` per event. Standards-compliant.\n *\n * The generator may throw — the wrapper catches and emits a final\n * `{ type: 'error', message }` event before closing the stream.\n *\n * The wrapper observes `request.signal` (EC-7) — when aborted, the\n * underlying generator is told to `return()` and the stream closes\n * promptly.\n *\n * Note (EC-12, Out of Scope): SSE backpressure (slow consumer) is not\n * handled here. For high-frequency token streaming consider a different\n * transport (WS) or a buffer policy. This MVP enqueues each event\n * immediately.\n */\n\nexport interface AgentEndpointHandlerArgs<\n  TCtx = unknown,\n  TBody = unknown,\n  TParams extends z.ZodType = z.ZodUndefined,\n> {\n  query: undefined\n  body: TBody\n  params: z.infer<TParams>\n  request: Request\n  ctx: TCtx\n  /**\n   * Mutable headers bag that the wrapper merges into the SSE response BEFORE\n   * the stream starts. Used by `createConversationHistory` to issue a\n   * conversation-id cookie on first request. Append entries via\n   * `cookieHeaders.append('set-cookie', '<cookie-string>')`.\n   *\n   * Cookies appended AFTER the first yield are NOT applied — the response\n   * headers commit when the wrapper constructs the Response, before the\n   * async generator runs. This is per HTTP semantics, not a wrapper choice.\n   */\n  cookieHeaders: Headers\n  /**\n   * Phase 3 (Production-Readiness #5) — request abort signal.\n   *\n   * Fires when the SSE client disconnects (browser closes tab, abort fetch,\n   * etc.). Thread this to `agent.send(msg, { signal })` so the SDK cancels\n   * the in-flight provider call — STOPS TOKENS FROM CHARGING for output\n   * the user will never receive.\n   *\n   * EC-1 (MUST FIX): the signal is derived via duck-type detection\n   * (`'aborted' in r.signal && typeof r.signal.addEventListener === 'function'`)\n   * to survive cross-realm scenarios (Node 18 polyfills, undici, Edge\n   * runtimes with their own AbortSignal globals). `instanceof AbortSignal`\n   * would fail in those cases.\n   */\n  signal: AbortSignal\n}\n\nexport interface AgentEndpointConfig<\n  TCtx = unknown,\n  TBody = unknown,\n  TParams extends z.ZodType = z.ZodUndefined,\n> {\n  /**\n   * Optional Zod schema for path params (e.g. `z.object({ id: z.string() })`).\n   * When present, the runner validates path params and returns 400 on mismatch\n   * BEFORE the generator runs; the validated params are threaded to the\n   * generator typed as `z.infer<TParams>` (D4).\n   */\n  params?: TParams\n  handler: (\n    args: AgentEndpointHandlerArgs<TCtx, TBody, TParams>,\n  ) => AsyncGenerator<AgentEvent, void, unknown>\n}\n\nconst SSE_HEADERS = {\n  'content-type': 'text/event-stream',\n  'cache-control': 'no-cache, no-transform',\n  connection: 'keep-alive',\n} as const\n\nfunction encodeSSE(event: AgentEvent): Uint8Array {\n  return new TextEncoder().encode(`data: ${JSON.stringify(event)}\\n\\n`)\n}\n\n/**\n * Resolve an AbortSignal from either a Web `Request` (`.signal`) or a\n * Node `IncomingMessage` (`.socket` close + `'aborted'`/'close' events).\n *\n * The framework's `executeRoute` passes IncomingMessage to route handlers\n * today, but `defineAgentEndpoint` was designed for the Web Standards\n * `Request` shape. This helper bridges both — preventing a runtime crash\n * (`Cannot read properties of undefined (reading 'aborted')`) that would\n * otherwise abort the SSE stream silently before the first yield.\n *\n * Node ≥23 regression (empty-SSE-stream): Node 23 added\n * `http.IncomingMessage.prototype.signal` — a Web `AbortSignal` that fires\n * `abort` the instant the request body is fully received (`req.complete ===\n * true`), NOT when the client disconnects. The earlier duck-type\n * (\"has `.signal` with `aborted` + `addEventListener`\") matched a genuine Web\n * `Request` AND, on Node ≥23, the Node `IncomingMessage` — so the helper\n * returned the request-lifecycle signal, already aborted by the time the\n * handler primes, and EVERY agent stream produced 0 bytes on Node 24.\n *\n * Discriminator: a Node `IncomingMessage` is an `EventEmitter` (`typeof\n * r.on === 'function'`); a Web `Request` is not. So `r.signal` is trusted\n * directly ONLY when this is not a Node request. For the Node path the only\n * lifecycle event that means \"client disconnected\" (rather than \"request body\n * finished\") is the underlying SOCKET closing — `req`'s own `.signal`/`'close'`\n * fire at body-end on Node ≥23 and would kill a long-lived SSE response.\n */\nfunction resolveAbortSignal(request: unknown): AbortSignal {\n  if (typeof request !== 'object' || request === null) {\n    return new AbortController().signal\n  }\n  const r = request as {\n    signal?: unknown\n    aborted?: boolean\n    complete?: boolean\n    on?: (event: string, cb: () => void) => void\n    socket?: { on?: (event: string, cb: () => void) => void }\n  }\n\n  // A genuine Web `Request` exposes `.signal` and is NOT a Node EventEmitter.\n  const isNodeRequest = typeof r.on === 'function'\n  if (\n    !isNodeRequest &&\n    typeof r.signal === 'object' &&\n    r.signal !== null &&\n    'aborted' in r.signal &&\n    typeof (r.signal as AbortSignal).addEventListener === 'function'\n  ) {\n    return r.signal as AbortSignal\n  }\n\n  const controller = new AbortController()\n  const abort = () => {\n    if (!controller.signal.aborted) controller.abort()\n  }\n  if (r.aborted === true) controller.abort()\n  if (typeof r.on === 'function') {\n    // Explicit client abort (request reset mid-flight).\n    r.on('aborted', abort)\n    // `req`'s own 'close' fires at request-completion on Node ≥23 (body fully\n    // received), which is NOT a disconnect — guard with `complete`. A close\n    // while the request already completed normally is body-end noise.\n    r.on('close', () => {\n      if (r.complete !== true) abort()\n    })\n  }\n  // The underlying socket closes only on real connection teardown (client\n  // gone), never at request-body-end — the correct disconnect signal for a\n  // long-lived SSE response.\n  const socket = r.socket\n  if (socket && typeof socket.on === 'function') {\n    socket.on('close', abort)\n  }\n  return controller.signal\n}\n\nexport function defineAgentEndpoint<\n  TBody = unknown,\n  TCtx = unknown,\n  TParams extends z.ZodType = z.ZodUndefined,\n>(\n  config: AgentEndpointConfig<TCtx, TBody, TParams>,\n): RouteConfig<z.ZodUndefined, z.ZodUndefined, TParams, TCtx, Response> {\n  return {\n    params: config.params,\n    handler: async ({ request, ctx, body, query, params }) => {\n      const cookieHeaders = new Headers()\n      const signal = resolveAbortSignal(request)\n      const generator = config.handler({\n        request,\n        ctx: ctx,\n        body: body as TBody,\n        query: query,\n        params: params,\n        cookieHeaders,\n        signal,\n      })\n\n      // Prime the generator to its first yield. This forces the handler's\n      // synchronous + async setup (including `createConversationHistory` if\n      // used) to run BEFORE the Response headers commit, so any Set-Cookie\n      // lines appended to `cookieHeaders` land in the actual response.\n      //\n      // First-byte latency cost: bounded by the work up to the first yield\n      // (typically 100-500ms for an LLM chat with `agent.send`). Acceptable\n      // for the use case; alternative (heuristic detection of cookie writes)\n      // is brittle.\n      let firstResult: IteratorResult<AgentEvent, void>\n      let primeError: unknown\n      try {\n        firstResult = await generator.next()\n      } catch (err) {\n        primeError = err\n        firstResult = { value: undefined, done: true }\n      }\n\n      // Merge any cookies the handler issued into the response headers.\n      const responseHeaders = new Headers(SSE_HEADERS)\n      for (const value of cookieHeaders.getSetCookie()) {\n        responseHeaders.append('set-cookie', value)\n      }\n\n      const stream = new ReadableStream<Uint8Array>({\n        async start(controller) {\n          const onAbort = () => {\n            void generator.return(undefined)\n          }\n\n          if (signal.aborted) {\n            controller.close()\n            return\n          }\n          signal.addEventListener('abort', onAbort, { once: true })\n\n          try {\n            // If priming threw, yield a final error event and close.\n            if (primeError !== undefined) {\n              let message: string\n              if (primeError instanceof Error) {\n                message = primeError.message\n              } else if (typeof primeError === 'string') {\n                message = primeError\n              } else {\n                message = 'agent handler failed during setup'\n              }\n              controller.enqueue(encodeSSE({ type: 'error', message }))\n              return\n            }\n            // Enqueue the primed first value (if any).\n            if (firstResult.done !== true) {\n              controller.enqueue(encodeSSE(firstResult.value))\n            } else {\n              return\n            }\n            // Continue iterating remaining events.\n            for await (const event of generator) {\n              // `signal.aborted` can flip true asynchronously via the\n              // listener registered above. ESLint's narrowing only sees\n              // the false assertion at line 114; the dynamic abort is\n              // legitimate and the guard prevents enqueue-after-close.\n              // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n              if (signal.aborted) break\n              controller.enqueue(encodeSSE(event))\n            }\n          } catch (err) {\n            const message = err instanceof Error ? err.message : String(err)\n            controller.enqueue(encodeSSE({ type: 'error', message }))\n          } finally {\n            signal.removeEventListener('abort', onAbort)\n            controller.close()\n          }\n        },\n        cancel() {\n          void generator.return(undefined)\n        },\n      })\n\n      return new Response(stream, { headers: responseHeaders })\n    },\n  }\n}\n","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 (or the `streamAgentRun` adapter) sees as a tool failure and\n *   surfaces as an `error` AgentEvent on the SSE 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: (input: Record<string, unknown>) => string | Promise<string>\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> {\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  /** Handler invoked with the parsed input. */\n  handler: (input: z.infer<T>) => string | Promise<string>\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>(spec: DefineAgentToolSpec<T>): 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 (input: Record<string, unknown>): Promise<string> => {\n      const parsed = spec.inputSchema.parse(input)\n      return await spec.handler(parsed)\n    },\n  }\n}\n","import type { IncomingMessage } from 'node:http'\n\nexport interface WebSocketLike {\n  send(data: string | Buffer): void\n  close(code?: number, reason?: string): void\n}\n\nexport interface WebSocketHandler {\n  onOpen?: (ws: WebSocketLike, req: IncomingMessage) => void\n  onMessage?: (ws: WebSocketLike, data: string | Buffer) => void\n  onClose?: (ws: WebSocketLike, code: number, reason: Buffer) => void\n  onError?: (ws: WebSocketLike, error: Error) => void\n}\n\n/**\n * Define a WebSocket endpoint handler.\n * Identity function — provides type inference for WebSocket handlers.\n */\nexport function defineWebSocket(handler: WebSocketHandler): WebSocketHandler {\n  return handler\n}\n\n/**\n * T5a.2 Phase F slice 3/3 — Web-Standards WebSocket endpoint handler.\n *\n * Mirror of `WebSocketHandler` for the Web `Request` shape. `onOpen`\n * receives `request: Request` instead of `req: IncomingMessage`. The\n * rest of the lifecycle (onMessage, onClose, onError) is shape-agnostic\n * (`WebSocketLike` is already Web-standards-compatible per the existing\n * design — `send(string | Buffer)` works on both Node `ws` and Web\n * `WebSocket` instances; CF Workers / Bun / Deno coerce as needed at\n * the adapter boundary).\n *\n * Per `docs/plans/t5a2-incoming-message-to-request-shape-refactor-plan.md`\n * v1.0 § Phase F (closes Phase F).\n *\n * **Architectural note — WebSocket upgrade semantics differ across runtimes:**\n *   - Node + `ws`: `WebSocketServer.handleUpgrade(req, socket, head, cb)` —\n *     `req` is `IncomingMessage`. Use `WebSocketHandler`.\n *   - CF Workers: `new WebSocketPair()` + `request.headers` (the upgrade\n *     handshake IS a Web Request). Use `WebSocketHandlerWeb`.\n *   - Bun: `server.upgrade(request, { data })` — same Web Request shape.\n *   - Deno: `Deno.upgradeWebSocket(request)` — same Web Request shape.\n *\n * Cross-runtime WebSocket endpoints ship BOTH `WebSocketHandler` +\n * `WebSocketHandlerWeb` exports; the runtime adapter picks the matching\n * one. This is the canonical Hono / Nitric pattern.\n */\nexport interface WebSocketHandlerWeb {\n  onOpen?: (ws: WebSocketLike, request: Request) => void\n  onMessage?: (ws: WebSocketLike, data: string | Uint8Array) => void\n  onClose?: (ws: WebSocketLike, code: number, reason: string) => void\n  onError?: (ws: WebSocketLike, error: Error) => void\n}\n\n/**\n * Web-Standards `defineWebSocket` sibling. Identity function — provides\n * type inference for Web WebSocket handlers.\n *\n * **Type difference note vs Node path:**\n *   - `onMessage` data is `string | Uint8Array` instead of `string | Buffer`\n *     (Web standards have no `Buffer`; Node's Buffer is a Uint8Array\n *     subclass so the Node path's Buffer values flow through unchanged\n *     when adapters wrap them).\n *   - `onClose` reason is `string` instead of `Buffer` (Web `CloseEvent`\n *     exposes the reason as a UTF-8 string natively).\n */\nexport function defineWebSocketWeb(handler: WebSocketHandlerWeb): WebSocketHandlerWeb {\n  return handler\n}\n","import type { IncomingMessage } from 'node:http'\n\nimport type { WebSocketLike } from './define-websocket.js'\n\nexport interface ChannelHandler<TMessage = unknown> {\n  onSubscribe?: (ws: WebSocketLike, room: string, req: IncomingMessage) => void\n  onMessage?: (ws: WebSocketLike, room: string, data: TMessage) => void\n  onUnsubscribe?: (ws: WebSocketLike, room: string) => void\n}\n\n/**\n * Define a channel handler for WebSocket rooms.\n * Identity function — provides type inference for channel handlers.\n */\nexport function defineChannel<TMessage = unknown>(\n  handler: ChannelHandler<TMessage>,\n): ChannelHandler<TMessage> {\n  return handler\n}\n\n/**\n * T5a.2 Phase F slice 2/3 — Web-Standards channel handler.\n *\n * Mirror of `ChannelHandler<TMessage>` for the Web `Request` shape.\n * `onSubscribe` receives `request: Request` instead of `req: IncomingMessage`\n * — the rest of the surface (onMessage, onUnsubscribe) is shape-agnostic\n * (WebSocketLike is already Web-standards-compatible per `define-websocket.ts`).\n *\n * Per `docs/plans/t5a2-incoming-message-to-request-shape-refactor-plan.md`\n * v1.0 § Phase F.\n *\n * **Architectural note:** WebSocket upgrade semantics differ across\n * runtimes:\n *   - Node: `WebSocketServer.handleUpgrade(req, socket, head, cb)` —\n *     hands you `req: IncomingMessage` at the upgrade handshake.\n *   - CF Workers: `new WebSocketPair()` + `request.headers` (the upgrade\n *     handshake IS a Web Request) — hands you `request: Request`.\n *   - Bun: `server.upgrade(request, { data })` — same Web Request shape.\n *   - Deno: `Deno.upgradeWebSocket(request)` — same Web Request shape.\n *\n * Channel handlers targeting CF/Bun/Deno use `WebChannelHandler`; legacy\n * Node consumers stay on `ChannelHandler`. Cross-runtime channels ship\n * both shapes.\n */\nexport interface WebChannelHandler<TMessage = unknown> {\n  onSubscribe?: (ws: WebSocketLike, room: string, request: Request) => void\n  onMessage?: (ws: WebSocketLike, room: string, data: TMessage) => void\n  onUnsubscribe?: (ws: WebSocketLike, room: string) => void\n}\n\n/**\n * Web-Standards `defineChannel` sibling. Identity function — provides\n * type inference for Web channel handlers.\n */\nexport function defineWebChannel<TMessage = unknown>(\n  handler: WebChannelHandler<TMessage>,\n): WebChannelHandler<TMessage> {\n  return handler\n}\n","import type { TheoPlugin } from '../plugin-types.js'\n\n/**\n * Identity function for defining a Theo plugin.\n *\n * **Note:** Prefer `definePlugin` (shorter, canonical name per ADR-0008 D6).\n * Both functions are identical — `defineTheoPlugin` is kept as an alias for\n * existing in-tree consumers without forcing a migration sweep.\n */\nexport function defineTheoPlugin(plugin: TheoPlugin): TheoPlugin {\n  return plugin\n}\n"],"mappings":"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","names":[]}

package/dist/cli/index.js

@@ -5,12 +5,12 @@ import "tsx/esm";
 import cac from "cac";
 var cli = cac("theokit");
 cli.command("dev", "Start development server").option("--port <port>", "Port number").action(async (options) => {
-  const { devCommand } = await import("../dev-GBXOTXUP.js");
+  const { devCommand } = await import("../dev-OWW4XVIH.js");
   await devCommand({ port: options.port ? Number(options.port) : void 0 });
 });
 cli.command("build", "Build for production").option("--target <target>", "Deploy target (node, vercel, cloudflare)").action(async (options) => {
   try {
-    const { buildCommand } = await import("../build-QFRLSEZ4.js");
+    const { buildCommand } = await import("../build-HXND27XG.js");
     await buildCommand({ target: options.target });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -22,7 +22,7 @@ cli.command("build", "Build for production").option("--target <target>", "Deploy
 });
 cli.command("start", "Start production server").option("--port <port>", "Port number").action(async (options) => {
   try {
-    const { startCommand } = await import("../start-3ZHAXSJE.js");
+    const { startCommand } = await import("../start-KIQ5TTLR.js");
     await startCommand({ port: options.port ? Number(options.port) : void 0 });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -49,7 +49,7 @@ cli.command(
 });
 cli.command("routes", "List all routes, actions, and WebSocket endpoints").action(async () => {
   try {
-    const { routesCommand } = await import("../routes-LRYOIIAI.js");
+    const { routesCommand } = await import("../routes-EW7TP7NJ.js");
     await routesCommand();
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -98,7 +98,7 @@ cli.command(
   "Generate <distDir>/openapi.json from route schemas (opt-in via config.openapi)"
 ).option("--dry-run", "Print the document to stdout without writing to disk (EC-3)").action(async (options) => {
   try {
-    const { openapiCommand } = await import("../openapi-VR6AFBLJ.js");
+    const { openapiCommand } = await import("../openapi-FHY6HC6I.js");
     await openapiCommand({ dryRun: Boolean(options.dryRun) });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);

package/dist/client/index.d.ts

@@ -0,0 +1,418 @@
+import { z } from 'zod';
+import { T as TheoErrorEnvelope } from '../error-envelope-BsNzzAV5.js';
+export { FetchOptionsLike, Fetcher, QueryKey, UseTheoQueryConfig, buildUseTheoQueryConfig, stableQueryKey } from '../react-query/index.js';
+import { A as AgentEvent, a as AgentErrorEvent } from '../agent-events-DosDXkSV.js';
+export { b as AgentMessageEvent, c as AgentThinkingEvent, d as AgentToolCallEvent, e as AgentToolResultEvent } from '../agent-events-DosDXkSV.js';
+import { UIMessage } from 'ai';
+import * as react from 'react';
+import { LinkProps as LinkProps$1 } from 'react-router';
+
+/** Infer the response type from a route's handler return */
+type InferResponse<T> = T extends {
+    handler: (...args: never[]) => infer R;
+} ? Awaited<R> : unknown;
+/** Extract the query Zod schema type, handling optional properties */
+type ExtractQuery<T> = T extends {
+    query?: infer Q;
+} ? (Q extends z.ZodType ? Q : never) : never;
+/** Extract the body Zod schema type, handling optional properties */
+type ExtractBody<T> = T extends {
+    body?: infer B;
+} ? (B extends z.ZodType ? B : never) : never;
+/** Infer query type from a route's query Zod schema */
+type InferQuery<T> = [ExtractQuery<T>] extends [never] ? undefined : ExtractQuery<T> extends z.ZodUndefined ? undefined : z.infer<ExtractQuery<T>>;
+/** Infer body type from a route's body Zod schema */
+type InferBody<T> = [ExtractBody<T>] extends [never] ? undefined : ExtractBody<T> extends z.ZodUndefined ? undefined : z.infer<ExtractBody<T>>;
+/** Build the options type based on what schemas the route has */
+type TheoFetchOptions<T> = Omit<RequestInit, 'body' | 'method'> & (InferQuery<T> extends undefined ? {
+    query?: never;
+} : {
+    query: InferQuery<T>;
+}) & (InferBody<T> extends undefined ? {
+    body?: never;
+} : {
+    body: InferBody<T>;
+});
+declare class TheoFetchError extends Error {
+    status: number;
+    code?: string;
+    issues?: unknown[];
+    /**
+     * G5 T2.1 — canonical envelope view of the server-side error. Use this in
+     * consumer code that wants to switch on a typed TheoErrorCode instead of
+     * coupling to the legacy `.status` / `.code` flat fields.
+     */
+    readonly envelope: TheoErrorEnvelope;
+    constructor(status: number, body?: unknown);
+}
+declare function theoFetch<T>(url: string, options?: TheoFetchOptions<T>): Promise<InferResponse<T>>;
+
+/**
+ * Phase 3 of G1 (g1-client-codegen-plan.md):
+ *
+ * `createAppClient(baseUrl?, fetchImpl?)` returns a Proxy that walks property
+ * access (`client.posts.id.get(...)`) into a `theoFetch` invocation against
+ * `{baseUrl}/posts/{params.id}` with method `GET`.
+ *
+ * Type safety is delivered by the `.d.ts` file emitted in Phase 2 — this
+ * runtime is structurally untyped. Power users may use `theoFetch` directly
+ * when they need to escape the Proxy facade.
+ *
+ * Edge cases absorbed:
+ *  - EC-1 (thenable trap): `then` / `catch` / `finally` / `toJSON` / `Symbol.*`
+ *    return `undefined` so that accidental `await client.posts` resolves to a
+ *    plain Proxy value (it is NOT thenable) instead of looping.
+ *  - EC-7 (abort signal): `opts.signal` is spread through to the underlying
+ *    fetchImpl unchanged — verified in unit tests.
+ *
+ * Bundle target: ≤ 2KB gzipped.
+ */
+
+type FetchImpl = typeof theoFetch;
+interface CreateAppClientOptions {
+    /** Base URL for the API. Defaults to `/api`. */
+    baseUrl?: string;
+    /** Test-only fetch override. Production callers should not pass this. */
+    fetchImpl?: FetchImpl;
+}
+declare function createAppClient<TAppClient = unknown>(baseUrlOrOptions?: string | CreateAppClientOptions, legacyFetchImpl?: FetchImpl): TAppClient;
+
+/**
+ * T5.1 — client-side microtask batching.
+ *
+ * Collects all `dispatch` calls within the same microtask and sends them as a
+ * single HTTP POST to the configured transport. Each caller's promise resolves
+ * with its own result; one failed item does not break the others (per-item
+ * error isolation).
+ *
+ * Designed as a transport-agnostic primitive so unit tests do not require
+ * network access. The default transport (fetch to `/api/__theo_batch__`)
+ * lives alongside this module but is created by the consumer (e.g., theoFetch).
+ */
+interface BatchRequest {
+    path: string;
+    method: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+type BatchResponse = {
+    index: number;
+    data: unknown;
+} | {
+    index: number;
+    error: {
+        message: string;
+        code?: string;
+    };
+};
+type BatchTransport = (requests: BatchRequest[]) => Promise<BatchResponse[]>;
+interface BatcherOptions {
+    transport: BatchTransport;
+    /** Maximum batch size before flushing into multiple parallel batches. */
+    max?: number;
+}
+interface Batcher {
+    dispatch(req: BatchRequest): Promise<unknown>;
+}
+declare function createBatcher(options: BatcherOptions): Batcher;
+
+/**
+ * Accumulated assistant text (M5-1): the concatenation of every `message`
+ * event's `content`. Pure. Assumes append/delta semantics — a server that
+ * emits full-snapshot messages should read `events` directly.
+ */
+declare function deriveLiveText(events: readonly AgentEvent[]): string;
+/**
+ * The current error (M5-1): the last `error` event, or `undefined`. Surfaces
+ * the full `AgentErrorEvent` (with `code`/`retriable`) so the UI can branch.
+ * Pure.
+ */
+declare function deriveError(events: readonly AgentEvent[]): AgentErrorEvent | undefined;
+/**
+ * T5.2 — useAgentStream
+ *
+ * React hook to consume an agent endpoint defined with `defineAgentEndpoint`.
+ *
+ * Transport (ADR D7, EC-3): fetch + ReadableStream — NOT EventSource.
+ * EventSource is GET-only; agent endpoints need POST + body.
+ *
+ * Returns:
+ *   events  — array of AgentEvents accumulated so far
+ *   send    — call with a payload to (re)open a stream
+ *   status  — 'idle' | 'streaming' | 'done' | 'error'
+ *   abort   — manually cancel an in-flight stream
+ *
+ * Cleanup (EC-8): on unmount, the current AbortController fires .abort(),
+ * which propagates to the underlying fetch and the ReadableStream reader.
+ * Safe under React.StrictMode double-mount.
+ */
+type AgentStreamStatus = 'idle' | 'streaming' | 'done' | 'error';
+interface UseAgentStreamReturn<TBody = unknown> {
+    events: AgentEvent[];
+    status: AgentStreamStatus;
+    /** Accumulated assistant text — concatenation of all `message` contents (M5-1). */
+    liveText: string;
+    /** The last `error` event, or `undefined` (M5-1). */
+    error: AgentErrorEvent | undefined;
+    send: (body: TBody) => void;
+    abort: () => void;
+    reset: () => void;
+}
+interface UseAgentStreamOptions {
+    /** Extra headers (e.g., auth). */
+    headers?: Record<string, string>;
+    /** Override fetch (rare — primarily for tests). */
+    fetch?: typeof fetch;
+}
+declare function useAgentStream<TBody = unknown>(path: string, options?: UseAgentStreamOptions): UseAgentStreamReturn<TBody>;
+
+/**
+ * A correlated, UI-facing view of one tool invocation (M5-2).
+ *
+ * `foldAgentToolCards` correlates a `tool_call` with its `tool_result` (by
+ * `id`, falling back to FIFO-by-name) into a single card so consumers stop
+ * hand-rolling `switch(event.type)`.
+ */
+interface AgentToolCard {
+    /** Correlation id (the event `id`, or a synthesized `tool-<index>`). */
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    status: 'running' | 'success' | 'error';
+    /** The `tool_result.data` payload, once the result arrives. */
+    result?: unknown;
+}
+/**
+ * Classifies a `tool_result.data` payload as success/error. Injectable so the
+ * correlator is decoupled from any specific tool-result envelope shape.
+ */
+type ToolEnvelopeResolver = (data: unknown) => {
+    error: boolean;
+};
+interface FoldAgentToolCardsOptions {
+    /** Override the default envelope classifier. */
+    resolveEnvelope?: ToolEnvelopeResolver;
+}
+/**
+ * Default envelope resolver: an object (or a JSON STRING parsing to an object)
+ * with `ok === false` is an error; everything else is success (conservative).
+ * sdk-tools handlers return a JSON STRING, so string parsing is intentional.
+ */
+declare function defaultResolveEnvelope(data: unknown): {
+    error: boolean;
+};
+/**
+ * Fold an `AgentEvent[]` into correlated {@link AgentToolCard}s (M5-2). Pure.
+ *
+ * Correlation: a `tool_result` matches its `tool_call` by `id` when both carry
+ * one; otherwise it matches the oldest still-`running` card with the same
+ * `name` (FIFO). An unmatched `tool_result` becomes its own finished card.
+ * A `tool_call` with no result stays `running`. The error status comes from
+ * `options.resolveEnvelope` (default {@link defaultResolveEnvelope}).
+ */
+declare function foldAgentToolCards(events: readonly AgentEvent[], options?: FoldAgentToolCardsOptions): AgentToolCard[];
+
+/** {@link useAgentToolCards} return — the stream result plus correlated tool cards. */
+interface UseAgentToolCardsReturn<TBody = unknown> extends UseAgentStreamReturn<TBody> {
+    /** Correlated tool cards folded from the stream events (M5-2). */
+    toolCards: AgentToolCard[];
+}
+/**
+ * `useAgentStream` + correlated tool cards (M5-2). Composes the stream hook with
+ * the pure {@link foldAgentToolCards} reducer; pass `resolveEnvelope` to classify
+ * tool-result payloads (default flags `{ ok: false }` envelopes as errors).
+ */
+declare function useAgentToolCards<TBody = unknown>(path: string, options?: UseAgentStreamOptions & FoldAgentToolCardsOptions): UseAgentToolCardsReturn<TBody>;
+
+/**
+ * T5.2 — Pure SSE consumer used by useAgentStream.
+ *
+ * Split out from the React hook so the wire behavior can be tested
+ * without a DOM. The hook is glue: useState + useEffect + this primitive.
+ *
+ * Transport (ADR D7, EC-3): fetch + ReadableStream — NOT EventSource.
+ * EventSource is GET-only and cannot carry a body. Agent endpoints need
+ * POST + JSON body, so we use fetch + manual SSE chunk parsing.
+ */
+interface ConsumeOptions<TBody = unknown> {
+    /** Request body — JSON-serialized into the POST. */
+    body: TBody;
+    /** Called once per SSE event parsed off the stream. */
+    onEvent: (event: AgentEvent) => void;
+    /** Optional fetch override (tests). */
+    fetch?: typeof fetch;
+    /** Optional abort signal — passed through to fetch. */
+    signal?: AbortSignal;
+    /** Extra headers (e.g., auth). */
+    headers?: Record<string, string>;
+}
+/**
+ * Parse a single SSE line of the form `data: <json>`.
+ * Returns null for non-data lines, comments, or malformed JSON.
+ */
+declare function parseSSEChunk(line: string): AgentEvent | null;
+/**
+ * POSTs to `path` with `body`, reads the SSE response, and invokes
+ * `onEvent` for each parsed AgentEvent. Resolves when the server
+ * closes the stream or the signal aborts.
+ *
+ * T1.1 — Attaches `X-Theo-Action: '1'` so 0.3.0 strict CSRF mode accepts
+ * the request. The user can override (or suppress) by passing the header
+ * in `options.headers` — spread order ensures their value wins.
+ */
+declare function consumeAgentStream<TBody = unknown>(path: string, options: ConsumeOptions<TBody>): Promise<void>;
+
+/**
+ * M2 (theokit-ai-first) — read a TheoKit agent endpoint's `UIMessageStream` SSE `Response`
+ * into reconstructed assistant `UIMessage`s, reusing the `ai` package's own consumer
+ * primitives (`parseJsonEventStream` + `readUIMessageStream`) — the exact path
+ * `@ai-sdk/react`'s `useChat` runs internally. No reinvented wire parser (Rule 9).
+ *
+ * `ai` is an OPTIONAL peer dependency, so it is imported dynamically: an app that never
+ * calls an agent never pays for it, and importing `theokit/client` does not hard-require
+ * `ai` (mirrors how the agent runtime dynamically imports `@theokit/sdk`). An agent app
+ * always has `ai` installed (it is the UIMessageStream consumer).
+ *
+ * `onMessage` is invoked on every reconstruction step with the latest snapshot of the
+ * assistant message, so a caller (the `useAgent` hook) can render streaming updates.
+ */
+declare function consumeUIMessageStream(response: Response, onMessage: (message: UIMessage) => void): Promise<void>;
+
+/**
+ * M2 (theokit-ai-first) — `useAgent`, the typed client hook for the `agents/*.ts` convention.
+ *
+ * A thin React hook over `consumeUIMessageStream` (which reuses `ai`'s own UIMessageStream
+ * reader). `useAgent('support')` binds to `POST /api/agents/support`; the generated
+ * `@theo/agents` module (`.theokit/agents.d.ts`) types `send` to the agent's `input` schema,
+ * so the request shape is inferred end-to-end from the server `defineAgent({ input })` with
+ * ZERO manual wiring (DoD line 2).
+ *
+ * Transport mirrors `useAgentStream`: fetch + ReadableStream (POST needs a body; EventSource
+ * is GET-only). `ai` is loaded lazily by `consumeUIMessageStream` so non-agent apps never
+ * pay for it.
+ */
+type UseAgentStatus = 'idle' | 'streaming' | 'done' | 'error';
+interface UseAgentReturn<TInput = unknown> {
+    /** Reconstructed assistant messages so far (ai `UIMessage[]`). */
+    messages: UIMessage[];
+    status: UseAgentStatus;
+    /** The last error, or `undefined`. */
+    error: Error | undefined;
+    /** Send a request; opens a new stream. Typed to the agent's `input` schema. */
+    send: (input: TInput) => void;
+    /** Abort an in-flight stream. */
+    abort: () => void;
+    /** Clear messages + error, back to idle. */
+    reset: () => void;
+}
+interface UseAgentOptions {
+    /** Extra request headers (e.g., auth). */
+    headers?: Record<string, string>;
+    /** Override fetch (primarily for tests). */
+    fetch?: typeof fetch;
+}
+/**
+ * Bind to the agent endpoint at `path` (`/api/agents/<name>`). Prefer the generated
+ * `useAgent` from `@theo/agents` (typed by agent name); this base accepts an explicit path.
+ */
+declare function useAgent<TInput = unknown>(path: string, options?: UseAgentOptions): UseAgentReturn<TInput>;
+
+type PrefetchBehavior = 'none' | 'intent' | 'viewport';
+interface LinkProps extends LinkProps$1 {
+    /** Prefetch strategy. Default: 'intent' (on hover + focus). */
+    prefetch?: PrefetchBehavior;
+}
+/**
+ * TheoKit Link — drop-in replacement for react-router Link with prefetch.
+ *
+ * @example
+ * ```tsx
+ * import { Link } from 'theokit/client'
+ *
+ * <Link to="/contacts">Contacts</Link>
+ * <Link to="/dashboard" prefetch="viewport">Dashboard</Link>
+ * <Link to="/settings" prefetch="none">Settings</Link>
+ * ```
+ */
+declare function Link({ prefetch, to, onMouseEnter, onFocus, ...rest }: LinkProps): react.JSX.Element;
+
+/**
+ * <Metadata> — SEO-ready head tags from a single component.
+ *
+ * Uses React 19's native <title>/<meta>/<link> hoisting to <head>.
+ * No build-time extraction needed — works in SSR and client.
+ *
+ * @example
+ * ```tsx
+ * import { Metadata } from 'theokit/client'
+ *
+ * export default function ContactsPage() {
+ *   return (
+ *     <>
+ *       <Metadata
+ *         title="Contacts | My CRM"
+ *         description="Manage your contacts"
+ *         ogImage="/og/contacts.png"
+ *         canonical="https://mycrm.com/contacts"
+ *       />
+ *       <h1>Contacts</h1>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+interface MetadataProps {
+    title?: string;
+    description?: string;
+    canonical?: string;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    ogType?: string;
+    ogUrl?: string;
+    twitterCard?: 'summary' | 'summary_large_image';
+    /** Custom meta tags rendered as children */
+    children?: React.ReactNode;
+}
+declare function Metadata(props: MetadataProps): react.JSX.Element;
+
+/**
+ * <Image> — optimized image component with lazy loading.
+ *
+ * Renders a standard <img> with:
+ *   - loading="lazy" by default (eager with priority={true})
+ *   - decoding="async" for non-blocking decode
+ *   - width/height for CLS prevention
+ *   - srcSet/sizes forwarded for responsive images
+ *
+ * No CDN, no Sharp, no build-time optimization — pure HTML attributes
+ * that deliver 80% of the performance value at zero complexity.
+ *
+ * @example
+ * ```tsx
+ * import { Image } from 'theokit/client'
+ *
+ * <Image src="/team.jpg" alt="Team photo" width={800} height={600} />
+ * <Image src="/hero.jpg" alt="Hero" priority />
+ * <Image
+ *   src="/product.jpg"
+ *   alt="Product"
+ *   width={400}
+ *   height={300}
+ *   srcSet="/product-400.jpg 400w, /product-800.jpg 800w"
+ *   sizes="(max-width: 768px) 100vw, 400px"
+ * />
+ * ```
+ */
+interface ImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+    /** Image source URL (required). */
+    src: string;
+    /** Alt text for accessibility (required). */
+    alt: string;
+    /** If true, loading="eager" — use for above-the-fold images. */
+    priority?: boolean;
+}
+declare function Image({ priority, loading, decoding, ...props }: ImageProps): react.JSX.Element;
+
+export { AgentErrorEvent, AgentEvent, type AgentStreamStatus, type AgentToolCard, type BatchRequest, type BatchResponse, type BatchTransport, type Batcher, type BatcherOptions, type ConsumeOptions, type CreateAppClientOptions, type FoldAgentToolCardsOptions, Image, type ImageProps, type InferBody, type InferQuery, type InferResponse, Link, type LinkProps, Metadata, type MetadataProps, type PrefetchBehavior, TheoFetchError, type TheoFetchOptions, type ToolEnvelopeResolver, type UseAgentOptions, type UseAgentReturn, type UseAgentStatus, type UseAgentStreamOptions, type UseAgentStreamReturn, type UseAgentToolCardsReturn, consumeAgentStream, consumeUIMessageStream, createAppClient, createBatcher, defaultResolveEnvelope, deriveError, deriveLiveText, foldAgentToolCards, parseSSEChunk, theoFetch, useAgent, useAgentStream, useAgentToolCards };

package/dist/client/index.js

@@ -599,11 +599,90 @@ function useAgentToolCards(path, options = {}) {
   return { ...stream, toolCards };
 }
 
+// src/client/consume-ui-message-stream.ts
+async function consumeUIMessageStream(response, onMessage) {
+  if (response.body === null) return;
+  const { parseJsonEventStream, readUIMessageStream, uiMessageChunkSchema } = await import("ai");
+  const parsed = parseJsonEventStream({ stream: response.body, schema: uiMessageChunkSchema });
+  const chunkStream = new ReadableStream({
+    async start(controller) {
+      for await (const result of parsed) {
+        if (result.success) controller.enqueue(result.value);
+      }
+      controller.close();
+    }
+  });
+  for await (const message of readUIMessageStream({ stream: chunkStream })) {
+    onMessage(message);
+  }
+}
+
+// src/client/use-agent.ts
+import { useCallback as useCallback2, useRef as useRef2, useState as useState2 } from "react";
+function useAgent(path, options = {}) {
+  const [messages, setMessages] = useState2([]);
+  const [status, setStatus] = useState2("idle");
+  const [error, setError] = useState2(void 0);
+  const controllerRef = useRef2(null);
+  const abort = useCallback2(() => {
+    controllerRef.current?.abort();
+    controllerRef.current = null;
+  }, []);
+  const reset = useCallback2(() => {
+    abort();
+    setMessages([]);
+    setError(void 0);
+    setStatus("idle");
+  }, [abort]);
+  const send = useCallback2(
+    (input) => {
+      abort();
+      const controller = new AbortController();
+      controllerRef.current = controller;
+      setMessages([]);
+      setError(void 0);
+      setStatus("streaming");
+      const fetchImpl = options.fetch ?? globalThis.fetch;
+      void (async () => {
+        try {
+          const response = await fetchImpl(path, {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              accept: "text/event-stream",
+              "X-Theo-Action": "1",
+              ...options.headers
+            },
+            body: JSON.stringify(input),
+            signal: controller.signal
+          });
+          await consumeUIMessageStream(response, (message) => {
+            setMessages((prev) => {
+              const next = [...prev];
+              const idx = next.findIndex((m) => m.id === message.id);
+              if (idx >= 0) next[idx] = message;
+              else next.push(message);
+              return next;
+            });
+          });
+          setStatus("done");
+        } catch (err) {
+          if (controller.signal.aborted) return;
+          setError(err instanceof Error ? err : new Error(String(err)));
+          setStatus("error");
+        }
+      })();
+    },
+    [abort, options.fetch, options.headers, path]
+  );
+  return { messages, status, error, send, abort, reset };
+}
+
 // src/client/link.tsx
 import {
   Link as RouterLink
 } from "react-router";
-import { useRef as useRef2, useCallback as useCallback2, useEffect as useEffect2 } from "react";
+import { useRef as useRef3, useCallback as useCallback3, useEffect as useEffect2 } from "react";
 import { jsx } from "react/jsx-runtime";
 var prefetched = /* @__PURE__ */ new Set();
 function injectPrefetch(href) {
@@ -620,8 +699,8 @@ function resolveTo(to) {
   return to?.pathname ?? "";
 }
 function Link({ prefetch = "intent", to, onMouseEnter, onFocus, ...rest }) {
-  const ref = useRef2(null);
-  const handleIntent = useCallback2(
+  const ref = useRef3(null);
+  const handleIntent = useCallback3(
     (event) => {
       if (prefetch === "intent") {
         injectPrefetch(resolveTo(to));
@@ -703,6 +782,7 @@ export {
   TheoFetchError,
   buildUseTheoQueryConfig,
   consumeAgentStream,
+  consumeUIMessageStream,
   createAppClient,
   createBatcher,
   defaultResolveEnvelope,
@@ -712,6 +792,7 @@ export {
   parseSSEChunk,
   stableQueryKey,
   theoFetch,
+  useAgent,
   useAgentStream,
   useAgentToolCards
 };