@jini-ai/chat 0.5.4 → 0.5.6

package/dist/core/assistant-client/attachment-liveness.js

@@ -0,0 +1,93 @@
+/**
+ * @file Restore cached attachment references only after the host confirms their bytes still exist.
+ * Drafts persist references separately from text; staged bytes have a host-defined TTL. Dropping
+ * an unconfirmed live reference costs a re-drag, while restoring a dead one causes a failed turn.
+ * Ref shape, endpoint and probe cap enter through host ports: malformed/excess refs, refusals,
+ * network failures and timeouts are discarded, without losing the draft's words.
+ * HEAD avoids downloading every attachment to answer a liveness question. The host endpoint must
+ * support it (Express routes HEAD through a GET handler when no HEAD handler exists and omits the
+ * body); get-chat-attachment-route.test.ts covers the original composed route.
+ */
+/** In-flight probes. Matches `createDaemonAttachmentUploader`'s own upload concurrency — enough to
+ *  hide localhost latency, few enough to leave the page's connection budget alone. */
+const DEFAULT_CONCURRENCY = 2;
+/** Abort deadline per probe. A restore runs at mount behind the composer, so a wedged request must
+ *  not keep a worker (and the operator's attachment chips) pending indefinitely. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * Whether the server still serves this one reference.
+ *
+ * @param ref opaque `attachment:<uuid>` capability id (`ChatAttachment.path`).
+ * @returns `true` only on a 2xx. Every refusal and every fault answers `false` — the caller cannot
+ *   act differently on them, and a probe that could not reach the server has not confirmed anything.
+ * @complexity O(1); one request, abandoned after `timeoutMs`.
+ */
+async function isAttachmentStillServed(ref, options) {
+    try {
+        const response = await options.fetchImpl(options.endpoint({ ref }, {}), {
+            method: "HEAD",
+            credentials: "same-origin",
+            signal: AbortSignal.timeout(options.timeoutMs),
+        });
+        return response.ok;
+    }
+    catch {
+        // A network fault, an abort, or a same-origin policy refusal. Indistinguishable from here, and
+        // all mean the same thing: nothing was confirmed, so the reference does not come back.
+        return false;
+    }
+}
+/**
+ * Runs `probe` over `refs` with at most `concurrency` in flight, answering positionally.
+ *
+ * Shared-iterator workers rather than a chunked `Promise.all` loop, for the same reason
+ * `createDaemonAttachmentUploader` uses them: a chunked loop stalls the whole batch on its slowest
+ * member, and this one runs while the operator is looking at a half-restored composer.
+ *
+ * @complexity O(n) requests, at most `concurrency` concurrent; O(n) space for the verdicts.
+ */
+async function probeAll(refs, concurrency, probe) {
+    const verdicts = new Array(refs.length).fill(false);
+    const entries = refs.entries();
+    async function worker() {
+        for (const [index, ref] of entries) {
+            verdicts[index] = await probe(ref);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, refs.length)) }, worker));
+    return verdicts;
+}
+/**
+ * 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 function createChatAttachmentValidator({ fetch, endpoint, isSupportedRef, maxProbedAttachments }, options = {}) {
+    const probeOptions = {
+        fetchImpl: fetch,
+        endpoint,
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    };
+    const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+    return async (attachments) => {
+        const candidates = attachments
+            .slice(0, maxProbedAttachments)
+            .filter((candidate) => isSupportedRef({ ref: candidate.path }, {}));
+        if (candidates.length === 0)
+            return [];
+        const verdicts = await probeAll(candidates.map((candidate) => candidate.path), concurrency, (ref) => isAttachmentStillServed(ref, probeOptions));
+        return candidates.filter((_, index) => verdicts[index]);
+    };
+}
+//# sourceMappingURL=attachment-liveness.js.map

package/dist/core/assistant-client/durable-run-subscription.d.ts

@@ -0,0 +1,39 @@
+import type { ChatMessage } from "../messages.js";
+import type { RunHandlers } from "../transport.js";
+import type { RunNotices } from "../run-events/entry.js";
+export interface DurableRunBinding {
+    readonly messageId: string;
+    readonly conversationId: string;
+}
+export interface DurableSubscriptionPorts {
+    readonly read: (required: {
+        runId: string;
+        messageId?: string;
+    }, optional: {}) => Promise<ChatMessage | null | "gone">;
+    readonly stream: (required: {
+        runId: string;
+        cursor: string;
+        frame: (kind: string, data: string, cursor: string) => void;
+        dropped: () => void;
+    }, optional: {}) => () => void;
+    readonly schedule: (required: {
+        work: () => void;
+        delayMs: number;
+    }, optional: {}) => () => void;
+}
+type CheckpointHandlers = RunHandlers & {
+    onCheckpoint?: (message: ChatMessage) => void;
+};
+/** SSE is a view of one attempt. The saved message owns terminal state and can point at a new
+ * attempt after recovery; neither a browser 404 nor a closed stream may fail the logical run. */
+export declare function followDurableRun({ runId: initialRunId, handlers, signal, binding, ports, notices, bindings }: {
+    runId: string;
+    handlers: CheckpointHandlers;
+    signal?: AbortSignal;
+    binding?: DurableRunBinding;
+    ports: DurableSubscriptionPorts;
+    notices: RunNotices;
+    bindings: Map<string, DurableRunBinding>;
+}, _optional?: {}): () => void;
+export {};
+//# sourceMappingURL=durable-run-subscription.d.ts.map

package/dist/core/assistant-client/durable-run-subscription.js

@@ -0,0 +1,96 @@
+import { translateRunFrame } from "../run-events/entry.js";
+/** SSE is a view of one attempt. The saved message owns terminal state and can point at a new
+ * attempt after recovery; neither a browser 404 nor a closed stream may fail the logical run. */
+export function followDurableRun({ runId: initialRunId, handlers, signal, binding, ports, notices, bindings }, _optional = {}) {
+    let runId = initialRunId;
+    let cursor = "";
+    let stopped = false;
+    let reading = false;
+    let dropped = false;
+    let stopStream;
+    let stopTimer;
+    let messageId = binding?.messageId;
+    function stop() {
+        stopped = true;
+        stopStream?.();
+        stopTimer?.();
+        signal?.removeEventListener("abort", stop);
+    }
+    function finish(message) {
+        stop();
+        handlers.onCheckpoint?.(message);
+        if (message.runStatus === "failed" && !handlers.onCheckpoint)
+            handlers.onError(new Error("The assistant could not finish this answer. Saved work is above."));
+        handlers.onDone(message.events ?? []);
+    }
+    function open() {
+        dropped = false;
+        stopStream?.();
+        stopStream = ports.stream({ runId, cursor, frame, dropped: () => { dropped = true; void read().catch(() => undefined); } }, {});
+    }
+    function frame(kind, data, nextCursor) {
+        if (stopped)
+            return;
+        if (nextCursor)
+            cursor = nextCursor;
+        const outcome = translateRunFrame({ kind, raw: data, notices }, {});
+        // An attempt's error/end may be followed by a continuation. Only the row can finalize it.
+        if (outcome.terminal || outcome.error) {
+            void read().catch(() => undefined);
+            return;
+        }
+        // With the checkpoint-capable hook, render only durable projections. Replaying a daemon
+        // prefix into a seeded bubble would duplicate its text; the server folds those deltas once.
+        if (handlers.onCheckpoint)
+            return;
+        for (const event of outcome.events)
+            handlers.onEvent(event);
+    }
+    async function read() {
+        if (stopped || reading)
+            return;
+        reading = true;
+        stopTimer?.();
+        stopTimer = undefined;
+        try {
+            const message = await ports.read({ runId, ...(messageId ? { messageId } : {}) }, {});
+            if (stopped || !message)
+                return;
+            if (message === "gone") {
+                stop();
+                return;
+            }
+            applySavedMessage(message);
+        }
+        finally {
+            reading = false;
+            if (!stopped)
+                stopTimer = ports.schedule({ work: () => void read().catch(() => undefined), delayMs: 1_000 }, {});
+        }
+    }
+    function applySavedMessage(message) {
+        messageId = message.id;
+        if (["succeeded", "failed", "canceled"].includes(message.runStatus ?? "")) {
+            finish(message);
+            return;
+        }
+        handlers.onCheckpoint?.(message);
+        if (message.runId && message.runId !== runId) {
+            runId = message.runId;
+            cursor = "";
+            if (binding)
+                bindings.set(runId, binding);
+            dropped = true;
+        }
+        if (dropped)
+            open();
+    }
+    if (signal?.aborted)
+        return stop;
+    signal?.addEventListener("abort", stop);
+    open();
+    // Polling also covers an attempt that dies before a first frame/connection error arrives.
+    stopTimer = ports.schedule({ work: () => void read().catch(() => undefined), delayMs: 1_000 }, {});
+    return stop;
+}
+//# sourceMappingURL=durable-run-subscription.js.map

package/dist/core/assistant-client/entry.d.ts

@@ -0,0 +1,13 @@
+/** Daemon/BYOK/AG-UI chat client lifecycles. Host routes, identity and authenticated I/O are ports. */
+export { createAssistantTransportClient } from "./transport.js";
+export type { AssistantTransportPorts, AssistantTransportOptions, AssistantTransportClient, ByokFrameContext, ByokStreamContext } from "./transport.js";
+export type { AgUiClient, AgUiClientPorts, AgUiRunClient, AgUiEventContext } from "./ag-ui-transport.js";
+export { followDurableRun } from "./durable-run-subscription.js";
+export type { DurableRunBinding, DurableSubscriptionPorts } from "./durable-run-subscription.js";
+export { activeRunStub, messageWriteKey, persistableMessages } from "./messages.js";
+export type { AssistantConversation } from "./messages.js";
+export { createChatAttachmentValidator } from "./attachment-liveness.js";
+export type { ChatAttachmentValidatorInput, ChatAttachmentValidatorOptions } from "./attachment-liveness.js";
+export { createA2uiActionPoster } from "./a2ui-action-poster.js";
+export type { A2uiActionPosterInput, CreateA2uiActionPosterOptions, A2uiActionDeliveryOutcome } from "./a2ui-action-poster.js";
+//# sourceMappingURL=entry.d.ts.map

package/dist/core/assistant-client/entry.js

@@ -0,0 +1,7 @@
+/** Daemon/BYOK/AG-UI chat client lifecycles. Host routes, identity and authenticated I/O are ports. */
+export { createAssistantTransportClient } from "./transport.js";
+export { followDurableRun } from "./durable-run-subscription.js";
+export { activeRunStub, messageWriteKey, persistableMessages } from "./messages.js";
+export { createChatAttachmentValidator } from "./attachment-liveness.js";
+export { createA2uiActionPoster } from "./a2ui-action-poster.js";
+//# sourceMappingURL=entry.js.map

package/dist/core/assistant-client/messages.d.ts

@@ -0,0 +1,73 @@
+import type { ChatMessage } from "../messages.js";
+export interface AssistantConversation {
+    id: string;
+    title: string | null;
+    titleSource: "fallback" | "generated" | "manual";
+    messageCount: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * The subset of a live transcript that is worth writing: user turns, and assistant turns whose run
+ * has reached a terminal status.
+ *
+ * An assistant message that is still `queued` or `running` is rewritten on every delta, so
+ * persisting it would turn one reply into hundreds of writes for a row that is about to be
+ * replaced anyway.
+ *
+ * A `failed`/`canceled` assistant turn with EMPTY content is kept deliberately, and this is the
+ * place a future "stop writing those, they are just noise" change would land — don't (2026-09-11
+ * chat-lifecycle repair, Defect 3). The row's `events_json` is the only durable record of why the
+ * run died: the daemon's own event log is in-memory and gone with the process, so the stored
+ * `"Run failed — the agent process exited without answering"` notice with its exit code and signal
+ * is all that survives, and the pane renders it on reload. The real problem those rows caused was
+ * being replayed into the NEXT run's prompt as if they were answers, and that is fixed on the read
+ * side instead — see `assistant-transport.ts`'s `historyForTranscript`/`isAnsweredAssistantTurn`.
+ * Deleting them here would trade a history bug for a forensics hole.
+ */
+export declare function persistableMessages({ messages }: {
+    messages: ChatMessage[];
+}, _options?: Record<string, never>): ChatMessage[];
+/**
+ * The key the admin's chat writers use to remember "this message is already saved": the message id,
+ * plus the run id when there is one.
+ *
+ * The run id is part of the key because `@jini-ai/chat`'s `retry` keeps the assistant message id and
+ * starts a NEW run under it. Keyed by id alone, the first run had already marked the id saved, so the
+ * retry's in-flight stub was never written (and the API finalizer never followed it) and its final
+ * answer was never saved either. A message with no run id (a user turn, an old row) keys by id alone.
+ */
+export declare function messageWriteKey({ message }: {
+    message: Pick<ChatMessage, "id" | "runId">;
+}, _options?: Record<string, never>): string;
+/**
+ * The one message worth a durable "this run is in flight" stub write — the newest message, if it is
+ * a non-terminal assistant turn that has acquired a `runId`. `null` when there is nothing to record.
+ *
+ * Exists for reattach (2026-09-11 investigation): {@link persistableMessages} above deliberately
+ * never durably writes a `queued`/`running` assistant row (this file's own module doc explains why —
+ * avoiding a write per streamed token), which means today a run's `runId` exists NOWHERE outside the
+ * live browser tab that started it. Reload the tab, switch conversations and back, or lose the tab
+ * to a crash mid-run, and the id needed to resume watching that run is gone even though the run
+ * itself is still going server-side — there is nothing left for a reattach to find. `useAssistantChats`'s
+ * `persistRunStub` calls this once per `onMessagesChange` delta and writes at most once per message
+ * id (see that function's own doc), so this adds exactly one extra `PUT` per run, not one per token.
+ *
+ * Scoped to the LAST message only, not "any non-terminal assistant message anywhere in the array":
+ * `useConversation.ts`'s `sendMessage`/`retry` always append the run's assistant placeholder last,
+ * so a non-terminal row earlier in the array can only be a stale leftover from an earlier defect or
+ * race — recording ITS id as "the current run" would point a future reattach at the wrong turn.
+ *
+ * `saveMessage`'s server-side route upserts by message id (`ON CONFLICT(id) DO UPDATE`,
+ * `Jini/packages/sqlite`'s `chat-history/store.ts`), so this stub write and the message's eventual
+ * terminal-state write (through the normal {@link persistableMessages} path) converge on the same
+ * row rather than creating two — the terminal write simply overwrites `run_status`/`content`/
+ * `events_json` in place once the run settles.
+ *
+ * @complexity O(1) — reads only the last array element, unlike {@link persistableMessages}'s O(n)
+ *   scan, so calling this on every delta alongside the existing `flush` call costs nothing material.
+ */
+export declare function activeRunStub({ messages }: {
+    messages: ChatMessage[];
+}, _options?: Record<string, never>): ChatMessage | null;
+//# sourceMappingURL=messages.d.ts.map

package/dist/core/assistant-client/messages.js

@@ -0,0 +1,68 @@
+import { isTerminalRunStatus } from "../messages.js";
+/**
+ * The subset of a live transcript that is worth writing: user turns, and assistant turns whose run
+ * has reached a terminal status.
+ *
+ * An assistant message that is still `queued` or `running` is rewritten on every delta, so
+ * persisting it would turn one reply into hundreds of writes for a row that is about to be
+ * replaced anyway.
+ *
+ * A `failed`/`canceled` assistant turn with EMPTY content is kept deliberately, and this is the
+ * place a future "stop writing those, they are just noise" change would land — don't (2026-09-11
+ * chat-lifecycle repair, Defect 3). The row's `events_json` is the only durable record of why the
+ * run died: the daemon's own event log is in-memory and gone with the process, so the stored
+ * `"Run failed — the agent process exited without answering"` notice with its exit code and signal
+ * is all that survives, and the pane renders it on reload. The real problem those rows caused was
+ * being replayed into the NEXT run's prompt as if they were answers, and that is fixed on the read
+ * side instead — see `assistant-transport.ts`'s `historyForTranscript`/`isAnsweredAssistantTurn`.
+ * Deleting them here would trade a history bug for a forensics hole.
+ */
+export function persistableMessages({ messages }, _options = {}) {
+    return messages.filter((message) => message.role === "user" || isTerminalRunStatus({ status: message.runStatus }));
+}
+/**
+ * The key the admin's chat writers use to remember "this message is already saved": the message id,
+ * plus the run id when there is one.
+ *
+ * The run id is part of the key because `@jini-ai/chat`'s `retry` keeps the assistant message id and
+ * starts a NEW run under it. Keyed by id alone, the first run had already marked the id saved, so the
+ * retry's in-flight stub was never written (and the API finalizer never followed it) and its final
+ * answer was never saved either. A message with no run id (a user turn, an old row) keys by id alone.
+ */
+export function messageWriteKey({ message }, _options = {}) {
+    return message.runId === undefined ? message.id : `${message.id}:${message.runId}`;
+}
+/**
+ * The one message worth a durable "this run is in flight" stub write — the newest message, if it is
+ * a non-terminal assistant turn that has acquired a `runId`. `null` when there is nothing to record.
+ *
+ * Exists for reattach (2026-09-11 investigation): {@link persistableMessages} above deliberately
+ * never durably writes a `queued`/`running` assistant row (this file's own module doc explains why —
+ * avoiding a write per streamed token), which means today a run's `runId` exists NOWHERE outside the
+ * live browser tab that started it. Reload the tab, switch conversations and back, or lose the tab
+ * to a crash mid-run, and the id needed to resume watching that run is gone even though the run
+ * itself is still going server-side — there is nothing left for a reattach to find. `useAssistantChats`'s
+ * `persistRunStub` calls this once per `onMessagesChange` delta and writes at most once per message
+ * id (see that function's own doc), so this adds exactly one extra `PUT` per run, not one per token.
+ *
+ * Scoped to the LAST message only, not "any non-terminal assistant message anywhere in the array":
+ * `useConversation.ts`'s `sendMessage`/`retry` always append the run's assistant placeholder last,
+ * so a non-terminal row earlier in the array can only be a stale leftover from an earlier defect or
+ * race — recording ITS id as "the current run" would point a future reattach at the wrong turn.
+ *
+ * `saveMessage`'s server-side route upserts by message id (`ON CONFLICT(id) DO UPDATE`,
+ * `Jini/packages/sqlite`'s `chat-history/store.ts`), so this stub write and the message's eventual
+ * terminal-state write (through the normal {@link persistableMessages} path) converge on the same
+ * row rather than creating two — the terminal write simply overwrites `run_status`/`content`/
+ * `events_json` in place once the run settles.
+ *
+ * @complexity O(1) — reads only the last array element, unlike {@link persistableMessages}'s O(n)
+ *   scan, so calling this on every delta alongside the existing `flush` call costs nothing material.
+ */
+export function activeRunStub({ messages }, _options = {}) {
+    const last = messages.at(-1);
+    if (!last || last.role !== "assistant" || last.runId === undefined)
+        return null;
+    return isTerminalRunStatus({ status: last.runStatus }) ? null : last;
+}
+//# sourceMappingURL=messages.js.map

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

@@ -0,0 +1,164 @@
+import type { AgentEvent } from "../events.js";
+import type { ChatMessage } from "../messages.js";
+import type { ChatTransport, RunHandlers, StartRunInput } from "../transport.js";
+import type { ExecutionConfig } from "@jini-ai/ui";
+import type { RunNotices } from "../run-events/entry.js";
+import type { createAgUiRunClient } from "./ag-ui-transport.js";
+import type { DurableRunBinding } from "./durable-run-subscription.js";
+export interface AssistantTransportOptions {
+    /**
+     * Read fresh on every `startRun` call, never captured once — matching `AssistantDock.tsx`'s own
+     * `runContext` convention (see that file's doc on why `frontendBindToken` is read the same way):
+     * the operator can flip the runtime picker's mode mid-session, and a captured value would keep
+     * routing every later turn through whichever mode was selected when the transport was first
+     * built (`AssistantDock.tsx` memoizes the transport once, for the reason its own comment gives —
+     * rebuilding it would drop in-flight runs).
+     */
+    getExecutionConfig?: (required: Record<string, never>, optional: Record<string, never>) => ExecutionConfig;
+    /**
+     * ADR-059's AG-UI canary toggle — deliberately NOT a value on {@link ExecutionConfig}: that type
+     * is `@jini-ai/ui`'s own closed `'local-cli' | 'byok'` union, a separate repo/package, and
+     * extending it would mean a cross-repo edit this ADR explicitly avoids (Decision 1: "a zero-touch
+     * addition to Jini"). Read fresh on every `startRun` call, same "never captured" convention
+     * {@link getExecutionConfig} already establishes, for the same reason: an operator can flip this
+     * mid-session without rebuilding the memoized transport.
+     */
+    getAgUiEnabled?: (required: Record<string, never>, optional: Record<string, never>) => boolean;
+    /**
+     * Agent ids whose own CLI/ACP session already carries multi-turn conversation memory across
+     * spawns — `@jini-ai/agent-runtime`'s `resumesSessionViaCli`/`resumesSessionViaAcpLoad`, projected
+     * client-safe as `AssistantAgentSummary.carriesOwnMemory` (`assistant/agents.ts` in the host server).
+     * {@link runPrompt}'s own doc has the full "used to send only the newest message" background; this
+     * option is the inverse regression it introduced for exactly these agents — see `startRun`'s Local
+     * CLI branch below, which resends the doc's own contract instead of the full transcript ONLY for an
+     * agentId this set contains: "the caller trusts this adapter's CLI to carry its own multi-turn
+     * conversation memory... and should skip resending the rendered transcript on follow-up turns"
+     * (`types.ts`). Resending it anyway would duplicate everything the daemon's own `--resume`/
+     * `session/load` already restores (`agent-session-resume.ts`).
+     *
+     * Read fresh on every `startRun` call, same "never captured" convention {@link getExecutionConfig}/
+     * {@link getAgUiEnabled} already establish: the admin's own `/api/agents` probe resolves
+     * asynchronously and can still be in flight when this transport is first built, and an operator can
+     * switch the Local CLI agent pick mid-session.
+     *
+     * Omitted, or an agentId absent from the returned set, keeps today's behavior — the full transcript
+     * is sent. That is the SAFE default for a def this option's source has not resolved as resume-capable
+     * yet: sending redundant history to a resume-capable def costs extra tokens, but withholding history
+     * from a stateless def would silently erase its memory — the two failure directions are not
+     * symmetric, so "unknown" must resolve to "send everything," not to "send only the latest message."
+     */
+    getResumeCapableAgentIds?: (required: Record<string, never>, optional: Record<string, never>) => ReadonlySet<string>;
+    /**
+     * This pane's conversation id, adopting one if none is active yet —
+     * `useAssistantChats.ensureConversationId` (`hooks/use-assistant-chats.hooks.ts`), wired through
+     * `AssistantDock`'s `useAssistantTransport`. Awaited by `startRun` ONLY when `input.context` names
+     * no conversation, which in practice means the first turn of a chat.
+     *
+     * Why the transport has to be the one to ask: the admin adopts a conversation lazily, from the
+     * first message delta — and `@jini-ai/chat`'s `useChatPane.sendPrompt` freezes `runContext(...)`
+     * into `input.context` BEFORE calling `conversation.sendMessage(...)`, the very call that produces
+     * that delta. So on turn 1 there is no id to capture yet, and `runContext` (synchronous by
+     * contract) has no way to wait for one. `startRun` is the last point in the chain that can still
+     * `await`, which makes it the only place the run can acquire the identity its agent-CLI session id
+     * gets filed under. Without it, `agent-daemon-server.ts`'s `onStarted` skipped its entire
+     * session-capture subscription for turn 1, and turn 2 — sent only the bare latest user message,
+     * trusting a resume that had nothing stored — answered with none of the conversation.
+     *
+     * Contract: resolves `null` rather than rejecting when creation fails. `startRun` treats that as
+     * "send the turn anyway, with no conversationId" — one run with no resumable session is a far
+     * smaller loss than a run that never happens.
+     */
+    ensureConversationId?: (required: Record<string, never>, optional: Record<string, never>) => Promise<string | null>;
+    /**
+     * Writes one user message to durable storage — `useAssistantChats.persistUserTurn`
+     * (`hooks/use-assistant-chats.hooks.ts`), wired through `AssistantDock`'s `useAssistantTransport`.
+     * Awaited by `startRun` on the Local CLI path before `POST /api/runs`, including a delta's pending
+     * PUT. Acceptance persists the same message with its stub if the browser write fails. See
+     * {@link persistUserTurnBeforeDispatch} for the defect and the idempotency contract.
+     *
+     * Optional for transports without the dock's persistence hook; acceptance still receives the
+     * exact user message, and the delta-driven `flush` can write the same ID afterward.
+     * Its rejection is swallowed at the call site rather than failing the turn.
+     */
+    persistUserTurn?: (required: {
+        conversationId: string;
+        message: ChatMessage;
+    }, optional: Record<string, never>) => Promise<void>;
+}
+export interface AssistantTransportPorts {
+    readonly runsUrl: string;
+    readonly byokTurnUrl: string;
+    readonly byokRunIdPrefix: string;
+    readonly notices: RunNotices;
+    readonly fetch: typeof fetch;
+    readonly mintId: (required: Record<string, never>, optional: Record<string, never>) => string;
+    readonly projectPrompt: (required: {
+        prompt: string;
+        context: StartRunInput["context"];
+    }, optional: Record<string, never>) => string;
+    readonly projectInput: (required: {
+        input: StartRunInput;
+    }, optional: Record<string, never>) => StartRunInput;
+    readonly bindRun: (required: {
+        runId: string;
+        binding: DurableRunBinding;
+    }, optional: Record<string, never>) => void;
+    readonly runBinding: (required: {
+        runId: string;
+    }, optional: Record<string, never>) => DurableRunBinding | undefined;
+    readonly followRun: (required: {
+        runId: string;
+        handlers: RunHandlers;
+        signal?: AbortSignal;
+    }, optional: Record<string, never>) => void;
+    readonly acceptRun: (required: {
+        body: unknown;
+        signal?: AbortSignal;
+        requestSignal?: AbortSignal;
+        messageId: unknown;
+        conversationId?: string;
+    }, optional: Record<string, never>) => Promise<Response>;
+    readonly agUi: ReturnType<typeof createAgUiRunClient>;
+}
+export interface ByokFrameContext {
+    collected: AgentEvent[];
+    handlers: RunHandlers;
+    finish: () => void;
+}
+export interface ByokStreamContext extends ByokFrameContext {
+    runId: string;
+    controller: AbortController;
+}
+export interface AssistantTransportClient {
+    createAssistantTransport(required: {
+        options?: AssistantTransportOptions;
+    }, optional?: Record<string, never>): ChatTransport;
+    historyForTranscript(required: {
+        history: readonly ChatMessage[];
+    }, optional?: Record<string, never>): ChatMessage[];
+    undeliveredUserPrompt(required: {
+        history: readonly ChatMessage[];
+    }, optional?: Record<string, never>): string;
+    buildLocalCliContextRef(required: {
+        input: StartRunInput;
+        prompt: string;
+        resolvedConversationId?: string;
+    }, optional?: Record<string, never>): Record<string, unknown>;
+    handleByokFrame(required: {
+        frame: {
+            event: string;
+            data: string;
+        };
+        ctx: ByokFrameContext;
+    }, optional?: Record<string, never>): void;
+    consumeByokStream(required: {
+        body: ReadableStream<Uint8Array>;
+        ctx: ByokStreamContext;
+    }, optional?: Record<string, never>): Promise<void>;
+}
+/** Bind transport effects once; in-flight controllers belong to this client, never the package.
+ * Positional run methods implement the existing ChatTransport contract. */
+export declare function createAssistantTransportClient({ ports }: {
+    ports: AssistantTransportPorts;
+}, _options?: Record<string, never>): AssistantTransportClient;
+//# sourceMappingURL=transport.d.ts.map