theokit 0.12.0 → 0.12.1

package/dist/adapters/web-shim.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Web-to-Node bridge used by adapters whose runtimes provide a `Request`
+ * (Web Standard) but where TheoKit's `executeRoute` expects a Node-style
+ * IncomingMessage/ServerResponse pair.
+ *
+ * Used by adapters that target Node-compatible runtimes (Bun, Netlify
+ * Functions, AWS Lambda Node). Cloudflare uses an inline version of the same
+ * pattern — long-term it should consolidate here too.
+ *
+ * NOT used by Deno Deploy: Deno's stdlib does not have `Buffer`/`node:http`
+ * by default and forcing the shim there bloats the bundle. Deno wiring is
+ * tracked separately and will likely require executeRoute to accept Web
+ * Standard Request directly.
+ */
+interface ShimRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    socket: {
+        remoteAddress: string;
+    };
+    on: (event: 'data' | 'end' | 'error', cb: (chunk?: unknown) => void) => unknown;
+}
+interface ShimResponse {
+    statusCode: number;
+    headersSent: boolean;
+    writableEnded: boolean;
+    writeHead: (status: number, headers?: Record<string, string>) => void;
+    setHeader: (key: string, value: string) => void;
+    getHeader: (key: string) => string | undefined;
+    write: (chunk: Uint8Array | string) => boolean;
+    end: (body?: Uint8Array | string) => void;
+}
+interface ShimContext {
+    req: ShimRequest;
+    res: ShimResponse;
+    /** Resolves to a Web Standard Response once `res.end()` is called. */
+    toResponse: () => Promise<Response>;
+}
+interface CreateWebShimOptions {
+    /**
+     * CR-018 fix: how to resolve the client IP from forwarded headers.
+     *
+     * - `'platform'` (default for `cf-connecting-ip`): trust runtime-injected
+     *   headers only (`cf-connecting-ip` on Cloudflare, `x-real-ip` on
+     *   Netlify/Vercel when the platform writes it). Ignores
+     *   `x-forwarded-for` because clients can spoof it.
+     * - `'trusted-proxy'`: read the **rightmost** entry of `x-forwarded-for`.
+     *   Only safe when the request literally went through a trusted proxy
+     *   that strips client-set headers and appends the real client IP last.
+     * - `'none'`: skip all forwarded-header lookups and report
+     *   `'0.0.0.0'`. Force this when the adapter has no reliable way to
+     *   identify the client (rate-limiters then must use a different key).
+     *
+     * Default: `'platform'`.
+     */
+    trustedProxy?: 'platform' | 'trusted-proxy' | 'none';
+}
+/**
+ * Build Node-style req/res objects around a Web Standard Request.
+ * `toResponse()` returns a Promise that resolves when `res.end()` has been
+ * invoked, materializing a Web Standard Response with the accumulated body
+ * + headers + status.
+ */
+declare function createWebShim(request: Request, options?: CreateWebShimOptions): ShimContext;
+
+export { type CreateWebShimOptions, type ShimContext, type ShimRequest, type ShimResponse, createWebShim };

package/dist/adapters/ws-shim.d.ts

@@ -0,0 +1,55 @@
+/**
+ * T3.1 — WebSocket cross-runtime bridges.
+ *
+ * Exports 4 bridges (Node `ws` package, Bun.serve, Deno.upgradeWebSocket,
+ * Cloudflare WebSocketPair) that adapt each runtime's native WebSocket API
+ * to a common `WebSocketLike` interface that user handlers (`defineWebSocket`)
+ * can consume uniformly.
+ */
+interface WebSocketLike {
+    send(data: string | Uint8Array | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    on(event: 'message' | 'close' | 'error', cb: (data?: unknown) => void): void;
+}
+interface WsHandler {
+    onOpen?: (ws: WebSocketLike) => void;
+    onMessage?: (ws: WebSocketLike, data: unknown) => void;
+    onClose?: (ws: WebSocketLike, code?: number, reason?: string) => void;
+    onError?: (ws: WebSocketLike, err: unknown) => void;
+}
+interface NodeWsLike {
+    on(event: string, cb: (arg?: unknown) => void): unknown;
+    send(data: unknown): void;
+    close(code?: number, reason?: string): void;
+}
+declare function createNodeWsBridge(handler: WsHandler): {
+    attach(nativeWs: NodeWsLike): WebSocketLike;
+};
+interface BunWsContext {
+    send(data: unknown): void;
+    close(code?: number, reason?: string): void;
+}
+interface BunWebSocketConfig {
+    open: (ws: BunWsContext) => void;
+    message: (ws: BunWsContext, message: unknown) => void;
+    close: (ws: BunWsContext, code?: number, reason?: string) => void;
+}
+declare function createBunWsBridge(handler: WsHandler): BunWebSocketConfig;
+interface DenoLike {
+    upgradeWebSocket(req: Request): {
+        response: Response;
+        socket: {
+            send(data: unknown): void;
+            close(code?: number, reason?: string): void;
+            addEventListener(event: string, cb: (e: unknown) => void): void;
+        };
+    };
+}
+declare function createDenoWsBridge(handler: WsHandler, denoNs: DenoLike): {
+    handle(request: Request): Response;
+};
+declare function createCloudflareWsBridge(handler: WsHandler): {
+    handle(request: Request): Response;
+};
+
+export { type BunWebSocketConfig, type WebSocketLike, type WsHandler, createBunWsBridge, createCloudflareWsBridge, createDenoWsBridge, createNodeWsBridge };

package/dist/agent-events-DosDXkSV.d.ts

@@ -0,0 +1,94 @@
+/**
+ * core/contracts/agent-events.ts
+ *
+ * Canonical home for the AgentEvent wire-format contract (T2.2 of
+ * architecture-cleanup plan; ADR-0001 v3 invariant #3 exception).
+ *
+ * Server emits via SSE; client consumes. Discriminated union by `type`.
+ * Both `server/agent/*` and `client/*` import from here.
+ *
+ * Per ADR-0001 v3: `cache → core/contracts`, `client → core/contracts`,
+ * `devtools → core/contracts` are LEGAL direct imports (this is the
+ * documented exception to the `no-cross-module-deep-import` rule).
+ */
+/**
+ * Discriminated union for AgentRunError codes (Phase 1 — Production-Readiness #3).
+ *
+ * Mirrors `@theokit/sdk`'s `AgentRunErrorCode` without hard-importing the SDK
+ * type (D2 decoupling). EC-7 forward-compat: `(string & {})` fallback preserves
+ * autocompletion for the known codes while accepting future codes the SDK may
+ * introduce — autocomplete works AND TS doesn't reject unknown codes.
+ */
+type AgentRunErrorCode = 'auth' | 'rate_limit' | 'quota_exceeded' | 'invalid_model' | 'invalid_request' | 'invalid_input' | 'context_too_large' | 'safety_blocked' | 'provider_unreachable' | 'tool_runtime_error' | 'aborted' | 'unknown' | (string & {});
+interface AgentMessageEvent {
+    type: 'message';
+    content: string;
+    /** Optional id for client-side dedup / animation keys. */
+    id?: string;
+}
+interface AgentToolCallEvent {
+    type: 'tool_call';
+    name: string;
+    args: Record<string, unknown>;
+    id?: string;
+}
+interface AgentToolResultEvent {
+    type: 'tool_result';
+    name: string;
+    data: unknown;
+    id?: string;
+}
+/**
+ * Error event emitted via SSE.
+ *
+ * Phase 1 — Production-Readiness #3:
+ *   New optional fields `code/provider/retriable/retryAfterMs` discriminate
+ *   error classes for client-side handling (auth → sign-in CTA; rate_limit →
+ *   countdown; quota_exceeded → upsell; etc.).
+ *
+ * Backward compat (D4): all new fields are optional. Existing clients that
+ * read only `event.message` keep working unchanged. New clients can safely
+ * `switch (event.code)` — `undefined` (legacy server) is a valid case.
+ *
+ * EC-15 (DOCUMENT): `message` is *trusted* to not contain secrets. SDK's
+ * `AgentRunError.message` is propagated verbatim. The SDK's `providerError`
+ * is NEVER serialized into this event — quarantined to prevent leakage.
+ */
+interface AgentErrorEvent {
+    type: 'error';
+    message: string;
+    id?: string;
+    /** Discriminated error class — see AgentRunErrorCode. */
+    code?: AgentRunErrorCode;
+    /** Provider id (e.g., 'openai', 'anthropic', 'openrouter'). */
+    provider?: string;
+    /** Whether the SAME request can be retried as-is. */
+    retriable?: boolean;
+    /** Hint from provider's Retry-After header (milliseconds). Zero is valid (immediate retry). */
+    retryAfterMs?: number;
+}
+/**
+ * Extended thinking / reasoning event.
+ *
+ * Carries the model's reasoning text (when the model supports extended
+ * thinking). Mirrors the `@theokit/agents` stream-layer `ThinkingEvent`
+ * (`packages/agents/src/bridge/agent-stream-events.ts`) so the two layers
+ * agree on the wire form; defined here (not imported) to keep `core/contracts`
+ * free of a dependency on `@theokit/agents` (G1 dependency direction).
+ *
+ * Consumers that switch only on the other variants are unaffected (additive);
+ * a consumer that wants to surface reasoning opts in by handling `'thinking'`.
+ */
+interface AgentThinkingEvent {
+    type: 'thinking';
+    content: string;
+    /** Optional id for client-side dedup / animation keys. */
+    id?: string;
+}
+/**
+ * Runtime AgentEvent — discriminated union of the 5 variants emitted by
+ * agent endpoints. Server produces; client consumes.
+ */
+type AgentEvent = AgentMessageEvent | AgentToolCallEvent | AgentToolResultEvent | AgentErrorEvent | AgentThinkingEvent;
+
+export type { AgentEvent as A, AgentErrorEvent as a, AgentMessageEvent as b, AgentThinkingEvent as c, AgentToolCallEvent as d, AgentToolResultEvent as e, AgentRunErrorCode as f };

package/dist/audit-log-BQWM5YLG.d.ts

@@ -0,0 +1,60 @@
+/**
+ * T4.1 — Audit logging interface + default JSON stdout sink.
+ *
+ * Per ADR D4: define the interface; ship a zero-dep default; reserve
+ * adapter shapes for Postgres, File, OpenTelemetry, Sentry as follow-up
+ * packages. Persistence has heavy deps (`pg`, `better-sqlite3`); we
+ * keep core dep-free and let users opt in.
+ *
+ * Compatibility:
+ *   - Node / Bun / Deno / Vercel — console.log is sync, captured.
+ *   - Edge runtimes (CF Workers, Vercel Edge) — console.log is captured
+ *     but may be rate-limited by the platform. For high-volume edge audit,
+ *     implement a custom sink writing to a queue / HTTP endpoint.
+ */
+interface AuditEvent {
+    /** Domain-qualified verb. Convention: `<domain>.<verb>` (e.g. csrf.warn, session.rotated). */
+    action: string;
+    /** Who triggered the event. Anonymous = no auth at time of event. */
+    actor?: {
+        type: 'user' | 'system' | 'anonymous';
+        id?: string;
+    };
+    /** What was operated on (optional). */
+    resource?: {
+        type: string;
+        id?: string;
+    };
+    /** Arbitrary event-specific metadata. JSON-serializable. */
+    metadata?: Record<string, unknown>;
+    /** ISO 8601 timestamp. If absent, sink fills in `new Date().toISOString()`. */
+    timestamp?: string;
+    /** Optional trace id (populated by middleware from `x-trace-id`). */
+    traceId?: string;
+}
+interface AuditLogger {
+    log(event: AuditEvent): void | Promise<void>;
+}
+/**
+ * Default sink: one JSON line per event to stdout. Sync. Never throws.
+ *
+ * EC: circular refs / BigInt values fall back to a placeholder line so
+ * the event is still observable (action + traceId) without crashing the
+ * request lifecycle.
+ */
+declare class JsonStdoutSink implements AuditLogger {
+    log(event: AuditEvent): void;
+}
+/**
+ * No-op logger. Returned when `config.audit` is unset. Zero overhead;
+ * framework wiring sites null-check before calling.
+ */
+declare function createNoOpLogger(): AuditLogger;
+/**
+ * T4.2 — Safe-emit wrapper. Used by framework wiring sites (csrf.ts,
+ * rate-limit.ts, session.ts) so a logger throw NEVER propagates into
+ * the request handler.
+ */
+declare function safeAudit(logger: AuditLogger | undefined, event: AuditEvent): void;
+
+export { type AuditLogger as A, JsonStdoutSink as J, type AuditEvent as a, createNoOpLogger as c, safeAudit as s };

package/dist/boot/index.d.ts

@@ -0,0 +1,39 @@
+import { R as ReservedRoutes } from '../health-route-C0hk64_U.js';
+
+/**
+ * M7-3 — `theokit/boot`: programmatic boot surface for the convention server.
+ *
+ * The programmatic surface is a Web `fetch` handler (the universal "fetch
+ * handler is the entry point" contract — see the hono reference in
+ * knowledge-base/discoveries/blueprints/m7-http-dual-surface-blueprint.md
+ * "Coverage Corner 4"). It composes M7-1 (typed 404 envelope) + M7-2 (reserved
+ * health/ready routes) and binds NO socket, so embedders + integration tests
+ * can fire requests in-process via `app.fetch(new Request(...))`.
+ *
+ * The CLI's `startDevServer`/`startCommand` (Vite/SSR machinery) intentionally
+ * stay in the `cli` module — `boot` must not depend on `cli` (architecture DAG:
+ * nothing depends on `cli`). The fetch handler IS the portable boot surface.
+ *
+ * @public
+ */
+
+/** Options for {@link createConventionFetchHandler}. */
+interface ConventionFetchHandlerOptions {
+    /** Reserved health/ready routes (M7-2). Liveness defaults to 200 even when omitted. */
+    readonly reservedRoutes?: ReservedRoutes;
+}
+/** A socketless convention-server handle. */
+interface ConventionFetchHandle {
+    /** Serve a single request in-process (no socket). Reserved routes first, else a typed 404. */
+    fetch(request: Request): Promise<Response>;
+    /** Idempotent teardown. The in-process handler holds no socket, so this is a safe no-op. */
+    close(): Promise<void>;
+}
+/**
+ * Build an in-process convention-server `fetch` handler. Reserved `/__theo/*`
+ * routes (health/ready) are served first; any other path yields a typed
+ * `NOT_FOUND` envelope (404) via the same translator the wire boundary uses.
+ */
+declare function createConventionFetchHandler(options?: ConventionFetchHandlerOptions): ConventionFetchHandle;
+
+export { type ConventionFetchHandle, type ConventionFetchHandlerOptions, createConventionFetchHandler };

package/dist/client/index.d.ts

@@ -0,0 +1,362 @@
+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 * 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>;
+
+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 UseAgentStreamOptions, type UseAgentStreamReturn, type UseAgentToolCardsReturn, consumeAgentStream, createAppClient, createBatcher, defaultResolveEnvelope, deriveError, deriveLiveText, foldAgentToolCards, parseSSEChunk, theoFetch, useAgentStream, useAgentToolCards };