theokit 0.29.0 → 0.30.0

package/dist/{chunk-H243MR3F.js → chunk-TGTNRUH3.js}

@@ -7,7 +7,7 @@ import {
 import {
   parseRequestBody,
   warnOnce
-} from "./chunk-Z5IGLBWE.js";
+} from "./chunk-WFNLNIJX.js";
 import {
   scanMiddlewares
 } from "./chunk-ZEGYW52B.js";
@@ -1393,4 +1393,4 @@ export {
   extractTraceId,
   extractTraceIdFromRequest
 };
-//# sourceMappingURL=chunk-H243MR3F.js.map
+//# sourceMappingURL=chunk-TGTNRUH3.js.map

package/dist/{chunk-W4XWVTN4.js → chunk-UYFZ6DDW.js}

@@ -1,6 +1,6 @@
 import {
   isZodLike
-} from "./chunk-H243MR3F.js";
+} from "./chunk-TGTNRUH3.js";
 import {
   validateCsrfRequest
 } from "./chunk-TSLSIRBR.js";
@@ -642,4 +642,4 @@ export {
   validateRouteInput,
   executeWebRequest
 };
-//# sourceMappingURL=chunk-W4XWVTN4.js.map
+//# sourceMappingURL=chunk-UYFZ6DDW.js.map

package/dist/{chunk-Z5IGLBWE.js → chunk-WFNLNIJX.js}

@@ -326,4 +326,4 @@ export {
   _resetWarnOnceForTests,
   warnOnce
 };
-//# sourceMappingURL=chunk-Z5IGLBWE.js.map
+//# sourceMappingURL=chunk-WFNLNIJX.js.map

package/dist/client/core.d.ts

@@ -0,0 +1,294 @@
+import { ChatTransport, UIMessage, UIMessageChunk } from 'ai';
+
+/**
+ * M41 (ADR-0050 D2) — a HITL approval decision sent to settle a paused gated-tool call. Mirrors the
+ * `POST /api/agents/<name>/approve/<id>` wire body (`approve-agent.ts` `parseApprovalBody`). Defined
+ * on the client side (not imported from `server/`) as the client's view of the boundary contract.
+ */
+interface ApprovalDecision {
+    /** Whether the paused gated tool may proceed. */
+    approved: boolean;
+    /** Optional reason surfaced to the model on denial. */
+    reason?: string;
+    /** Optional small structured note (edited args, a reviewer comment) — capped server-side at 16 KiB. */
+    payload?: unknown;
+}
+/**
+ * M43 (ADR-0052) — per-request context attached uniformly across every transport.
+ *
+ * `headers` is the serializable, HTTP-native half (an auth token → request headers on `HttpTransport`);
+ * `metadata` is the structured, same-process half forwarded to the in-process runner
+ * (`InProcessTransport`) / the Tauri `invoke` (`ChannelTransport`). Threaded through the seam's existing
+ * `ChatRequestOptions` — NOT a new channel. The turn input stays the request `body`.
+ */
+interface RequestContext {
+    /** Per-request headers (e.g. auth). HTTP-native; mapped to request headers by `HttpTransport`. */
+    headers?: Record<string, string>;
+    /** Structured per-request context (tenant, provider, …) forwarded to in-process / channel runners. */
+    metadata?: unknown;
+}
+/**
+ * M41 (ADR-0050 D1/D2) — the client transport seam.
+ *
+ * It IS `ai`'s `ChatTransport<UIMessage>` (the adopted SOTA interface — we do NOT invent a parallel
+ * one) plus ONE optional method, `approve`, for TheoKit's OUT-OF-BAND HITL (the server pauses the run;
+ * the client settles it via a separate call). `ai`'s `ChatTransport` has no `approve` because its HITL
+ * is in-band (a re-sent message part); ours is out-of-band, and the settle route differs per transport
+ * (HTTP `POST /approve/<id>` vs an inline callback), so it belongs on the transport. `approve` is
+ * optional — agents without gated tools never settle an approval.
+ *
+ * `HttpTransport` (web) and `InProcessTransport` (TUI/desktop) implement this; `useAgent` drives it.
+ */
+type AgentTransport = ChatTransport<UIMessage> & {
+    approve?(approvalId: string, decision: ApprovalDecision): Promise<void>;
+};
+
+type UseAgentStatus = 'idle' | 'streaming' | 'done' | 'error';
+/** The observable state the store exposes (stable reference between emits — `useSyncExternalStore` contract). */
+interface AgentClientState {
+    messages: UIMessage[];
+    status: UseAgentStatus;
+    error: Error | undefined;
+}
+/**
+ * M41 (ADR-0050 D6) — the framework-agnostic agent client store.
+ *
+ * Holds `messages`/`status`/`error`, drives an {@link AgentTransport}, and notifies subscribers on
+ * change. It is the SINGLE consolidation point: web (`HttpTransport`) and terminal/desktop
+ * (`InProcessTransport`) run the SAME store. `useAgent` is a thin React binding over it via
+ * `useSyncExternalStore`; a standalone (no-React) client (M44) can subscribe directly. Being
+ * framework-agnostic, it is unit-tested without a DOM.
+ */
+declare class AgentClient<TInput = unknown> {
+    #private;
+    constructor(transport: AgentTransport, contextResolver?: () => RequestContext | undefined);
+    /** Subscribe to state changes; returns an unsubscribe fn. */
+    subscribe: (listener: () => void) => (() => void);
+    /** The current immutable snapshot (stable reference until the next emit). */
+    getSnapshot: () => AgentClientState;
+    /** Send a typed input; opens a fresh stream (replaces prior messages). */
+    send: (input: TInput) => void;
+    /** Resume an interrupted stream via the transport's `reconnectToStream` (no-op when unavailable). */
+    reconnect: () => void;
+    /** Abort an in-flight stream (not an error — leaves messages as-is). */
+    abort: () => void;
+    /** Clear messages + error, back to idle. */
+    reset: () => void;
+    /** Settle a paused HITL approval via the transport's HITL path (HTTP POST or inline callback). */
+    approve: (approvalId: string, decision: ApprovalDecision) => Promise<void>;
+}
+
+interface CreateAgentClientOptions {
+    /**
+     * M43 — per-request context attached to every turn (`headers` → HTTP; `metadata` → in-process/channel).
+     * A value OR a resolver. **To keep context live across sends, pass a RESOLVER** (`() => ({...})`) — a
+     * plain value is captured at construction and not re-read, so mutating `options.context` afterwards has
+     * no effect (unlike `useAgent`, which reads a live ref). A resolver is re-evaluated every send/reconnect.
+     */
+    context?: RequestContext | (() => RequestContext | undefined);
+}
+/**
+ * M44 (ADR-0053) — the standalone (no-React) agent client. A plain handle over the framework-agnostic
+ * {@link AgentClient} store: drive a turn, observe state, settle HITL — from a node script, a CLI, a
+ * test, or a non-React UI, over ANY {@link AgentTransport}.
+ */
+interface AgentClientHandle<TInput = unknown> {
+    /** Send a typed input; opens a fresh stream (replaces prior messages). */
+    send(input: TInput): void;
+    /** Abort an in-flight stream. */
+    abort(): void;
+    /** Clear messages + error, back to idle. */
+    reset(): void;
+    /** Settle a paused HITL approval via the transport's HITL path. */
+    approve(approvalId: string, decision: ApprovalDecision): Promise<void>;
+    /** Resume an interrupted stream (no-op when the transport can't). */
+    reconnect(): void;
+    /** Subscribe to state changes; returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** The current immutable snapshot (messages / status / error). */
+    getState(): AgentClientState;
+    /**
+     * Drive one turn and yield the assistant `UIMessage` as it streams (progressive snapshots); iteration
+     * ends when the turn settles. A `for await` script takes the last yielded value as the final result;
+     * a failed turn rejects the iterator with the run error.
+     */
+    stream(input: TInput): AsyncIterable<UIMessage>;
+}
+/**
+ * Create a standalone (no-React) agent client over a transport. `useAgent` is the React binding over the
+ * same store; this is the equivalent for any JS runtime — one agent, consumable everywhere on the seam.
+ */
+declare function createAgentClient<TInput = unknown>(transport: AgentTransport, options?: CreateAgentClientOptions): AgentClientHandle<TInput>;
+
+/** Extra request headers — a static record OR a resolver called per request (for dynamic auth). */
+type HeadersResolver = Record<string, string> | (() => Record<string, string> | undefined);
+interface HttpTransportOptions {
+    /** Agent endpoint path or URL, e.g. `/api/agents/support`. */
+    api: string;
+    /**
+     * Extra request headers (e.g. auth). Static record OR a resolver evaluated on EVERY request — pass a
+     * resolver when the value is dynamic (a rotating JWT), so a stale header is never sent. Merged UNDER
+     * per-request headers.
+     */
+    headers?: HeadersResolver;
+    /** Override fetch (primarily for tests / non-browser hosts) — static; resolved once at construction. */
+    fetch?: typeof fetch;
+}
+/**
+ * M41 (ADR-0050 D3) — `ChatTransport` over the web agent path.
+ *
+ * - `sendMessages`: `POST <api>` with the UIMessageStream `accept` + the `X-Theo-Action` CSRF header
+ *   (HTTP method + headers are identical to the pre-M41 `useAgent` fetch; the body shape is a superset —
+ *   `{ ...input, messages: [UIMessage] }` — which the server's dual-path parser accepts, so no
+ *   regression), captures the server-minted `x-theokit-run-id`, and returns `ReadableStream<UIMessageChunk>`
+ *   via `ai`'s own SSE parser (`responseToChunkStream`).
+ * - `reconnectToStream`: `GET <api>/runs/<runId>/stream` (M37 durable transport); 404 → `null` (the run
+ *   completed / was evicted). A caller may pass a `Last-Event-ID` header to resume only the tail; by
+ *   default the server replays the run from the start and the client upserts by message id (idempotent).
+ * - `approve`: `POST <api>/approve/<id>` (out-of-band HITL settle).
+ *
+ * Implemented directly (not by subclassing `DefaultChatTransport`) because reconnect keys on our
+ * server-minted `runId` captured from a response header, which the base class does not expose — see
+ * ADR-0050 D3.
+ */
+declare class HttpTransport implements AgentTransport {
+    #private;
+    constructor(options: HttpTransportOptions);
+    sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
+    reconnectToStream(options: Parameters<ChatTransport<UIMessage>['reconnectToStream']>[0]): Promise<ReadableStream<UIMessageChunk> | null>;
+    approve(approvalId: string, decision: ApprovalDecision): Promise<void>;
+}
+
+/** An inline approval request handed to the transport's resolver (structural — no server import). */
+interface InProcessApprovalRequestLike {
+    approvalId: string;
+    toolName: string;
+    opts: unknown;
+}
+/** Resolve one gated-tool approval inline (mirrors the SDK's `boolean | HitlDecision` return). */
+type InProcessAwaitApproval = (req: InProcessApprovalRequestLike) => Promise<boolean | ApprovalDecision>;
+/** The input the injected runner receives (structurally compatible with `StreamAgentTurnInProcessInput`). */
+interface InProcessRunInput {
+    message: string;
+    sessionId?: string;
+    signal?: AbortSignal;
+    awaitApproval?: InProcessAwaitApproval;
+    /** M43 — per-request context (from `sendMessages`'s `metadata`) — tenant / provider / auth for the runner. */
+    context?: unknown;
+}
+/**
+ * The in-process turn runner. The consumer binds `streamAgentTurnInProcess(mod, apiKey, …)`:
+ * `new InProcessTransport({ run: (input) => streamAgentTurnInProcess(mod, apiKey, input) })`.
+ * Injecting it keeps this client module decoupled from `server/` and makes the transport testable.
+ */
+type InProcessRunner = (input: InProcessRunInput) => AsyncGenerator<UIMessageChunk>;
+interface InProcessTransportOptions {
+    run: InProcessRunner;
+}
+/**
+ * M41 (ADR-0050 D4) — `ChatTransport` over the in-process seam (`streamAgentTurnInProcess`), for the
+ * terminal/desktop surfaces that run client + server in ONE process (no HTTP loopback).
+ *
+ * - `sendMessages`: bridge the injected runner's `AsyncGenerator<UIMessageChunk>` into a
+ *   `ReadableStream<UIMessageChunk>` (honoring `abortSignal`, which the runner forwards to the SDK).
+ * - `reconnectToStream`: always `null` — a single process has no dropped server-side stream to resume
+ *   (mirrors `ai`'s `DirectChatTransport`).
+ * - `approve`: resolve the pending inline approval by id (the run parks on `awaitApproval`). An unknown
+ *   id rejects (fail-fast, Rule 8 — never a silent resolve).
+ *
+ * Error asymmetry vs `HttpTransport` (by design, matching the `ChatTransport` contract): a runner that
+ * throws SYNCHRONOUSLY surfaces the error when the stream is READ (via `controller.error`), not from the
+ * `sendMessages` promise — whereas `HttpTransport` throws from `sendMessages` on a non-2xx response.
+ */
+declare class InProcessTransport implements AgentTransport {
+    #private;
+    constructor(options: InProcessTransportOptions);
+    sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
+    reconnectToStream(): Promise<ReadableStream<UIMessageChunk> | null>;
+    approve(approvalId: string, decision: ApprovalDecision): Promise<void>;
+}
+
+/** Handlers the transport hands to the injected push source for one turn. */
+interface ChannelTurnHandlers {
+    /** One pushed JSONL line (a serialized `UIMessageChunk`). */
+    onLine: (line: string) => void;
+    /** The turn ended — no more lines. */
+    onClose: () => void;
+    /** The push source failed. */
+    onError?: (err: unknown) => void;
+}
+/**
+ * The injected push source — a Tauri `Channel`/`invoke` bridge, kept STRUCTURAL so core adds no
+ * `@tauri-apps/*` dependency and the transport is testable with a fake (ADR-0051 D2). The Tauri app
+ * wires it: `new Channel()`, `channel.onmessage = onLine`, `invoke('run_agent', { message, channel })`,
+ * returning a teardown that aborts the sidecar turn.
+ */
+interface ChannelPushSource {
+    /**
+     * Start a turn; deliver each JSONL `UIMessageChunk` line to `onLine`, then `onClose`. Return a teardown.
+     * `turn.context` (M43) is the per-request context (from the seam's `metadata`) — the Tauri `invoke`
+     * forwards it to the sidecar. When no context is set it is present as `context: undefined` (the key is
+     * NOT absent) — a sidecar that checks `'context' in turn` should treat `undefined` as "no context".
+     */
+    start(turn: {
+        message: string;
+        context?: unknown;
+    }, handlers: ChannelTurnHandlers): () => void;
+    /** Optional HITL settle (another Tauri `invoke`). */
+    settle?(approvalId: string, decision: ApprovalDecision): Promise<void>;
+}
+interface ChannelTransportOptions {
+    source: ChannelPushSource;
+}
+/**
+ * M42 (ADR-0051) — `ChatTransport` over a Tauri-`Channel`-shaped push source, for the desktop webview.
+ *
+ * - `sendMessages`: start the turn via the injected source and bridge its pushed JSONL frames into a
+ *   `ReadableStream<UIMessageChunk>` (built in `start` — a Channel is push, so the stream's queue buffers
+ *   frames; ADR-0051 D3). A malformed JSONL line is SKIPPED, never fatal (ADR-0051 D4, Rule 8). `abortSignal`
+ *   tears down the source and closes the stream.
+ * - `reconnectToStream`: always `null` — the M36 sidecar runs the turn directly (no durable server stream);
+ *   this is the honest parity for a single-process push surface (ADR-0051 D5; mirrors `InProcessTransport`).
+ * - `approve`: routes to the injected `settle` (another Tauri `invoke`); absent `settle` → a typed error.
+ *
+ * The push source is INJECTED — core stays Tauri-agnostic and this transport is unit-tested with a fake.
+ */
+declare class ChannelTransport implements AgentTransport {
+    #private;
+    constructor(options: ChannelTransportOptions);
+    sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
+    reconnectToStream(): Promise<ReadableStream<UIMessageChunk> | null>;
+    approve(approvalId: string, decision: ApprovalDecision): 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>;
+/**
+ * M41 (ADR-0050 D3) — the reusable middle piece: a UIMessageStream SSE `Response` →
+ * `ReadableStream<UIMessageChunk>`, reusing `ai`'s own `parseJsonEventStream` (the exact primitive
+ * `useChat` runs). This is precisely what a `ChatTransport.sendMessages` returns, so `HttpTransport`
+ * builds on it directly (no reinvented wire parser — Rule 9). A body-less response yields an empty stream.
+ */
+declare function responseToChunkStream(response: Response): Promise<ReadableStream<UIMessageChunk>>;
+/**
+ * M41 (ADR-0050 D6) — read a `ReadableStream<UIMessageChunk>` into reconstructed assistant
+ * `UIMessage`s via `ai`'s `readUIMessageStream`. Shared by `consumeUIMessageStream` (Response path)
+ * and the framework-agnostic `AgentClient` store (transport path). `onMessage` fires on every
+ * reconstruction step so a caller can render streaming updates.
+ */
+declare function consumeChunkStream(stream: ReadableStream<UIMessageChunk>, onMessage: (message: UIMessage) => void): Promise<void>;
+
+export { AgentClient, type AgentClientHandle, type AgentClientState, type AgentTransport, type ApprovalDecision, type ChannelPushSource, ChannelTransport, type ChannelTransportOptions, type ChannelTurnHandlers, type CreateAgentClientOptions, type HeadersResolver, HttpTransport, type HttpTransportOptions, type InProcessApprovalRequestLike, type InProcessAwaitApproval, type InProcessRunInput, type InProcessRunner, InProcessTransport, type InProcessTransportOptions, type RequestContext, type UseAgentStatus, consumeChunkStream, consumeUIMessageStream, createAgentClient, responseToChunkStream };

package/dist/client/core.js

@@ -0,0 +1,22 @@
+import {
+  AgentClient,
+  ChannelTransport,
+  HttpTransport,
+  InProcessTransport,
+  consumeChunkStream,
+  consumeUIMessageStream,
+  createAgentClient,
+  responseToChunkStream
+} from "../chunk-RBRDTYOO.js";
+import "../chunk-DGUM43GV.js";
+export {
+  AgentClient,
+  ChannelTransport,
+  HttpTransport,
+  InProcessTransport,
+  consumeChunkStream,
+  consumeUIMessageStream,
+  createAgentClient,
+  responseToChunkStream
+};
+//# sourceMappingURL=core.js.map

package/dist/client/index.d.ts

@@ -1,7 +1,9 @@
 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 { UIMessageChunk, UIMessage, ChatTransport } from 'ai';
+import { RequestContext, UseAgentStatus, ApprovalDecision, AgentTransport } from './core.js';
+export { AgentClient, AgentClientHandle, AgentClientState, ChannelPushSource, ChannelTransport, ChannelTransportOptions, ChannelTurnHandlers, CreateAgentClientOptions, HttpTransport, HttpTransportOptions, InProcessApprovalRequestLike, InProcessAwaitApproval, InProcessRunInput, InProcessRunner, InProcessTransport, InProcessTransportOptions, consumeChunkStream, consumeUIMessageStream, createAgentClient, responseToChunkStream } from './core.js';
+import { UIMessage } from 'ai';
 import * as react from 'react';
 import { LinkProps as LinkProps$1 } from 'react-router';
 
@@ -115,114 +117,6 @@ interface Batcher {
 }
 declare function createBatcher(options: BatcherOptions): Batcher;
 
-/**
- * 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>;
-/**
- * M41 (ADR-0050 D3) — the reusable middle piece: a UIMessageStream SSE `Response` →
- * `ReadableStream<UIMessageChunk>`, reusing `ai`'s own `parseJsonEventStream` (the exact primitive
- * `useChat` runs). This is precisely what a `ChatTransport.sendMessages` returns, so `HttpTransport`
- * builds on it directly (no reinvented wire parser — Rule 9). A body-less response yields an empty stream.
- */
-declare function responseToChunkStream(response: Response): Promise<ReadableStream<UIMessageChunk>>;
-/**
- * M41 (ADR-0050 D6) — read a `ReadableStream<UIMessageChunk>` into reconstructed assistant
- * `UIMessage`s via `ai`'s `readUIMessageStream`. Shared by `consumeUIMessageStream` (Response path)
- * and the framework-agnostic `AgentClient` store (transport path). `onMessage` fires on every
- * reconstruction step so a caller can render streaming updates.
- */
-declare function consumeChunkStream(stream: ReadableStream<UIMessageChunk>, onMessage: (message: UIMessage) => void): Promise<void>;
-
-/**
- * M41 (ADR-0050 D2) — a HITL approval decision sent to settle a paused gated-tool call. Mirrors the
- * `POST /api/agents/<name>/approve/<id>` wire body (`approve-agent.ts` `parseApprovalBody`). Defined
- * on the client side (not imported from `server/`) as the client's view of the boundary contract.
- */
-interface ApprovalDecision {
-    /** Whether the paused gated tool may proceed. */
-    approved: boolean;
-    /** Optional reason surfaced to the model on denial. */
-    reason?: string;
-    /** Optional small structured note (edited args, a reviewer comment) — capped server-side at 16 KiB. */
-    payload?: unknown;
-}
-/**
- * M43 (ADR-0052) — per-request context attached uniformly across every transport.
- *
- * `headers` is the serializable, HTTP-native half (an auth token → request headers on `HttpTransport`);
- * `metadata` is the structured, same-process half forwarded to the in-process runner
- * (`InProcessTransport`) / the Tauri `invoke` (`ChannelTransport`). Threaded through the seam's existing
- * `ChatRequestOptions` — NOT a new channel. The turn input stays the request `body`.
- */
-interface RequestContext {
-    /** Per-request headers (e.g. auth). HTTP-native; mapped to request headers by `HttpTransport`. */
-    headers?: Record<string, string>;
-    /** Structured per-request context (tenant, provider, …) forwarded to in-process / channel runners. */
-    metadata?: unknown;
-}
-/**
- * M41 (ADR-0050 D1/D2) — the client transport seam.
- *
- * It IS `ai`'s `ChatTransport<UIMessage>` (the adopted SOTA interface — we do NOT invent a parallel
- * one) plus ONE optional method, `approve`, for TheoKit's OUT-OF-BAND HITL (the server pauses the run;
- * the client settles it via a separate call). `ai`'s `ChatTransport` has no `approve` because its HITL
- * is in-band (a re-sent message part); ours is out-of-band, and the settle route differs per transport
- * (HTTP `POST /approve/<id>` vs an inline callback), so it belongs on the transport. `approve` is
- * optional — agents without gated tools never settle an approval.
- *
- * `HttpTransport` (web) and `InProcessTransport` (TUI/desktop) implement this; `useAgent` drives it.
- */
-type AgentTransport = ChatTransport<UIMessage> & {
-    approve?(approvalId: string, decision: ApprovalDecision): Promise<void>;
-};
-
-type UseAgentStatus = 'idle' | 'streaming' | 'done' | 'error';
-/** The observable state the store exposes (stable reference between emits — `useSyncExternalStore` contract). */
-interface AgentClientState {
-    messages: UIMessage[];
-    status: UseAgentStatus;
-    error: Error | undefined;
-}
-/**
- * M41 (ADR-0050 D6) — the framework-agnostic agent client store.
- *
- * Holds `messages`/`status`/`error`, drives an {@link AgentTransport}, and notifies subscribers on
- * change. It is the SINGLE consolidation point: web (`HttpTransport`) and terminal/desktop
- * (`InProcessTransport`) run the SAME store. `useAgent` is a thin React binding over it via
- * `useSyncExternalStore`; a standalone (no-React) client (M44) can subscribe directly. Being
- * framework-agnostic, it is unit-tested without a DOM.
- */
-declare class AgentClient<TInput = unknown> {
-    #private;
-    constructor(transport: AgentTransport, contextResolver?: () => RequestContext | undefined);
-    /** Subscribe to state changes; returns an unsubscribe fn. */
-    subscribe: (listener: () => void) => (() => void);
-    /** The current immutable snapshot (stable reference until the next emit). */
-    getSnapshot: () => AgentClientState;
-    /** Send a typed input; opens a fresh stream (replaces prior messages). */
-    send: (input: TInput) => void;
-    /** Resume an interrupted stream via the transport's `reconnectToStream` (no-op when unavailable). */
-    reconnect: () => void;
-    /** Abort an in-flight stream (not an error — leaves messages as-is). */
-    abort: () => void;
-    /** Clear messages + error, back to idle. */
-    reset: () => void;
-    /** Settle a paused HITL approval via the transport's HITL path (HTTP POST or inline callback). */
-    approve: (approvalId: string, decision: ApprovalDecision) => Promise<void>;
-}
-
 interface UseAgentReturn<TInput = unknown, TToolNames extends string = string> {
     /** Reconstructed assistant messages so far (ai `UIMessage[]`). */
     messages: UIMessage[];
@@ -268,147 +162,6 @@ interface UseAgentOptions {
  */
 declare function useAgent<TInput = unknown>(pathOrTransport: string | AgentTransport, options?: UseAgentOptions): UseAgentReturn<TInput>;
 
-/** Extra request headers — a static record OR a resolver called per request (for dynamic auth). */
-type HeadersResolver = Record<string, string> | (() => Record<string, string> | undefined);
-interface HttpTransportOptions {
-    /** Agent endpoint path or URL, e.g. `/api/agents/support`. */
-    api: string;
-    /**
-     * Extra request headers (e.g. auth). Static record OR a resolver evaluated on EVERY request — pass a
-     * resolver when the value is dynamic (a rotating JWT), so a stale header is never sent. Merged UNDER
-     * per-request headers.
-     */
-    headers?: HeadersResolver;
-    /** Override fetch (primarily for tests / non-browser hosts) — static; resolved once at construction. */
-    fetch?: typeof fetch;
-}
-/**
- * M41 (ADR-0050 D3) — `ChatTransport` over the web agent path.
- *
- * - `sendMessages`: `POST <api>` with the UIMessageStream `accept` + the `X-Theo-Action` CSRF header
- *   (HTTP method + headers are identical to the pre-M41 `useAgent` fetch; the body shape is a superset —
- *   `{ ...input, messages: [UIMessage] }` — which the server's dual-path parser accepts, so no
- *   regression), captures the server-minted `x-theokit-run-id`, and returns `ReadableStream<UIMessageChunk>`
- *   via `ai`'s own SSE parser (`responseToChunkStream`).
- * - `reconnectToStream`: `GET <api>/runs/<runId>/stream` (M37 durable transport); 404 → `null` (the run
- *   completed / was evicted). A caller may pass a `Last-Event-ID` header to resume only the tail; by
- *   default the server replays the run from the start and the client upserts by message id (idempotent).
- * - `approve`: `POST <api>/approve/<id>` (out-of-band HITL settle).
- *
- * Implemented directly (not by subclassing `DefaultChatTransport`) because reconnect keys on our
- * server-minted `runId` captured from a response header, which the base class does not expose — see
- * ADR-0050 D3.
- */
-declare class HttpTransport implements AgentTransport {
-    #private;
-    constructor(options: HttpTransportOptions);
-    sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
-    reconnectToStream(options: Parameters<ChatTransport<UIMessage>['reconnectToStream']>[0]): Promise<ReadableStream<UIMessageChunk> | null>;
-    approve(approvalId: string, decision: ApprovalDecision): Promise<void>;
-}
-
-/** An inline approval request handed to the transport's resolver (structural — no server import). */
-interface InProcessApprovalRequestLike {
-    approvalId: string;
-    toolName: string;
-    opts: unknown;
-}
-/** Resolve one gated-tool approval inline (mirrors the SDK's `boolean | HitlDecision` return). */
-type InProcessAwaitApproval = (req: InProcessApprovalRequestLike) => Promise<boolean | ApprovalDecision>;
-/** The input the injected runner receives (structurally compatible with `StreamAgentTurnInProcessInput`). */
-interface InProcessRunInput {
-    message: string;
-    sessionId?: string;
-    signal?: AbortSignal;
-    awaitApproval?: InProcessAwaitApproval;
-    /** M43 — per-request context (from `sendMessages`'s `metadata`) — tenant / provider / auth for the runner. */
-    context?: unknown;
-}
-/**
- * The in-process turn runner. The consumer binds `streamAgentTurnInProcess(mod, apiKey, …)`:
- * `new InProcessTransport({ run: (input) => streamAgentTurnInProcess(mod, apiKey, input) })`.
- * Injecting it keeps this client module decoupled from `server/` and makes the transport testable.
- */
-type InProcessRunner = (input: InProcessRunInput) => AsyncGenerator<UIMessageChunk>;
-interface InProcessTransportOptions {
-    run: InProcessRunner;
-}
-/**
- * M41 (ADR-0050 D4) — `ChatTransport` over the in-process seam (`streamAgentTurnInProcess`), for the
- * terminal/desktop surfaces that run client + server in ONE process (no HTTP loopback).
- *
- * - `sendMessages`: bridge the injected runner's `AsyncGenerator<UIMessageChunk>` into a
- *   `ReadableStream<UIMessageChunk>` (honoring `abortSignal`, which the runner forwards to the SDK).
- * - `reconnectToStream`: always `null` — a single process has no dropped server-side stream to resume
- *   (mirrors `ai`'s `DirectChatTransport`).
- * - `approve`: resolve the pending inline approval by id (the run parks on `awaitApproval`). An unknown
- *   id rejects (fail-fast, Rule 8 — never a silent resolve).
- *
- * Error asymmetry vs `HttpTransport` (by design, matching the `ChatTransport` contract): a runner that
- * throws SYNCHRONOUSLY surfaces the error when the stream is READ (via `controller.error`), not from the
- * `sendMessages` promise — whereas `HttpTransport` throws from `sendMessages` on a non-2xx response.
- */
-declare class InProcessTransport implements AgentTransport {
-    #private;
-    constructor(options: InProcessTransportOptions);
-    sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
-    reconnectToStream(): Promise<ReadableStream<UIMessageChunk> | null>;
-    approve(approvalId: string, decision: ApprovalDecision): Promise<void>;
-}
-
-/** Handlers the transport hands to the injected push source for one turn. */
-interface ChannelTurnHandlers {
-    /** One pushed JSONL line (a serialized `UIMessageChunk`). */
-    onLine: (line: string) => void;
-    /** The turn ended — no more lines. */
-    onClose: () => void;
-    /** The push source failed. */
-    onError?: (err: unknown) => void;
-}
-/**
- * The injected push source — a Tauri `Channel`/`invoke` bridge, kept STRUCTURAL so core adds no
- * `@tauri-apps/*` dependency and the transport is testable with a fake (ADR-0051 D2). The Tauri app
- * wires it: `new Channel()`, `channel.onmessage = onLine`, `invoke('run_agent', { message, channel })`,
- * returning a teardown that aborts the sidecar turn.
- */
-interface ChannelPushSource {
-    /**
-     * Start a turn; deliver each JSONL `UIMessageChunk` line to `onLine`, then `onClose`. Return a teardown.
-     * `turn.context` (M43) is the per-request context (from the seam's `metadata`) — the Tauri `invoke`
-     * forwards it to the sidecar. When no context is set it is present as `context: undefined` (the key is
-     * NOT absent) — a sidecar that checks `'context' in turn` should treat `undefined` as "no context".
-     */
-    start(turn: {
-        message: string;
-        context?: unknown;
-    }, handlers: ChannelTurnHandlers): () => void;
-    /** Optional HITL settle (another Tauri `invoke`). */
-    settle?(approvalId: string, decision: ApprovalDecision): Promise<void>;
-}
-interface ChannelTransportOptions {
-    source: ChannelPushSource;
-}
-/**
- * M42 (ADR-0051) — `ChatTransport` over a Tauri-`Channel`-shaped push source, for the desktop webview.
- *
- * - `sendMessages`: start the turn via the injected source and bridge its pushed JSONL frames into a
- *   `ReadableStream<UIMessageChunk>` (built in `start` — a Channel is push, so the stream's queue buffers
- *   frames; ADR-0051 D3). A malformed JSONL line is SKIPPED, never fatal (ADR-0051 D4, Rule 8). `abortSignal`
- *   tears down the source and closes the stream.
- * - `reconnectToStream`: always `null` — the M36 sidecar runs the turn directly (no durable server stream);
- *   this is the honest parity for a single-process push surface (ADR-0051 D5; mirrors `InProcessTransport`).
- * - `approve`: routes to the injected `settle` (another Tauri `invoke`); absent `settle` → a typed error.
- *
- * The push source is INJECTED — core stays Tauri-agnostic and this transport is unit-tested with a fake.
- */
-declare class ChannelTransport implements AgentTransport {
-    #private;
-    constructor(options: ChannelTransportOptions);
-    sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
-    reconnectToStream(): Promise<ReadableStream<UIMessageChunk> | null>;
-    approve(approvalId: string, decision: ApprovalDecision): Promise<void>;
-}
-
 type PrefetchBehavior = 'none' | 'intent' | 'viewport';
 interface LinkProps extends LinkProps$1 {
     /** Prefetch strategy. Default: 'intent' (on hover + focus). */
@@ -556,4 +309,4 @@ declare function mountMcpApp(container: HTMLElement, resource: {
     html: string;
 }, opts: McpAppHostOptions): McpAppHandle;
 
-export { AgentClient, type AgentClientState, type AgentTransport, type ApprovalDecision, type BatchRequest, type BatchResponse, type BatchTransport, type Batcher, type BatcherOptions, type ChannelPushSource, ChannelTransport, type ChannelTransportOptions, type ChannelTurnHandlers, type CreateAppClientOptions, type GuestMessage, HttpTransport, type HttpTransportOptions, Image, type ImageProps, type InProcessApprovalRequestLike, type InProcessAwaitApproval, type InProcessRunInput, type InProcessRunner, InProcessTransport, type InProcessTransportOptions, type InferBody, type InferQuery, type InferResponse, Link, type LinkProps, MCP_APP_SANDBOX, type McpAppHandle, type McpAppHostOptions, Metadata, type MetadataProps, type PrefetchBehavior, type RequestContext, TheoFetchError, type TheoFetchOptions, type UseAgentOptions, type UseAgentReturn, type UseAgentStatus, consumeChunkStream, consumeUIMessageStream, createAppClient, createBatcher, createGuestMessageHandler, mountMcpApp, responseToChunkStream, theoFetch, useAgent };
+export { AgentTransport, ApprovalDecision, type BatchRequest, type BatchResponse, type BatchTransport, type Batcher, type BatcherOptions, type CreateAppClientOptions, type GuestMessage, Image, type ImageProps, type InferBody, type InferQuery, type InferResponse, Link, type LinkProps, MCP_APP_SANDBOX, type McpAppHandle, type McpAppHostOptions, Metadata, type MetadataProps, type PrefetchBehavior, RequestContext, TheoFetchError, type TheoFetchOptions, type UseAgentOptions, type UseAgentReturn, UseAgentStatus, createAppClient, createBatcher, createGuestMessageHandler, mountMcpApp, theoFetch, useAgent };