theokit 0.12.0 → 0.13.0

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

@@ -0,0 +1,313 @@
+import { z } from 'zod';
+import { A as AgentEvent } from '../../agent-events-DosDXkSV.js';
+import { UIMessageChunk } from 'ai';
+import { b as WebSocketLike } from '../../define-websocket-CdK94O-D.js';
+export { W as WebSocketHandler, a as WebSocketHandlerWeb, d as defineWebSocket, c as defineWebSocketWeb } from '../../define-websocket-CdK94O-D.js';
+import { IncomingMessage } from 'node:http';
+import { T as TheoPlugin } from '../../plugin-types-DNJGxr4Z.js';
+export { H as HEALTH_PATH, a as HealthRouteConfig, b as READY_PATH, c as ReadyRouteConfig, d as ReservedResponse, R as ReservedRoutes, e as defineHealthRoute, f as defineReadyRoute, s as serveReservedRoute } from '../../health-route-C0hk64_U.js';
+
+/**
+ * core/contracts/route-config.ts
+ *
+ * Canonical home for `RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>` —
+ * the contract shape consumed by `defineRoute()` (server) and
+ * `defineCachedRoute()` (cache).
+ *
+ * Moved here in T2.2 of architecture-cleanup so `cache → core/contracts`
+ * is the legal edge (replacing the prior `cache → server` violation).
+ *
+ * GAP-4 (plan v1.1): the 5-arity generic shape `<TQuery, TBody, TParams, TCtx, TResponse>`
+ * MUST be preserved byte-by-byte. Type tests assert this in
+ * `tests/unit/route-config-generic-arity.test.ts`.
+ */
+
+interface RouteConfig<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown, TResponse = unknown> {
+    query?: TQuery;
+    body?: TBody;
+    params?: TParams;
+    status?: number;
+    /**
+     * Optional Zod schema for the handler's plain-object return value. When
+     * present, BOTH runtimes (Node `executeRoute` + Web `executeWebRequest`)
+     * validate the handler's plain-object return against it BEFORE serializing.
+     *
+     * A mismatch is a SERVER fault (the handler violated its own declared
+     * contract) → 500 `INTERNAL_SERVER_ERROR`, distinct from the 400 used for
+     * input (`query`/`body`/`params`) validation failures.
+     *
+     * `Response`-instance returns (and `undefined`/`null` → 204) are NOT
+     * validated. This is a plain optional field — runtime validation only; the
+     * handler return type is NOT statically inferred from `response` (YAGNI).
+     */
+    response?: z.ZodType;
+    /**
+     * Opt out of CSRF enforcement for this route. Use for endpoints that
+     * legitimately receive third-party POSTs (Stripe webhooks, GitHub
+     * webhooks, OAuth callbacks). Defaults to enforced per `config.security.csrf`.
+     *
+     * Setting `csrf: false` only disables the per-route check — it does NOT
+     * disable the global mode setting for other routes.
+     */
+    csrf?: false;
+    handler: (ctx: {
+        query: z.infer<TQuery>;
+        body: z.infer<TBody>;
+        params: z.infer<TParams>;
+        request: Request;
+        ctx: TCtx;
+    }) => TResponse | Promise<TResponse>;
+}
+
+/**
+ * Define a typed HTTP route.
+ * Identity function — provides type inference for route handlers.
+ */
+declare function defineRoute<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown, TResponse = unknown>(config: RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>): RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>;
+
+/**
+ * Action wire-protocol accept mode per plan g3-server-actions-and-useaction
+ * v1.2 ADR D1. Default behavior (when omitted) is `'json'`. `'form'` opts the
+ * action into FormData multipart parsing for progressive-enhancement forms;
+ * the runtime in `server/http/action-execute.ts` will coerce FormData entries
+ * against the `input` schema via `formDataToObject` (Astro pattern).
+ */
+type ActionAccept = 'form' | 'json';
+interface ActionConfig<TInput extends z.ZodType, TCtx = unknown> {
+    /**
+     * Zod input schema. Required: every action declares its input contract via
+     * Zod (architecture rule: zod-is-SSOT). The shape becomes the handler's
+     * typed `input` parameter via `z.infer<TInput>`.
+     */
+    input: TInput;
+    /**
+     * Wire-protocol accept mode. Defaults to `'json'` when omitted. Setting
+     * `'form'` switches the runtime to FormData multipart parsing — the input
+     * schema MUST be `z.object(...)` so field-by-field coercion can drive
+     * boolean string / number / array coercion (Astro pattern).
+     */
+    accept?: ActionAccept;
+    /**
+     * Opt OUT of CSRF enforcement for this action. Default (omitted) keeps the
+     * multi-header CSRF gate active. Set `false` for endpoints intentionally
+     * callable without the `X-Theo-Action` header (e.g. public webhooks). The
+     * runtime in `server/http/action-execute.ts` reads this flag.
+     */
+    csrf?: false;
+    handler: (ctx: {
+        input: z.infer<TInput>;
+        ctx: TCtx;
+    }) => unknown;
+}
+/**
+ * Define a typed server action.
+ *
+ * Identity function — provides type inference for action handlers. The
+ * runtime that consumes the config (validation + invocation + serialization)
+ * lives in `server/http/action-execute.ts`.
+ *
+ * Per plan g3-server-actions-and-useaction v1.2 § Phase 1 / T1.2: the new
+ * `accept?: 'form' | 'json'` field is the only contract change vs the
+ * pre-G3 identity. Existing callsites (`defineAction({input, handler})`)
+ * continue to compile — `accept` is opt-in.
+ */
+declare function defineAction<TInput extends z.ZodType, TCtx = unknown>(config: ActionConfig<TInput, TCtx>): ActionConfig<TInput, TCtx>;
+
+type MiddlewareHandler = (request: Request, next: (request: Request) => Promise<Response>) => Response | Promise<Response>;
+/**
+ * Define a middleware handler.
+ * Identity function — provides type annotation for middleware.
+ */
+declare function defineMiddleware(handler: MiddlewareHandler): MiddlewareHandler;
+
+/**
+ * T5.1 — defineAgentEndpoint
+ *
+ * Sugar over defineRoute (ADR D4). Accepts an async generator that yields
+ * AgentEvents and produces a RouteConfig whose handler returns a Response
+ * streaming Server-Sent Events (SSE).
+ *
+ * Wire format: `data: <JSON>\n\n` per event. Standards-compliant.
+ *
+ * The generator may throw — the wrapper catches and emits a final
+ * `{ type: 'error', message }` event before closing the stream.
+ *
+ * The wrapper observes `request.signal` (EC-7) — when aborted, the
+ * underlying generator is told to `return()` and the stream closes
+ * promptly.
+ *
+ * Note (EC-12, Out of Scope): SSE backpressure (slow consumer) is not
+ * handled here. For high-frequency token streaming consider a different
+ * transport (WS) or a buffer policy. This MVP enqueues each event
+ * immediately.
+ */
+interface AgentEndpointHandlerArgs<TCtx = unknown, TBody = unknown, TParams extends z.ZodType = z.ZodUndefined> {
+    query: undefined;
+    body: TBody;
+    params: z.infer<TParams>;
+    request: Request;
+    ctx: TCtx;
+    /**
+     * Mutable headers bag that the wrapper merges into the SSE response BEFORE
+     * the stream starts. Used by `createConversationHistory` to issue a
+     * conversation-id cookie on first request. Append entries via
+     * `cookieHeaders.append('set-cookie', '<cookie-string>')`.
+     *
+     * Cookies appended AFTER the first yield are NOT applied — the response
+     * headers commit when the wrapper constructs the Response, before the
+     * async generator runs. This is per HTTP semantics, not a wrapper choice.
+     */
+    cookieHeaders: Headers;
+    /**
+     * Phase 3 (Production-Readiness #5) — request abort signal.
+     *
+     * Fires when the SSE client disconnects (browser closes tab, abort fetch,
+     * etc.). Thread this to `agent.send(msg, { signal })` so the SDK cancels
+     * the in-flight provider call — STOPS TOKENS FROM CHARGING for output
+     * the user will never receive.
+     *
+     * EC-1 (MUST FIX): the signal is derived via duck-type detection
+     * (`'aborted' in r.signal && typeof r.signal.addEventListener === 'function'`)
+     * to survive cross-realm scenarios (Node 18 polyfills, undici, Edge
+     * runtimes with their own AbortSignal globals). `instanceof AbortSignal`
+     * would fail in those cases.
+     */
+    signal: AbortSignal;
+}
+interface AgentEndpointConfig<TCtx = unknown, TBody = unknown, TParams extends z.ZodType = z.ZodUndefined> {
+    /**
+     * Optional Zod schema for path params (e.g. `z.object({ id: z.string() })`).
+     * When present, the runner validates path params and returns 400 on mismatch
+     * BEFORE the generator runs; the validated params are threaded to the
+     * generator typed as `z.infer<TParams>` (D4).
+     */
+    params?: TParams;
+    handler: (args: AgentEndpointHandlerArgs<TCtx, TBody, TParams>) => AsyncGenerator<AgentEvent, void, unknown>;
+}
+declare function defineAgentEndpoint<TBody = unknown, TCtx = unknown, TParams extends z.ZodType = z.ZodUndefined>(config: AgentEndpointConfig<TCtx, TBody, TParams>): RouteConfig<z.ZodUndefined, z.ZodUndefined, TParams, TCtx, Response>;
+
+declare function uiMessageStreamResponse(chunks: AsyncIterable<UIMessageChunk>): 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 (or the `streamAgentRun` adapter) sees as a tool failure and
+ *   surfaces as an `error` AgentEvent on the SSE 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>) => string | Promise<string>;
+}
+/**
+ * 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> {
+    /** 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. */
+    handler: (input: z.infer<T>) => string | Promise<string>;
+}
+/**
+ * Build a {@link CustomTool} from a Zod 3 schema + handler.
+ *
+ * Behavior:
+ * - Validates `name` matches the LLM tool-name regex.
+ * - Requires `inputSchema` to be a `ZodObject` (Anthropic + SDK contract).
+ * - Warns (not throws) if `description` is empty — empty descriptions
+ *   degrade LLM tool selection.
+ * - Converts the Zod schema to JSON Schema 7 inline (no `$ref`s — LLMs handle
+ *   inline schemas more reliably).
+ * - Strips the top-level `$schema` field (Anthropic rejects schemas with
+ *   `$schema` at root in some provider modes).
+ * - Wraps the handler to parse the input via the Zod schema BEFORE invoking
+ *   the user code — bad LLM-supplied input throws `ZodError`, which the SDK
+ *   converts to `tool_result(isError)`.
+ *
+ * @public
+ */
+declare function defineAgentTool<T extends z.ZodType>(spec: DefineAgentToolSpec<T>): CustomTool;
+
+interface ChannelHandler<TMessage = unknown> {
+    onSubscribe?: (ws: WebSocketLike, room: string, req: IncomingMessage) => void;
+    onMessage?: (ws: WebSocketLike, room: string, data: TMessage) => void;
+    onUnsubscribe?: (ws: WebSocketLike, room: string) => void;
+}
+/**
+ * Define a channel handler for WebSocket rooms.
+ * Identity function — provides type inference for channel handlers.
+ */
+declare function defineChannel<TMessage = unknown>(handler: ChannelHandler<TMessage>): ChannelHandler<TMessage>;
+/**
+ * T5a.2 Phase F slice 2/3 — Web-Standards channel handler.
+ *
+ * Mirror of `ChannelHandler<TMessage>` for the Web `Request` shape.
+ * `onSubscribe` receives `request: Request` instead of `req: IncomingMessage`
+ * — the rest of the surface (onMessage, onUnsubscribe) is shape-agnostic
+ * (WebSocketLike is already Web-standards-compatible per `define-websocket.ts`).
+ *
+ * Per `docs/plans/t5a2-incoming-message-to-request-shape-refactor-plan.md`
+ * v1.0 § Phase F.
+ *
+ * **Architectural note:** WebSocket upgrade semantics differ across
+ * runtimes:
+ *   - Node: `WebSocketServer.handleUpgrade(req, socket, head, cb)` —
+ *     hands you `req: IncomingMessage` at the upgrade handshake.
+ *   - CF Workers: `new WebSocketPair()` + `request.headers` (the upgrade
+ *     handshake IS a Web Request) — hands you `request: Request`.
+ *   - Bun: `server.upgrade(request, { data })` — same Web Request shape.
+ *   - Deno: `Deno.upgradeWebSocket(request)` — same Web Request shape.
+ *
+ * Channel handlers targeting CF/Bun/Deno use `WebChannelHandler`; legacy
+ * Node consumers stay on `ChannelHandler`. Cross-runtime channels ship
+ * both shapes.
+ */
+interface WebChannelHandler<TMessage = unknown> {
+    onSubscribe?: (ws: WebSocketLike, room: string, request: Request) => void;
+    onMessage?: (ws: WebSocketLike, room: string, data: TMessage) => void;
+    onUnsubscribe?: (ws: WebSocketLike, room: string) => void;
+}
+/**
+ * Web-Standards `defineChannel` sibling. Identity function — provides
+ * type inference for Web channel handlers.
+ */
+declare function defineWebChannel<TMessage = unknown>(handler: WebChannelHandler<TMessage>): WebChannelHandler<TMessage>;
+
+/**
+ * Identity function for defining a Theo plugin.
+ *
+ * **Note:** Prefer `definePlugin` (shorter, canonical name per ADR-0008 D6).
+ * Both functions are identical — `defineTheoPlugin` is kept as an alias for
+ * existing in-tree consumers without forcing a migration sweep.
+ */
+declare function defineTheoPlugin(plugin: TheoPlugin): TheoPlugin;
+
+export { type ActionAccept, type ActionConfig, type AgentEndpointConfig, type AgentEndpointHandlerArgs, type ChannelHandler, type CustomTool, type DefineAgentToolSpec, type MiddlewareHandler, type RouteConfig, type WebChannelHandler, WebSocketLike, defineAction, defineAgentEndpoint, defineAgentTool, defineChannel, defineMiddleware, defineRoute, defineTheoPlugin, defineWebChannel, uiMessageStreamResponse };

package/dist/server/define/index.js

@@ -8,9 +8,11 @@ import {
   defineTheoPlugin,
   defineWebChannel,
   defineWebSocket,
-  defineWebSocketWeb,
+  defineWebSocketWeb
+} from "../../chunk-ZSTZXR2D.js";
+import {
   uiMessageStreamResponse
-} from "../../chunk-AD74EAK3.js";
+} from "../../chunk-NHJMZCAS.js";
 import {
   HEALTH_PATH,
   READY_PATH,

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

@@ -0,0 +1,11 @@
+export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, N as NotFoundError, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoError, _ as _resetMiddlewareCacheForTests, s as appendCookieToHeaders, t as appendDeleteCookieToHeaders, u as createCorsHandler, v as createCorsWebHandler, w as deleteCookie, x as envelopeCodeToStatus, y as executeAction, z as executeRoute, A as extractTraceId, D as extractTraceIdFromRequest, F as fromUnknown, G as getCookie, I as getCookieFromRequest, J as handleBatchRequest, K as handleRequestError, L as handleWebRequestError, P as loadCustomErrorPages, Q as matchesOrigin, R as parseCookieHeader, U as parseTraceparent, W as runMiddlewareAndContext, X as sendError, Y as sendJson, Z as serializeCookie, $ as serveStaticFile, a0 as serverErrorToEnvelope, a1 as setCookie } from '../../index-B40qUSrQ.js';
+import '../../error-envelope-BsNzzAV5.js';
+import 'node:http';
+import '../../plugin-types-DNJGxr4Z.js';
+import '../../plugin-runner-BGBkzgi0.js';
+import '../../job-backend-CgC8Xf33.js';
+import '../../match-CfbEFRG4.js';
+import 'vite';
+import '../../csrf-BBrEZSBW.js';
+import '../../audit-log-BQWM5YLG.js';
+import 'zod';