@basein/runner 0.3.17 → 0.3.19

package/dist/record/remote-recorder.js

@@ -54,8 +54,8 @@ import { credentialsPath, describeBody, isAuthResponse, issuedFor, loadCredentia
 import { errText, logDetail, logEvery, logLine } from "../util/log.js";
 import { serviceHeaders } from "../util/service-headers.js";
 import { isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal, } from "../util/service-health.js";
-import { redactJsonText, redactText } from "./redact.js";
-import { capJsonText, capText, DEFAULT_MAX_PAYLOAD_BYTES, preCut, REPORT_PAYLOAD_MAX_BYTES, } from "./truncate.js";
+import { redact, redactJsonText, redactText } from "./redact.js";
+import { capJsonText, capText, DEFAULT_MAX_PAYLOAD_BYTES, preCut, REPORT_PAYLOAD_MAX_BYTES, truncateString, } from "./truncate.js";
 /**
  * Caps for the free text this recorder sends, in UTF-8 bytes. Tool payloads
  * arrive capped at 64 KiB by their producers; text never passed through one,
@@ -149,6 +149,8 @@ const AUTH_RECHECK_MS = 1_500;
 const AUTH_REJECTED_RETRY_MS = 10 * 60_000;
 /** Execution reports ride their own lane: a matched turn has no run on the service. */
 const EXECUTIONS = "__executions__";
+/** Tool lists too (the service's autocorrect.md AC12): they belong to no run. */
+const TOOL_LISTS = "__tool_lists__";
 /** A send that did not succeed, with the status the service answered, if it answered. */
 export class ServiceError extends Error {
     status;
@@ -207,10 +209,14 @@ function pendStep(step) {
  * input, then the outputs, each in the order the steps ran. A payload that
  * does not fit is left out; its step keeps its verdict, and the costs the
  * report exists for are never what gives way.
+ *
+ * `extra` rides outside that budget: an answered turn's whole calls
+ * ({@link answerCallsBody}), which hold themselves to a budget of their own.
+ * Counted inside it, they would leave no room for a single step's payload.
  */
-function reportBody(fields, steps) {
+function reportBody(fields, steps, extra = {}) {
     if (!steps)
-        return JSON.stringify(fields);
+        return JSON.stringify({ ...fields, ...extra });
     const sent = steps.map(({ step }) => ({
         ...step,
         error: typeof step.error === "string"
@@ -243,7 +249,125 @@ function reportBody(fields, steps) {
         add(i, "toolInput");
     for (const i of all)
         add(i, "toolOutput");
-    return JSON.stringify({ ...fields, steps: sent });
+    return JSON.stringify({ ...fields, steps: sent, ...extra });
+}
+/** What one answered turn's call may carry of its output, in UTF-8 bytes (review item 12). */
+export const ANSWER_CALL_OUTPUT_MAX_BYTES = 64 * 1024;
+/** All of one report's answer calls together, serialized, in UTF-8 bytes. */
+export const ANSWER_CALLS_MAX_BYTES = 600_000;
+/** Below this, an output is not cut further to make room: the calls are left out instead. */
+const ANSWER_CALL_OUTPUT_MIN_BYTES = 1_024;
+/** At most this many calls go: a plan keeps no more verdicts than this either. */
+const ANSWER_CALLS_MAX = 200;
+const utf8Bytes = (text) => Buffer.byteLength(text, "utf8");
+/** One output as it goes: redacted — by its keys when it is JSON — and cut at `max` bytes with the marker. */
+function answerOutput(text, max) {
+    let clean;
+    try {
+        JSON.parse(text);
+        clean = redactJsonText(text);
+    }
+    catch {
+        clean = redactText(text);
+    }
+    return truncateString(clean, max);
+}
+/**
+ * An answered turn's calls as they are sent (the service's review of
+ * calcscenarioautocorrect.md, item 12): each input redacted again, each output
+ * redacted and cut at {@link ANSWER_CALL_OUTPUT_MAX_BYTES}, and all of them
+ * held to `maxBytes` serialized by cutting the largest outputs first — every
+ * output above one common length is cut to it, the longest length that fits.
+ * The cut is the recordings' own, "… [truncated N of M bytes]", so a reader
+ * can tell a short answer from a cut one. Undefined when there is nothing to
+ * send, or when even outputs of {@link ANSWER_CALL_OUTPUT_MIN_BYTES} would not
+ * fit (inputs that large): the service then reads the report's cut copies,
+ * as it did before, rather than half a list.
+ */
+export function answerCallsBody(calls, maxBytes = ANSWER_CALLS_MAX_BYTES) {
+    if (!calls || calls.length === 0)
+        return undefined;
+    const base = calls.slice(0, ANSWER_CALLS_MAX).map((c) => {
+        const input = redact(c.input);
+        return {
+            stepIndex: c.stepIndex,
+            // The service takes 200 characters of a name, and refuses the whole list past it.
+            toolName: String(c.toolName ?? "").slice(0, 200),
+            input: (input && typeof input === "object" && !Array.isArray(input) ? input : {}),
+            output: answerOutput(typeof c.output === "string" ? c.output : "", ANSWER_CALL_OUTPUT_MAX_BYTES),
+            ...(c.isError === true ? { isError: true } : {}),
+        };
+    });
+    const sized = (cap) => {
+        const cut = base.map((c) => (utf8Bytes(c.output) > cap ? { ...c, output: truncateString(c.output, cap) } : c));
+        return { calls: cut, bytes: utf8Bytes(JSON.stringify(cut)) };
+    };
+    const whole = sized(ANSWER_CALL_OUTPUT_MAX_BYTES);
+    if (whole.bytes <= maxBytes)
+        return whole.calls;
+    if (sized(ANSWER_CALL_OUTPUT_MIN_BYTES).bytes > maxBytes)
+        return undefined;
+    // The longest common length that fits, found by halving to within a
+    // kilobyte: each try is one serialization — six or so in all — and the
+    // measure is the real one, escapes and markers in.
+    let lo = ANSWER_CALL_OUTPUT_MIN_BYTES;
+    let hi = ANSWER_CALL_OUTPUT_MAX_BYTES;
+    while (hi - lo > 1_024) {
+        const mid = Math.floor((lo + hi) / 2);
+        if (sized(mid).bytes <= maxBytes)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return sized(lo).calls;
+}
+/** The day a finish says, checked: a line of at most 400 characters, a `YYYY-MM-DD`; undefined when neither. */
+function agentDayBody(day) {
+    if (!day)
+        return undefined;
+    const said = typeof day.said === "string" ? redactText(day.said).replace(/\s+/g, " ").trim().slice(0, 400) : "";
+    const local = typeof day.local === "string" && /^\d{4}-\d{2}-\d{2}$/.test(day.local) ? day.local : "";
+    if (!said && !local)
+        return undefined;
+    return { ...(said ? { said } : {}), ...(local ? { local } : {}) };
+}
+const ATTENTION_REASONS = new Set([
+    "checking",
+    "rejected",
+    "rejected_again",
+    "verifying",
+    "verify_failed",
+    "verify_stale",
+]);
+/** The plans of a `GET /scenarios/attention` answer, read off the wire: at most five, each checked. */
+function attentionPlans(body) {
+    const raw = body?.plans;
+    if (!Array.isArray(raw))
+        return [];
+    const plans = [];
+    for (const item of raw) {
+        if (plans.length >= 5)
+            break;
+        if (!item || typeof item !== "object")
+            continue;
+        const p = item;
+        if (typeof p.scenarioId !== "string" || !p.scenarioId || typeof p.url !== "string")
+            continue;
+        // Not held — only a correction waits — the service says neither since
+        // when nor why.
+        const heldSince = typeof p.heldSince === "string" && p.heldSince ? p.heldSince.slice(0, 40) : null;
+        plans.push({
+            scenarioId: p.scenarioId.slice(0, 100),
+            title: typeof p.title === "string" ? p.title.slice(0, 500) : "",
+            heldSince,
+            reason: heldSince
+                ? (typeof p.reason === "string" && ATTENTION_REASONS.has(p.reason) ? p.reason : "checking")
+                : null,
+            correction: p.correction === "proposed" ? "proposed" : null,
+            url: p.url.slice(0, 1_000),
+        });
+    }
+    return plans;
 }
 /** A tool error is JSON when a producer serialized it, and prose when it did not. */
 function pendError(text) {
@@ -676,9 +800,10 @@ export class RemoteRecorder {
             toolName: data.toolName,
             toolOutput: out(toolOutput),
             toolError: out(toolError),
-            // Omitted, not nulled, when absent: an ordinary answer is the body it
-            // has always been. Only a plan's own call recorded into a redo carries
-            // one (`byPlan`, the service's autocorrect.md AC2).
+            // Omitted, not nulled, when absent. A call's id rides on both of its
+            // rows, and `isError` on the answer of one that failed (review item
+            // 7); a plan's own call recorded into a redo carries `byPlan` too
+            // (the service's autocorrect.md AC2).
             metadata: data.metadata,
         }));
         return id;
@@ -707,15 +832,20 @@ export class RemoteRecorder {
         // user's data, so it is cleaned and cut like every other text sent.
         const error = pend(metrics?.error, TEXT_CAPS.reportError);
         const asked = metrics?.incomplete;
+        // The day its agent was told it is (review item 1). Cleaned here, like
+        // every text sent: the line comes out of a system prompt.
+        const agentDay = agentDayBody(metrics?.agentDay);
         this.enqueueRun(runId, "finish", sizeOf(output, error), () => 
-        // `error` and `incomplete` are omitted, not nulled, when absent, so the
-        // finish of an ordinary run is the body it has always been.
+        // `error`, `incomplete` and `agentDay` are omitted, not nulled, when
+        // absent, so the finish of an ordinary run is the body it has always
+        // been. An older service drops `agentDay`.
         this.post(`/recordings/runs/${runId}/finish`, {
             finalOutput: out(output),
             error: out(error),
             originalCostUsd: metrics?.costUsd,
             originalMs: metrics?.durationMs,
             incomplete: asked ? this.incompleteOf(runId, asked.lossy) : undefined,
+            agentDay,
         }));
     }
     /**
@@ -727,6 +857,128 @@ export class RemoteRecorder {
         const lostSteps = this.runs.get(runId)?.lostSteps ?? 0;
         return lossy || lostSteps > 0 ? { lostSteps, lossy } : undefined;
     }
+    /**
+     * One wrapped server's tool list (the service's autocorrect.md AC12): the
+     * names, descriptions and input schemas a correction from an agent's answer
+     * writes a step with. On its own lane, and never counted as a recording's
+     * lost send. Quiet towards the service's health: a list the service refuses
+     * (an older one's 404, the route's own rate limit, a fault of that route)
+     * opens no breaker the hooks wait on. Resolves true when the service took it.
+     *
+     * `project` is the list's project (review item 16): two projects with a
+     * server of one name keep a list each. An older service drops the field.
+     */
+    reportTools(serverName, tools, project) {
+        return new Promise((resolve) => {
+            const body = JSON.stringify(project ? { serverName, project, tools } : { serverName, tools });
+            this.enqueue({
+                lane: TOOL_LISTS,
+                kind: "tools",
+                bytes: body.length + 256,
+                send: async () => {
+                    try {
+                        await this.request("POST", "/recordings/tools", body, { quiet: true });
+                        logDetail("recorder.tools_sent", { server: serverName, tools: tools.length });
+                        resolve(true);
+                    }
+                    catch (err) {
+                        if (err instanceof AccountChanged)
+                            throw err;
+                        logEvery(`recorder.tools_failed:${serverName}`, 10 * 60_000, "recorder.tools_failed", {
+                            server: serverName,
+                            why: err instanceof ServiceError && err.status === 404
+                                ? "the service does not take tool lists yet"
+                                : "the tool list was not sent; it is sent again later",
+                            error: errText(err),
+                        });
+                        resolve(false);
+                    }
+                },
+                abandon: () => resolve(false),
+            });
+        });
+    }
+    /** The account this recorder sends for, as signed in now. */
+    accountId() {
+        return this.session.user.id;
+    }
+    /**
+     * The plans of this account that wait for their owner (`GET
+     * /scenarios/attention`; the service's review of calcscenarioautocorrect.md,
+     * item 8): what the line a session start shows is made of. Asked on a
+     * session start's path, so it is bounded (1.5 s by default), asked only
+     * while the service is known to answer, and quiet towards its health: a
+     * slow or refusing answer here opens no breaker the hooks wait on. Null on
+     * any failure — an older service's 404 included — and never a throw.
+     */
+    async scenarioAttention(opts = {}) {
+        try {
+            if (!this.mayHotWait())
+                return null;
+            const body = await this.request("GET", "/scenarios/attention", undefined, {
+                timeoutMs: opts.timeoutMs ?? 1_500,
+                quiet: true,
+            });
+            return attentionPlans(body);
+        }
+        catch (err) {
+            logEvery("recorder.attention_failed", 10 * 60_000, "recorder.attention_failed", {
+                why: err instanceof ServiceError && err.status === 404
+                    ? "the service does not list plans that need their owner yet"
+                    : "the plans that need their owner were not read; a session start says nothing of them",
+                error: errText(err),
+            });
+            return null;
+        }
+    }
+    /**
+     * The agent said a replay's results do not answer its request (`POST
+     * /scenarios/:scenarioId/dispute`; the service's review of
+     * calcscenarioautocorrect.md, item 19). `executionId` is the turn's
+     * execution ticket — the id its report books under at the end of the turn,
+     * so while the turn runs the service has the ticket and not yet the row.
+     * Awaited — the agent waits for one sentence back — bounded (10 s by
+     * default), and quiet towards the service's health. Never throws.
+     */
+    async disputeScenario(scenarioId, report, opts = {}) {
+        if (!/^scn_[\w-]+$/.test(scenarioId))
+            return { ok: false, why: "no_plan" };
+        this.checkCredentials();
+        if (this.state !== "recording")
+            return { ok: false, why: "signed_out" };
+        // The agent's own words: they may quote what a tool returned.
+        const reason = redactText(String(report.reason ?? "")).trim().slice(0, 2_000);
+        try {
+            const body = await this.request("POST", `/scenarios/${scenarioId}/dispute`, JSON.stringify({
+                reason,
+                by: "agent",
+                ...(report.executionId ? { executionId: report.executionId } : {}),
+            }), { timeoutMs: opts.timeoutMs ?? 10_000, quiet: true });
+            const b = (body && typeof body === "object" ? body : {});
+            const answer = {
+                ok: b.ok === true,
+                held: b.held === true,
+                ...(typeof b.why === "string" && b.why ? { why: b.why.slice(0, 200) } : {}),
+            };
+            logLine("recorder.disputed", {
+                scenario: scenarioId,
+                execution: report.executionId,
+                ok: answer.ok,
+                held: answer.held,
+                why: answer.why,
+            });
+            return answer;
+        }
+        catch (err) {
+            const status = err instanceof ServiceError ? err.status : undefined;
+            logLine("recorder.dispute_failed", {
+                scenario: scenarioId,
+                why: status === 404 ? "the service does not take reports that a replay was wrong yet" : "the report was not sent",
+                error: errText(err),
+            });
+            return { ok: false, why: status === 404 ? "unsupported" : "service_error" };
+        }
+    }
     /**
      * Report what a matched turn cost (docs/calculatedReplay.md §11.2).
      *
@@ -746,11 +998,28 @@ export class RemoteRecorder {
         const error = pend(report.error, TEXT_CAPS.reportError);
         const answer = pend(report.answer, TEXT_CAPS.reportAnswer);
         const steps = report.steps?.map(pendStep);
+        // The plan's whole calls go only beside an answer (review item 12): the
+        // service keeps them only while it keeps the answer.
+        const calls = answer && report.answerCalls?.length ? report.answerCalls : undefined;
+        const callBytes = calls
+            ? calls.reduce((n, c) => n + c.output.length + 256, 0) + JSON.stringify(calls.map((c) => c.input)).length
+            : 0;
         this.enqueue({
             lane: EXECUTIONS,
             kind: "report",
-            bytes: sizeOf(prompt, error, answer, ...(steps ?? []).flatMap((s) => [s.toolInput, s.toolOutput])) + 1024,
+            bytes: sizeOf(prompt, error, answer, ...(steps ?? []).flatMap((s) => [s.toolInput, s.toolOutput])) +
+                Math.min(callBytes, ANSWER_CALLS_MAX_BYTES + 64 * 1024) +
+                1024,
             send: async () => {
+                // Shaped here, off the hook's path: the cuts serialize the calls a few times.
+                const answerCalls = calls ? answerCallsBody(calls) : undefined;
+                if (calls && !answerCalls) {
+                    logLine("execution.answer_calls_left_out", {
+                        scenario: report.scenarioId,
+                        calls: calls.length,
+                        why: "the plan's calls did not fit the report even cut short — the service reads the report's own copies",
+                    });
+                }
                 // A redo whose run the service refused to create is no run of its:
                 // never named (the service's autocorrect.md AC1), even when the
                 // refusal came after the report was built.
@@ -795,7 +1064,10 @@ export class RemoteRecorder {
                     // ...or only answered: its answer, capped and redacted like any
                     // text (AC11). Additive, like `redoneBy`.
                     answer: out(answer),
-                }, steps), { retryTransient: Boolean(report.ticket) });
+                }, steps, 
+                // Beside the answer, the plan's calls whole (review item 12),
+                // outside the steps' budget. Additive: an older service drops them.
+                answerCalls ? { answerCalls } : {}), { retryTransient: Boolean(report.ticket) });
                 const r = (body ?? {});
                 const failed = report.steps?.filter((s) => s.status === "failed").length ?? 0;
                 logLine("execution.reported", {
@@ -817,6 +1089,7 @@ export class RemoteRecorder {
                     // `bir investigate` prints it beside the outcome: "redone by run_…".
                     redoneBy: report.redoneBy?.runId,
                     ownCalls: report.redoneBy?.ownCalls,
+                    answerCalls: answerCalls?.length,
                 });
             },
         });
@@ -1130,8 +1403,9 @@ export class RemoteRecorder {
         catch {
             /* never */
         }
-        // A matched turn records nothing by design: nothing was lost.
-        if (why !== "not_created") {
+        // A matched turn records nothing by design: nothing was lost. Nor is a
+        // tool list a recording's send (AC12): it is sent again later.
+        if (why !== "not_created" && job.kind !== "tools") {
             this.droppedSends += 1;
             if (run) {
                 run.dropped += 1;
@@ -1453,6 +1727,9 @@ export class RemoteRecorder {
     async request(method, path, body, opts = {}) {
         let retried401 = false;
         let retriedTransient = false;
+        const health = opts.quiet
+            ? { fail: (_reason) => undefined, ok: (_started) => undefined }
+            : { fail: (reason) => this.health.fail(reason), ok: (started) => this.health.ok(started) };
         const user = this.session.user.id;
         for (let attempt = 0;; attempt++) {
             if (attempt > 0 && !opts.anonymous && this.session.user.id !== user) {
@@ -1487,13 +1764,13 @@ export class RemoteRecorder {
                     await sleep(jitterMs());
                     continue;
                 }
-                this.health.fail(reason);
+                health.fail(reason);
                 throw new ServiceError(`${method} ${path}: ${reason}`);
             }
             if (res.status === 401 && !opts.anonymous) {
                 // Release the socket now rather than at GC, then renew — once.
                 await res.body?.cancel().catch(() => undefined);
-                this.health.ok(started);
+                health.ok(started);
                 if (retried401)
                     throw new ServiceError(`HTTP 401 ${method} ${path}`, 401);
                 retried401 = true;
@@ -1523,7 +1800,7 @@ export class RemoteRecorder {
                 if (opts.signal?.aborted)
                     throw err;
                 const reason = signal.aborted ? `timed out after ${timeoutMs} ms reading the answer` : reasonOf(err);
-                this.health.fail(reason);
+                health.fail(reason);
                 throw new ServiceError(`${method} ${path}: ${reason}`, res.status);
             }
             if (isUnhealthyStatus(res.status)) {
@@ -1533,19 +1810,19 @@ export class RemoteRecorder {
                     await sleep(retryDelayMs(res));
                     continue;
                 }
-                this.health.fail(`HTTP ${res.status}`);
+                health.fail(`HTTP ${res.status}`);
                 throw new ServiceError(`HTTP ${res.status} ${method} ${path}${detail(text, type)}`, res.status);
             }
             // A 2xx web page is a captive portal or a website, and a 403 one a CDN's
             // challenge — not the API answering. An empty or plain 2xx is: only the
             // body decides, not a `text/html` a framework put on `res.send("ok")`.
             if ((res.ok || res.status === 403) && isWebPage(text, type)) {
-                this.health.fail("html");
+                health.fail("html");
                 throw new ServiceError(`HTTP ${res.status} ${method} ${path} — the answer was a web page, not the BaseIn API`, res.status);
             }
             // Anything else is the service answering, including a 4xx — an older
             // service's 404 must not look like an outage.
-            this.health.ok(started);
+            health.ok(started);
             if (!res.ok) {
                 if (res.status === 409 && retriedTransient)
                     return undefined; // the first attempt landed

package/dist/record/switchable-recorder.js

@@ -52,6 +52,12 @@ const NEUTRAL = {
     reportExecution: () => undefined,
     backfillContext: () => undefined,
     probeIfFailing: () => undefined,
+    // A tool list (the service's autocorrect.md AC12): not taken, so sent again later.
+    reportTools: () => Promise.resolve(false),
+    accountId: () => undefined,
+    // Signed out: no plan to list for a session start, no report taken (review items 8, 19).
+    scenarioAttention: () => Promise.resolve(null),
+    disputeScenario: () => Promise.resolve({ ok: false, why: "signed_out" }),
 };
 /**
  * `RemoteRecorder`'s private helpers. They are methods at runtime (TypeScript's

package/dist/replay/bundle.d.ts

@@ -55,6 +55,14 @@ export interface AssembleOptions {
      * feed the agent's own task, which continues. `handover` wins over this.
      */
     subTask?: boolean;
+    /**
+     * `bir`'s report tool, by the name the agent calls it, when the session has
+     * it (`mcp__bir__report_wrong_result`): the words that forbid every tool
+     * call make one exception for it ({@link withReportException}). Only the
+     * live and mixed bundles forbid tools; a hand-over and a sub-task already
+     * leave the agent its tools.
+     */
+    reportTool?: string;
 }
 /**
  * Compose the bundle. `maxChars` is a hard ceiling on the returned string.

package/dist/replay/bundle.js

@@ -70,6 +70,24 @@ const MIXED_HEADER = "[BaseInstRunner calculated replay] A known-good tool seque
     "because their tool cannot be executed here — treat them as possibly out of date. " +
     "Use them to answer the user's request now — do NOT call any tools.";
 const MIXED_FOOTER = "\n\nAnswer the user's request using the results above. Do not call any tools.";
+/**
+ * The one exception the "do NOT call any tools" lines make, when the session
+ * has `bir`'s own report tool (the service's review of
+ * calcscenarioautocorrect.md, item 19). A plan that took the wrong half of an
+ * "if … otherwise" is caught only when the agent says so, and these lines
+ * told it not even to check: an agent that sees the results do not answer
+ * the request may now say so, in one call that undoes nothing, and then tell
+ * the user. Without the tool the lines stay exactly as they were.
+ */
+function withReportException(text, tool) {
+    if (!tool)
+        return text;
+    const except = `do NOT call any tools, except: if these results do not answer the request (for example, ` +
+        `the wrong branch of an if/otherwise was taken), call ${tool} with why, then tell the user.`;
+    return text
+        .replace("do NOT call any tools.", except)
+        .replace("Do not call any tools.", `Do not call any tools (except ${tool}, as said above).`);
+}
 /**
  * The scenario stopped before the task was done (fallbk.md), so the model must
  * NOT be told to answer without tools — the rest of the work is its own. The
@@ -108,16 +126,12 @@ export function assembleBundle(entries, maxChars, opts = {}) {
         ? HANDOVER_HEADER
         : opts.subTask
             ? SUBTASK_HEADER
-            : anyRecorded
-                ? MIXED_HEADER
-                : LIVE_HEADER;
+            : withReportException(anyRecorded ? MIXED_HEADER : LIVE_HEADER, opts.reportTool);
     const footer = opts.handover
         ? HANDOVER_FOOTER
         : opts.subTask
             ? SUBTASK_FOOTER
-            : anyRecorded
-                ? MIXED_FOOTER
-                : LIVE_FOOTER;
+            : withReportException(anyRecorded ? MIXED_FOOTER : LIVE_FOOTER, opts.reportTool);
     const fixedCost = header.length +
         footer.length +
         entries.reduce((sum, e) => sum +

package/dist/replay/condition-words.d.ts

@@ -0,0 +1,28 @@
+/**
+ * condition-words — the request's own words for its decision (the service's
+ * segmentsbreakdown.md SB-18).
+ *
+ * When a plan stops at its decision, the hand-over note quotes the sentences
+ * of the live request that hold a word for a condition ("if … otherwise"), so
+ * the agent sees which choice is its own to make. Only the request's words:
+ * never the condition the service keeps, which is written from the recorded
+ * run and would hint at the half the recording took.
+ *
+ * The word lists are the service's (its src/scenarios/condition.ts), copied
+ * exactly. Keep the two the same: the service decides which requests may hold
+ * a condition with them, and this quotes the sentences they find.
+ */
+/** The longest quote a decision note carries, in characters. */
+export declare const MAX_DECISION_QUOTE = 600;
+/** Whether a text has a word for a condition in it: the service's `mayHoldCondition`. */
+export declare function mayHoldCondition(text: string): boolean;
+/**
+ * The sentences of `request` that hold a word for a condition, in order,
+ * each on one line of single spaces, joined by a space. Cut to at most `max`
+ * characters, ending in "…" when cut. Null when no sentence holds one.
+ *
+ * Lines are sentences of their own: the request is split at line breaks
+ * first, then at {@link SENTENCE_BREAK}.
+ */
+export declare function conditionSentences(request: string | null | undefined, max?: number): string | null;
+//# sourceMappingURL=condition-words.d.ts.map

package/dist/replay/condition-words.js

@@ -0,0 +1,59 @@
+/**
+ * condition-words — the request's own words for its decision (the service's
+ * segmentsbreakdown.md SB-18).
+ *
+ * When a plan stops at its decision, the hand-over note quotes the sentences
+ * of the live request that hold a word for a condition ("if … otherwise"), so
+ * the agent sees which choice is its own to make. Only the request's words:
+ * never the condition the service keeps, which is written from the recorded
+ * run and would hint at the half the recording took.
+ *
+ * The word lists are the service's (its src/scenarios/condition.ts), copied
+ * exactly. Keep the two the same: the service decides which requests may hold
+ * a condition with them, and this quotes the sentences they find.
+ */
+/** Words that say a part of a task depends on something: English, and the Hebrew the service reads. */
+const CONDITION_WORDS = /\b(if|otherwise|else|unless|only when|only if|in case|whether)\b/i;
+const HEBREW_CONDITION = /(^|[\s,.;:!?"'()\-])(אם|אחרת|אלא אם|במקרה ש|רק אם|רק כאשר)($|[\s,.;:!?"'()\-])/;
+/** The longest quote a decision note carries, in characters. */
+export const MAX_DECISION_QUOTE = 600;
+/** Whether a text has a word for a condition in it: the service's `mayHoldCondition`. */
+export function mayHoldCondition(text) {
+    return CONDITION_WORDS.test(text) || HEBREW_CONDITION.test(text);
+}
+/**
+ * Where one sentence ends and the next begins: after `.`, `!`, `?` or `…` and
+ * white space, in front of a capital letter, a letter of a script with no
+ * capitals (Hebrew), a quote mark or a bracket. Never in front of a digit or a
+ * small letter, so "Nov. 20" and "e.g. the" stay in one sentence.
+ */
+const SENTENCE_BREAK = /(?<=[.!?…])\s+(?=[\p{Lu}\p{Lo}"'“‘(\[])/u;
+/**
+ * The sentences of `request` that hold a word for a condition, in order,
+ * each on one line of single spaces, joined by a space. Cut to at most `max`
+ * characters, ending in "…" when cut. Null when no sentence holds one.
+ *
+ * Lines are sentences of their own: the request is split at line breaks
+ * first, then at {@link SENTENCE_BREAK}.
+ */
+export function conditionSentences(request, max = MAX_DECISION_QUOTE) {
+    if (typeof request !== "string" || request.trim() === "")
+        return null;
+    const sentences = request
+        .replace(/\r\n?/g, "\n")
+        .split("\n")
+        .flatMap((line) => line.split(SENTENCE_BREAK))
+        .map((s) => s.replace(/\s+/g, " ").trim())
+        .filter((s) => s !== "" && mayHoldCondition(s));
+    if (sentences.length === 0)
+        return null;
+    const quote = sentences.join(" ");
+    if (quote.length <= max)
+        return quote;
+    let cut = quote.slice(0, Math.max(0, max - 1));
+    // Never half of a character written as two code units (an emoji).
+    if (/[\uD800-\uDBFF]$/.test(cut))
+        cut = cut.slice(0, -1);
+    return `${cut.trimEnd()}…`;
+}
+//# sourceMappingURL=condition-words.js.map