@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/chat-routes/detached-turn.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Detached (autonomous) turn → live buffer bridge.
+ *
+ * The interactive lane (`createChatTurnRoutes`) already streams a user-typed
+ * turn to the browser while it runs. An AUTONOMOUS turn — a mission step, a
+ * queue job, an inbound-email review — runs detached (`dispatchPrompt`/
+ * `streamPrompt` server-side so it survives no one watching) and, historically,
+ * only persisted its FINAL message. A browser opening the session mid-run saw a
+ * dead screen: the live tokens existed server-side but were never written to
+ * the turn-event buffer the client re-attach path (`listRunning` + `/replay`)
+ * reads.
+ *
+ * `runDetachedTurn` is that missing bridge, packaged. It taps the same buffer
+ * the interactive lane uses (`createBufferedTurnTap`) with the same producer
+ * mapping (`createSandboxChatProducer`), so an autonomous run is watchable
+ * token-by-token exactly like an interactive one — while staying durable
+ * (a durable driver re-invokes it after a crash; a turn that finished
+ * server-side short-circuits instead of re-streaming). Products supply only the
+ * domain seams: the raw sandbox event stream, the turn store, and the ids.
+ *
+ * This is app-shell mechanism (turn durability + live projection), not engine:
+ * it owns no loop logic and imports no SDK — the event source is an injected
+ * `AsyncIterable`.
+ */
+import type { ModelFailoverAttempt } from '../model-resolution/failover';
+import { type TurnEventStore } from '../stream/index';
+import { type AssistantDraftStore, type DraftPersistenceTuning } from './draft-persistence';
+import { type SandboxChatProducerOptions } from './sandbox-producer';
+import type { ChatTurnUsage } from './turn-routes';
+/** The normalized structured message body (tool-call / file / plan / interaction
+ *  parts) that `/chat-store` persists as the durable assistant row — the same
+ *  shape `createSandboxChatProducer().assistantParts()` returns. */
+export type DetachedTurnParts = Array<Record<string, unknown>>;
+/** Authoritative final receipt for a turn that finished server-side, or whose
+ *  live stream carried no usage (some harness paths only expose tokens via the
+ *  completed-turn record, e.g. `box.findCompletedTurn(turnId)`). */
+export interface DetachedTurnFinal {
+    text?: string;
+    usage?: ChatTurnUsage;
+    /** The structured parts to persist when this receipt is more complete than
+     *  the live stream (cached, finished server-side, or a fast stream that
+     *  delivered scalar text before its message-part events). Omitted when the
+     *  record only carries a usage receipt. */
+    parts?: DetachedTurnParts;
+}
+/** Define options for managing and projecting a detached turn event stream in a session */
+export interface DetachedTurnOptions {
+    store: TurnEventStore;
+    turnId: string;
+    /** Thread/session id — recorded as the buffer scope so a browser opening the
+     *  session mid-run rediscovers this turn via `listRunning(scopeId)` after it
+     *  has lost the turnId. */
+    scopeId: string;
+    /** The raw sandbox event stream for this turn (e.g. `streamSandboxPrompt`).
+     *  Ownership of the box, prompt, tooling, and attachments stays with the
+     *  caller — this only projects the stream.
+     *
+     *  An already-open stream is bound to one model and cannot fail over. Prefer
+     *  {@link openEvents}; exactly one of the two is required. */
+    events?: AsyncIterable<unknown>;
+    /** Open the raw sandbox stream FOR A GIVEN MODEL — the failover-capable form
+     *  of {@link events}. Wiring it turns failover on with no further flag
+     *  whenever {@link fallbackModels} is non-empty. Requires {@link model}.
+     *
+     *  An autonomous run is the case that most needs this: nobody is watching to
+     *  notice a dead upstream and retry by hand, so without failover the mission
+     *  step or queue job simply fails. Forwarded to the producer. */
+    openEvents?: SandboxChatProducerOptions['openEvents'];
+    /** Models to try, in order, when `model`'s upstream is dead. Product config —
+     *  see the producer's note on why a same-family fallback is not automatically
+     *  safe and why every fallback is surfaced. */
+    fallbackModels?: SandboxChatProducerOptions['fallbackModels'];
+    /** Opt out of failover while still using {@link openEvents}. */
+    modelFailover?: false;
+    /** Maximum time to open/start one model event source through its first event.
+     *  Forwarded to the producer; default 120 seconds. */
+    openTimeoutMs?: SandboxChatProducerOptions['openTimeoutMs'];
+    /** Hard deadline after the source's first lifecycle event for the first
+     *  answer-bearing event. Forwarded to the producer; default 60 seconds. */
+    firstResponseTimeoutMs?: SandboxChatProducerOptions['firstResponseTimeoutMs'];
+    /** Fired when a model is abandoned mid-chain (telemetry/alerting). */
+    onModelFallback?: SandboxChatProducerOptions['onModelFallback'];
+    /** The PREFERRED model. Recorded on the persisted assistant message + usage
+     *  receipt — unless failover moved the turn, in which case the model that
+     *  actually served is recorded instead and surfaced on the result. */
+    model?: string;
+    /** Per-flush buffer coalescer. Default `coalesceDeltas`. */
+    coalesce?: (events: unknown[]) => unknown[];
+    /** Which ask kinds the product renders a card for; anything else is
+     *  auto-declined via {@link declineInteraction}. Forwarded to the producer. */
+    isRenderableInteraction?: SandboxChatProducerOptions['isRenderableInteraction'];
+    /** Resolve a non-renderable ask so the run never hangs in the broker. An
+     *  autonomous turn has NO human watching to answer an ask, so a caller that
+     *  omits this risks the run blocking until the broker times out — wire it for
+     *  any unattended run. Forwarded to the producer. */
+    declineInteraction?: SandboxChatProducerOptions['declineInteraction'];
+    /** Opt-in eager promotion of harness-emitted `file` parts. Forwarded to the
+     *  producer (see its docs). */
+    promoteFilePart?: SandboxChatProducerOptions['promoteFilePart'];
+    /** Authoritative final receipt, consulted whenever a re-invoke finds a prior
+     *  buffer: (a) an already-`complete` turn returns it as the cached result,
+     *  (b) a `running` turn (crash mid-run) uses it to detect a run that finished
+     *  server-side, and (c) a clean run whose stream carried no usage or only
+     *  scalar text falls back to it. For Sandbox runs, use
+     *  `readCompletedSandboxTurn` so the exact completed session message
+     *  restores tool/file parts as well as text. */
+    completedResult?: () => Promise<DetachedTurnFinal | null | undefined>;
+    /** Clear the prior partial buffer for `turnId` before a genuine re-stream.
+     *  A crash mid-run leaves buffered rows at seqs 1..N with status `running`;
+     *  re-streaming restarts the tap's seq at 0 and would duplicate/interleave
+     *  rows. Wire this (delete `turnId`'s buffered events) so a retry is clean.
+     *  Unset, a re-stream over a `running` buffer is still attempted but logged
+     *  as a possible-duplication hazard. */
+    resetBuffer?: (turnId: string) => Promise<void>;
+    /** Own the durable assistant row for this turn instead of returning the body
+     *  for the caller to insert — and keep it in step with the stream.
+     *
+     *  An autonomous run is exactly the case a late viewer hits: nobody is
+     *  watching when it starts, so by the time a browser opens the session the
+     *  streaming gateway's hot event buffer may already have expired it. Keeping
+     *  that buffer short is what makes it affordable at scale (its Redis
+     *  footprint is linear in `ttl x concurrent sessions`), so the durable row —
+     *  written incrementally here — is what serves the late viewer.
+     *
+     *  WIRING THIS TRANSFERS ROW OWNERSHIP: the returned {@link
+     *  DetachedTurnResult.messageId} names the row this call wrote (draft rows
+     *  during the stream, authoritative values at the end, retraction when the
+     *  turn produced nothing). The caller must NOT insert its own assistant row
+     *  for the turn. Omit the seam and nothing changes — the result is returned
+     *  and the caller persists it exactly as today.
+     *
+     *  Idempotency reuses the turn's own identity: the row id defaults to
+     *  `assistant:<turnId>`, so a durable driver re-invoking after a crash
+     *  patches the same row instead of duplicating parts. */
+    persist?: DraftPersistenceTuning & {
+        store: AssistantDraftStore;
+        threadId: string;
+        /** Deterministic row id. Default `assistant:<turnId>`. */
+        messageId?: string;
+        /** Pre-persist text transform (`/redact`), applied to drafts AND the final
+         *  write — parity with the interactive lane's `transformFinalText`. */
+        transformText?: (text: string) => string | Promise<string>;
+    };
+    log?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/** Describe the result of a detached turn including state, text, parts, usage, and optional error or cache flag */
+export interface DetachedTurnResult {
+    /** `completed` — clean drain: persist + bill. `failed` — a terminal error
+     *  event, including the producer's structured `sandbox.stream_failed` event
+     *  when the raw sandbox stream throws: skip billing, render an error row. */
+    state: 'completed' | 'failed';
+    text: string;
+    /** The structured assistant body to persist (tool calls, file/plan/interaction
+     *  parts). Empty array when the run produced none. */
+    parts: DetachedTurnParts;
+    usage: ChatTurnUsage;
+    /** Present when `state === 'failed'`. */
+    error?: string;
+    /** True when a prior buffer meant this call returned a cached/finished result
+     *  WITHOUT re-streaming (durable-driver retry after a crash). */
+    cached: boolean;
+    /** The durable assistant row this call wrote, when `persist` was wired.
+     *  `null` when the turn produced nothing and the row was retracted. Absent
+     *  when the caller owns persistence (today's behavior). */
+    messageId?: string | null;
+    /** The model that SERVED the turn — the fallback's id when failover moved it.
+     *  A caller that bills or scores per model must read this, not the model it
+     *  requested. */
+    model?: string;
+    /** The caller's explicit model request, before shell failover. */
+    requestedModel?: string;
+    /** The effective model echoed by the downstream sandbox. */
+    servedModel?: string;
+    /** The effective provider echoed by the downstream sandbox. */
+    servedProvider?: string;
+    /** How the downstream sandbox selected the effective model. */
+    servedSource?: 'request' | 'environment' | 'profile';
+    /** True when the preferred model did not serve. Makes an autonomous
+     *  downgrade — which no human watched happen — attributable after the fact. */
+    usedModelFallback?: boolean;
+    /** Every model tried, in order, with the reason each was abandoned. */
+    modelAttempts?: ModelFailoverAttempt[];
+}
+/**
+ * Stream a detached turn into the live turn-event buffer, durably.
+ *
+ * - Idempotent: an already-`complete` turn returns the cached result without
+ *   re-streaming (a second event sequence would collide with the buffered one).
+ * - Crash-safe: a `running` turn (a prior attempt crashed mid-tap) consults
+ *   `completedResult` to detect a run that finished server-side; only a run that
+ *   genuinely did not complete is re-streamed, and then over a `resetBuffer`-
+ *   cleared buffer so seqs don't corrupt.
+ * - Marks the turn `running` under `scopeId` so a mid-run browser finds it.
+ * - Settles `complete`/`error` so the client stops tailing and billing/render
+ *   can branch on `state`.
+ */
+export declare function runDetachedTurn(opts: DetachedTurnOptions): Promise<DetachedTurnResult>;

package/dist/chat-routes/dispatch-parts.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `buildDispatchParts` — assemble the `PromptInputPart[]` a turn carrying
+ * attachments and/or `@`-mentions dispatches to the sandbox. `parts[0]` is
+ * always the full prompt text (typed text plus the attachment + mention pointer
+ * blocks); each attachment or mention becomes one media part. An attachment
+ * (read from the product store via the injected reader) draws the inline byte
+ * budget first; a mention (read from the LIVE box) takes what is left. A file
+ * inlines as a `data:` URI when it fits the remaining budget, otherwise uses
+ * the in-box file reference supported by the current sandbox prompt contract.
+ * Every media part is deduped by its resolved absolute path. This module only
+ * produces the parts array; the caller decides when a turn dispatches parts
+ * instead of a plain string.
+ *
+ * Storage-parameterized port of gtm-agent's `dispatch-parts.ts`: the vault
+ * default reader is dropped (`readAttachment` is REQUIRED — the product supplies
+ * its store adapter), the `GTM_SANDBOX_VAULT_DIR` prefixing becomes the required
+ * `resolveAttachmentPath` seam, the `GTM_MULTIMODAL_FORCE_PATH` env fallback
+ * becomes an explicit `forcePath` flag, and every budget cap reads an overridable
+ * `./wire` constant. Kept behavior-identical for gtm-agent#618 adoption (the
+ * demotion math and emitted part shapes reproduce its dispatched prompt bytes).
+ */
+import { type PromptInputPart } from '../sandbox';
+import { type SandboxExecChannel } from '../sandbox/binary-read';
+import { type ChatTurnPartInput } from './wire';
+import type { ChatAttachmentPart, ChatMentionPart } from '../chat-store/parts';
+import type { ReadAttachmentFn } from './attachment-store';
+export type { PromptInputPart };
+/** Resolve the outcome of dispatching parts with success status and corresponding value or error message */
+export type DispatchPartsOutcome = {
+    succeeded: true;
+    value: PromptInputPart[];
+} | {
+    succeeded: false;
+    error: string;
+};
+/** One mention file's size (always) and inline bytes (only when the caller
+ *  asked for them — a path-only mention never reads its bytes). */
+type SandboxMentionReadOutcome = {
+    succeeded: true;
+    value: {
+        size: number;
+        base64?: string;
+    };
+} | {
+    succeeded: false;
+    error: string;
+};
+/** Resolve sandbox mention details by reading from a specified path with optional byte reading */
+export type ReadSandboxMentionFn = (box: SandboxExecChannel, absolutePath: string, options: {
+    readBytes: boolean;
+}) => Promise<SandboxMentionReadOutcome>;
+/**
+ * Convert the browser-safe chat attachment contract into the current sandbox
+ * prompt contract. Images carry exactly one URL or path; generic files carry a
+ * filename and URL.
+ */
+export declare function normalizeChatPromptForSandbox(prompt: string | readonly ChatTurnPartInput[]): string | PromptInputPart[];
+/** Build input parameters for dispatching chat message parts including text, attachments, mentions, and history */
+export interface BuildDispatchPartsInput {
+    text: string;
+    attachments: ChatAttachmentPart[];
+    mentions?: ChatMentionPart[];
+    history: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    systemPrompt: string;
+    /** Serialized size of the backend profile the SDK inlines into the same
+     *  prompt request body — a large, non-negotiable rider that must come out of
+     *  the inline budget or near-cap attachments 413 at the proxy instead of
+     *  demoting to path parts. */
+    profileWireBytes: number;
+    /** The product's workspace/tenant key, passed to `readAttachment`. */
+    scopeId: string;
+    /** Maps an attachment's store-relative path to the in-box absolute path a
+     *  local media reference uses (same style as `fileMentionsToParts`'s
+     *  `resolvePath`). */
+    resolveAttachmentPath: (path: string) => string;
+    /** Maps a mention's workspace-relative path to its in-box absolute path.
+     *  Default: {@link BuildDispatchPartsInput.resolveAttachmentPath} — in gtm the
+     *  vault mount roots both; a product that mounts them apart overrides this. */
+    resolveMentionPath?: (path: string) => string;
+    /** The turn's already-ensured box — required when `mentions` is non-empty
+     *  (mention bytes are read from the live box, not the store). */
+    box?: SandboxExecChannel;
+    /** Force every media part to a local file reference, skipping all inlining. */
+    forcePath?: boolean;
+    /** REQUIRED store reader for attachment content — no default (the product
+     *  owns its store; see {@link ReadAttachmentFn}). */
+    readAttachment: ReadAttachmentFn;
+    readSandboxMention?: ReadSandboxMentionFn;
+    /** Whole-request proxy cap. Default {@link DISPATCH_REQUEST_MAX_BYTES}. */
+    requestMaxBytes?: number;
+    /** JSON-envelope reserve off the top of the request cap. Default
+     *  {@link DISPATCH_STRUCTURAL_RESERVE_BYTES}. */
+    structuralReserveBytes?: number;
+    /** Sidecar per-request parts-array cap. Default {@link DISPATCH_MAX_PARTS}. */
+    maxParts?: number;
+}
+/** Build dispatch parts from input by resolving mentions, paths, and applying size constraints asynchronously */
+export declare function buildDispatchParts(input: BuildDispatchPartsInput): Promise<DispatchPartsOutcome>;

package/dist/chat-routes/draft-persistence.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Incremental ("draft") persistence of the assistant row WHILE a turn streams.
+ *
+ * Why this exists — the scale argument, not a convenience:
+ *
+ * A live turn is readable from two places. The hot path is the session
+ * gateway's in-memory/Redis event buffer, which exists so a viewer survives a
+ * network blip: it is keyed one sorted set per session, refreshed on every
+ * push, and expires on a TTL. Its memory cost is `arrival_rate x TTL x
+ * bytes_per_session` — strictly LINEAR in the TTL. Stretching that TTL to
+ * cover "a viewer who opens the tab later" is a category error: it buys memory
+ * proportional to the increase and still serves nothing to a viewer who
+ * arrives past the new horizon.
+ *
+ * So the hot buffer must stay SHORT (live delivery + reconnect only), and
+ * durable storage must serve history. That only works if durable storage
+ * actually HAS the in-flight turn — which, before this module, it did not: the
+ * assistant row was written once, after the stream drained. A viewer arriving
+ * mid-turn past the hot window read an empty transcript.
+ *
+ * This module closes that gap: the assistant row is inserted early and patched
+ * on a coalesced cadence, so the durable transcript is at most one interval
+ * (default 2 s) behind the live stream and the hot buffer never has to be the
+ * history tier.
+ *
+ * Mechanism only. It owns no vocabulary: the caller supplies the snapshot
+ * function, the store, and the deterministic row id.
+ *
+ * Four properties the cadence guarantees:
+ * - **Time-floored.** At most one write per `intervalMs`, never one per token.
+ * - **Dirty-gated.** Only content-bearing events arm a write; heartbeats,
+ *   status pings, and lifecycle envelopes never do.
+ * - **Single-flight.** A write already in flight suppresses the next trigger
+ *   instead of queueing; the final write is authoritative regardless of how
+ *   many drafts landed.
+ * - **Best-effort.** A store failure is logged and swallowed — a durability
+ *   optimization must never kill a healthy stream (the same rule
+ *   `withDurableChatProjection` already states).
+ */
+import { type ChatMessagePart } from '../chat-store/parts';
+import type { ChatTurnUsage } from './turn-routes';
+/** Message row shape the writer reads back when re-entering a turn. */
+export interface DraftStoredMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    parts?: ChatMessagePart[] | null;
+    model?: string | null;
+    requestedModel?: string | null;
+    servedModel?: string | null;
+    servedProvider?: string | null;
+    servedSource?: string | null;
+}
+/** Values written to the assistant row — the intersection of the append and
+ *  patch shapes, so one snapshot serves both. */
+export interface AssistantRowValues {
+    content: string;
+    parts?: ChatMessagePart[];
+    model?: string | null;
+    requestedModel?: string | null;
+    servedModel?: string | null;
+    servedProvider?: string | null;
+    servedSource?: string | null;
+    inputTokens?: number | null;
+    outputTokens?: number | null;
+    reasoningTokens?: number | null;
+    cacheReadTokens?: number | null;
+    cacheWriteTokens?: number | null;
+    costUsd?: number | null;
+}
+/** The store capability incremental persistence needs on top of
+ *  `appendMessage`. A store without `updateMessage` cannot patch a row, so it
+ *  cannot draft at all — the caller keeps today's single-write behavior. */
+export interface AssistantDraftStore {
+    listMessages(threadId: string): Promise<DraftStoredMessage[]>;
+    appendMessage(input: AssistantRowValues & {
+        id?: string;
+        threadId: string;
+        role: 'user' | 'assistant';
+    }): Promise<unknown>;
+    updateMessage?(id: string, patch: AssistantRowValues): Promise<unknown>;
+    deleteMessage?(id: string): Promise<unknown>;
+}
+/** Live snapshot of the assistant body, taken from the producer's own
+ *  accumulators. `parts` is the DRAFT projection (`draftParts()`), never the
+ *  finalized one — see `draftAssistantParts`. */
+export interface AssistantDraftSnapshot {
+    content: string;
+    parts?: Array<Record<string, unknown>>;
+    usage?: ChatTurnUsage;
+    model?: string;
+}
+/** Product-tunable cadence. Defaults are stated on each field; a product with
+ *  a chattier or heavier workload moves them without forking the writer. */
+export interface DraftPersistenceTuning {
+    /** Minimum wall-clock gap between draft writes, in ms. Default 2000.
+     *
+     *  Justification for 2 s, from a measured tool-heavy production run (517
+     *  stream events over ~90 s wall = ~5.7 events/s): a 2 s floor with the
+     *  dirty gate turns 517 candidate writes into <= 45, while leaving the
+     *  durable row at most 2 s stale — an order of magnitude below the time it
+     *  takes a viewer to open a tab and render, so a late viewer never perceives
+     *  the lag. Fleet arithmetic at 10k concurrent 60 s runs: <= 30 updates per
+     *  run x 167 run-starts/s = ~334 row-updates/s spread over per-tenant
+     *  shards. Lower it and write amplification grows with no perceptible
+     *  freshness gain; raise it past ~5 s and a late viewer starts seeing a
+     *  visibly truncated answer. */
+    intervalMs?: number;
+    /** Serialized-parts size (bytes) past which the interval backs off, so a
+     *  turn accumulating a megabyte-scale `parts` blob does not rewrite it every
+     *  interval. Default 262144 (256 KiB) -> interval x 2.5; ten times that ->
+     *  interval x 5. The final write is never throttled. */
+    backoffBytes?: number;
+    /** Per-tool-part output cap applied to DRAFTS ONLY (bytes). A tool returning
+     *  a large blob would otherwise be rewritten in full on every draft. The
+     *  final write always carries the untruncated value. Default 32768 (32 KiB);
+     *  0 disables truncation. */
+    maxDraftToolOutputBytes?: number;
+}
+/** Define the inputs required to construct an assistant draft writer */
+export interface AssistantDraftWriterOptions extends DraftPersistenceTuning {
+    store: AssistantDraftStore;
+    threadId: string;
+    /** DETERMINISTIC row id for this turn's assistant message — the whole
+     *  idempotency mechanism. Derived from the turn's existing identity
+     *  (`deriveExecutionId` in the interactive lane, the turn id in the detached
+     *  lane), so a re-entered turn addresses the SAME row: the writer looks the
+     *  id up before its first insert and patches what it finds. */
+    messageId: string;
+    /** Read the producer's live accumulators. Returns null before the producer
+     *  is resolved (the assembly defers box resolution into the first pull). */
+    snapshot(): AssistantDraftSnapshot | null;
+    /** Pre-persist text transform (`/redact`'s `redactPII`). Applied to the
+     *  draft's scalar content AND every draft text part — parity with the final
+     *  write, or incremental persistence would re-open the at-rest PII leak that
+     *  transform closed, just seconds earlier and on every turn. */
+    transformText?(text: string): string | Promise<string>;
+    log?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/** Coalescing writer that keeps one durable assistant row in step with a
+ *  streaming turn. Created per turn; not reusable. */
+export interface AssistantDraftWriter {
+    /** Arm/trigger a draft write from one engine event. Synchronous by design —
+     *  the write itself is fire-and-forget so the stream is never blocked on
+     *  store latency. */
+    notify(event: {
+        type?: unknown;
+    }): void;
+    /** Stop drafting and settle any in-flight write. Called before the final
+     *  write so a late draft can never clobber the authoritative row. */
+    close(): Promise<void>;
+    /** Write the AUTHORITATIVE completion values onto this turn's row —
+     *  insert-or-patch under the same deterministic id, un-throttled and
+     *  un-truncated. Errors propagate: the final write is the one that must not
+     *  fail silently. Implies {@link close}. */
+    finalize(values: AssistantRowValues): Promise<void>;
+    /** The durable row this turn is writing, once one exists. */
+    rowId(): string | undefined;
+    /** Retract the row for a turn that produced nothing (mirrors the final
+     *  write's empty-turn skip, which leaves no row at all today). Also retracts
+     *  a row a PREVIOUS attempt left behind, so a re-entered turn that ends
+     *  empty converges on "no row" rather than a stale partial. */
+    discard(): Promise<void>;
+    /** Diagnostics: how many draft writes actually reached the store. */
+    writeCount(): number;
+}
+/** True when this event should arm a draft write. */
+export declare function isDraftContentEvent(event: {
+    type?: unknown;
+}): boolean;
+/** Build the coalescing draft writer for one turn. */
+export declare function createAssistantDraftWriter(options: AssistantDraftWriterOptions): AssistantDraftWriter;
+/** True when a store can support incremental persistence at all. Without
+ *  `updateMessage` a draft row could never be patched, so the caller keeps
+ *  today's exact single-write behavior. */
+export declare function storeSupportsDraftPersistence(store: AssistantDraftStore): boolean;
+/** The row id an `appendMessage` actually returned, or `null` when the store
+ *  returned nothing usable. `ChatTurnMessageStore.appendMessage` is typed
+ *  `Promise<unknown>` so a product adapter is free to resolve `void`; every
+ *  caller that wants to NAME the row it just wrote has to read defensively.
+ *
+ *  Deliberately no fallback to a caller-assigned id — see `writeOnce`, which
+ *  adds its own. A caller that let the store mint the id has nothing to fall
+ *  back TO, and guessing one would report a row that may not exist. */
+export declare function rowIdOf(inserted: unknown): string | null;
+/** The default deterministic assistant-row id for a turn. Readable on purpose
+ *  (an operator grepping a transcript row id finds the run), and stable across
+ *  re-entries because every input already is. */
+export declare function assistantRowIdForTurn(turnKey: string): string;

package/dist/chat-routes/durable-projection.d.ts

@@ -0,0 +1,18 @@
+import type { ChatTurnRouteProducer } from './turn-routes';
+/** Resolve chat route events and materialize their durable state records */
+export interface ChatRouteDurableProjection {
+    observe(event: unknown): void | Promise<void>;
+    materialize(): Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>>;
+}
+/** Log chat route projection messages with optional metadata for durable processing */
+export type ChatRouteDurableProjectionLogger = (message: string, meta?: Record<string, unknown>) => void;
+/** Adds durable lifecycle projection to any producer lane without moving its
+ * transport into agent-app. Purely STRUCTURAL: agent-app ships no implementer
+ * of {@link ChatRouteDurableProjection} and deliberately does not — the one it
+ * used to ship (`/durable-chat`) was removed in 0.44.0 with zero fleet imports.
+ * Pass any `{ observe, materialize }` object backed by your own store. The projection is observed inline and its
+ * materialized parts replace same-key pending snapshots after the stream
+ * drains. Projection persistence is best-effort for the live lane: a store
+ * outage must not terminate an otherwise healthy sandbox stream. Failures are
+ * reported through the optional logger so products can retain diagnostics. */
+export declare function withDurableChatProjection(producer: ChatTurnRouteProducer, projection: ChatRouteDurableProjection, log?: ChatRouteDurableProjectionLogger): ChatTurnRouteProducer;

package/dist/chat-routes/file-index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `createSandboxFileIndexRoute` — server side of `@`-file-mentions
+ * (companion to sandbox-ui#184's composer mention primitive). Serves a flat,
+ * ignore-filtered listing of the workspace sandbox so `useFileMentions`
+ * (`/web-react`) can filter it client-side without a round trip per
+ * keystroke.
+ *
+ * Same seam style as `createUploadRoute`: `authorize({ request })` resolves a
+ * structural `{ tree(path, opts) }` handle (the shape of the sandbox SDK's
+ * `box.fs.tree`) — no SDK import here. `authorize` also carries the
+ * cold-box signal: a sandbox that isn't running yet answers `{ status:
+ * 'warming' }` directly, never provisions-and-waits inside this route.
+ *
+ * A box can also be running with its workspace root not yet materialised, which
+ * `authorize` cannot see; the route recognises that one signal off `fs.tree`
+ * and answers `warming` too, so every consumer gets the retry-and-wait state
+ * instead of a 500. Every other `tree()` failure propagates.
+ */
+import type { FileMention } from './wire';
+/** One entry from a structural `tree()` scan. Mirrors the sandbox SDK's
+ *  `FileTreeFile` (`path`, `size`, `mtime`) — `mtime` is unused here so it's
+ *  omitted from the structural match. */
+export interface SandboxTreeFile {
+    path: string;
+    size: number;
+}
+/** Structural match of the sandbox SDK's `box.fs.tree` result shape
+ *  (`FileTreeResult`). `stats.truncated` is the only stat this route reads;
+ *  the rest ride through unread on the real SDK type. */
+export interface SandboxTreeResult {
+    root: string;
+    files: SandboxTreeFile[];
+    stats: {
+        truncated: boolean;
+    };
+}
+/** Structural match of the sandbox SDK's `box.fs` tree surface. */
+export interface SandboxFileTreeSource {
+    tree(path: string, options?: {
+        maxDepth?: number;
+    }): Promise<SandboxTreeResult>;
+}
+/** Describe a ready file index response with workspace-relative entries and truncation status */
+export interface FileIndexReadyResponse {
+    status: 'ready';
+    /** Workspace-relative entries. Same shape as `FileMention` (`./wire`) so a
+     *  client can hand a response entry straight to `fileMentionsToParts` /
+     *  `buildMentionPromptBlock` without remapping. */
+    files: FileMention[];
+    /** True when either the underlying scan truncated (SDK-side cap) or this
+     *  route's own `maxEntries` cap trimmed the filtered list. The client
+     *  should show "showing first N files" rather than imply completeness. */
+    truncated: boolean;
+    generatedAt: string;
+}
+/** Cold-box answer: no provisioning happened, no files were scanned. The
+ *  client shows a warming state and retries — this route never blocks on a
+ *  box coming up. Two situations produce it: `authorize` reporting a box that
+ *  is not running, and a running box whose workspace root does not exist yet
+ *  (see `isMissingRootError`). */
+export interface FileIndexWarmingResponse {
+    status: 'warming';
+}
+/** Resolve a response indicating the file index is either ready or warming up */
+export type FileIndexResponse = FileIndexReadyResponse | FileIndexWarmingResponse;
+/** Short-TTL cache seam so repeat popover opens in the same session don't
+ *  re-scan the workspace. Host-provided (e.g. a KV binding); `key` is
+ *  whatever `authorize` returns as `cacheKey` — this route treats it opaquely. */
+export interface FileIndexCache {
+    get(key: string): Promise<FileIndexReadyResponse | null> | FileIndexReadyResponse | null;
+    put(key: string, value: FileIndexReadyResponse, options?: {
+        ttlSeconds?: number;
+    }): Promise<void> | void;
+}
+/** Define authorization details and parameters for indexing a file workspace with optional caching and ignore rules */
+export type FileIndexAuthorization = {
+    status: 'ready';
+    /** Structural sandbox `fs` handle, usually `ensureWorkspaceSandbox(...)` → `box.fs`. */
+    fs: SandboxFileTreeSource;
+    /** Workspace root to index (e.g. `/home/agent`). */
+    root: string;
+    /** Extra ignore segments for this request, merged with the route's
+     *  defaults + `CreateSandboxFileIndexRouteOptions.ignore`. */
+    ignore?: string[];
+    /** Opaque cache key for the optional cache seam. Omit to skip caching
+     *  for this request (e.g. a workspace the host chooses not to cache). */
+    cacheKey?: string;
+} | {
+    status: 'warming';
+} | {
+    status: 'denied';
+    response: Response;
+};
+/** Define options to authorize and configure sandbox file index route behavior */
+export interface CreateSandboxFileIndexRouteOptions {
+    /** Authenticate the caller, resolve the sandbox `fs` handle, and signal a
+     *  cold box — never provisions or waits. */
+    authorize(args: {
+        request: Request;
+    }): Promise<FileIndexAuthorization>;
+    /** Extra ignore segments beyond the route's defaults (node_modules, .git,
+     *  dotfiles/dot-dirs, common build dirs). Matched as exact path-segment
+     *  names, same rule as the defaults. */
+    ignore?: string[];
+    /** Passed to `fs.tree` as `options.maxDepth`. Default 12. */
+    maxDepth?: number;
+    /** Hard cap on entries returned after filtering. Default 5000. */
+    maxEntries?: number;
+    /** Optional host-provided cache seam. */
+    cache?: FileIndexCache;
+    /** Cache TTL in seconds when `cache` is set. Default 20. */
+    cacheTtlSeconds?: number;
+}
+/** Resolve a sandbox file index route with authorization, caching, and configurable depth and entries limits */
+export declare function createSandboxFileIndexRoute(options: CreateSandboxFileIndexRouteOptions): (request: Request) => Promise<Response>;