theokit 0.2.4 → 0.4.0

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

@@ -0,0 +1,229 @@
+import { a as AgentErrorEvent, A as AgentEvent } from '../../agent-events-B3KNV9ER.js';
+export { b as AgentMessageEvent, e as AgentRunErrorCode, c as AgentToolCallEvent, d as AgentToolResultEvent } from '../../agent-events-B3KNV9ER.js';
+
+/**
+ * Item #4 — `streamAgentRun`
+ *
+ * Adapter that consumes the `@theokit/sdk` `Run.stream()` async generator
+ * (SDKMessage variants) and yields TheoKit `AgentEvent`s suitable for SSE
+ * via `defineAgentEndpoint`. One line at the consumer side:
+ *
+ *   ```ts
+ *   const run = await agent.send(message)
+ *   yield* streamAgentRun(run)
+ *   ```
+ *
+ * Mapping table (SDK → AgentEvent):
+ *
+ * | SDK message                          | AgentEvent yielded                     |
+ * |---|---|
+ * | assistant.content[].type==='text'    | { type: 'message', content }           |
+ * | assistant.content[].type==='tool_use'| (none — covered by tool_call below)    |
+ * | tool_call(status='running')          | { type: 'tool_call', name, args, id }  |
+ * | tool_call(status='completed')        | { type: 'tool_result', name, data, id }|
+ * | tool_call(status='error')            | { type: 'error', message, id }         |
+ * | run.wait() status==='error'          | { type: 'error', message }             |
+ * | run.wait() status==='cancelled'      | (none — cancel ≠ error)                |
+ * | system / user / thinking / status /  | (none — internal SDK telemetry)        |
+ * |   task / request / object_delta      |                                        |
+ *
+ * Abort semantics: when the consumer calls `generator.return()` on the
+ * outer `defineAgentEndpoint` generator, `streamAgentRun` exits the
+ * `for await` loop and does NOT call `run.wait()`. Cleanup of in-flight
+ * SDK resources is the SDK consumer's responsibility (`run.cancel()`).
+ */
+/**
+ * Local mirror of the SDK's `Run` interface — only the surfaces we consume.
+ * The message contract is minimal (just `{ type: string }`) so the SDK's
+ * `SDKMessage` discriminated union IS structurally assignable without any
+ * cast at the consumer site (covariant — TS accepts the SDK's typed message
+ * as the wider `{ type: string }`). Property access inside `streamAgentRun`
+ * narrows via runtime type guards.
+ *
+ * `import type` from `@theokit/sdk` would couple TheoKit to the SDK at type-
+ * resolution time even for consumers who never use the agent surface.
+ */
+interface AgentRunLike {
+    stream: () => AsyncIterable<{
+        type: string;
+    }>;
+    wait: () => Promise<AgentRunResult>;
+}
+/**
+ * Re-exported as a convenience for test fixtures. Production code typically
+ * passes an SDK `Run` directly (structural match via `{ type: string }`).
+ */
+type AgentRunStreamMessage = {
+    type: 'assistant';
+    message: {
+        role: 'assistant';
+        content: {
+            type: string;
+            text?: string;
+        }[];
+    };
+} | {
+    type: 'tool_call';
+    name: string;
+    status: 'running' | 'completed' | 'error';
+    args?: unknown;
+    result?: unknown;
+    call_id: string;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/** Subset of the SDK `RunResult` we consume. */
+interface AgentRunResult {
+    status: 'finished' | 'error' | 'cancelled';
+    error?: {
+        message: string;
+        code?: string;
+        cause?: unknown;
+    };
+}
+/**
+ * Map an SDK error to the AgentErrorEvent shape. Pure function — easy to test.
+ *
+ * Backward compat (D4): non-AgentRunError throws yield only `message` field
+ * (legacy shape); discriminated fields stay `undefined`.
+ *
+ * Return type is the specific `AgentErrorEvent` (not the union) for ergonomic
+ * call-site access — `errorToEvent(err).code` works without narrowing.
+ */
+declare function errorToEvent(err: unknown, id?: string): AgentErrorEvent;
+declare function streamAgentRun(run: AgentRunLike): AsyncGenerator<AgentEvent, void, unknown>;
+
+/**
+ * Item #5 — `createConversationHistory`
+ *
+ * Orchestrator that resolves a stable `agentId` from (explicit → session →
+ * cookie → fresh UUID), then returns an `@theokit/sdk` `Agent` via
+ * `Agent.getOrCreate(agentId, options)`. Conversation turns auto-persist in
+ * `<cwd>/.theokit/agents/<agentId>/messages.jsonl` — SDK owns the storage
+ * (ADR D1). `MemorySettings` (facts recall layer) is opt-in passthrough via
+ * `options.memory` (ADR D2).
+ *
+ * Security: agentId from cookie/explicit is attacker-controlled. The SDK
+ * uses it as a filesystem path component AND we serialize it into Set-Cookie.
+ * EC-1 enforces a strict regex `^[a-zA-Z0-9_-]{1,128}$` at every entry point;
+ * invalid values fall through (treated as "missing") rather than throw.
+ */
+/**
+ * Minimum surface of an SDK Agent that consumers care about post-creation.
+ * Structural match — any object with `send` + `dispose` of compatible
+ * shape works. `send` returns a `SdkRunLike` (a Run-shaped object) that
+ * `streamAgentRun` can consume. Permissive `unknown` for now; consumers
+ * who want stricter types can cast to the SDK's own types.
+ *
+ * **T5.2 (architecture-cleanup) — DP-7 decision: KEEP (Opt B).** The 5 duck-typed
+ * mirrors below were flagged as "over-engineered" by the 2026-05-27 architecture
+ * review. Decision: KEEP them because `@theokit/sdk` is `devDependency` (not
+ * required at runtime for consumers that don't use agent features). Removing
+ * the mirrors would force a hard runtime dep on the SDK, breaking consumers
+ * who build TheoKit apps without the agent layer.
+ *
+ * @kept Defensive duck-type. Do NOT replace with direct SDK type imports unless
+ *   `@theokit/sdk` is promoted from devDependency to dependency. If promoting,
+ *   ALSO drop the mirrors (Opt A from the architecture-cleanup plan T5.2).
+ */
+interface SdkRunLike {
+    stream: () => AsyncIterable<{
+        type: string;
+    }>;
+    wait: () => Promise<{
+        status: 'finished' | 'error' | 'cancelled';
+        error?: {
+            message: string;
+        };
+    }>;
+}
+interface SdkAgent {
+    send: (message: string, options?: unknown) => Promise<SdkRunLike>;
+    dispose: () => Promise<void>;
+}
+/**
+ * Phase 2 — structural duck-type of `@theokit/sdk`'s `ConversationStorageAdapter`.
+ *
+ * D2 (decoupling): we mirror the SDK's shape locally rather than hard-import
+ * the SDK type. This lets consumers pass any object matching the structural
+ * contract (own implementation, SDK's `FileSystemConversationStorage`,
+ * `InMemoryConversationStorage`, or a Postgres/Redis recipe).
+ *
+ * EC-5 (SHOULD TEST — sync drift detection): the SDK type MUST be assignable
+ * to this interface AND vice-versa. A contract test asserts both directions.
+ *
+ * `unknown` for the message payload avoids coupling to the SDK's `SDKMessage`
+ * shape. Real consumers cast at the call site if they need stricter types.
+ */
+interface ConversationStorageLike {
+    getMessages(conversationId: string): Promise<readonly unknown[]>;
+    appendMessage(conversationId: string, message: unknown): Promise<void>;
+    deleteConversation(conversationId: string): Promise<void>;
+    listConversationIds?(opts?: {
+        limit?: number;
+    }): Promise<readonly string[] | undefined>;
+    dispose?(): Promise<void>;
+}
+/**
+ * Minimum surface of `AgentOptions` accepted by `Agent.getOrCreate`. Forward-
+ * compatible: callers pass whatever the SDK supports (memory, tools, etc.).
+ *
+ * Phase 2 adds typed `conversationStorage` slot. The index signature still
+ * passes everything else opaquely.
+ */
+interface SdkAgentOptions {
+    apiKey?: string;
+    model?: {
+        id: string;
+    };
+    tools?: readonly unknown[];
+    memory?: Record<string, unknown>;
+    /**
+     * Phase 2 (Production-Readiness #1) — pluggable conversation persistence.
+     * Default (when omitted): SDK falls back to `FileSystemConversationStorage`.
+     * Required for serverless / multi-host deploys.
+     */
+    conversationStorage?: ConversationStorageLike;
+    [key: string]: unknown;
+}
+interface ConversationHistoryArgs {
+    /** Request — for reading the conversation cookie. */
+    request: Request | {
+        headers?: {
+            cookie?: string;
+        } | Headers;
+    };
+    /**
+     * Response-like surface that accepts a `Set-Cookie` header. The primitive
+     * appends a Set-Cookie line when issuing a new conversation id. If absent,
+     * the primitive still reads the existing cookie but cannot issue a new
+     * one — useful for read-only contexts.
+     */
+    response?: {
+        headers: Headers;
+    };
+    /** Explicit override — wins over session/cookie/uuid (ADR D3 step 1). */
+    agentId?: string;
+    /** Auth session containing a `conversationId` field — ADR D3 step 2. */
+    session?: {
+        conversationId?: string;
+    } | null;
+    /** SDK AgentOptions forwarded to Agent.getOrCreate. apiKey + model required. */
+    options: SdkAgentOptions;
+    /** Cookie name override. Default: 'theo_conversation'. */
+    cookieName?: string;
+    /** Cookie max-age in seconds. Default + min: 30 days. Non-positive coerced to default (EC-4). */
+    cookieMaxAge?: number;
+}
+interface ConversationHistoryResult {
+    /** The SDK Agent, ready to receive `agent.send(message)`. */
+    agent: SdkAgent;
+    /** The resolved conversation id (useful for logging / debugging). */
+    conversationId: string;
+    /** True when the id was newly generated (no prior cookie / session). */
+    isNew: boolean;
+}
+declare function createConversationHistory(args: ConversationHistoryArgs): Promise<ConversationHistoryResult>;
+
+export { AgentErrorEvent, AgentEvent, type AgentRunLike, type AgentRunResult, type AgentRunStreamMessage, type ConversationHistoryArgs, type ConversationHistoryResult, type ConversationStorageLike, type SdkAgent, type SdkAgentOptions, type SdkRunLike, createConversationHistory, errorToEvent, streamAgentRun };

package/dist/server/agent/index.js

@@ -0,0 +1,16 @@
+import {
+  __resetSdkForTests,
+  __setSdkForTests,
+  createConversationHistory,
+  errorToEvent,
+  streamAgentRun
+} from "../../chunk-RESN62GB.js";
+import "../../chunk-DGUM43GV.js";
+export {
+  __resetSdkForTests,
+  __setSdkForTests,
+  createConversationHistory,
+  errorToEvent,
+  streamAgentRun
+};
+//# 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.d.ts

@@ -49,6 +49,51 @@ interface SessionManager<TSession> {
     rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
 }
 declare function createSessionManager<TSession>(config: SessionConfig): SessionManager<TSession>;
+/**
+ * T5a.2 Phase D slice 3/3 — Web-Standards session manager.
+ *
+ * Mirror of `SessionManager<TSession>` for the Web `Request` + `Headers`
+ * shape. Same `SessionConfig`, same encryption (`encrypt`/`decrypt` from
+ * `./crypto.js`), same dual-key rotation logic (CR-002 constant-time
+ * decrypt fallback walk + transparent re-encrypt), same OWASP A07
+ * `rotateSession` invariant.
+ *
+ * **Signature differences vs `SessionManager`:**
+ *   - Read methods take `Request` (instead of `IncomingMessage`).
+ *   - Write methods take a `Headers` instance to mutate (instead of
+ *     `ServerResponse`) — caller passes the headers they're building
+ *     for their `Response` constructor.
+ *
+ * Uses `getCookieFromRequest` / `appendCookieToHeaders` /
+ * `appendDeleteCookieToHeaders` from Phase B slice 6/6.
+ */
+interface SessionManagerWeb<TSession> {
+    getSession(request: Request): Promise<TSession | null>;
+    getSessionWithMeta(request: Request): Promise<{
+        data: TSession | null;
+        meta: SessionMeta;
+    }>;
+    createSession(target: Headers, data: TSession): Promise<void>;
+    destroySession(target: Headers): void;
+    rotateSession(request: Request, target: Headers): Promise<TSession | null>;
+}
+declare function createSessionManagerWeb<TSession>(config: SessionConfig): SessionManagerWeb<TSession>;
+/**
+ * T5a.2 Phase D slice 3/3 — Web-Standards transparent re-encrypt helper.
+ *
+ * Mirror of `rotateIfNeeded(sm, req, res)` for the Web Request + Headers
+ * shape. Reads session via `getSessionWithMeta`; if the cookie was
+ * decrypted with a legacy secret (index > 0), re-issues the cookie with
+ * the newest secret via `createSession(target, data)`.
+ *
+ * **EC-4 honest framing:** unlike the IncomingMessage path where the
+ * timing constraint is "before `res.writeHead` fires", the Web Request
+ * path's constraint is "before the `Response` object is constructed and
+ * returned to the runtime". Caller MUST invoke `rotateIfNeededWeb`
+ * BEFORE building the final `Response(body, { headers: target })` so the
+ * re-encrypted Set-Cookie lands on the wire.
+ */
+declare function rotateIfNeededWeb<TSession>(sm: SessionManagerWeb<TSession>, request: Request, target: Headers): Promise<TSession | null>;
 /**
  * T3.2 — Transparent re-encrypt helper (EC-4 timing-safe wrapper).
  *
@@ -371,4 +416,4 @@ declare function clearOidcCache(): void;
  */
 declare function discoverOidcProvider(issuer: string | URL): Promise<OidcMetadata>;
 
-export { AuthRequiredError, type BackupCode, type BackupCodeOptions, type OidcMetadata, type PkceChallenge, type SessionConfig, type SessionManager, type SessionMeta, type ThrottleOptions, type ThrottleState, type TotpAlgorithm, type TotpOptions, type TotpUriOptions, type VerifyTotpOptions, _resetKeyCacheForTests, assertProductionSecret, checkThrottle, clearOidcCache, createSessionManager, decrypt, discoverOidcProvider, encrypt, generateBackupCodes, generateNonce, generateOAuthState, generatePkceChallenge, generateTotp, generateTotpSecret, pkceChallengeFromVerifier, recordAttempt, requireAuth, rotateIfNeeded, totpUri, verifyBackupCode, verifyOAuthState, verifyTotp };
+export { AuthRequiredError, type BackupCode, type BackupCodeOptions, type OidcMetadata, type PkceChallenge, type SessionConfig, type SessionManager, type SessionManagerWeb, type SessionMeta, type ThrottleOptions, type ThrottleState, type TotpAlgorithm, type TotpOptions, type TotpUriOptions, type VerifyTotpOptions, _resetKeyCacheForTests, assertProductionSecret, checkThrottle, clearOidcCache, createSessionManager, createSessionManagerWeb, decrypt, discoverOidcProvider, encrypt, generateBackupCodes, generateNonce, generateOAuthState, generatePkceChallenge, generateTotp, generateTotpSecret, pkceChallengeFromVerifier, recordAttempt, requireAuth, rotateIfNeeded, rotateIfNeededWeb, totpUri, verifyBackupCode, verifyOAuthState, verifyTotp };

package/dist/server/auth/index.js

@@ -4,6 +4,7 @@ import {
   checkThrottle,
   clearOidcCache,
   createSessionManager,
+  createSessionManagerWeb,
   decrypt,
   discoverOidcProvider,
   encrypt,
@@ -15,16 +16,20 @@ import {
   pkceChallengeFromVerifier,
   recordAttempt,
   rotateIfNeeded,
+  rotateIfNeededWeb,
   totpUri,
   verifyBackupCode,
   verifyOAuthState,
   verifyTotp
-} from "../../chunk-VRHXOKRP.js";
+} from "../../chunk-NZXH2LQQ.js";
+import {
+  generateNonce
+} from "../../chunk-C3ZZ56YZ.js";
+import "../../chunk-ZJQ4O76G.js";
 import {
   AuthRequiredError,
-  generateNonce,
   requireAuth
-} from "../../chunk-PB4GR7EP.js";
+} from "../../chunk-4HBI7DHP.js";
 import "../../chunk-DGUM43GV.js";
 export {
   AuthRequiredError,
@@ -33,6 +38,7 @@ export {
   checkThrottle,
   clearOidcCache,
   createSessionManager,
+  createSessionManagerWeb,
   decrypt,
   discoverOidcProvider,
   encrypt,
@@ -46,6 +52,7 @@ export {
   recordAttempt,
   requireAuth,
   rotateIfNeeded,
+  rotateIfNeededWeb,
   totpUri,
   verifyBackupCode,
   verifyOAuthState,

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

@@ -1,4 +1,4 @@
-import { c as StorageAdapter } from '../../storage-types-DtIVejC1.js';
+import { d as StorageAdapter } from '../../storage-types-DsDTCPbp.js';
 
 /**
  * Cost tracking types (R0.5.11).
@@ -147,8 +147,6 @@ declare class InMemoryUsageStorage implements UsageStorageAdapter, StorageAdapte
     dispose(): Promise<void>;
     record(input: UsageRecord | ToolUsageRecord): Promise<void>;
     getUsage(query: UsageQuery): Promise<UsageResult>;
-    /** @internal — test helper to inspect raw record stream */
-    __getRecords(): readonly (UsageRecord | ToolUsageRecord)[];
 }
 
 interface TrackAgentToolsOptions {

package/dist/server/cost/index.js

@@ -2,7 +2,7 @@ import {
   InMemoryUsageStorage,
   trackAgentRun,
   trackAgentTools
-} from "../../chunk-64JI5LTO.js";
+} from "../../chunk-RMU7EBRO.js";
 import "../../chunk-DGUM43GV.js";
 export {
   InMemoryUsageStorage,

package/dist/server/cron/index.js

@@ -13,8 +13,10 @@ import {
   translateCronToVercel,
   validateCronSchedule,
   writeCronManifest
-} from "../../chunk-4QTKSLTO.js";
-import "../../chunk-YLBSSEHX.js";
+} from "../../chunk-K4M64WD6.js";
+import "../../chunk-Y4H3JNVK.js";
+import "../../chunk-6NEXVBPY.js";
+import "../../chunk-7MQOHNHE.js";
 import "../../chunk-X2VVCJ4V.js";
 import "../../chunk-DGUM43GV.js";
 export {

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

@@ -0,0 +1,281 @@
+import { z } from 'zod';
+import { A as AgentEvent } from '../../agent-events-B3KNV9ER.js';
+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';
+
+/**
+ * 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;
+    /**
+     * 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;
+    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> {
+    query: undefined;
+    body: TBody;
+    params: undefined;
+    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> {
+    handler: (args: AgentEndpointHandlerArgs<TCtx, TBody>) => AsyncGenerator<AgentEvent, void, unknown>;
+}
+declare function defineAgentEndpoint<TBody = unknown, TCtx = unknown>(config: AgentEndpointConfig<TCtx, TBody>): RouteConfig<z.ZodUndefined, z.ZodUndefined, z.ZodUndefined, TCtx, 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 };