theokit 0.43.12 → 0.44.3

package/dist/client/core.d.ts

@@ -1,89 +1,6 @@
-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 {
-    /** The CURRENT turn's assistant messages (per-turn; reset each `send`). Back-compat — unchanged since M41. */
-    messages: UIMessage[];
-    /**
-     * M46 — the full conversation: committed turns + the current turn's user message + in-flight assistant.
-     * Accumulated across sends (never reset except by `reset()`), with stable ids committed exactly once.
-     * Render this instead of hand-rolling a transcript from `messages`.
-     */
-    thread: 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>;
-}
+import { ApprovalDecision, AgentClientState, RequestContext, AgentTransport } from '@theokit/agents/client';
+export { AgentClient, AgentClientState, AgentTransport, ApprovalDecision, ChannelPushSource, ChannelTransport, ChannelTransportOptions, ChannelTurnHandlers, HeadersResolver, HttpTransport, HttpTransportOptions, InProcessApprovalRequestLike, InProcessAwaitApproval, InProcessRunInput, InProcessRunner, InProcessTransport, InProcessTransportOptions, RequestContext, UseAgentStatus, consumeChunkStream, consumeUIMessageStream, responseToChunkStream } from '@theokit/agents/client';
+import { UIMessage } from 'ai';
 
 interface CreateAgentClientOptions {
     /**
@@ -131,175 +48,4 @@ interface AgentClientHandle<TInput = unknown> {
  */
 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 };
+export { type AgentClientHandle, type CreateAgentClientOptions, createAgentClient };

package/dist/client/core.js

@@ -1,14 +1,18 @@
 import {
-  AgentClient,
-  ChannelTransport,
-  HttpTransport,
-  InProcessTransport,
-  consumeChunkStream,
+  createAgentClient
+} from "../chunk-WDGYCBNI.js";
+import "../chunk-XTHN6JBX.js";
+
+// src/client/core.ts
+import { AgentClient } from "@theokit/agents/client";
+import { HttpTransport } from "@theokit/agents/client";
+import { InProcessTransport } from "@theokit/agents/client";
+import { ChannelTransport } from "@theokit/agents/client";
+import {
   consumeUIMessageStream,
-  createAgentClient,
-  responseToChunkStream
-} from "../chunk-KPRJS3II.js";
-import "../chunk-DGUM43GV.js";
+  responseToChunkStream,
+  consumeChunkStream
+} from "@theokit/agents/client";
 export {
   AgentClient,
   ChannelTransport,

package/dist/client/core.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../../src/client/core.ts"],"mappings":";;;;;;AAYA,SAAS,mBAAmB;AAK5B,SAAS,qBAAqB;AAE9B,SAAS,0BAA0B;AAQnC,SAAS,wBAAwB;AAQjC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":[]}

package/dist/client/index.d.ts

@@ -1,11 +1,12 @@
 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 { InProcessRunner, InProcessTransport, ChannelPushSource, ChannelTransport, RequestContext, UseAgentStatus, ApprovalDecision, AgentTransport } from './core.js';
-export { AgentClient, AgentClientHandle, AgentClientState, ChannelTransportOptions, ChannelTurnHandlers, CreateAgentClientOptions, HttpTransport, HttpTransportOptions, InProcessApprovalRequestLike, InProcessAwaitApproval, InProcessRunInput, InProcessTransportOptions, consumeChunkStream, consumeUIMessageStream, createAgentClient, responseToChunkStream } from './core.js';
-import { UIMessage } from 'ai';
+export { AgentClient, AgentClientState, AgentHandle, AgentTransport, ApprovalDecision, ChannelPushSource, ChannelTransport, ChannelTransportOptions, ChannelTurnHandlers, HttpTransport, HttpTransportOptions, InProcessApprovalRequestLike, InProcessAwaitApproval, InProcessRunInput, InProcessRunner, InProcessTransport, InProcessTransportOptions, RequestContext, agentHandle, consumeChunkStream, consumeUIMessageStream, isAgentHandle, responseToChunkStream } from '@theokit/agents/client';
+export { UseAgentOptions, UseAgentReturn, UseAgentStatus, useAgent } from '@theokit/agents/client/react';
+export { AgentClientHandle, CreateAgentClientOptions, createAgentClient } from './core.js';
 import * as react from 'react';
 import { LinkProps as LinkProps$1 } from 'react-router';
+import 'ai';
 
 /** Infer the response type from a route's handler return */
 type InferResponse<T> = T extends {
@@ -117,96 +118,6 @@ interface Batcher {
 }
 declare function createBatcher(options: BatcherOptions): Batcher;
 
-/**
- * M47 (ADR-M47-2) — a typed, client-safe handle for an exposed agent.
- *
- * It carries ONLY the HTTP `path` at runtime plus phantom `input`/`toolNames` types (never populated) — so
- * `useAgent(chat)` / `createAgentClient(chat…)` bind with NO magic string (the path is generated from the
- * `@Expose` exposure, not hand-typed) and NO duplicated input type (the input type flows through the phantom
- * generic, inferred from the agent's `.input()`). This mirrors tRPC/Hono's type-only handle: the client
- * pulls the agent's TYPE via `import type`, never its server runtime. The generated `@theo/agents` module
- * emits one `export const <name> = agentHandle('/api/agents/<name>')` per agent, typed with the phantoms.
- */
-interface AgentHandle<TInput = unknown, TToolNames extends string = string> {
-    /** The agent's HTTP endpoint path (e.g. `/api/agents/chat`). The only serializable/runtime-bearing field. */
-    readonly path: string;
-    /**
-     * M47 — bind this agent in-process (TUI / single-process): wraps the app's runner in an
-     * {@link InProcessTransport}. `useAgent(chat.inProcess(run))` drives the SAME agent without HTTP.
-     */
-    inProcess(run: InProcessRunner): InProcessTransport;
-    /**
-     * M47 — bind this agent over a push channel (Tauri desktop webview): wraps the source in a
-     * {@link ChannelTransport}. `createAgentClient(chat.channel(source))` drives the SAME agent.
-     */
-    channel(source: ChannelPushSource): ChannelTransport;
-    /** Phantom — the agent's `input` type, carried for `useAgent(handle).send` inference. Never populated. */
-    readonly __input?: TInput;
-    /** Phantom — the agent's tool-name union, carried end-to-end. Never populated. */
-    readonly __toolNames?: TToolNames;
-}
-/**
- * Build an {@link AgentHandle} from an agent's HTTP path. Types are supplied by the caller/codegen. The
- * `inProcess`/`channel` binders are methods (dropped by `JSON.stringify`, so the `{ path }` core stays
- * serializable + client-safe) that produce the M41 transports for the non-web surfaces.
- */
-declare function agentHandle<TInput = unknown, TToolNames extends string = string>(path: string): AgentHandle<TInput, TToolNames>;
-/** Narrow an unknown binding to an {@link AgentHandle} (has a string `path`, is not a transport). */
-declare function isAgentHandle(value: unknown): value is AgentHandle;
-
-interface UseAgentReturn<TInput = unknown, TToolNames extends string = string> {
-    /** The CURRENT turn's assistant messages (per-turn; reset each `send`). Back-compat since M41. */
-    messages: UIMessage[];
-    /**
-     * M46 — the full conversation to render: committed turns + the current turn's user + in-flight
-     * assistant, accumulated across sends with stable ids. Prefer this over hand-rolling a transcript
-     * from `messages`. Same shape on every surface (web/desktop/TUI) — it lives in the core store.
-     */
-    thread: UIMessage[];
-    status: UseAgentStatus;
-    /** The last error, or `undefined`. */
-    error: Error | undefined;
-    /** Send a request; opens a new stream. Typed to the agent's `input` schema. */
-    send: (input: TInput) => void;
-    /** Abort an in-flight stream. */
-    abort: () => void;
-    /** Clear messages + error, back to idle. */
-    reset: () => void;
-    /** Settle a paused HITL approval (HTTP `POST /approve/<id>` for web; the inline callback in-process). */
-    approve: (approvalId: string, decision: ApprovalDecision) => Promise<void>;
-    /** Resume an interrupted stream (M37 durable transport for web; a no-op in-process). */
-    reconnect: () => void;
-    /**
-     * The union of tool names this agent can emit (M8), carried end-to-end from the `agent()` builder's
-     * accumulated tool-name type through the generated `@theo/agents` client. Type-only witness (never
-     * populated at runtime). Resolves to the literal union for builder agents, `string` otherwise.
-     */
-    readonly __toolNames?: TToolNames;
-}
-interface UseAgentOptions {
-    /**
-     * Extra request headers (e.g., auth) — applied when a string path builds an `HttpTransport`. Read on
-     * EVERY request, so a value that changes across renders (a rotating JWT) is never sent stale.
-     */
-    headers?: Record<string, string>;
-    /** Override fetch (primarily for tests) — captured when a string path builds an `HttpTransport`. */
-    fetch?: typeof fetch;
-    /**
-     * M43 — per-request context attached uniformly to EVERY transport (`headers` → HTTP request headers;
-     * `metadata` → the in-process runner / Tauri invoke). A value OR a resolver evaluated on every
-     * send/reconnect, so a rotating token/tenant is never stale.
-     */
-    context?: RequestContext | (() => RequestContext | undefined);
-}
-/**
- * Bind to an agent by endpoint path (`/api/agents/<name>`), by a typed {@link AgentHandle} (M47 — the
- * generated `chat` handle; kills the magic string + duplicated input type), or by an explicit
- * {@link AgentTransport}. Prefer the generated `useAgent` from `@theo/agents` (typed by agent name or
- * handle); this base accepts all three. The store is created once per binding identity — memoize a
- * transport before passing it.
- */
-declare function useAgent<TInput = unknown>(binding: string | AgentHandle<TInput> | AgentTransport, options?: UseAgentOptions): UseAgentReturn<TInput>;
-
 type PrefetchBehavior = 'none' | 'intent' | 'viewport';
 interface LinkProps extends LinkProps$1 {
     /** Prefetch strategy. Default: 'intent' (on hover + focus). */
@@ -264,7 +175,7 @@ interface MetadataProps {
     /** Custom meta tags rendered as children */
     children?: React.ReactNode;
 }
-declare function Metadata(props: MetadataProps): react.JSX.Element;
+declare function Metadata(props: Readonly<MetadataProps>): react.JSX.Element;
 
 /**
  * <Image> — optimized image component with lazy loading.
@@ -302,7 +213,7 @@ interface ImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
     /** If true, loading="eager" — use for above-the-fold images. */
     priority?: boolean;
 }
-declare function Image({ priority, loading, decoding, ...props }: ImageProps): react.JSX.Element;
+declare function Image({ priority, loading, decoding, ...props }: Readonly<ImageProps>): react.JSX.Element;
 
 /**
  * M30 (ADR-0041) — client host for MCP App `ui://` resources.
@@ -354,4 +265,4 @@ declare function mountMcpApp(container: HTMLElement, resource: {
     html: string;
 }, opts: McpAppHostOptions): McpAppHandle;
 
-export { type AgentHandle, AgentTransport, ApprovalDecision, type BatchRequest, type BatchResponse, type BatchTransport, type Batcher, type BatcherOptions, ChannelPushSource, ChannelTransport, type CreateAppClientOptions, type GuestMessage, Image, type ImageProps, InProcessRunner, InProcessTransport, 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, agentHandle, createAppClient, createBatcher, createGuestMessageHandler, isAgentHandle, mountMcpApp, theoFetch, useAgent };
+export { 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, TheoFetchError, type TheoFetchOptions, createAppClient, createBatcher, createGuestMessageHandler, mountMcpApp, theoFetch };

package/dist/client/index.js

@@ -1,21 +1,14 @@
 import {
-  AgentClient,
-  ChannelTransport,
-  HttpTransport,
-  InProcessTransport,
-  consumeChunkStream,
-  consumeUIMessageStream,
-  createAgentClient,
-  responseToChunkStream
-} from "../chunk-KPRJS3II.js";
+  createAgentClient
+} from "../chunk-WDGYCBNI.js";
 import {
   buildUseTheoQueryConfig,
   stableQueryKey
-} from "../chunk-FH3DYBAN.js";
+} from "../chunk-ANS4ELRH.js";
 import {
   HTTP_METHOD_LOWERCASE
-} from "../chunk-WSJKACWB.js";
-import "../chunk-DGUM43GV.js";
+} from "../chunk-C34PMLSN.js";
+import "../chunk-XTHN6JBX.js";
 
 // src/client/theo-fetch.ts
 import superjson from "superjson";
@@ -394,62 +387,21 @@ function createAppClient(baseUrlOrOptions, legacyFetchImpl) {
   return makeProxy({ segments: [], baseUrl, fetchImpl });
 }
 
-// src/client/use-agent.ts
-import { useMemo, useRef, useSyncExternalStore } from "react";
-
-// src/client/agent-handle.ts
-function agentHandle(path) {
-  return {
-    path,
-    inProcess: (run) => new InProcessTransport({ run }),
-    channel: (source) => new ChannelTransport({ source })
-  };
-}
-function isAgentHandle(value) {
-  return typeof value === "object" && value !== null && typeof value.path === "string" && typeof value.sendMessages !== "function";
-}
-
-// src/client/use-agent.ts
-function useAgent(binding, options = {}) {
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-  let api;
-  if (typeof binding === "string") api = binding;
-  else if (isAgentHandle(binding)) api = binding.path;
-  const bindingIdentity = api ?? binding;
-  const client = useMemo(
-    () => new AgentClient(
-      api !== void 0 ? new HttpTransport({
-        api,
-        headers: () => optionsRef.current.headers,
-        fetch: optionsRef.current.fetch
-      }) : binding,
-      // M43 — resolve context live from the ref each send/reconnect (never stale). A value or a resolver.
-      () => {
-        const ctx = optionsRef.current.context;
-        return typeof ctx === "function" ? ctx() : ctx;
-      }
-    ),
-    // bindingIdentity captures api/binding; options resolve live via optionsRef (rebuild would drop messages).
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [bindingIdentity]
-  );
-  const state = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
-  return {
-    messages: state.messages,
-    thread: state.thread,
-    status: state.status,
-    error: state.error,
-    send: client.send,
-    abort: client.abort,
-    reset: client.reset,
-    approve: client.approve,
-    reconnect: client.reconnect
-  };
-}
+// src/client/index.ts
+import {
+  consumeUIMessageStream,
+  responseToChunkStream,
+  consumeChunkStream
+} from "@theokit/agents/client";
+import { useAgent } from "@theokit/agents/client/react";
+import { agentHandle, isAgentHandle } from "@theokit/agents/client";
+import { HttpTransport } from "@theokit/agents/client";
+import { InProcessTransport } from "@theokit/agents/client";
+import { ChannelTransport } from "@theokit/agents/client";
+import { AgentClient } from "@theokit/agents/client";
 
 // src/client/link.tsx
-import { useRef as useRef2, useCallback, useEffect } from "react";
+import { useRef, useCallback, useEffect } from "react";
 import { Link as RouterLink } from "react-router";
 import { jsx } from "react/jsx-runtime";
 var prefetched = /* @__PURE__ */ new Set();
@@ -473,7 +425,7 @@ function Link({
   onFocus,
   ...rest
 }) {
-  const ref = useRef2(null);
+  const ref = useRef(null);
   const handleIntent = useCallback(
     (event) => {
       if (prefetch === "intent") {