toolroll 0.9.95 → 0.9.97

package/dist/lead.d.ts

@@ -1,5 +1,6 @@
 import { type LeadProgress } from "./lead-progress.js";
 import type { ChatConfig, LeadSession, LeadThread, Store } from "./store.js";
+import type { LeadFailureDetail } from "./lead-latency-schema.js";
 import type { Integration } from "./integrations.js";
 import type { VerifiedApprover } from "./principal.js";
 import { type LeadHistoryMessage } from "./converse.js";
@@ -128,8 +129,9 @@ export declare const LEAD_FAILURE_COPY: {
     readonly empty: "The lead sent back an empty answer. Nothing was kept. Send your message again.";
     readonly 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 declare function leadFailureText(reason: string | null, unknownSpend?: boolean): string;
+/** 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 declare function leadFailureText(reason: string | null, unknownSpend?: boolean, detail?: LeadFailureDetail | null): string;
 /** How long a provider that ignored its abort at the turn's deadline is waited for before the turn ends without it.
  * Its process group was already killed at the deadline; this only bounds the wait for the transport to say so. */
 export declare const LEAD_ABORT_GRACE_MS = 5000;

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>;