toolroll 0.9.96 → 0.9.97

package/dist/lead.js

@@ -1,7 +1,8 @@
 import { Buffer } from "node:buffer";
 import { leadToolFailureReason, leadToolLabel } from "./lead-progress.js";
 import { createHash } from "node:crypto";
-import { leadTimeoutNotice } from "./store.js";
+import { leadAskAwaitsAnswer, leadQuickAnswersOn, leadTimeoutNotice, setLeadTurnRoute } from "./store.js";
+import { quickAdvertises, quickLeadModel, quickRoute, quickStepEscalates, routeWords } from "./lead-route.js";
 import { RESULT_IMAGES_PER_TURN_CAP } from "./chat-evidence.js";
 import { isVerifiedApprover, reproveApprover } from "./principal.js";
 import { LEAD_MAX_CALLS_PER_STEP, LEAD_MAX_STEPS, LEAD_TOOL_RESULT_CAP_BYTES, TURN_WALL_CLOCK_MS, composeLeadRequest, credentialKeyOf, isDirectChatProvider, leadWorstCaseForPrice, performLeadRequest, priceForConfig, cacheWorstPrice, settleWithCache, subscriptionCredentialKey, } from "./converse.js";
@@ -74,8 +75,9 @@ export const LEAD_FAILURE_COPY = {
     empty: "The lead sent back an empty answer. Nothing was kept. Send your message again.",
     unusable: "The lead's answer couldn't be used, so it was thrown away. Nothing was kept. Send your message again.",
 };
-/** A failed turn's saved reason as plain words, for a surface that reads the turn back later (a restart, a delivery retry). */
-export function leadFailureText(reason, unknownSpend = false) {
+/** A failed turn's saved reason as plain words, for a surface that reads the turn back later (a restart, a delivery retry).
+ * Its saved detail (v158), when known, names the exact cause the person saw live ("not installed", "sign-in expired"). */
+export function leadFailureText(reason, unknownSpend = false, detail = null) {
     // A turn whose cost is unknown paused chat: say what happened (its reason's first sentence), then that the person must
     // confirm the cost before chat runs again — never "send it again", which would only meet the pause.
     if (unknownSpend) {
@@ -87,6 +89,10 @@ export function leadFailureText(reason, unknownSpend = false) {
         const happened = /^[^.]*\./.exec(leadFailureText(reason))?.[0] ?? "The lead's reply didn't finish.";
         return `${happened} Its cost isn't known, so chat is paused. Confirm the cost on the Chat page to turn chat back on.`;
     }
+    if (reason === "provider-error" && detail === "not-installed")
+        return LEAD_FAILURE_COPY.notInstalled;
+    if (reason === "provider-error" && detail === "sign-in")
+        return LEAD_FAILURE_COPY.signIn;
     switch (reason) {
         case "over-reservation": return "This reply reported more use than was set aside for it, so it was stopped and its cost counted. Send your message again.";
         case "timeout":
@@ -212,6 +218,13 @@ export async function runLeadTurn(input) {
     // The channel's standing, proved before anything is admitted or sent.
     if (input.revalidate !== undefined && !(await input.revalidate()).ok)
         return refuse("channel");
+    // Which model answers (responsive-chat.md §8), decided once, before the turn: the faster one only for a plain read
+    // question with quick answers on; everything else on the configured model, as before.
+    const quickOn = leadQuickAnswersOn(store);
+    const quickModel = quickOn ? quickLeadModel(store) : config.model;
+    let route = quickRoute({ enabled: quickOn, provider: config.provider, mainModel: config.model, message,
+        hasContext: input.context !== undefined, hasReplyImage: input.replyImage !== undefined, askOpen: quickOn && leadAskAwaitsAnswer(store, thread.id, clock()),
+        quickModel, quickAllowed: quickOn && store.agentPolicyRefusal(config.provider, quickModel) === null }).route;
     let now = clock();
     store.sweepStaleLeadTurns(now);
     const view = leadViewContextFor(store, who);
@@ -282,6 +295,7 @@ export async function runLeadTurn(input) {
         const started = store.startLeadTurn(turnId, now);
         if (!started.ok)
             throw new Error("new lead turn could not start");
+        setLeadTurnRoute(store, turnId, started.generation, route);
         if (input.queuedMessageId === undefined)
             store.appendLeadMessage({ thread: thread.id, turn: turnId, role: "operator", text: message }, now);
         else {
@@ -308,6 +322,12 @@ export async function runLeadTurn(input) {
     }
     catch { /* a watcher never breaks the turn */ } };
     progress({ kind: "started", turn: turnId });
+    /** Text that looked like a secret was held back: every preview closes, once (responsive-chat.md §2.1). */
+    let blockedSaid = false;
+    const blockPreview = () => { if (!blockedSaid) {
+        blockedSaid = true;
+        progress({ kind: "blocked", turn: turnId });
+    } };
     let proposals = 0;
     let reads = 0;
     let steps = 0;
@@ -336,18 +356,18 @@ export async function runLeadTurn(input) {
         return store.listLeadTurnEvidence(turnId).map(one => one.artifact);
     };
     /** The turn ends failed: its drafts are deleted, its cost settled — the whole reservation when any of it is unknown. */
-    const fail = (failed, message, unknownSpend) => {
+    const fail = (failed, message, unknownSpend, failureDetail = null) => {
         now = clock();
-        store.finalizeLeadTurn(turnId, started.generation, { state: "failed", settledMicrousd: settled, unknownSpend, tokensIn, tokensOut, failureReason: failed }, now);
+        store.finalizeLeadTurn(turnId, started.generation, { state: "failed", settledMicrousd: settled, unknownSpend, tokensIn, tokensOut, failureReason: failed, failureDetail }, now);
         store.dropLeadAsk(turnId);
         return { ok: false, turn: turnId, failed, message, unknownSpend };
     };
     /** The turn stopped at its deadline: the notice is saved in the thread with whatever its completed tool calls proposed, in
      * the same write that ends the turn, so a refresh, another device or a restart shows the same outcome. */
-    const timedOut = (unknownSpend) => {
+    const timedOut = (unknownSpend, failureDetail = null) => {
         now = clock();
         const message = leadTimeoutNotice(proposals > 0, unknownSpend);
-        const saved = store.finalizeLeadTurn(turnId, started.generation, { state: "failed", settledMicrousd: settled, unknownSpend, tokensIn, tokensOut, failureReason: "timeout", keepProposals: true, message: { text: message, activity: activitySummary(reads, proposals, steps) } }, now);
+        const saved = store.finalizeLeadTurn(turnId, started.generation, { state: "failed", settledMicrousd: settled, unknownSpend, tokensIn, tokensOut, failureReason: "timeout", failureDetail, keepProposals: true, message: { text: message, activity: activitySummary(reads, proposals, steps) } }, now);
         store.dropLeadAsk(turnId);
         if (!saved)
             return { ok: false, turn: turnId, failed: "superseded", message: LEAD_FAILURE_COPY.stopped, unknownSpend: false };
@@ -387,6 +407,8 @@ export async function runLeadTurn(input) {
     let repaired = false;
     /** The turn's one shorten step for a reply over its channel's message limit (LEAD_REPLY_LIMITS); still over, it is split. */
     let shortened = false;
+    /** Why the next step runs, when it re-asks about the reply itself (repair or shorten): the live status says so. */
+    let nextReason;
     const replyLimit = input.channel === undefined ? null : LEAD_REPLY_LIMITS[input.channel];
     const unbacked = (text) => {
         const claim = deliverableClaim(text);
@@ -403,7 +425,10 @@ export async function runLeadTurn(input) {
         if (remainingMs <= 0)
             return timedOut(false);
         // This request's advertised tools: fixed for the request; a tool found in its reply is advertised from the next one.
-        const advertised = advertisedTools();
+        // A quick step (§8) advertises the reads, and find_tools as its way to ask for more, on the faster model.
+        const quick = route === "fast";
+        const stepModel = quick ? quickModel : config.model;
+        const advertised = quick ? LEAD_TOOL_SCHEMAS.filter(one => quickAdvertises(one.name)) : advertisedTools();
         const advertisedNames = new Set(advertised.map(one => one.name));
         const request = direct ? composeDirect(input.key, advertised) : composeSubscription(advertised);
         // Tool results join the outbound body: scanned again before every dispatch.
@@ -411,7 +436,7 @@ export async function runLeadTurn(input) {
         if (scanForSecrets(outbound).length > 0) {
             return fail("secret-refused", LEAD_FAILURE_COPY.secretRead, false);
         }
-        const step = store.openLeadStep({ leadTurn: turnId, generation: started.generation, approver: who.name, credentialKey, provider: config.provider, model: config.model, deadlineMs: remainingMs + 10_000 }, now);
+        const step = store.openLeadStep({ leadTurn: turnId, generation: started.generation, approver: who.name, credentialKey, provider: config.provider, model: stepModel, deadlineMs: remainingMs + 10_000 }, now);
         if (!step.ok) {
             if (step.reason === "latched")
                 return fail("latched", LEAD_FAILURE_COPY.paused, false);
@@ -421,7 +446,8 @@ export async function runLeadTurn(input) {
         if (!stepStarted.ok)
             return fail("provider-error", LEAD_FAILURE_COPY.notStarted, false);
         steps++;
-        progress({ kind: "step", turn: turnId, step: steps });
+        progress({ kind: "step", turn: turnId, step: steps, ...(nextReason === undefined ? {} : { reason: nextReason }) });
+        nextReason = undefined;
         const requestBytes = Buffer.byteLength(outbound, "utf8");
         let result;
         // The turn owns its deadline (lead-stall, release check 2438): at the deadline the request is aborted, which ends a
@@ -430,7 +456,9 @@ export async function runLeadTurn(input) {
         const controller = new AbortController();
         const abortAt = setTimeout(() => controller.abort(), remainingMs);
         const settle = (work) => settleBy(work, remainingMs + LEAD_ABORT_GRACE_MS)
-            .then(value => value === LATE || controller.signal.aborted ? { ok: false, problem: "timeout" } : value)
+            // A harness that ended at the deadline still says whether it had written anything (recorded, never shown).
+            .then(value => value === LATE ? { ok: false, problem: "timeout" } : controller.signal.aborted
+            ? { ok: false, problem: "timeout", ...(!value.ok && "quiet" in value && typeof value.quiet === "boolean" ? { quiet: value.quiet } : {}) } : value)
             .finally(() => clearTimeout(abortAt));
         if (direct) {
             result = await settle(performLeadRequest(request, directProvider, controller.signal, fetcher)
@@ -440,7 +468,7 @@ export async function runLeadTurn(input) {
             const runner = input.subscriptionRunner ?? performSubscriptionLeadRequest;
             result = await settle((async () => runner({
                 provider: subscriptionProvider,
-                model: config.model,
+                model: stepModel,
                 system: LEAD_CONTRACT,
                 dataDocument: document,
                 history,
@@ -449,15 +477,22 @@ export async function runLeadTurn(input) {
                 signal: controller.signal,
                 // The reply as it is written; text that looks like a secret is
                 // never shown (the finished reply is scanned again before saving).
-                ...(input.onProgress === undefined ? {} : { onText: (text) => { if (!controller.signal.aborted && scanForSecrets(text).length === 0)
-                        progress({ kind: "text", turn: turnId, step: steps, text }); } }),
+                ...(input.onProgress === undefined ? {} : { onText: (text) => { if (controller.signal.aborted)
+                        return; if (scanForSecrets(text).length === 0)
+                        progress({ kind: "text", turn: turnId, step: steps, text });
+                    else
+                        blockPreview(); } }),
             }))().catch(() => ({ ok: false, problem: "provider-error" })));
         }
         now = clock();
         const finishStep = (outcome) => store.finalizeChatTurn(step.id, stepStarted.generation, outcome, now);
         if (!result.ok) {
             if (!direct) {
-                finishStep({ state: "failed", failureReason: result.problem === "timeout" ? "timeout" : result.problem === "malformed-reply" ? "malformed-reply" : "provider-error", settledMicrousd: 0 });
+                // The exact cause, saved (v158): what a later reader shows, and what the next timeout diagnosis reads.
+                const quiet = "quiet" in result ? result.quiet : undefined;
+                const detail = result.problem === "timeout" ? (quiet === true ? "timeout-silent" : quiet === false ? "timeout-output" : null)
+                    : result.problem === "not-found" ? "not-installed" : result.problem === "malformed-reply" ? null : "sign-in";
+                finishStep({ state: "failed", failureReason: result.problem === "timeout" ? "timeout" : result.problem === "malformed-reply" ? "malformed-reply" : "provider-error", settledMicrousd: 0, failureDetail: detail });
                 const message = result.problem === "not-found"
                     ? LEAD_FAILURE_COPY.notInstalled
                     : result.problem === "timeout"
@@ -466,29 +501,32 @@ export async function runLeadTurn(input) {
                             ? LEAD_FAILURE_COPY.unreadable
                             : LEAD_FAILURE_COPY.signIn;
                 if (result.problem === "timeout")
-                    return timedOut(false);
-                return fail(result.problem === "malformed-reply" ? "malformed-reply" : "provider-error", message, false);
+                    return timedOut(false, detail);
+                return fail(result.problem === "malformed-reply" ? "malformed-reply" : "provider-error", message, false, detail);
             }
             if (result.problem.startsWith("status-")) {
                 // The provider ANSWERED with an error: nothing billed for this step.
-                finishStep({ state: "failed", failureReason: "provider-error", settledMicrousd: 0 });
-                return fail("provider-error", LEAD_FAILURE_COPY.refused, false);
+                finishStep({ state: "failed", failureReason: "provider-error", settledMicrousd: 0, failureDetail: "refused" });
+                return fail("provider-error", LEAD_FAILURE_COPY.refused, false, "refused");
             }
             if (result.problem === "timeout") {
                 finishStep({ state: "failed", failureReason: "timeout", settledMicrousd: null, unknownSpend: true });
                 return timedOut(true);
             }
             if (result.problem === "network") {
-                finishStep({ state: "failed", failureReason: "provider-error", settledMicrousd: null, unknownSpend: true });
-                return fail("provider-error", LEAD_FAILURE_COPY.lostUnknownCost, true);
+                finishStep({ state: "failed", failureReason: "provider-error", settledMicrousd: null, unknownSpend: true, failureDetail: "lost" });
+                return fail("provider-error", LEAD_FAILURE_COPY.lostUnknownCost, true, "lost");
             }
             finishStep({ state: "failed", failureReason: "malformed-reply", settledMicrousd: null, unknownSpend: true });
             return fail("malformed-reply", LEAD_FAILURE_COPY.unreadableUnknownCost, true);
         }
         const answer = result.answer;
         // The streamed reply's finished text, once, secret-checked whole: only now may its last word show live.
-        if (!direct && input.onProgress !== undefined && !controller.signal.aborted && answer.text !== "" && scanForSecrets(answer.text).length === 0) {
-            progress({ kind: "text", turn: turnId, step: steps, text: answer.text, final: true });
+        if (!direct && input.onProgress !== undefined && !controller.signal.aborted && answer.text !== "") {
+            if (scanForSecrets(answer.text).length === 0)
+                progress({ kind: "text", turn: turnId, step: steps, text: answer.text, final: true });
+            else
+                blockPreview();
         }
         // Usage that cannot be true — more input tokens than bytes sent — is a
         // malformed reply with unknown cost, never a number to settle by.
@@ -512,7 +550,9 @@ export async function runLeadTurn(input) {
             cacheReadTokens: answer.cacheReadTokens ?? null, cacheWriteTokens: answer.cacheWriteTokens ?? null,
             // v140: what the provider itself reported for this request (absent: unreported, kept NULL).
             modelReported: answer.modelReported ?? null, providerTurns: answer.providerTurns ?? null, reportedCostUsd: answer.reportedCostUsd ?? null,
-            billingReported: answer.billingReported ?? null });
+            billingReported: answer.billingReported ?? null,
+            // v158: the tools this step asked for, names only (responsive-chat.md §7.2), so the next latency call is data-driven.
+            tools: answer.calls.map(one => one.name) });
         tokensIn += answer.tokensIn;
         tokensOut += answer.tokensOut;
         if (answer.cacheReadTokens === undefined)
@@ -527,6 +567,14 @@ export async function runLeadTurn(input) {
         const changed = guard(await revalidated());
         if (changed !== null)
             return changed;
+        // A quick step that asked for more than a read (§8): its calls are discarded unrun, and the configured model takes the
+        // reply over from the same history, for this step and every later one. Steps and the turn's deadline still bind.
+        if (route === "fast" && quickStepEscalates(answer.calls)) {
+            route = "escalated";
+            setLeadTurnRoute(store, turnId, started.generation, route);
+            lastText = "";
+            continue;
+        }
         if (answer.calls.length === 0) {
             if (answer.text.trim() === "")
                 return fail("malformed-reply", LEAD_FAILURE_COPY.empty, false);
@@ -534,6 +582,7 @@ export async function runLeadTurn(input) {
             const claim = unbacked(answer.text);
             if (claim !== null && !repaired && steps < maxSteps) {
                 repaired = true;
+                nextReason = "repair";
                 history.push({ role: "assistant", text: answer.text, calls: [] });
                 history.push({ role: "operator", text: deliverableRepair(claim) });
                 continue;
@@ -541,6 +590,7 @@ export async function runLeadTurn(input) {
             const candidate = claim === null ? answer.text : dropDeliverableClaims(answer.text);
             if (replyLimit !== null && candidate.length > replyLimit && !shortened && steps < maxSteps) {
                 shortened = true;
+                nextReason = "shorten";
                 history.push({ role: "assistant", text: answer.text, calls: [] });
                 history.push({ role: "operator", text: shortenAsk([{ field: "Your reply", limit: replyLimit, length: candidate.length }]) });
                 continue;
@@ -598,10 +648,13 @@ export async function runLeadTurn(input) {
         reply = `${last === "" ? "" : `${last}\n\n`}(I stopped here: this answer needed more steps than ${maxSteps < LEAD_MAX_STEPS ? "this conversation's remaining spending allows" : "one reply allows"}. Ask me to carry on.)`;
     }
     // Ruling 11: model text is scanned before it becomes durable.
-    if (scanForSecrets(reply).length > 0)
+    if (scanForSecrets(reply).length > 0) {
+        blockPreview();
         return fail("secret-refused", LEAD_FAILURE_COPY.secretReply, false);
+    }
     now = clock();
-    const activity = activitySummary(reads, proposals, steps, cacheKnown && tokensIn > 0 ? Math.min(1, cacheRead / tokensIn) : null);
+    const routed = routeWords(route, quickModel, config.model);
+    const activity = `${activitySummary(reads, proposals, steps, cacheKnown && tokensIn > 0 ? Math.min(1, cacheRead / tokensIn) : null)}${routed === null ? "" : ` · ${routed}`}`;
     // One write (finding 12): settle, debit, promote the drafts, append the assistant text.
     const finalized = store.finalizeLeadTurn(turnId, started.generation, { state: "answered", settledMicrousd: settled, tokensIn, tokensOut, message: { text: reply, activity } }, now);
     if (!finalized)

package/dist/live-reply.d.ts

@@ -0,0 +1,83 @@
+import type { LeadLiveTool, LeadProgress } from "./lead-progress.js";
+import { type ShapeOptions } from "./reply-shape.js";
+export type LiveView = {
+    phase: "queued";
+} | {
+    phase: "working";
+    status: string;
+} | {
+    phase: "writing";
+    status: string;
+    text: string;
+} | {
+    phase: "closed";
+    why: "answered" | "failed" | "blocked";
+};
+/** The status line's fixed words (§2.3). A running tool reads as its own label plus "…". */
+export declare const LIVE_STATUS: {
+    readonly queued: "Waiting for your earlier messages…";
+    readonly thinking: "Thinking…";
+    readonly writing: "Writing…";
+    readonly repair: "Fixing the reply…";
+    readonly shorten: "Shortening the reply…";
+    /** A preview closed because text looked like a password or key; the turn itself may still answer. */
+    readonly held: "Working on it…";
+};
+/** Could the end of this text be the start of a password or key? Then nothing of it shows yet. */
+export declare function secretMayStart(text: string): boolean;
+/**
+ * What of a reply still being written is settled: everything before its last whitespace (the unfinished last word
+ * stays out), then cut back before any code fence, code span, bold run or link that hasn't closed yet. Trailing
+ * whitespace is trimmed.
+ */
+export declare function settledText(raw: string): string;
+/**
+ * A partial as it may be shown: `blocked` when it holds a password or key (the preview closes), `withheld` while its
+ * tail could still become one (show nothing new), else the settled text shaped for display. A step's finished text
+ * (`final`, secret-checked whole by the engine) shows whole.
+ */
+export declare function partialDisplay(raw: string, final: boolean, shape?: ShapeOptions): {
+    kind: "blocked";
+} | {
+    kind: "withheld";
+} | {
+    kind: "shown";
+    text: string;
+};
+export type LiveReply = {
+    /** Feed one engine event; true when the view changed. Events after close are ignored. */
+    push(event: LeadProgress): boolean;
+    /** The turn ended (its outcome is the engine's, never inferred from text). Idempotent; a blocked close stays blocked. */
+    close(why: "answered" | "failed"): void;
+    view(): LiveView;
+    /** The status line now, also once a blocked preview closed while the turn runs on. */
+    status(): string;
+    /** Each step's tool calls, for a surface that lists them behind a disclosure. Fixed copy only, never model text. */
+    tools(): LeadLiveTool[][];
+    readonly turn: number | null;
+};
+/** One turn's live reply. `shape`: the owner's message (`asked`) and this app's origins, as the final reply is shaped. */
+export declare function createLiveReply(shape?: ShapeOptions, options?: {
+    queued?: boolean;
+}): LiveReply;
+export type LiveSender<V> = {
+    /** Offer the newest view: it replaces any view still waiting. Ignored once closed. */
+    offer(view: V): void;
+    /** Drop the waiting view, wait for the request in flight to settle, then refuse every later view. */
+    close(): Promise<void>;
+    /** Grows with every offered view; a transport may use it to refuse an older one. */
+    readonly generation: number;
+    readonly closed: boolean;
+};
+/**
+ * The serialized sender for one live surface message (§2.4). `standing` re-proves the viewer's right to see this turn
+ * before every send (it may await; the close is re-checked after it). `spacingMs` is the least time between two sends,
+ * read before each one (a surface widens it after the platform asks for a pause). A failed send drops that view:
+ * previews are best effort.
+ */
+export declare function createLiveSender<V>(options: {
+    send: (view: V, generation: number) => unknown;
+    standing?: () => boolean | Promise<boolean>;
+    spacingMs?: number | (() => number);
+    now?: () => number;
+}): LiveSender<V>;

package/dist/live-reply.js

@@ -0,0 +1,302 @@
+/**
+ * The shared live-reply core (docs/plans/responsive-chat.md §2): one lead turn's `LeadProgress` turned into text-only
+ * views that every surface renders. Surfaces never read `LeadProgress` themselves.
+ *
+ *   queued → working (one status line) → writing (status + display-safe partial text) → closed (answered | failed | blocked)
+ *
+ * Nothing here is durable or authoritative: the saved thread message and its cards remain the record, and no view ever
+ * carries a card, a button, an ask or an approval. A partial is the reply as written so far, cut back to what is
+ * settled (never an unfinished word, code span, link or bold run), withheld while its tail could be the start of a
+ * password or key, and shaped with the final reply's own presentation policy (presentation, not redaction).
+ *
+ * `createLiveSender` is the one sender per live surface message (§2.4): at most one request in flight, one pending
+ * slot holding only the newest view, a generation that only grows, and `close()` — after which nothing more is sent,
+ * and which resolves only once the request in flight has settled, so durable delivery can start strictly after it.
+ */
+import { scanForSecrets } from "./evidence.js";
+import { shapeReply, shapeReplyPrefix } from "./reply-shape.js";
+/** The status line's fixed words (§2.3). A running tool reads as its own label plus "…". */
+export const LIVE_STATUS = {
+    queued: "Waiting for your earlier messages…",
+    thinking: "Thinking…",
+    writing: "Writing…",
+    repair: "Fixing the reply…",
+    shorten: "Shortening the reply…",
+    /** A preview closed because text looked like a password or key; the turn itself may still answer. */
+    held: "Working on it…",
+};
+/** One token that could still grow into a match of a secret family: a non-empty prefix of one of its openings, or the
+ * whole opening followed by its body characters. Preceded by a non-word character or the start, as the detectors'
+ * own word boundaries are. */
+function opening(leads, body) {
+    const escape = (text) => text.replace(/[.*+?^${}()|[\]\\/-]/g, "\\$&");
+    const alternatives = new Set();
+    for (const lead of leads) {
+        for (let length = 1; length < lead.length; length += 1)
+            alternatives.add(escape(lead.slice(0, length)));
+        alternatives.add(`${escape(lead)}${body}*`);
+    }
+    return `(?:${[...alternatives].join("|")})`;
+}
+/**
+ * The start of every `SECRET_PATTERNS` family (evidence.ts), checked against the end of the text written so far:
+ * while any matches, the partial is withheld. Single-token families look at the unfinished last token; the families
+ * whose match spans spaces (a private-key header, an npm `_authToken = value`) look at the whole last line.
+ */
+const SECRET_STARTS = [
+    // private-key: "-----BEGIN RSA PRIVATE KEY-----", partway. No start boundary: the complete detector has none either.
+    /-{1,5}(?:B(?:E(?:G(?:I(?:N(?:[ \t][A-Z \t]*-{0,5})?)?)?)?)?)?$/,
+    // npm-auth-token: "_authToken = value", partway.
+    new RegExp(String.raw `(?:^|[^A-Za-z0-9])${opening(["_authToken"], String.raw `[\s=]`)}\S*$`),
+    // aws-access-key, github-token, slack-token, openai-key, stripe-key, google-api-key, gitlab-token.
+    new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["AKIA", "ASIA"], "[0-9A-Z]")}$`),
+    new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["ghp_", "gho_", "ghu_", "ghs_", "ghr_", "github_pat_"], "[A-Za-z0-9_]")}$`),
+    new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["xoxb-", "xoxa-", "xoxp-", "xoxr-", "xoxs-"], "[A-Za-z0-9-]")}$`),
+    new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["sk-"], "[A-Za-z0-9_-]")}$`),
+    new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["sk_live_", "sk_test_", "rk_live_", "rk_test_", "whsec_"], "[A-Za-z0-9]")}$`),
+    new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["AIza"], "[0-9A-Za-z_-]")}$`),
+    new RegExp(String.raw `(?:^|[^A-Za-z0-9_])${opening(["glpat-"], "[A-Za-z0-9_-]")}$`),
+    // telegram-bot-token: "123456789:AA…".
+    /(?:^|[^A-Za-z0-9_])\d+(?::(?:A(?:A[A-Za-z0-9_-]*)?)?)?$/,
+    // discord-bot-token: "M…24.…6.…27".
+    /(?:^|[^A-Za-z0-9_])[MN][A-Za-z\d]*(?:\.[\w-]*(?:\.[\w-]*)?)?$/,
+    // password-in-url: "scheme://user:password@host", partway (a scheme and its colon are enough to wait).
+    /(?:^|[^A-Za-z0-9+.-])[a-z][a-z0-9+.-]*:\S*$/i,
+];
+/** Could the end of this text be the start of a password or key? Then nothing of it shows yet. */
+export function secretMayStart(text) {
+    const lastLine = text.replace(/\r\n?/g, "\n").split("\n").at(-1) ?? "";
+    return SECRET_STARTS.some(pattern => pattern.test(lastLine));
+}
+/**
+ * What of a reply still being written is settled: everything before its last whitespace (the unfinished last word
+ * stays out), then cut back before any code fence, code span, bold run or link that hasn't closed yet. Trailing
+ * whitespace is trimmed.
+ */
+export function settledText(raw) {
+    const text = raw.replace(/\r\n?/g, "\n");
+    let end = text.length;
+    while (end > 0 && !/\s/.test(text[end - 1]))
+        end -= 1;
+    const shown = text.slice(0, end);
+    let fence = -1, code = -1, bold = -1, link = -1;
+    let linkState = null;
+    for (let index = 0; index < shown.length; index += 1) {
+        if (shown.startsWith("```", index)) {
+            fence = fence === -1 ? index : -1;
+            index += 2;
+            continue;
+        }
+        if (fence !== -1)
+            continue;
+        const char = shown[index];
+        if (char === "\n") {
+            code = -1;
+            bold = -1;
+            link = -1;
+            linkState = null;
+            continue;
+        }
+        if (char === "`") {
+            code = code === -1 ? index : -1;
+            continue;
+        }
+        if (code !== -1)
+            continue;
+        if (shown.startsWith("**", index)) {
+            bold = bold === -1 ? index : -1;
+            index += 1;
+            continue;
+        }
+        if (char === "[" && linkState === null) {
+            link = index;
+            linkState = "label";
+            continue;
+        }
+        if (linkState === "label" && char === "]") {
+            if (shown[index + 1] === "(") {
+                linkState = "url";
+                index += 1;
+            }
+            else {
+                link = -1;
+                linkState = null;
+            }
+            continue;
+        }
+        if (linkState === "url" && (char === ")" || /\s/.test(char))) {
+            link = -1;
+            linkState = null;
+        }
+    }
+    const cut = Math.min(...[fence, code, bold, link].filter(at => at !== -1), shown.length);
+    return shown.slice(0, cut).trimEnd();
+}
+/**
+ * A partial as it may be shown: `blocked` when it holds a password or key (the preview closes), `withheld` while its
+ * tail could still become one (show nothing new), else the settled text shaped for display. A step's finished text
+ * (`final`, secret-checked whole by the engine) shows whole.
+ */
+export function partialDisplay(raw, final, shape = {}) {
+    if (scanForSecrets(raw).length > 0)
+        return { kind: "blocked" };
+    if (!final && secretMayStart(raw))
+        return { kind: "withheld" };
+    const text = final ? shapeReply(raw, shape) : shapeReplyPrefix(settledText(raw), shape);
+    // Shaping only relabels and removes; a secret in what it returns would mean it came from somewhere else. Never shown.
+    if (scanForSecrets(text).length > 0)
+        return { kind: "blocked" };
+    return { kind: "shown", text };
+}
+/** One turn's live reply. `shape`: the owner's message (`asked`) and this app's origins, as the final reply is shaped. */
+export function createLiveReply(shape = {}, options = {}) {
+    const steps = [];
+    let queued = options.queued === true;
+    let closed = null;
+    let turn = null;
+    let last = "";
+    const current = () => steps.at(-1) ?? (steps.push({ calls: [], raw: "", shown: "" }), steps.at(-1));
+    const status = () => {
+        const step = steps.at(-1);
+        const running = step?.calls.filter(call => call.state === "running").at(-1);
+        if (running !== undefined)
+            return `${running.label}…`;
+        if (step?.reason !== undefined)
+            return LIVE_STATUS[step.reason];
+        if (closed === "blocked")
+            return LIVE_STATUS.held;
+        if (step !== undefined && step.raw.trim() !== "")
+            return LIVE_STATUS.writing;
+        return LIVE_STATUS.thinking;
+    };
+    const view = () => {
+        if (closed !== null)
+            return { phase: "closed", why: closed };
+        if (queued && steps.length === 0)
+            return { phase: "queued" };
+        const text = [...steps].reverse().find(step => step.shown !== "")?.shown ?? "";
+        return text === "" ? { phase: "working", status: status() } : { phase: "writing", status: status(), text };
+    };
+    const changed = () => {
+        const now = JSON.stringify(view());
+        if (now === last)
+            return false;
+        last = now;
+        return true;
+    };
+    last = JSON.stringify(view());
+    return {
+        get turn() { return turn; },
+        push(event) {
+            if (closed !== null)
+                return false;
+            turn ??= event.turn;
+            queued = false;
+            switch (event.kind) {
+                case "started": break;
+                case "step":
+                    steps.push({ calls: [], raw: "", shown: "", ...(event.reason === undefined ? {} : { reason: event.reason }) });
+                    break;
+                case "tool":
+                    current().calls.push({ id: event.id, label: event.label, state: "running" });
+                    break;
+                case "tool-result":
+                    for (const step of steps) {
+                        const index = step.calls.findIndex(call => call.id === event.id);
+                        if (index !== -1) {
+                            step.calls[index] = { id: event.id, label: step.calls[index].label, ...event.outcome };
+                            break;
+                        }
+                    }
+                    break;
+                case "text": {
+                    const step = current();
+                    step.raw = event.text;
+                    const shown = partialDisplay(event.text, event.final === true, shape);
+                    if (shown.kind === "blocked") {
+                        closed = "blocked";
+                        for (const one of steps)
+                            one.shown = "";
+                    }
+                    else if (shown.kind === "shown")
+                        step.shown = shown.text;
+                    break;
+                }
+                case "blocked":
+                    closed = "blocked";
+                    for (const one of steps)
+                        one.shown = "";
+                    break;
+            }
+            return changed();
+        },
+        close(why) {
+            if (closed === null)
+                closed = why;
+            for (const one of steps)
+                one.shown = "";
+            changed();
+        },
+        view,
+        status,
+        tools: () => steps.map(step => step.calls.map(call => ({ ...call }))),
+    };
+}
+/**
+ * The serialized sender for one live surface message (§2.4). `standing` re-proves the viewer's right to see this turn
+ * before every send (it may await; the close is re-checked after it). `spacingMs` is the least time between two sends,
+ * read before each one (a surface widens it after the platform asks for a pause). A failed send drops that view:
+ * previews are best effort.
+ */
+export function createLiveSender(options) {
+    const spacing = () => typeof options.spacingMs === "function" ? options.spacingMs() : options.spacingMs ?? 0;
+    const now = options.now ?? Date.now;
+    let generation = 0;
+    let closed = false;
+    let pending = null;
+    let inflight = null;
+    let timer = null;
+    let lastSent = Number.NEGATIVE_INFINITY;
+    const pump = () => {
+        if (closed || inflight !== null || timer !== null || pending === null)
+            return;
+        const wait = lastSent + spacing() - now();
+        if (wait > 0) {
+            timer = setTimeout(() => { timer = null; pump(); }, wait);
+            timer.unref?.();
+            return;
+        }
+        const next = pending;
+        pending = null;
+        inflight = (async () => {
+            try {
+                if (options.standing !== undefined && !(await options.standing()))
+                    return;
+                if (closed)
+                    return;
+                lastSent = now();
+                await options.send(next.view, next.generation);
+            }
+            catch { /* best effort: this view is dropped */ }
+        })().finally(() => { inflight = null; pump(); });
+    };
+    return {
+        get generation() { return generation; },
+        get closed() { return closed; },
+        offer(view) {
+            if (closed)
+                return;
+            generation += 1;
+            pending = { view, generation };
+            pump();
+        },
+        async close() {
+            closed = true;
+            pending = null;
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = null;
+            await inflight;
+        },
+    };
+}