agentfootprint 10.3.1 → 10.5.0

package/dist/esm/ag-ui/frontendTools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * frontendTools — tools the PAGE runs (AG-UI "frontend tools"), as tools an
+ * agent can be given.
+ *
+ * A frontend tool does its work in the browser: a date picker, a confirmation
+ * dialog, a chart the person adjusts. The server never runs it. Its tool here
+ * has no body: a call PAUSES the run, the page receives the call
+ * (`RUN_FINISHED { outcome: success, pendingToolCallIds }`), runs it, and sends
+ * the result as a `tool` message in its next request, which continues the
+ * paused run with that result as the call's answer.
+ *
+ * WHAT IT CAN NEVER DO. The tool runs nothing on the server, so it holds no
+ * server privilege: no credential (`needs`), no artifact (`wants`), no
+ * capability. Its NAME and its contract (description, input schema) are the
+ * APP's — `agUi({ frontendTools })` allow-lists it — never the page's: a
+ * description the model reads is an instruction, and a page does not get to
+ * write the agent's instructions. A page that declares a tool the app did not
+ * list is refused by name. Its result is the page's word, read by the model
+ * like any tool result.
+ */
+import { type Tool } from '../tools/tools.js';
+/** A frontend tool's contract, as the APP declares it. */
+export interface AgUiFrontendTool {
+    /** What the tool does, in the words the model reads. */
+    readonly description: string;
+    /** The JSON Schema of its arguments. */
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+/**
+ * Check the app's frontend tools at construction and return, per name, how to
+ * build the tool an agent is given — fresh for every request.
+ *
+ * @throws TypeError naming the tool when its name or contract is not usable.
+ */
+export declare function frontendToolBuilders(declared: Readonly<Record<string, AgUiFrontendTool>> | undefined): ReadonlyMap<string, () => Tool>;
+/** Does this pause wait on the page — a frontend tool's call? Read from the pause's own data. */
+export declare function isFrontendToolPause(pauseData: unknown): boolean;

package/dist/esm/ag-ui/frontendTools.js

@@ -0,0 +1,64 @@
+/**
+ * frontendTools — tools the PAGE runs (AG-UI "frontend tools"), as tools an
+ * agent can be given.
+ *
+ * A frontend tool does its work in the browser: a date picker, a confirmation
+ * dialog, a chart the person adjusts. The server never runs it. Its tool here
+ * has no body: a call PAUSES the run, the page receives the call
+ * (`RUN_FINISHED { outcome: success, pendingToolCallIds }`), runs it, and sends
+ * the result as a `tool` message in its next request, which continues the
+ * paused run with that result as the call's answer.
+ *
+ * WHAT IT CAN NEVER DO. The tool runs nothing on the server, so it holds no
+ * server privilege: no credential (`needs`), no artifact (`wants`), no
+ * capability. Its NAME and its contract (description, input schema) are the
+ * APP's — `agUi({ frontendTools })` allow-lists it — never the page's: a
+ * description the model reads is an instruction, and a page does not get to
+ * write the agent's instructions. A page that declares a tool the app did not
+ * list is refused by name. Its result is the page's word, read by the model
+ * like any tool result.
+ */
+import { defineTool } from '../tools/tools.js';
+import { pauseHere } from '../core/pause.js';
+/** The key a frontend tool's pause carries — how a host knows the run waits on the page. */
+const FRONTEND_TOOL_PAUSE = 'agUiFrontendTool';
+/** A tool name every provider accepts. */
+const NAME = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * Check the app's frontend tools at construction and return, per name, how to
+ * build the tool an agent is given — fresh for every request.
+ *
+ * @throws TypeError naming the tool when its name or contract is not usable.
+ */
+export function frontendToolBuilders(declared) {
+    const builders = new Map();
+    for (const [name, contract] of Object.entries(declared ?? {})) {
+        if (!NAME.test(name))
+            throw new TypeError(`agUi(): frontend tool '${name}' — a tool name is letters, digits, _ and - (at most 64).`);
+        if (contract === null ||
+            typeof contract !== 'object' ||
+            typeof contract.description !== 'string' ||
+            contract.description.trim().length === 0 ||
+            contract.inputSchema === null ||
+            typeof contract.inputSchema !== 'object')
+            throw new TypeError(`agUi(): frontend tool '${name}' needs a description and an inputSchema — the app's ` +
+                `own contract, which is what the model is shown.`);
+        const { description } = contract;
+        const inputSchema = structuredClone(contract.inputSchema);
+        builders.set(name, () => defineTool({
+            name,
+            description,
+            inputSchema,
+            // Runs nothing here: the page runs it, and its result continues the run.
+            execute: async () => pauseHere({ [FRONTEND_TOOL_PAUSE]: name }),
+        }));
+    }
+    return builders;
+}
+/** Does this pause wait on the page — a frontend tool's call? Read from the pause's own data. */
+export function isFrontendToolPause(pauseData) {
+    return (typeof pauseData === 'object' &&
+        pauseData !== null &&
+        typeof pauseData[FRONTEND_TOOL_PAUSE] === 'string');
+}
+//# sourceMappingURL=frontendTools.js.map

package/dist/esm/ag-ui/frontendTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontendTools.js","sourceRoot":"","sources":["../../../src/ag-ui/frontendTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAa,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAU7C,4FAA4F;AAC5F,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAE/C,0CAA0C;AAC1C,MAAM,IAAI,GAAG,uBAAuB,CAAC;AAErC;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgE;IAEhE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC/C,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAClB,MAAM,IAAI,SAAS,CACjB,0BAA0B,IAAI,2DAA2D,CAC1F,CAAC;QACJ,IACE,QAAQ,KAAK,IAAI;YACjB,OAAO,QAAQ,KAAK,QAAQ;YAC5B,OAAO,QAAQ,CAAC,WAAW,KAAK,QAAQ;YACxC,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YACxC,QAAQ,CAAC,WAAW,KAAK,IAAI;YAC7B,OAAO,QAAQ,CAAC,WAAW,KAAK,QAAQ;YAExC,MAAM,IAAI,SAAS,CACjB,0BAA0B,IAAI,uDAAuD;gBACnF,iDAAiD,CACpD,CAAC;QACJ,MAAM,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC;QACjC,MAAM,WAAW,GAAG,eAAe,CAAC,QAAQ,CAAC,WAAW,CAA4B,CAAC;QACrF,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,CACtB,UAAU,CAAC;YACT,IAAI;YACJ,WAAW;YACX,WAAW;YACX,yEAAyE;YACzE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,mBAAmB,CAAC,EAAE,IAAI,EAAE,CAAC;SAChE,CAAC,CACH,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,mBAAmB,CAAC,SAAkB;IACpD,OAAO,CACL,OAAO,SAAS,KAAK,QAAQ;QAC7B,SAAS,KAAK,IAAI;QAClB,OAAQ,SAAqC,CAAC,mBAAmB,CAAC,KAAK,QAAQ,CAChF,CAAC;AACJ,CAAC"}

package/dist/esm/ag-ui/ids.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ids — every id the AG-UI adapter mints, from ONE grammar.
+ *
+ *   <run>/<kind>/<n>/<address>
+ *
+ *   run      the AG-UI `runId`, through `encodeIdentityField` — `%` and `/`
+ *            escaped, so it holds no `/`;
+ *   kind     one of {@link AgUiIdKind} — no `/`;
+ *   n        a decimal ordinal — no `/`;
+ *   address  the agentfootprint `runtimeStageId` of the event that opened the
+ *            entity (`call-llm#18`, `step-p/x/tool-calls#97`) — any string.
+ *
+ * INJECTIVE by construction: the first three `/` end the three segments that
+ * cannot hold one, so two different (run, kind, n, address) tuples never spell
+ * the same id. `test/ag-ui/ids.test.ts` pins it with a property test.
+ *
+ * WHY THE ADDRESS, NOT THE PROVIDER'S ID. A model's tool-call id is not unique
+ * in a run: a provider may reuse it across iterations, and two parallel branches
+ * routinely mint the same one (`call_1`, `c1`). An AG-UI client finds a tool
+ * call by its id across the WHOLE conversation, so a reused id would land a new
+ * call's arguments on an old message. And under a redaction policy the record
+ * serves every id as the placeholder. The address — the stage execution that
+ * produced the entity, unique within a run — is unique, survives redaction (it
+ * is the record's own key, never a value a policy selects) and lines up with the
+ * recording; the run segment makes it unique across the thread. The provider's
+ * id, as the record serves it, rides `metadata.agentfootprint.toolCallId`.
+ */
+/** The kinds of entity the adapter mints ids for. */
+export type AgUiIdKind = 'text' | 'reasoning' | 'tool' | 'result' | 'agent' | 'interrupt';
+/** One run's minter: ordinals counted per (kind, address), ids spelled by {@link agUiId}. */
+export interface AgUiIdMinter {
+    /** The next id of `kind` at `address` — `n` counts up from 0 per (kind, address). */
+    next(kind: AgUiIdKind, address: string): {
+        readonly id: string;
+        readonly n: number;
+    };
+    /** The id of `kind` at `address` with a KNOWN ordinal — a tool result reuses its call's. */
+    at(kind: AgUiIdKind, n: number, address: string): string;
+}
+/** Spell one id. Exported for the property test; the minter is the only caller. */
+export declare function agUiId(runId: string, kind: AgUiIdKind, n: number, address: string): string;
+/** A minter for the AG-UI run `runId`. Refuses an empty run id: it would mint `_` ids. */
+export declare function agUiIdMinter(runId: string): AgUiIdMinter;

package/dist/esm/ag-ui/ids.js

@@ -0,0 +1,49 @@
+/**
+ * ids — every id the AG-UI adapter mints, from ONE grammar.
+ *
+ *   <run>/<kind>/<n>/<address>
+ *
+ *   run      the AG-UI `runId`, through `encodeIdentityField` — `%` and `/`
+ *            escaped, so it holds no `/`;
+ *   kind     one of {@link AgUiIdKind} — no `/`;
+ *   n        a decimal ordinal — no `/`;
+ *   address  the agentfootprint `runtimeStageId` of the event that opened the
+ *            entity (`call-llm#18`, `step-p/x/tool-calls#97`) — any string.
+ *
+ * INJECTIVE by construction: the first three `/` end the three segments that
+ * cannot hold one, so two different (run, kind, n, address) tuples never spell
+ * the same id. `test/ag-ui/ids.test.ts` pins it with a property test.
+ *
+ * WHY THE ADDRESS, NOT THE PROVIDER'S ID. A model's tool-call id is not unique
+ * in a run: a provider may reuse it across iterations, and two parallel branches
+ * routinely mint the same one (`call_1`, `c1`). An AG-UI client finds a tool
+ * call by its id across the WHOLE conversation, so a reused id would land a new
+ * call's arguments on an old message. And under a redaction policy the record
+ * serves every id as the placeholder. The address — the stage execution that
+ * produced the entity, unique within a run — is unique, survives redaction (it
+ * is the record's own key, never a value a policy selects) and lines up with the
+ * recording; the run segment makes it unique across the thread. The provider's
+ * id, as the record serves it, rides `metadata.agentfootprint.toolCallId`.
+ */
+import { encodeIdentityField } from '../memory/identity/encode.js';
+/** Spell one id. Exported for the property test; the minter is the only caller. */
+export function agUiId(runId, kind, n, address) {
+    return `${encodeIdentityField(runId)}/${kind}/${n}/${address}`;
+}
+/** A minter for the AG-UI run `runId`. Refuses an empty run id: it would mint `_` ids. */
+export function agUiIdMinter(runId) {
+    if (typeof runId !== 'string' || runId.length === 0) {
+        throw new TypeError('AG-UI: `runId` must be a non-empty string — every id the run mints is under it.');
+    }
+    const counts = new Map();
+    return {
+        next(kind, address) {
+            const key = `${kind}\u0000${address}`;
+            const n = counts.get(key) ?? 0;
+            counts.set(key, n + 1);
+            return { id: agUiId(runId, kind, n, address), n };
+        },
+        at: (kind, n, address) => agUiId(runId, kind, n, address),
+    };
+}
+//# sourceMappingURL=ids.js.map

package/dist/esm/ag-ui/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../src/ag-ui/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAanE,mFAAmF;AACnF,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,IAAgB,EAAE,CAAS,EAAE,OAAe;IAChF,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;AACjE,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,SAAS,CACjB,iFAAiF,CAClF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,OAAO;QACL,IAAI,CAAC,IAAI,EAAE,OAAO;YAChB,MAAM,GAAG,GAAG,GAAG,IAAI,SAAS,OAAO,EAAE,CAAC;YACtC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACvB,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;QACpD,CAAC;QACD,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC;KAC1D,CAAC;AACJ,CAAC"}

package/dist/esm/ag-ui/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ag-ui — the AG-UI protocol adapter over agentfootprint's event stream.
+ *
+ * `agUi()` is the adapter a host takes (`streamHandler` on
+ * `agentfootprint/hosting`): it reads an untrusted request (a `RunAgentInput`,
+ * or a gateway's own body through a `reader`), plans the turn against what the
+ * server holds, translates the run and frames it (`agUiSse`, or a gateway's
+ * own envelope through `framing`).
+ * `agUiSerializer` turns one run's served events into AG-UI events; `agUiSse`
+ * frames them for the wire with the official `@ag-ui/encoder`. Published
+ * through the `agentfootprint/ag-ui` door. The fixed sentences and the id
+ * grammar stay internal — tests import them by module path.
+ */
+export { agUiSerializer, AG_UI_CUSTOM_EVENTS, type AgUiCustomContext, type AgUiCustomProjection, type AgUiSerializerOptions, type AgUiTranslation, } from './serializer.js';
+export { agUiSse, type AgUiEncoderModule, type AgUiSseOptions } from './framing.js';
+export { agUi, type AgUiOptions, type AgUiTranslationRun, type AgUiTranslationStrategy, } from './adapter.js';
+export type { AgUiFrontendTool } from './frontendTools.js';
+export { AG_UI_MAX_ID_LENGTH, readAgUiRunInput, type AgUiRequestFacts, type AgUiRequestReader, type AgUiTurnRequest, type AgUiValidator, } from './request.js';
+export { AG_UI_PROTOCOL_VERSION, type AgUiAddress, type AgUiEvent, type AgUiEventType, type AgUiInterrupt, type AgUiMessage, type AgUiMetadata, type AgUiResumeEntry, type AgUiRunInput, type AgUiRunOutcome, type AgUiSuspendedCall, type AgUiSuspendedScope, type AgUiSuspension, } from './types.js';

package/dist/esm/ag-ui/index.js

@@ -0,0 +1,19 @@
+/**
+ * ag-ui — the AG-UI protocol adapter over agentfootprint's event stream.
+ *
+ * `agUi()` is the adapter a host takes (`streamHandler` on
+ * `agentfootprint/hosting`): it reads an untrusted request (a `RunAgentInput`,
+ * or a gateway's own body through a `reader`), plans the turn against what the
+ * server holds, translates the run and frames it (`agUiSse`, or a gateway's
+ * own envelope through `framing`).
+ * `agUiSerializer` turns one run's served events into AG-UI events; `agUiSse`
+ * frames them for the wire with the official `@ag-ui/encoder`. Published
+ * through the `agentfootprint/ag-ui` door. The fixed sentences and the id
+ * grammar stay internal — tests import them by module path.
+ */
+export { agUiSerializer, AG_UI_CUSTOM_EVENTS, } from './serializer.js';
+export { agUiSse } from './framing.js';
+export { agUi, } from './adapter.js';
+export { AG_UI_MAX_ID_LENGTH, readAgUiRunInput, } from './request.js';
+export { AG_UI_PROTOCOL_VERSION, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/ag-ui/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ag-ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,cAAc,EACd,mBAAmB,GAKpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,EAA+C,MAAM,cAAc,CAAC;AACpF,OAAO,EACL,IAAI,GAIL,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,mBAAmB,EACnB,gBAAgB,GAKjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,sBAAsB,GAavB,MAAM,YAAY,CAAC"}

package/dist/esm/ag-ui/request.d.ts

@@ -0,0 +1,151 @@
+/**
+ * request — an AG-UI request (`RunAgentInput`) read as UNTRUSTED browser input,
+ * and the one turn it may ask for.
+ *
+ * Three steps. The first is the app's to replace; the other two are the CORE,
+ * and run whichever reader produced the request — so a reader can map another
+ * body onto a turn, and never weaken a rule:
+ *
+ *   the READER         a body → an {@link AgUiTurnRequest}. The default takes
+ *                      the body as an AG-UI `RunAgentInput`; a gateway that
+ *                      sends its own body shape passes its own
+ *                      ({@link AgUiRequestReader}). Mapping only — it decides
+ *                      nothing below;
+ *   readAgUiRequest    what a custom reader produced, copied as plain JSON (so
+ *                      a getter or a proxy cannot answer the check one way and
+ *                      the plan another; the default reader's body is parsed
+ *                      JSON already and is read as it is), then
+ *   readAgUiRunInput   its SHAPE, field by field, and
+ *                      the ids' FORMAT and length — nothing here is trusted,
+ *                      nothing the server holds is read;
+ *   planAgUiTurn       the turn, from the request AND what the server holds
+ *                      for the bound conversation.
+ *
+ * The core's steps refuse by NAME (a `WireRequestRefusal`: its own status and
+ * code; the field named, the value never quoted back).
+ *
+ * WHAT A REQUEST MAY DECIDE, and what it may not:
+ *   - the newest USER message is the run's message. Nothing else the browser
+ *     sends is ever conversation: its assistant and tool messages are its own
+ *     copy of what the server said, and the server's copy is the one kept
+ *     (`sessions`, or the agent's memory under the bound session). A system or
+ *     developer message is refused — the agent's instructions are its own;
+ *   - an ANSWER is taken only for the pause the server is keeping, matched to
+ *     the ids that pause handed out (`AgUiSuspension`): a resume entry naming
+ *     its interrupt, or the tool message answering the frontend tool call it is
+ *     waiting on. Any other tool result is refused — never folded in;
+ *   - a frontend tool runs only when the app allow-listed its NAME — with the
+ *     app's own description and schema, never the page's (a description the
+ *     model reads is an instruction) — and only on a host that keeps the paused
+ *     run until the page answers;
+ *   - `state` and `context` reach the agent only through the app's validators;
+ *     without one, a request carrying either is refused;
+ *   - identity, credentials and redaction never come from a request: the host
+ *     binds the thread to the caller the app authenticates (`ThreadBinder`).
+ * `forwardedProps` is never read.
+ */
+import type { HeldConversation, PlanFacts, ProtocolPlan, ProtocolRequestFacts, ThreadBinding } from '../hosting/protocolAdapter.js';
+import type { Tool } from '../tools/tools.js';
+import type { AgUiMessage, AgUiResumeEntry, AgUiRunInput, AgUiSuspension } from './types.js';
+/** The longest thread or run id read — longer is refused, never truncated. */
+export declare const AG_UI_MAX_ID_LENGTH = 128;
+/**
+ * Read one AG-UI request body — its shape and its ids — refusing what the
+ * protocol does not allow by the field's NAME, never by its value.
+ *
+ * @throws WireRequestRefusal (400, `ERR_INVALID_RUN_INPUT`)
+ */
+export declare function readAgUiRunInput(body: unknown): AgUiRunInput;
+/**
+ * What a request reader hands the core: the one turn a request asks for, in
+ * AG-UI's terms. `AgUiRunInput` is one (a `RunAgentInput` as sent); a reader
+ * for another body builds one from it — `tools` and `context` may be left out.
+ *
+ * It carries no identity, credential or redaction setting, and the core reads
+ * nothing else a reader adds: the caller is bound by the host's `ThreadBinder`,
+ * a credential reaches a run only through the host's `sealRequest`.
+ */
+export interface AgUiTurnRequest {
+    /** The conversation the request NAMES — format-checked, never a key. */
+    readonly threadId: string;
+    /** The run id the stream names this run by — format-checked. */
+    readonly runId: string;
+    readonly parentRunId?: string;
+    /**
+     * The messages, newest last. Only the newest is read — a user message (the
+     * run's message), or the `tool` message answering the frontend tool call a
+     * paused run waits on. A system or developer message anywhere is refused.
+     */
+    readonly messages: readonly AgUiMessage[];
+    /** The frontend tools the caller offers — run only when the app allow-listed the name. */
+    readonly tools?: AgUiRunInput['tools'];
+    /** Reaches the agent only through the app's `accept.context` validator. */
+    readonly context?: AgUiRunInput['context'];
+    /** Reaches the agent only through the app's `accept.state` validator. */
+    readonly state?: unknown;
+    /** Answers to the interrupt a paused run waits on — matched to the server's own record. */
+    readonly resume?: readonly AgUiResumeEntry[];
+}
+/**
+ * What a request reader is given: the request as the host read it — UNTRUSTED.
+ * The host port's own `ProtocolRequestFacts` (the parsed body, the headers).
+ */
+export type AgUiRequestFacts = ProtocolRequestFacts;
+/**
+ * The request-reading strategy: a body → the turn it asks for. Mapping only;
+ * every rule runs after it, in the core. Refuse a body it cannot read by
+ * throwing a `WireRequestRefusal` (its status and code reach the caller);
+ * anything else it throws is refused as a malformed request, in fixed words.
+ *
+ * @example A gateway that sends `{ conversationId, requestId, text }`
+ * ```ts
+ * const reader: AgUiRequestReader = ({ body }) => {
+ *   const b = body as { conversationId?: unknown; requestId?: unknown; text?: unknown };
+ *   return {
+ *     threadId: String(b.conversationId),
+ *     runId: String(b.requestId),
+ *     messages: [{ id: 'gateway-turn', role: 'user', content: String(b.text) }],
+ *   };
+ * };
+ * ```
+ */
+export type AgUiRequestReader = (request: AgUiRequestFacts) => AgUiTurnRequest;
+/** The default reader: the body IS an AG-UI `RunAgentInput`. */
+export declare const runAgentInputReader: AgUiRequestReader;
+/**
+ * The core's read of one request: `reader` maps the body, and what it produced
+ * is checked by {@link readAgUiRunInput} — whichever reader it was. A custom
+ * reader's answer is copied as plain JSON first; the default reader's is the
+ * parsed body itself, read exactly as before readers were replaceable.
+ *
+ * @throws WireRequestRefusal — the reader's own refusal, or the core's by name
+ *   (400, `ERR_INVALID_RUN_INPUT`).
+ */
+export declare function readAgUiRequest(reader: AgUiRequestReader, request: AgUiRequestFacts): AgUiRunInput;
+/** What a page's `state` or `context` is checked by before the agent may see it. */
+export type AgUiValidator = (value: unknown, at: {
+    /** The conversation the request was bound to — whose state this claims to be. */
+    readonly thread?: ThreadBinding;
+    readonly headers: Readonly<Record<string, string>>;
+}) => unknown;
+/** The rules one adapter plans by — built from `agUi()`'s options. */
+export interface AgUiTurnRules {
+    /** The frontend tools the app allow-listed, by name: each builds the tool the agent is given. */
+    readonly frontendTools: ReadonlyMap<string, () => Tool>;
+    readonly accept: {
+        readonly state?: AgUiValidator;
+        readonly context?: AgUiValidator;
+    };
+}
+/**
+ * Plan one turn: the request (read by {@link readAgUiRunInput}) against what
+ * the server holds for its bound conversation.
+ *
+ * @throws WireRequestRefusal — by name, for everything a page may not decide.
+ */
+export declare function planAgUiTurn(input: AgUiRunInput, held: HeldConversation, facts: PlanFacts, rules: AgUiTurnRules): ProtocolPlan;
+/**
+ * A stored suspension record, checked — the store holds bytes; a record that
+ * is not one this adapter wrote is `undefined`, and nothing is matched to it.
+ */
+export declare function readAgUiSuspension(value: unknown): AgUiSuspension | undefined;