@jini-ai/chat 0.5.4 → 0.5.6

package/dist/core/run-events/entry.js

@@ -3,17 +3,29 @@
  * compaction and paragraph boundaries so live and persisted turns agree. Notice strings, custom
  * event names and excluded run-ID prefixes are explicit host inputs, never product wire defaults.
  * Authenticated routing, ownership, boot repair and storage transactions remain host responsibilities. */
+import { decodeSseFrames, parseSseRecord } from "@jini-ai/agent-runtime/providers/sse-decode";
 import { assistantContentFromEvents } from "../assistant-content.js";
 import { mergeAdjacentTextEvents } from "../compact-events.js";
 function wireString(v) {
     return typeof v === "string" ? v : v == null ? "" : JSON.stringify(v);
 }
 /** Display a wire scalar or JSON value using the existing empty-null convention. */
-export function asString({ value }) {
+export function asString({ value }, _options = {}) {
     return wireString(value);
 }
+/**
+ * Parses a `"usage"` wire payload into its renderable `AgentEvent`.
+ *
+ * The one case in {@link translateRunAgentPayload}'s switch with real branching: four independent
+ * optional fields, each `typeof`-checked before use (a malformed/missing field must not throw or
+ * silently coerce to `0`/`NaN`). Pulled out (2026-08-06, complexity pass, sixth pass) so those four
+ * ternaries are scored in their own scope instead of the switch's — this is the fix for the earlier
+ * `@complexityExemption`'s cognitive attribution on `translateRunAgentPayload`, which credited the
+ * `mcp-ui`/`a2ui` cases (each a one-line unwrap, zero branching — see their own comments below) for
+ * a cost that actually came from here.
+ */
 /** Keep only numeric usage fields; omit absent fields without changing JSON output. */
-export function parseUsageEvent({ payload }) {
+export function parseUsageEvent({ payload }, _options = {}) {
     const usage = (payload.usage ?? {});
     return {
         kind: "usage",
@@ -23,8 +35,66 @@ export function parseUsageEvent({ payload }) {
         ...(typeof payload.durationMs === "number" ? { durationMs: payload.durationMs } : {}),
     };
 }
+/**
+ * Reduces one wire-level `RunAgentPayload` into zero or one renderable `AgentEvent`s.
+ *
+ * Exported (a pure function, so directly testable with no `EventSource`/`fetch` stub needed — see
+ * `assistant-transport.transcript.test.ts`'s own module doc for the same reasoning applied to
+ * `runPrompt`) so `assistant-transport.a2ui.test.ts` can assert the `"a2ui"` branch below in
+ * isolation.
+ *
+ * @complexityExemption (2026-08-06, complexity pass, sixth pass; bar is ≤9/≤9) **Score: 12
+ * cyclomatic / 3 cognitive. Bar: ≤9 cyclomatic AND ≤9 cognitive. Cyclomatic-only exemption —
+ * cognitive already clears the bar since {@link parseUsageEvent} above took the switch's only real
+ * branching out of this function's own scope.** (An earlier version of this comment attributed the
+ * cognitive cost to the `mcp-ui`/`a2ui` cases below; that was wrong — an independent audit measured
+ * that extracting `parseUsageEvent` alone drops cognitive from 11 to 3, which only makes sense if
+ * `usage` was the real source. `mcp-ui`/`a2ui` are one-line unwraps with zero branching, exactly as
+ * their own comments already said.) Cyclomatic stays over by construction, not by accident: this is
+ * a flat `switch` over `RunProtocolEventWire`'s closed `payload.type` vocabulary, one `case` per
+ * wire type, and cyclomatic counts every `case` as a branch regardless of shape. Tried and rejected:
+ * a `Record<string, (payload) => AgentEvent | null>` lookup table scores lower but loses two things
+ * a switch over a TS discriminated union keeps — exhaustiveness checking (a lookup table compiles
+ * with a missing key; this switch does not, once `payload.type` is narrowed to the real union rather
+ * than the wire's untyped `string`), and the ability to attach a multi-paragraph comment to one case
+ * explaining a specific interop bug (the `mcp-ui`/`a2ui` cases' comments each document why THAT case
+ * cannot fall through to `default` — see below). A lookup table would have to carry those as a
+ * parallel structure, one step removed from the code they explain. Left as a `switch`, documented
+ * here rather than only in this session's report.
+ */
+// Typed media (currently just images) the daemon attached alongside the flattened `content`
+// string — see `@jini-ai/protocol`'s `events.ts` doc on why the wire field is `unknown`
+// rather than a checked type here: the real shape is validated where `ToolCard` renders it.
+// Forwarded verbatim rather than re-validated a second time in this reducer — an
+// `Array.isArray` guard rather than a deep shape check, since a malformed entry inside it
+// is a rendering concern (`ToolCard`'s own `ToolResultMedia` already ignores anything that
+// isn't a recognized block), not a transport one.
+// An MCP content block the daemon withheld from the tool result because it is for the HUMAN,
+// not the model (`@jini-ai/daemon`'s `delegated-tool-bridge.ts` → `tool-result-surfaces.ts`).
+// Explicit rather than left to `default` below because the shapes do not line up: the default
+// passes the WHOLE wire payload as `data`, but `@jini-ai/chat`'s `McpUiSurfaceCard` runs
+// `parseUIResource` over each event's `data` and that requires the bare `EmbeddedResource`
+// (`{type:'resource', resource:{uri,mimeType,text}}`). Handing it the envelope instead fails
+// the `type !== 'resource'` check and renders an empty frame — a silent no-op, which is the
+// worst possible failure for a confirmation dialog. Unwrapping here is what makes the two ends
+// meet. `name` must stay `"mcp-ui"` to match `MCP_UI_EXT_EVENT_NAME`.
+// A2UI's own agent->renderer envelope (`@jini-ai/core`'s `SurfaceEmission` with
+// `channel: "a2ui"`, injected by `@jini-ai/daemon`'s `delegated-tool-bridge.ts` as
+// `{type: "a2ui", message: <AgentToRendererMessage>}`). Unwrapped to the bare `.message` here,
+// not left to the `default` branch below, for the same reason `mcp-ui` above is explicit:
+// `@jini-ai/chat/react`'s `A2uiSurfaceCard` (registered against `'a2ui'` in
+// `AssistantDock.tsx`) runs `extractSurfaceId`/`interpreter.applyAgentMessage` over each event's
+// `data` directly, and both require a bare, spec-shaped envelope — not the `{type, message}`
+// wire wrapper. Mirrors Jini's own reference host's identical `case "a2ui"` in
+// `examples/reference-web/src/daemon-transport.ts`.
+// thinking_start/stage_start/stage_end/surface_request/surface_response: no dedicated
+// chat-core variant. Routed through the `ext` escape hatch rather than dropped, so a future
+// renderer can opt in without a transport change.
+// Streamed tool input (with `--include-partial-messages`): the finished `tool_use` carries the
+// same input whole, and nothing renders the fragments. Kept, they became one no-op `ext` event
+// per chunk in the saved row.
 /** Reduce one daemon payload; preserve UI envelopes and drop duplicate input fragments. */
-export function translateRunAgentPayload({ payload }) {
+export function translateRunAgentPayload({ payload }, _options = {}) {
     switch (payload.type) {
         case "status":
             return { kind: "status", label: wireString(payload.label), ...(payload.detail ? { detail: wireString(payload.detail) } : {}) };
@@ -58,15 +128,51 @@ export function translateRunAgentPayload({ payload }) {
             return { kind: "ext", name: payload.type, data: payload };
     }
 }
+/**
+ * Turns a terminal stream `reason` into the one renderable event a human needs to see, or `null`
+ * when the reason speaks for itself.
+ *
+ * Only `max_tool_turns` qualifies today, and it qualifies for a specific reason: it is the one
+ * terminal reason that is INDISTINGUISHABLE from success in the pane. `stop`/`end_turn` mean the
+ * assistant finished; an `error` reason already renders as an error. A turn that hit the tool-step
+ * ceiling just stops — mid-task, with whatever partial text it had, and nothing on screen saying
+ * the work was cut short rather than completed. That is the failure this exists to close: the
+ * server now reports the loop's real reason (`byok-provider-turn.ts`'s `normalizeTurnResult`
+ * captures it instead of echoing the provider's last raw stop code), and until this, the browser
+ * received that reason and dropped it.
+ *
+ * Rendered as a `status` event rather than an `error`, deliberately: nothing failed. The turn did
+ * real work and stopped at a budget, and the useful next action is "ask it to continue", which is
+ * what the detail says.
+ */
 /** A host notice for a run that used its tool-step budget. */
-export function terminalReasonNotice({ reason, notice }) {
+export function terminalReasonNotice({ reason, notice }, _options = {}) {
     return reason === "max_tool_turns" ? { ...notice } : null;
 }
+/**
+ * Reads that classification off a raw `end` frame, or `null` when the run succeeded, sent nothing,
+ * or sent something unparseable.
+ *
+ * `code`/`signal`/`resumable` come back pre-rendered as display strings rather than as their wire
+ * types, because both callers ({@link terminalOutcomeNotice} and {@link terminalFailureError}) want
+ * the same human-facing rendering of an absent value (`"none"`/`"no"`) and neither does arithmetic
+ * on them. Rendering once, here, is what stops the operator-facing notice and the persisted error
+ * from describing the same dead run in two different ways.
+ *
+ * Every field is `typeof`-checked before use, and a malformed body returns `null` rather than
+ * throwing: this runs inside an `EventSource` listener whose other job is to END the run, and a
+ * throw there would strand the pane mid-turn over a cosmetic detail.
+ */
+/**
+ * Whether a failed run never started a process: no exit code, no signal, not resumable. That is the
+ * exact end the daemon's `failBeforeSpawn` and the host's own start refusals write, and a process
+ * that did run always exits with a code or a signal.
+ */
 function neverStarted(outcome) {
     return outcome.status === "failed" && outcome.code === "none" && outcome.signal === "none" && outcome.resumable === "no";
 }
 /** Read non-successful daemon classification without throwing on malformed frames. */
-export function readTerminalOutcome({ raw }) {
+export function readTerminalOutcome({ raw }, _options = {}) {
     if (!raw)
         return null;
     let payload;
@@ -89,8 +195,31 @@ export function readTerminalOutcome({ raw }) {
         resumable: payload.resumable === true ? "yes" : "no",
     };
 }
+/**
+ * Turns a daemon `end` frame's terminal outcome into a visible `status` event when — and only when —
+ * the run did NOT succeed.
+ *
+ * WHY THIS EXISTS (2026-09-06 chat-death investigation, `ADS-memory/reports/2026-09-06-chat-death-investigation.md`):
+ * `@jini-ai/protocol`'s `RunEndPayload` carries `status`/`code`/`signal`/`resumable`, and
+ * `@jini-ai/daemon`'s `finish()` is the ONLY event a terminal run emits — there is no separate
+ * `error` frame for a failed run. {@link subscribeToRun}'s `end` listener read only `reason` (a
+ * field `RunEndPayload` does not even have — it is BYOK-only), so a run the daemon had already
+ * classified `failed` arrived here indistinguishable from a completed one, was reported through
+ * `onDone`, and was persisted to `chat.db` as `run_status='succeeded'` with empty content. Two such
+ * rows existed in the investigated host's `chat.db` — one `codex`, one `claude`, 578 ms and 552 ms — and they
+ * are what "the chat just craps out with no error" actually looks like on disk.
+ *
+ * This is the SEEN half of that fix; {@link terminalFailureError} below is the WRITTEN-DOWN half
+ * (2026-09-07, owner-approved). An earlier version of this comment said the persistence change was
+ * deliberately NOT made and was out of scope until the owner signed off — that is no longer true,
+ * and the two halves stayed separate functions only because they disagree on exactly one input:
+ * `canceled` earns a notice but is not a failure.
+ *
+ * Returns `null` for a successful or absent status so a normal turn gains no extra event.
+ */
+// "exited without answering" would be false here: no process ever ran.
 /** A visible terminal classification rendered with host-supplied copy. */
-export function terminalOutcomeNotice({ raw, notices }) {
+export function terminalOutcomeNotice({ raw, notices }, _options = {}) {
     const outcome = readTerminalOutcome({ raw });
     if (!outcome)
         return null;
@@ -99,8 +228,46 @@ export function terminalOutcomeNotice({ raw, notices }) {
     return { kind: "status", label: outcome.status === "canceled" ? notices.canceledLabel : notices.failedLabel,
         detail: notices.terminalDetail({ outcome }) };
 }
+/**
+ * The reportable `Error` for a daemon `end` frame the daemon itself classified as `failed`, or
+ * `null` for every other terminal outcome.
+ *
+ * WHY THIS EXISTS (2026-09-07, owner-approved): it is what makes a dead run RECOVERABLE FROM THE
+ * DATABASE ALONE. Until now a failed run was reported only through `onDone`, so the durable record
+ * said `run_status='succeeded'` with empty content: the live transcript was the ONLY place the
+ * failure was visible, and once it was gone the row was indistinguishable from a successful turn
+ * that happened to answer with nothing. That lie is why diagnosing chat deaths burned multiple
+ * sessions and carried a wrong premise through two handoffs. `f682eff2` deliberately left it in
+ * place ("a behavior change to what the product writes down... out of scope until the owner signs
+ * off"); the owner has now signed off, and this is that change.
+ *
+ * NOTHING IN THIS FILE COMPUTES `runStatus`. Three pieces of `@jini-ai/chat` do, and the whole
+ * effect of this function rests on all three:
+ *   1. `useRunStream`'s `onError` sets the run's status to `'error'` — and its `onDone` is written
+ *      as `prev.status === 'error' ? prev.status : 'done'`, so an `onDone` arriving AFTER this
+ *      preserves the failure instead of overwriting it. That is what lets {@link subscribeToRun}
+ *      report the failure and STILL settle the run through `finish()` with its collected events
+ *      intact, rather than having to choose between the two. The call order in that listener is
+ *      load-bearing, not incidental.
+ *   2. `useConversation` maps run status `'error'` to `ChatMessage.runStatus: 'failed'`.
+ *   3. `isTerminalRunStatus` already counts `'failed'` as terminal, so `assistant-chats.ts`'s
+ *      `persistableMessages` KEEPS the message (it discards only still-streaming turns) and
+ *      `AssistantDock/hooks/AssistantDock.hooks.tsx`'s `shouldPublishOnMessagesChange` still
+ *      settles the dock. A failed run therefore cannot hang the pane waiting for a terminal state
+ *      that never arrives — which is the failure this change would otherwise have traded the wrong
+ *      record for.
+ *
+ * `canceled` is excluded on purpose: a run the operator stopped is not a failure, and
+ * `useRunStream.cancel()` already stamps its own `'canceled'` status. Marking it `failed` would
+ * swap one wrong record for another.
+ *
+ * Historical rows are NOT retrofitted. The investigated host's `chat.db` held 2 such rows on 2026-09-07 and
+ * the pre-split `content.db` copy held 6; nothing distinguishes a genuinely empty
+ * successful answer from a death after the fact, so a migration could only guess. Going-forward
+ * correctness is the goal.
+ */
 /** Report a failed run; operator cancellation is not a failure. */
-export function terminalFailureError({ raw }) {
+export function terminalFailureError({ raw }, _options = {}) {
     const outcome = readTerminalOutcome({ raw });
     if (!outcome || outcome.status !== "failed")
         return null;
@@ -108,8 +275,12 @@ export function terminalFailureError({ raw }) {
         return new Error("The run failed before the agent started.");
     return new Error(`The agent process exited without answering (exit code ${outcome.code}, signal ${outcome.signal}, resumable ${outcome.resumable}).`);
 }
+/** Reads a terminal frame's `reason` from either stream shape without letting a malformed or absent
+ *  body prevent the turn from ending: the daemon path wraps it in a `RunProtocolEventWire.payload`,
+ *  the BYOK path sends a bare `{reason}`, and `subscribeToRun`'s `end` event may carry no data at
+ *  all. A notice is a nicety; finishing the run is not. */
 /** Read a wrapped daemon or bare provider terminal reason, failing soft. */
-export function readTerminalReason({ raw, wrapped }) {
+export function readTerminalReason({ raw, wrapped }, _options = {}) {
     if (!raw)
         return "";
     try {
@@ -121,41 +292,50 @@ export function readTerminalReason({ raw, wrapped }) {
         return "";
     }
 }
+/** Preserve chat's per-line trimming and default event name; omit data-less keepalives. */
+function chatFrame(frame) {
+    return frame.dataLines.length > 0
+        ? { event: frame.event?.trim() ?? "message", data: frame.dataLines.map(line => line.trim()).join("\n") }
+        : null;
+}
+/**
+ * Parses one blank-line-delimited SSE frame's raw text into `{event, data}`, split out as its own
+ * pure function so it is directly testable with a plain string, no `ReadableStream`/reader involved.
+ *
+ * Returns `null` for a frame with no `data:` lines — {@link readSseFrames} skips yielding those
+ * (a bare `event: ping` keepalive, for example, or a frame carrying only an `id:` field).
+ */
 /** Parse the existing named SSE framing; bare keepalive frames return null. */
-export function parseFrame({ rawFrame }) {
-    let event = "message";
-    const dataLines = [];
-    for (const line of rawFrame.split("\n")) {
-        if (line.startsWith("event:"))
-            event = line.slice(6).trim();
-        else if (line.startsWith("data:"))
-            dataLines.push(line.slice(5).trim());
-    }
-    return dataLines.length > 0 ? { event, data: dataLines.join("\n") } : null;
+export function parseFrame({ rawFrame }, _options = {}) {
+    return chatFrame(parseSseRecord({ rawFrame }));
 }
-/** Decode the existing named SSE framing; cancellation always releases its reader. */
-export async function* readSseFrames({ body }) {
+/**
+ * Splits a `text/event-stream` response body into `{event, data}` frames. Frames are
+ * blank-line-delimited per the SSE spec; per-frame field parsing lives in {@link parseFrame} above.
+ *
+ * @complexity O(n) in response body bytes; O(1) additional buffering per chunk beyond the
+ * not-yet-terminated tail of the current frame.
+ * @overallScore 100
+ */
+/** Decode complete named frames; cancellation always releases its reader. Inherits shared framing costs. */
+export async function* readSseFrames({ body }, _options = {}) {
     const reader = body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
     let ended = false;
-    try {
+    async function* chunks() {
         for (;;) {
             const { done, value } = await reader.read();
             if (done) {
                 ended = true;
-                break;
-            }
-            buffer += decoder.decode(value, { stream: true });
-            let boundary = buffer.indexOf("\n\n");
-            while (boundary !== -1) {
-                const rawFrame = buffer.slice(0, boundary);
-                buffer = buffer.slice(boundary + 2);
-                const frame = parseFrame({ rawFrame });
-                if (frame)
-                    yield frame;
-                boundary = buffer.indexOf("\n\n");
+                return;
             }
+            yield value;
+        }
+    }
+    try {
+        for await (const decoded of decodeSseFrames({ source: chunks() }, { flushFinalFrame: false })) {
+            const frame = chatFrame(decoded);
+            if (frame)
+                yield frame;
         }
     }
     finally {
@@ -164,20 +344,37 @@ export async function* readSseFrames({ body }) {
         reader.releaseLock();
     }
 }
+/**
+ * Whether the agent daemon holds this run, so its event stream can be read at
+ * `/api/runs/:id/events`. A BYOK or AG-UI run id names a turn that lived on one browser request, and
+ * there is nothing server-side to watch.
+ */
 /** Identify runs held by the daemon using the host's excluded ID prefixes. */
-export function isDaemonRunId({ runId, excludedPrefixes }) {
+export function isDaemonRunId({ runId, excludedPrefixes }, _options = {}) {
     return runId.length > 0 && !excludedPrefixes.some(prefix => runId.startsWith(prefix));
 }
 /** Copy the host's interruption notice into a saved turn. */
-export function runInterruptedNotice({ notice }) {
+export function runInterruptedNotice({ notice }, _options = {}) {
     return { ...notice };
 }
+/**
+ * A chat message's `content` for a list of events: `@jini-ai/chat`'s own rule
+ * (`assistantContentFromEvents`, also what `useConversation` uses for a live turn), so a row the
+ * server finalizes reads the same as one the browser saved. That rule puts a paragraph break where a
+ * tool call or card sat between two text runs, so a working note is never glued onto the answer.
+ */
 /** Use the same paragraph-boundary rule as a live chat turn. */
-export function runContentFromEvents({ events }) {
+export function runContentFromEvents({ events }, _options = {}) {
     return assistantContentFromEvents({ events });
 }
+/**
+ * The events to SAVE for a turn: streamed `text`/`thinking` deltas joined into one event per run
+ * (`@jini-ai/chat`'s `mergeAdjacentTextEvents`). Live, one event per few tokens is what streams words
+ * onto the screen; saved, it only repeats the event wrapper per token. Used by every saver (the server
+ * finalizer and the chat PUT route the browser saves through), so both write the same shape.
+ */
 /** Compact adjacent text/thinking deltas for durable storage. */
-export function runEventsForSave({ events }) {
+export function runEventsForSave({ events }, _options = {}) {
     return mergeAdjacentTextEvents({ events });
 }
 function parseWire(raw) {
@@ -205,11 +402,17 @@ function parseJsonLine(line) {
 function numberOf(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
+/** `{attempt, maxAttempts}` from an `api_retry` line, keeping only the fields it actually carries. */
+// `api_retry` is Claude Code's own line shape, so the service it names is Claude.
 function retryData(line) {
     const attempt = numberOf(line.attempt);
     const maxAttempts = numberOf(line.max_retries);
     return { ...(attempt !== undefined ? { attempt } : {}), ...(maxAttempts !== undefined ? { maxAttempts } : {}), service: "Claude" };
 }
+/**
+ * Claude Code's stdout heartbeats → typed `status` events for the live activity line
+ * (`@jini-ai/chat`'s `run-activity.ts` reads `code`/`data`). `null` for any other line.
+ */
 function heartbeatStatus(line) {
     if (line.type === "tool_progress") {
         const elapsedSeconds = numberOf(line.elapsed_time_seconds);
@@ -225,7 +428,20 @@ function heartbeatStatus(line) {
         return { kind: "status", code: "thinking", label: "thinking" };
     return null;
 }
+/**
+ * Lines the daemon has already parsed into typed events, so keeping them as `raw` only stores them
+ * twice: `stream_event` (the token-by-token echo `--include-partial-messages` adds → `text`), and the
+ * whole `assistant`/`user` messages (→ `text`/`thinking`/`tool_use`/`tool_result`). The `user` echo
+ * repeats every tool result: one "summarize my posts" turn saved 129 KB of them. Matched on the
+ * line's start, not a parse, because a long line arrives split over several stdout chunks and its
+ * first piece is not valid JSON on its own. Claude Code writes `type` first on every line.
+ */
 const ECHO_LINE = /^\{"type":"(?:stream_event|assistant|user)"/;
+/**
+ * One CLI stdout/stderr chunk → events. Every JSON line that is a heartbeat also yields a typed
+ * `status` event; echo lines ({@link ECHO_LINE}) are dropped; everything else stays in ONE `raw`
+ * event, verbatim. A chunk with no JSON lines at all (a plain-format CLI) is one `raw` event, as before.
+ */
 function chunkEvent(raw) {
     const frame = parseWire(raw);
     if (!frame)
@@ -249,6 +465,8 @@ function chunkEvent(raw) {
         kept = chunk;
     return kept.length > 0 ? [{ kind: "raw", line: kept }, ...statuses] : statuses;
 }
+// Order matters and matches the browser's `end` listener: the `max_tool_turns` notice first, then
+// the failed/canceled notice, then the failure itself.
 function endOutcome(raw, notices) {
     const events = [];
     const reasonNotice = terminalReasonNotice({ reason: readTerminalReason({ raw, wrapped: true }), notice: notices.toolStepLimit });
@@ -262,8 +480,24 @@ function endOutcome(raw, notices) {
     const terminal = outcome?.status ?? "succeeded";
     return error ? { events, error, terminal } : { events, terminal };
 }
+/**
+ * Translates one named daemon SSE frame (`event:` name plus raw `data:` text) into its effect on the
+ * turn. The browser's `subscribeToRun` dispatches the result to `RunHandlers`; the server finalizer
+ * folds it into the row it saves. Never throws: a malformed frame yields no events rather than
+ * stranding either reader mid-turn.
+ *
+ * An `error` frame with no data is a connection error, not a run error — the browser's
+ * `EventSource` reports those on the same event name, so it must check for data before calling this.
+ *
+ * @complexity O(size of the frame).
+ */
+// The agent CLI's own output. `stderr` is where a dying CLI says WHY it is dying.
+// Shown AND saved as a status line, not only reported: the error is live-only state, so without
+// the event the saved turn (and a reload) showed a bare "failed" with the reason lost. This is
+// where the daemon's plain pre-spawn reason ("The assistant could not start: ...") and the
+// host's start refusals reach the user.
 /** Fold one named daemon frame into events, a failure and an optional terminal status. */
-export function translateRunFrame({ kind, raw, notices }) {
+export function translateRunFrame({ kind, raw, notices }, _options = {}) {
     switch (kind) {
         case "agent": {
             const frame = parseWire(raw);

package/dist/core/transcript.d.ts

@@ -13,12 +13,13 @@
  * transcript assembly, so they are generalized into caller-supplied hooks
  * (or dropped) below — see archived provenance ledger for the full accounting.
  */
+import { type UserTextRedactionOptions } from './user-text-redaction.js';
 import type { ChatMessage } from './messages.js';
 import type { PersistedArtifactFileRef } from './util/strip.js';
 /** The most recent `user`-authored message's content, or `''` if there isn't one. */
 export declare function latestUserPromptFromHistory({ history }: {
     history: ChatMessage[];
-}): string;
+}, options?: UserTextRedactionOptions): string;
 /**
  * Strip transcript-echo hazards from a prior assistant turn before it goes
  * back to the agent as history: an already-answered `<question-form>` /
@@ -43,7 +44,7 @@ export declare function sanitizePriorAssistantTurn({ content }: {
 }, { persistedArtifactFiles }?: {
     persistedArtifactFiles?: (ReadonlyArray<PersistedArtifactFileRef>) | undefined;
 }): string;
-export interface BuildTranscriptOptions {
+export interface BuildTranscriptOptions extends UserTextRedactionOptions {
     /**
      * Scope the transcript to messages from this agent's family onward,
      * dropping any older history from a different agent. Omit to include the

package/dist/core/transcript.js

@@ -1,13 +1,29 @@
+/**
+ * @module transcript
+ *
+ * Pure transcript-assembly helpers: turning a `ChatMessage[]` history into
+ * the flattened text a host sends to an agent as prior-turn context.
+ *
+ * Adapted from OD's `providers/daemon.ts` transcript section (see
+ * archived provenance ledger). The OD original also owned SSE/fetch transport
+ * (`streamViaDaemon`, `DaemonStreamHandlers`) — none of that is ported here;
+ * only the pure string-assembly helpers. It also hard-coded OD's BYOK/
+ * OpenCode agent-family policy and an `agent-browser`-tool-specific
+ * context-warning heuristic; both are OD product policy, not generic
+ * transcript assembly, so they are generalized into caller-supplied hooks
+ * (or dropped) below — see archived provenance ledger for the full accounting.
+ */
+import { redactUserMessage } from './user-text-redaction.js';
 import { summarizeArtifactsForTranscript } from './util/strip.js';
 const DEFAULT_MAX_TRANSCRIPT_MESSAGE_CHARS = 12_000;
 const DEFAULT_LARGE_TOOL_RESULT_CHARS = 8_000;
 const DEFAULT_HIGH_INPUT_TOKEN_WARNING_THRESHOLD = 200_000;
 /** The most recent `user`-authored message's content, or `''` if there isn't one. */
-export function latestUserPromptFromHistory({ history }) {
+export function latestUserPromptFromHistory({ history }, options = {}) {
     for (let i = history.length - 1; i >= 0; i -= 1) {
         const message = history[i];
         if (message?.role === 'user')
-            return message.content;
+            return redactUserMessage({ message }, options).message.content;
     }
     return '';
 }
@@ -122,7 +138,7 @@ export function buildTranscript({ history }, options = {}) {
     const scopedHistory = scopeHistoryToAgent(history, options.targetAgentId, isSameAgentFamily);
     const transcript = scopedHistory
         .map((m) => {
-        const trimmed = m.content.trim();
+        const trimmed = redactUserMessage({ message: m }, options).message.content.trim();
         const sanitized = m.role === 'assistant' ? sanitizePriorAssistantTurn({ content: trimmed }, { persistedArtifactFiles: resolvePersistedArtifactFiles(m) }) : trimmed;
         return `## ${m.role}\n${escapeTranscriptRoleDelimiters(truncateForTranscript(sanitized, maxMessageChars))}`;
     })

package/dist/core/user-text-redaction.d.ts

@@ -0,0 +1,56 @@
+import type { ChatMessage } from './messages.js';
+export interface SecretRedactionSignal {
+    readonly secretRedacted: true;
+    readonly count: number;
+}
+export interface UserTextRedaction {
+    readonly text: string;
+    readonly secretRedacted: boolean;
+    readonly count: number;
+}
+export type RedactUserText = (required: {
+    readonly text: string;
+}, optional?: {
+    readonly secretField?: boolean;
+}) => UserTextRedaction;
+export interface UserTextRedactionOptions {
+    /** Default on; hosts may supply a stricter credential policy without changing chat storage. */
+    readonly redactUserText?: RedactUserText;
+    /** Contains no user text or credential fragments. A host can offer its secure credential card. */
+    readonly onSecretRedacted?: (signal: SecretRedactionSignal) => void;
+}
+export declare const SECRET_REDACTED_NOTICE = "I removed what looked like a key from your message. If it was real, rotate it. Use the secure form to save it.";
+export declare const CREDENTIAL_CARD_GUIDANCE = "Use the secure form to save keys, tokens, passwords, and secrets. Chat answers are sent to the assistant.";
+/** Stricter than error redaction: also detects unlabelled long tokens, while retaining ordinary URLs,
+ * hexadecimal hashes, identifiers and prose. Strong credential syntax inside a URL is still caught. */
+export declare function redactUserText({ text }: {
+    readonly text: string;
+}, { secretField }?: {
+    readonly secretField?: boolean;
+}): UserTextRedaction;
+/** Prepare before storage OR model dispatch. Return only sanitized content and non-secret metadata. */
+export declare function redactUserMessage<T extends {
+    readonly role: string;
+    readonly content: string;
+}>({ message }: {
+    readonly message: T;
+}, options?: UserTextRedactionOptions): {
+    readonly message: T;
+    readonly secretRedacted: boolean;
+    readonly count: number;
+};
+/** Also protects replay of historical text accepted before the guard was installed. */
+export declare function redactUserHistory({ history }: {
+    readonly history: readonly ChatMessage[];
+}, options?: UserTextRedactionOptions): ChatMessage[];
+/** Redact model input and append the host's non-secret card guidance once, using the redaction
+ * signal rather than display text. `secretRedacted` carries an earlier ingress/composer signal;
+ * persistence must continue to use redactUserText/redactUserMessage without the model note. */
+export declare function guardUserText({ text }: {
+    readonly text: string;
+}, options?: {
+    readonly modelNote?: string;
+    readonly secretRedacted?: boolean;
+    readonly redactUserText?: RedactUserText;
+}): string;
+//# sourceMappingURL=user-text-redaction.d.ts.map

package/dist/core/user-text-redaction.js

@@ -0,0 +1,89 @@
+/** One credential policy for chat text; secure card values must bypass this text-only boundary. */
+import { redactSecretShapes } from '@jini-ai/diagnostics/redaction/secrets-only';
+export const SECRET_REDACTED_NOTICE = 'I removed what looked like a key from your message. If it was real, rotate it. Use the secure form to save it.';
+export const CREDENTIAL_CARD_GUIDANCE = 'Use the secure form to save keys, tokens, passwords, and secrets. Chat answers are sent to the assistant.';
+const REMOVED = '[token removed]';
+const INTERNAL_REMOVED = '[REDACTED:chat_secret]';
+const REDACTION_MARKER = /\[REDACTED:[^\]\r\n]+\]/g;
+const CHAT_RULES = [
+    { kind: 'chat_key', pattern: /(?<![A-Za-z0-9_-])sk-[A-Za-z0-9_-]{16,}/g, replacement: () => INTERNAL_REMOVED },
+    { kind: 'chat_key', pattern: /(?<![A-Za-z0-9_])xox[baprs]-[A-Za-z0-9-]{16,}/g, replacement: () => INTERNAL_REMOVED },
+    // Explicit authorization syntax catches even short values. Exempt scheme descriptions in prose.
+    { kind: 'chat_bearer', pattern: /\bBearer[ \t]+(?!\[REDACTED)(?!(?:token|tokens|authentication|authorization|auth|scheme|credentials?)\b)[A-Za-z0-9._~+\/=-]+/gi, replacement: () => 'Bearer ' + INTERNAL_REMOVED },
+];
+function entropy(text) {
+    const counts = new Map();
+    for (const char of text)
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    let bits = 0;
+    for (const count of counts.values()) {
+        const probability = count / text.length;
+        bits -= probability * Math.log2(probability);
+    }
+    return bits;
+}
+/** Stricter than error redaction: also detects unlabelled long tokens, while retaining ordinary URLs,
+ * hexadecimal hashes, identifiers and prose. Strong credential syntax inside a URL is still caught. */
+export function redactUserText({ text }, { secretField = false } = {}) {
+    // Existing removal markers must survive a second pass through assignment rules (api_key=…).
+    const literalMarkers = new Map();
+    let literalPrefix = 'chat_literal_';
+    while (text.includes(literalPrefix))
+        literalPrefix += '_';
+    const protectedText = text.replace(REDACTION_MARKER, marker => {
+        const key = '[REDACTED:' + literalPrefix + literalMarkers.size + ']';
+        literalMarkers.set(key, marker);
+        return key;
+    }).replaceAll(REMOVED, INTERNAL_REMOVED);
+    const base = redactSecretShapes({ text: protectedText, policy: { additionalRules: CHAT_RULES } });
+    let count = base.redactions;
+    const urls = [...base.text.matchAll(/\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"']+/gi)]
+        .map(match => ({ start: match.index, end: match.index + match[0].length }));
+    let cleaned = base.text.replace(/(?<![A-Za-z0-9_+\/=-])[A-Za-z0-9_+\/=-]{40,}(?![A-Za-z0-9_+\/=-])/g, (candidate, offset) => {
+        if (urls.some(url => offset >= url.start && offset < url.end))
+            return candidate;
+        if (/^[a-f0-9]+$/i.test(candidate) || !/[A-Za-z]/.test(candidate))
+            return candidate;
+        const bits = entropy(candidate);
+        const mixedAlphabet = /[A-Z]/.test(candidate) && /[a-z]/.test(candidate);
+        if (bits < 4 || (!/[0-9]/.test(candidate) && (!mixedAlphabet || bits < 4.5)))
+            return candidate;
+        count += 1;
+        return INTERNAL_REMOVED;
+    });
+    // A labelled credential answer can be a short password with no recognisable shape at all.
+    if (secretField && cleaned.trim() !== '' && cleaned !== INTERNAL_REMOVED) {
+        cleaned = INTERNAL_REMOVED;
+        count = Math.max(1, count);
+    }
+    return { text: cleaned.replace(REDACTION_MARKER, marker => literalMarkers.get(marker) ?? REMOVED), secretRedacted: count > 0, count };
+}
+/** Prepare before storage OR model dispatch. Return only sanitized content and non-secret metadata. */
+export function redactUserMessage({ message }, options = {}) {
+    if (message.role !== 'user')
+        return { message, secretRedacted: false, count: 0 };
+    const result = (options.redactUserText ?? redactUserText)({ text: message.content });
+    const signal = result.secretRedacted ? { secretRedacted: true, count: result.count } : undefined;
+    if (signal)
+        options.onSecretRedacted?.(signal);
+    return {
+        message: { ...message, content: result.text, ...(signal ? { secretRedaction: signal } : {}) },
+        secretRedacted: result.secretRedacted, count: result.count,
+    };
+}
+/** Also protects replay of historical text accepted before the guard was installed. */
+export function redactUserHistory({ history }, options = {}) {
+    return history.map(message => redactUserMessage({ message }, options).message);
+}
+/** Redact model input and append the host's non-secret card guidance once, using the redaction
+ * signal rather than display text. `secretRedacted` carries an earlier ingress/composer signal;
+ * persistence must continue to use redactUserText/redactUserMessage without the model note. */
+export function guardUserText({ text }, options = {}) {
+    const safe = (options.redactUserText ?? redactUserText)({ text }, {});
+    if (!safe.secretRedacted && options.secretRedacted !== true)
+        return safe.text;
+    if (!options.modelNote || safe.text.includes(options.modelNote))
+        return safe.text;
+    return `${safe.text}\n\n${options.modelNote}`;
+}
+//# sourceMappingURL=user-text-redaction.js.map