@jini-ai/chat 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.5.6 — 2026-10-08
+
+- Desktop 0.1.13 release fixes: see commits a2659d24 (admin), 5695a7c3 (chat, agent-runtime), 8ad4ac5c (devops).
+
+## 0.5.5 — 2026-10-08
+
+- Tovu clean-up release: code Tovu moved into Jini, plus the Jini clean-up (see the commit log).
+
 ## 0.5.4 — 2026-10-06
 
 - Prompt history in the composer: ↑ with the caret on the first line recalls earlier sent messages and ↓ on the last line walks forward; the first ↑ stashes the current draft (empty or not) and ↓ past the newest entry (or Escape) restores it exactly. Recalled entries are never mutated; consecutive duplicates collapse. New pure `createComposerHistoryState` / `transitionComposerHistory` / `composerHistoryKeyAction` / `mergeComposerHistory` / `normalizeComposerHistory` (core) and `createBrowserComposerHistoryStorage` (react, a `ComposerHistoryStoragePort` default). `useComposer`/`ChatPane` take `historyScope`, `historyStorage` and `historyMessages`.

package/dist/core/ag-ui/entry.d.ts

@@ -50,4 +50,37 @@ export declare function translateAgentEventToAgUi({ event, state }: {
 export declare function closeAgUiRun({ state }: {
     state: AgUiTranslationState;
 }): AgUiEvent[];
+/**
+ * Accumulates `TOOL_CALL_ARGS` deltas by `toolCallId` between a call's `TOOL_CALL_START` and
+ * `TOOL_CALL_END` — the inverse of `assistant-ag-ui.ts`'s server-side translator, which emits all
+ * three tool-call events back-to-back for one chat `tool_use` event today, but this side is written
+ * to accumulate real streamed deltas too (a future daemon driver that streams `tool_input_delta`
+ * incrementally needs no transport-layer change to render correctly). One instance per run, NOT a
+ * module-level singleton — the same reasoning `assistant-ag-ui.ts`'s `AgUiTranslationState` gives.
+ */
+export interface AgUiToAgentTranslationState {
+    toolCalls: Map<string, {
+        name: string;
+        argsJson: string;
+    }>;
+    readonly customEventNames: CustomEventNames;
+}
+export declare function createAgUiToAgentTranslationState({ customEventNames }: {
+    customEventNames: CustomEventNames;
+}, _options?: Record<string, never>): AgUiToAgentTranslationState;
+/**
+ * Translates one AG-UI event into zero or more chat-core `AgentEvent`s, threading `state` across
+ * calls within a single run for tool-call argument accumulation.
+ *
+ * `TEXT_MESSAGE_START`/`END` and the `REASONING_*` boundary markers translate to nothing: chat-core
+ * groups renderable output by a change in `AgentEvent.kind` alone (no message-boundary concept),
+ * the same asymmetry `translateRunAgentPayload` already has reducing the OTHER leg of this round
+ * trip (daemon wire -> `AgentEvent`) — this function is that reduction's mirror image. The two cases
+ * with real internal branching (`TOOL_CALL_END`, `CUSTOM`) and the one with a guard (`TOOL_CALL_ARGS`)
+ * are pulled into their own named functions above so this switch's own cost is just its case count.
+ */
+export declare function translateAgUiEventToAgentEvent({ event, state }: {
+    event: AgUiEvent;
+    state: AgUiToAgentTranslationState;
+}, _options?: Record<string, never>): AgentEvent[];
 //# sourceMappingURL=entry.d.ts.map

package/dist/core/ag-ui/entry.js

@@ -132,4 +132,84 @@ export function translateAgentEventToAgUi({ event, state }) {
 export function closeAgUiRun({ state }) {
     return closeOpenMessages(state);
 }
+export function createAgUiToAgentTranslationState({ customEventNames }, _options = {}) {
+    return { toolCalls: new Map(), customEventNames: { ...customEventNames } };
+}
+/** The `TOOL_CALL_ARGS` case of {@link translateAgUiEventToAgentEvent} — accumulates one delta onto
+ *  the in-flight call's buffer, a silent no-op for an id with no matching `TOOL_CALL_START`. Split
+ *  out so this `if` is scored in its own complexity budget rather than the switch's. */
+function accumulateToolCallArgs(toolCallId, delta, state) {
+    const call = state.toolCalls.get(toolCallId);
+    if (call)
+        call.argsJson += delta;
+}
+/** The `TOOL_CALL_END` case of {@link translateAgUiEventToAgentEvent} — parses the accumulated
+ *  args buffer (already removed from `state` by the caller) into one `tool_use` event, or `[]` for
+ *  an id with no matching `TOOL_CALL_START`. */
+function finalizeToolCallAgentEvent(toolCallId, call) {
+    if (!call)
+        return [];
+    let input = {};
+    try {
+        input = call.argsJson.length > 0 ? JSON.parse(call.argsJson) : {};
+    }
+    catch {
+        // A malformed/partial args buffer must not throw and drop the whole tool call — the raw
+        // string is still more useful to a human than nothing.
+        input = call.argsJson;
+    }
+    return [{ kind: "tool_use", id: toolCallId, name: call.name, input }];
+}
+/** The `CUSTOM` case of {@link translateAgUiEventToAgentEvent}. */
+function translateAgUiCustomEvent(event, names) {
+    // Host-supplied usage/status names: the server's own translator put the ORIGINAL `AgentEvent`
+    // straight into `.value` (see `assistant-ag-ui.ts`'s `translateAgentEventToAgUi`), so this is
+    // an exact round trip, not a re-derivation.
+    if (event.name === names.usage || event.name === names.status)
+        return [event.value];
+    if (event.name.startsWith(names.extensionPrefix))
+        return [{ kind: "ext", name: event.name.slice(names.extensionPrefix.length), data: event.value }];
+    return [{ kind: "ext", name: event.name, data: event.value }];
+}
+/**
+ * Translates one AG-UI event into zero or more chat-core `AgentEvent`s, threading `state` across
+ * calls within a single run for tool-call argument accumulation.
+ *
+ * `TEXT_MESSAGE_START`/`END` and the `REASONING_*` boundary markers translate to nothing: chat-core
+ * groups renderable output by a change in `AgentEvent.kind` alone (no message-boundary concept),
+ * the same asymmetry `translateRunAgentPayload` already has reducing the OTHER leg of this round
+ * trip (daemon wire -> `AgentEvent`) — this function is that reduction's mirror image. The two cases
+ * with real internal branching (`TOOL_CALL_END`, `CUSTOM`) and the one with a guard (`TOOL_CALL_ARGS`)
+ * are pulled into their own named functions above so this switch's own cost is just its case count.
+ */
+export function translateAgUiEventToAgentEvent({ event, state }, _options = {}) {
+    switch (event.type) {
+        case EventType.TEXT_MESSAGE_CONTENT:
+            return [{ kind: "text", text: event.delta }];
+        case EventType.REASONING_MESSAGE_CONTENT:
+            return [{ kind: "thinking", text: event.delta }];
+        case EventType.TOOL_CALL_START:
+            state.toolCalls.set(event.toolCallId, { name: event.toolCallName, argsJson: "" });
+            return [];
+        case EventType.TOOL_CALL_ARGS:
+            accumulateToolCallArgs(event.toolCallId, event.delta, state);
+            return [];
+        case EventType.TOOL_CALL_END: {
+            const call = state.toolCalls.get(event.toolCallId);
+            state.toolCalls.delete(event.toolCallId);
+            return finalizeToolCallAgentEvent(event.toolCallId, call);
+        }
+        case EventType.TOOL_CALL_RESULT:
+            // AG-UI's `ToolCallResultEvent` carries no `isError` field (verified against the real schema)
+            // — a genuine protocol-level fidelity gap, not a translator bug: chat's `isError` flag cannot
+            // survive the round trip through AG-UI's wire shape, so it always reconstructs as `false`.
+            return [{ kind: "tool_result", toolUseId: event.toolCallId, content: event.content, isError: false }];
+        case EventType.RAW:
+            return [{ kind: "raw", line: asString(event.event) }];
+        case EventType.CUSTOM:
+            return translateAgUiCustomEvent(event, state.customEventNames);
+        default:
+            return [];
+    }
+}
 //# sourceMappingURL=entry.js.map

package/dist/core/agentic/chat-capabilities.d.ts

@@ -8,10 +8,8 @@
  * Lives here rather than in a React package on purpose: a Node MCP server or HTTP route table
  * hosting this list must not drag a browser component graph into its process.
  *
- * This is a genuine chat product surface, not vocabulary — unlike its former siblings here
- * (capability.ts, page-capabilities.ts, …), which moved to `@jini-ai/agentic` on 2026-07-26 so a
- * non-chat consumer could depend on the vocabulary without depending on chat. This file stayed
- * behind on purpose: it's the proof the split is real (see `@jini-ai/agentic`'s archived provenance ledger).
+ * Chat outcomes belong here; generic capability vocabulary belongs to @jini-ai/agentic so
+ * non-chat consumers can use it independently of chat.
  */
 import type { CapabilityDef } from '@jini-ai/agentic';
 /** The bounded, explicit set of chat-pane capabilities every transport surface hosts. */

package/dist/core/agentic/index.d.ts

@@ -1,21 +1,8 @@
 /**
- * `@jini-ai/chat/core`'s internal `agentic/` barrel — the chat pane's own capability manifest. Not
- * a public subpath (there is no `"./agentic"` entry in package.json); re-exported from this
- * layer's root `index.ts` instead.
- *
- * Everything that used to live here besides `chat-capabilities.ts` (the framework-free
- * `CapabilityDef` vocabulary, the two shipped manifests' shared machinery, the `data-agent-*`
- * markup convention, and the protocol projections) moved to `@jini-ai/agentic` on 2026-07-26 — see
- * `packages/agentic/archived provenance ledger` for the extraction and why. This barrel now only exports
- * `CHAT_CAPABILITIES`, the seven `chat.*` verbs that are a genuine chat product surface rather
- * than generic vocabulary.
- *
- * The `CapabilityDef` re-export below is a pure back-compatibility alias with **no remaining
- * in-repo consumer**: `chat-react`'s `agent-tools.ts` shim did import it through this package when
- * that comment was written, but now imports it from `@jini-ai/agentic` directly. It stays only so
- * an external `import type { CapabilityDef } from '@jini-ai/chat-core'` (this layer's predecessor
- * package, retired 2026-08-03 — see `../index.ts`'s file doc) keeps compiling; new code should
- * import it from `@jini-ai/agentic`.
+ * Internal chat capability barrel, re-exported by chat/core rather than a public ./agentic subpath.
+ * CHAT_CAPABILITIES belongs to chat; generic capability vocabulary belongs to @jini-ai/agentic.
+ * The type re-exports preserve public compatibility. New code should import vocabulary from its
+ * owner, @jini-ai/agentic.
  */
 export { CHAT_CAPABILITIES } from './chat-capabilities.js';
 export type { CapabilityDef, CapabilityInputSchema, CapabilityRisk } from '@jini-ai/agentic';

package/dist/core/agentic/index.js

@@ -1,21 +1,8 @@
 /**
- * `@jini-ai/chat/core`'s internal `agentic/` barrel — the chat pane's own capability manifest. Not
- * a public subpath (there is no `"./agentic"` entry in package.json); re-exported from this
- * layer's root `index.ts` instead.
- *
- * Everything that used to live here besides `chat-capabilities.ts` (the framework-free
- * `CapabilityDef` vocabulary, the two shipped manifests' shared machinery, the `data-agent-*`
- * markup convention, and the protocol projections) moved to `@jini-ai/agentic` on 2026-07-26 — see
- * `packages/agentic/archived provenance ledger` for the extraction and why. This barrel now only exports
- * `CHAT_CAPABILITIES`, the seven `chat.*` verbs that are a genuine chat product surface rather
- * than generic vocabulary.
- *
- * The `CapabilityDef` re-export below is a pure back-compatibility alias with **no remaining
- * in-repo consumer**: `chat-react`'s `agent-tools.ts` shim did import it through this package when
- * that comment was written, but now imports it from `@jini-ai/agentic` directly. It stays only so
- * an external `import type { CapabilityDef } from '@jini-ai/chat-core'` (this layer's predecessor
- * package, retired 2026-08-03 — see `../index.ts`'s file doc) keeps compiling; new code should
- * import it from `@jini-ai/agentic`.
+ * Internal chat capability barrel, re-exported by chat/core rather than a public ./agentic subpath.
+ * CHAT_CAPABILITIES belongs to chat; generic capability vocabulary belongs to @jini-ai/agentic.
+ * The type re-exports preserve public compatibility. New code should import vocabulary from its
+ * owner, @jini-ai/agentic.
  */
 export { CHAT_CAPABILITIES } from './chat-capabilities.js';
 //# sourceMappingURL=index.js.map

package/dist/core/assistant-client/a2ui-action-poster.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module a2ui-action-poster
+ * Client delivery for A2uiSurfaceCard's onAgentAction: routes, fetch and failure reporting are
+ * host-supplied. Correlate by message.action/error.surfaceId, which names the exchange, rather
+ * than the chat runId. functionResponse instead correlates by functionCallId and is not addressed
+ * by this poster. The server validates the full renderer-to-agent envelope; checking an address
+ * here does not replace that boundary.
+ * Report a failed POST both through the injected reporter and the card's delivery outcome so a
+ * click cannot fail silently. Status alone provides actionable copy without coupling to each
+ * server error code; a 409 means the exchange closed, never that the person made a mistake.
+ */
+/** Delivery result compatible with A2uiSurfaceCard's onAgentAction outcome. Structural typing
+ * keeps this module independent of React; assigning the poster to the prop checks compatibility. */
+export type A2uiActionDeliveryOutcome = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export interface CreateA2uiActionPosterOptions {
+    /** Host path appended to baseUrl. The factory requires it explicitly. */
+    readonly path?: string;
+    /** Abandon a call after this many ms. Defaults to 30s, matching `createMcpUiToolCaller`'s own default. */
+    readonly timeoutMs?: number;
+    /** Extra headers per request. `content-type` is always set and cannot be overridden. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * Builds an `A2uiSurfaceCardProps["onAgentAction"]` handler that POSTs `{exchangeId, message}` to
+ * `baseUrl + path` and resolves to the delivery outcome, which the card uses to show a
+ * delivery-failure notice instead of leaving a click that looks like it did nothing.
+ *
+ * @param baseUrl - Origin to call. `""` for same-origin, the common case for an admin UI proxied to
+ * its own API.
+ * @complexity O(1) — one request per call.
+ */
+export declare function createA2uiActionPoster({ baseUrl, path, fetch, reportFailure }: A2uiActionPosterInput, options?: Omit<CreateA2uiActionPosterOptions, "path">): (runId: string | undefined, message: unknown) => Promise<A2uiActionDeliveryOutcome>;
+export interface A2uiActionPosterInput {
+    readonly baseUrl: string;
+    readonly path: string;
+    readonly fetch: typeof fetch;
+    readonly reportFailure: (required: {
+        args: readonly unknown[];
+    }, optional: Record<string, never>) => void;
+}
+//# sourceMappingURL=a2ui-action-poster.d.ts.map

package/dist/core/assistant-client/a2ui-action-poster.js

@@ -0,0 +1,113 @@
+/**
+ * @module a2ui-action-poster
+ * Client delivery for A2uiSurfaceCard's onAgentAction: routes, fetch and failure reporting are
+ * host-supplied. Correlate by message.action/error.surfaceId, which names the exchange, rather
+ * than the chat runId. functionResponse instead correlates by functionCallId and is not addressed
+ * by this poster. The server validates the full renderer-to-agent envelope; checking an address
+ * here does not replace that boundary.
+ * Report a failed POST both through the injected reporter and the card's delivery outcome so a
+ * click cannot fail silently. Status alone provides actionable copy without coupling to each
+ * server error code; a 409 means the exchange closed, never that the person made a mistake.
+ */
+const NO_SURFACE_ID_REASON = "This action doesn't say which surface it answers, so there's nowhere to send it.";
+/**
+ * Maps `a2ui-actions-route.ts`'s real non-2xx status codes to wording a non-technical person can
+ * act on. Deliberately keyed on status alone, not the route's `code`/`error` fields — every 400
+ * cause (bad JSON shape, a schema-rejected envelope, a `surfaceId`/`exchangeId` mismatch) reduces to
+ * the same actionable advice for a human, and a coarser mapping is less to keep in sync as the
+ * route's validation grows new failure modes.
+ *
+ * @param status - The response's HTTP status. Only called for a non-`ok` response.
+ * @complexity O(1).
+ * @overallScore 100
+ */
+function reasonForStatus(status) {
+    switch (status) {
+        case 409:
+            // `a2ui-actions-route.ts`'s own comment on this status: "no such exchange" and "already
+            // closed" both mean "this surface is no longer the one waiting on you" — the common case, not
+            // a mistake the human just made, so the wording must not read as one.
+            return "This surface is no longer waiting for a response — the agent has already moved on.";
+        case 400:
+            return "The agent didn't recognize this action. Reloading the conversation may fix it.";
+        case 401:
+            return "Your session couldn't be verified. Try reloading the page.";
+        default:
+            return `The action couldn't be delivered (server returned ${status}).`;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * The exchange id a renderer→agent message declares, or `undefined` if it declares none.
+ *
+ * Only `action` and `error` carry `surfaceId` on the wire — `functionResponse` correlates by
+ * `functionCallId` instead (see `interpreter.ts`'s module doc, decision 2). `buildAction`'s
+ * agent-directed branch only ever produces an `ActionMessage`, so the `functionResponse` case is
+ * unreachable from this call site today; handled anyway so this function's contract does not
+ * silently depend on that.
+ *
+ * @complexity O(1).
+ * @overallScore 100
+ */
+function surfaceIdOf(message) {
+    if (typeof message !== "object" || message === null)
+        return undefined;
+    const { action, error } = message;
+    const candidate = typeof action?.surfaceId === "string" ? action.surfaceId : error?.surfaceId;
+    return typeof candidate === "string" && candidate.length > 0 ? candidate : undefined;
+}
+/**
+ * Builds an `A2uiSurfaceCardProps["onAgentAction"]` handler that POSTs `{exchangeId, message}` to
+ * `baseUrl + path` and resolves to the delivery outcome, which the card uses to show a
+ * delivery-failure notice instead of leaving a click that looks like it did nothing.
+ *
+ * @param baseUrl - Origin to call. `""` for same-origin, the common case for an admin UI proxied to
+ * its own API.
+ * @complexity O(1) — one request per call.
+ */
+export function createA2uiActionPoster({ baseUrl, path, fetch, reportFailure }, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const endpoint = `${baseUrl.replace(/\/$/u, "")}${path}`;
+    return async (runId, message) => {
+        const exchangeId = surfaceIdOf(message);
+        if (!exchangeId) {
+            // Not reachable from `A2uiSurfaceCard`'s own call site today (see this module's doc), but a
+            // future `wantResponse`/`callFunction` path could reach here with a message this poster has no
+            // address for — reported rather than silently dropped, so a real gap is visible in devtools
+            // instead of looking like an action that quietly did nothing.
+            reportFailure({ args: [`[a2ui] cannot deliver an action with no surfaceId (run ${runId ?? "unknown"})`, message] }, {});
+            return { ok: false, reason: NO_SURFACE_ID_REASON };
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                credentials: "same-origin",
+                headers: { ...options.headers, "content-type": "application/json" },
+                body: JSON.stringify({ exchangeId, message }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const detail = await response.text().catch(() => "");
+                reportFailure({ args: [`[a2ui] action delivery failed (${response.status}) for surface ${exchangeId}`, detail] }, {});
+                return { ok: false, reason: reasonForStatus(response.status) };
+            }
+            return { ok: true };
+        }
+        catch (error) {
+            const timedOut = error instanceof Error && error.name === "AbortError";
+            reportFailure({ args: [`[a2ui] action delivery failed for surface ${exchangeId}`, timedOut ? `timed out after ${timeoutMs}ms` : error] }, {});
+            return {
+                ok: false,
+                reason: timedOut
+                    ? "This took too long to deliver and was given up on."
+                    : "Couldn't reach the server to deliver this action.",
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+//# sourceMappingURL=a2ui-action-poster.js.map

package/dist/core/assistant-client/ag-ui-transport.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @module assistant-transport-ag-ui
+ * ADR-059: a host-injected official HttpAgent owns HTTP, SSE framing and event validation for a
+ * projection of the same daemon lifecycle. No second run lifecycle or local SSE parser lives here.
+ * HttpAgent.run returns a cold Observable: subscribe to start it, then resolve startAgUiRun on
+ * the first notification, rather than await the Observable or wait for the whole run to finish.
+ * Mid-stream abort arrives as RUN_ERROR{code:"abort"} on the normal event path and finishes cleanly.
+ * Before headers, abort instead rejects fetch and reaches subscription.error; inspect the signal
+ * there so an intentional stop cannot become a user-facing failure.
+ */
+import type { RunAgentInput } from "@ag-ui/core";
+import type { AgUiEvent, AgUiToAgentTranslationState, CustomEventNames } from "../ag-ui/entry.js";
+import type { AgentEvent } from "../events.js";
+import type { RunHandlers, StartRunInput } from "../transport.js";
+export interface AgUiClient {
+    readonly abortController: AbortController;
+    abortRun(): void;
+    run(input: RunAgentInput): {
+        subscribe(observer: {
+            next: (event: unknown) => void;
+            error: (error: unknown) => void;
+            complete: () => void;
+        }): unknown;
+    };
+}
+export interface AgUiClientPorts {
+    readonly endpoint: string;
+    readonly runIdPrefix: string;
+    readonly customEventNames: CustomEventNames;
+    readonly mintId: (required: Record<string, never>, optional: Record<string, never>) => string;
+    readonly createAgent: (required: {
+        url: string;
+        threadId: string;
+    }, optional: Record<string, never>) => AgUiClient;
+}
+export interface AgUiEventContext {
+    collected: AgentEvent[];
+    handlers: RunHandlers;
+    state: AgUiToAgentTranslationState;
+    finish: () => void;
+}
+export interface AgUiRunClient {
+    isAgUiRunId(required: {
+        runId: string;
+    }, optional?: Record<string, never>): boolean;
+    handleAgUiEvent(required: {
+        event: AgUiEvent;
+        ctx: AgUiEventContext;
+    }, optional?: Record<string, never>): void;
+    startAgUiRun(required: {
+        input: StartRunInput;
+        handlers: RunHandlers;
+    }, optional?: Record<string, never>): Promise<{
+        runId: string;
+    }>;
+    reattachAgUiRun(required: {
+        handlers: RunHandlers;
+    }, optional?: Record<string, never>): Promise<void>;
+    fetchAgUiRunStatus(required: Record<string, never>, optional?: Record<string, never>): Promise<null>;
+    stopAgUiRun(required: {
+        runId: string;
+    }, optional?: Record<string, never>): Promise<void>;
+}
+/** Bind the official client without adding its dependency to every chat consumer. */
+export declare function createAgUiRunClient({ ports }: {
+    ports: AgUiClientPorts;
+}, _options?: Record<string, never>): AgUiRunClient;
+//# sourceMappingURL=ag-ui-transport.d.ts.map

package/dist/core/assistant-client/ag-ui-transport.js

@@ -0,0 +1,147 @@
+import { EventType } from "@ag-ui/core";
+import { createAgUiToAgentTranslationState, translateAgUiEventToAgentEvent } from "../ag-ui/entry.js";
+/** Bind the official client without adding its dependency to every chat consumer. */
+export function createAgUiRunClient({ ports }, _options = {}) {
+    /** In-flight AG-UI turns' driving `HttpAgent`, keyed by the client-minted runId — the ONLY way
+     *  {@link stopAgUiRun} can cancel a turn: like BYOK, there is no server-side run record on THIS
+     *  path to `POST .../cancel` against. Storing the agent (not a bare `AbortController`) lets
+     *  `stopAgUiRun` call its own `abortRun()`, which both aborts the fetch AND (per the package's own
+     *  convention) surfaces a clean `RUN_ERROR{code:"abort"}` through the normal event path rather than
+     *  a raw network error. */
+    const agUiAgents = new Map();
+    /**
+     * Dispatches one already-parsed AG-UI event. `HttpAgent` owns SSE framing and per-event zod
+     * validation entirely, and hands us finished event objects. `RUN_ERROR` with `code: "abort"` is the
+     * real package's own convention for a mid-stream abort (see module doc) — routed to `finish()`, not
+     * `onError`. Every other event is reduced through {@link translateAgUiEventToAgentEvent} and
+     * forwarded to both `collected` (the final transcript `onDone` receives) and `handlers.onEvent`
+     * (live rendering).
+     */
+    function handleAgUiEvent(event, ctx) {
+        if (event.type === EventType.RUN_ERROR) {
+            if (event.code === "abort") {
+                ctx.finish();
+                return;
+            }
+            ctx.handlers.onError(new Error(event.message || "AG-UI run failed"));
+            return;
+        }
+        if (event.type === EventType.RUN_FINISHED) {
+            ctx.finish();
+            return;
+        }
+        for (const translated of translateAgUiEventToAgentEvent({ event, state: ctx.state }, {})) {
+            ctx.collected.push(translated);
+            ctx.handlers.onEvent(translated);
+        }
+    }
+    /** Every AG-UI message role requires an id; preserve ChatMessage.id across translation. */
+    function toAgUiMessage(message) {
+        if (message.role === "user")
+            return { id: message.id, role: "user", content: message.content };
+        return { id: message.id, role: "assistant", content: message.content };
+    }
+    /**
+     * The AG-UI canary run path (ADR-059) — drives a real `@ag-ui/client` `HttpAgent` against
+     * `assistant-ag-ui.ts`'s route, same one-turn-per-call shape as `startByokRun`. `credentials:
+     * "same-origin"` is explicit even though modern `fetch()` already defaults to it for same-origin
+     * requests, matching this transport's other paths' explicitness about the session cookie.
+     */
+    async function startAgUiRun(input, handlers) {
+        const runId = `${ports.runIdPrefix}${ports.mintId({}, {})}`;
+        // The conversation-level id, stable across turns — a genuine AG-UI `threadId`, distinct from the
+        // per-turn `runId` minted fresh above. Falls back to minting one only for a conversation that has
+        // none yet (e.g. the very first turn).
+        const threadId = input.conversationId ?? ports.mintId({}, {});
+        const agent = ports.createAgent({ url: ports.endpoint, threadId }, {});
+        agUiAgents.set(runId, agent);
+        input.signal?.addEventListener("abort", () => agent.abortRun());
+        const messages = input.history.filter((message) => message.content.trim().length > 0).map(toAgUiMessage);
+        const runAgentInput = {
+            threadId,
+            runId,
+            state: null,
+            messages,
+            tools: [],
+            context: [],
+            forwardedProps: {
+                ...(input.agentId ? { agentId: input.agentId } : {}),
+                ...(input.history.some(message => message.role === "user" && message.secretRedaction?.secretRedacted) ? { secretRedacted: true } : {}),
+            },
+        };
+        const collected = [];
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            agUiAgents.delete(runId);
+            handlers.onDone(collected);
+        };
+        const state = createAgUiToAgentTranslationState({ customEventNames: ports.customEventNames }, {});
+        // Deliberately racing the Observable's first `next`/`error` against this Promise rather than
+        // awaiting it directly — `HttpAgent.run()` returns a cold Observable, never a Promise (module
+        // doc). The subscription itself keeps running after this Promise settles, driving `handlers`
+        // through to `finish()` in the background — matching `startByokRun`'s "resolves once STARTED, not
+        // once finished" contract.
+        return new Promise((resolve, reject) => {
+            let startSettled = false;
+            agent.run(runAgentInput).subscribe({
+                next: (event) => {
+                    if (!startSettled) {
+                        startSettled = true;
+                        resolve({ runId });
+                    }
+                    handleAgUiEvent(event, { collected, handlers, state, finish });
+                },
+                error: (error) => {
+                    agUiAgents.delete(runId);
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    if (!startSettled) {
+                        startSettled = true;
+                        reject(err);
+                        return;
+                    }
+                    // Aborting BEFORE headers arrive rejects the underlying fetch() itself, surfacing here
+                    // rather than through `handleAgUiEvent`'s `code: "abort"` check (module doc).
+                    if (agent.abortController.signal.aborted) {
+                        finish();
+                        return;
+                    }
+                    // Error THEN finish: an errored Observable never calls `complete`, so without this the turn
+                    // is never settled and the events collected before the failure never reach `onDone`. Same
+                    // order as `subscribeToRun`'s `end` listener, so the run is still recorded as failed.
+                    handlers.onError(err);
+                    finish();
+                },
+                complete: () => {
+                    finish();
+                },
+            });
+        });
+    }
+    /** No server-side run record exists on this path (module doc) — a reload has already discarded the
+     *  original `fetch()`'s response body, so there is nothing to resume. Same honest "already over"
+     *  answer `assistant-transport.ts`'s BYOK branch gives for the identical situation. */
+    async function reattachAgUiRun(handlers) {
+        handlers.onDone([]);
+    }
+    /** Same reasoning as {@link reattachAgUiRun} — no server-side run record to fetch status for. */
+    async function fetchAgUiRunStatus() {
+        return null;
+    }
+    /** An AG-UI run's only cancellation handle is the `HttpAgent` {@link startAgUiRun} registered for
+     *  this exact id — same shape as BYOK's `stopRun` branch. */
+    async function stopAgUiRun(runId) {
+        agUiAgents.get(runId)?.abortRun();
+    }
+    return {
+        isAgUiRunId: ({ runId }, _options = {}) => runId.startsWith(ports.runIdPrefix),
+        handleAgUiEvent: ({ event, ctx }, _options = {}) => handleAgUiEvent(event, ctx),
+        startAgUiRun: ({ input, handlers }, _options = {}) => startAgUiRun(input, handlers),
+        reattachAgUiRun: ({ handlers }, _options = {}) => reattachAgUiRun(handlers),
+        fetchAgUiRunStatus: (_required, _options = {}) => fetchAgUiRunStatus(),
+        stopAgUiRun: ({ runId }, _options = {}) => stopAgUiRun(runId),
+    };
+}
+//# sourceMappingURL=ag-ui-transport.js.map

package/dist/core/assistant-client/attachment-liveness.d.ts

@@ -0,0 +1,37 @@
+import type { ChatAttachment } from "../messages.js";
+export interface ChatAttachmentValidatorOptions {
+    /** Injected `fetch` for tests; defaults to the page's own. */
+    readonly fetchImpl?: typeof fetch;
+    /** In-flight probe cap. Defaults to {@link DEFAULT_CONCURRENCY}. */
+    readonly concurrency?: number;
+    /** Per-probe abort deadline in ms. Defaults to {@link DEFAULT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Builds the `validateAttachments` callback `<ChatPane>` calls when it restores a persisted draft.
+ *
+ * @param input.fetch injected request implementation; the host supplies it explicitly.
+ * @param input.endpoint resolves a reference to the host's HEAD-capable read endpoint.
+ * @param input.isSupportedRef validates the host's staged-reference grammar before a request.
+ * @param input.maxProbedAttachments bounds request fan-out from malformed or hand-edited drafts.
+ * @param options.concurrency in-flight probe cap; defaults to {@link DEFAULT_CONCURRENCY}.
+ * @param options.timeoutMs per-probe abort deadline; defaults to {@link DEFAULT_TIMEOUT_MS}.
+ * @returns a validator taking the cached references and resolving to the subset still served, in
+ *   the order they were given. Never rejects: a caller's only sane response to a rejection is to
+ *   restore nothing, which is what an empty subset already means.
+ * @complexity O(n) requests bounded by input.maxProbedAttachments, at most concurrency at once.
+ * @example
+ * <ChatPane validateAttachments={createChatAttachmentValidator({ fetch, endpoint, isSupportedRef, maxProbedAttachments })} />
+ */
+export declare function createChatAttachmentValidator({ fetch, endpoint, isSupportedRef, maxProbedAttachments }: ChatAttachmentValidatorInput, options?: Omit<ChatAttachmentValidatorOptions, "fetchImpl">): (attachments: readonly ChatAttachment[]) => Promise<readonly ChatAttachment[]>;
+export interface ChatAttachmentValidatorInput {
+    readonly fetch: typeof fetch;
+    readonly endpoint: (required: {
+        ref: string;
+    }, optional: Record<string, never>) => string;
+    readonly isSupportedRef: (required: {
+        ref: string;
+    }, optional: Record<string, never>) => boolean;
+    readonly maxProbedAttachments: number;
+}
+//# sourceMappingURL=attachment-liveness.d.ts.map