@sema-agent/server 1.322.0 → 2.0.0

package/dist/degenerate-instrument.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Degenerate-repetition instrument (a/b classifier).
+ *
+ * When a task fails with `errorCode === "output.degenerate"` (core 1.59), core hands back
+ * `salvagedOutput` = the degenerate turn's **whole** text (the good head + the looped garbage tail).
+ * Core's *salvage ②* — recovering the "last substantive turn" instead of the current one — is being
+ * gated on REAL data: how often is the useful answer actually in an EARLIER turn vs. in the degenerate
+ * turn itself? This instrument answers that, per event, without changing any behaviour.
+ *
+ * Classification (since the last user message = this task's own turns):
+ *  - **a** good+garbage SAME turn — the degenerate turn carries a substantive unique head before the
+ *    loop. Whole-turn salvage ① + a tail-trim is enough; ② would add nothing.
+ *  - **b** good EARLIER / degenerate LATER — a substantive assistant turn already exists before the
+ *    degenerate one. ② ("last-substantive-turn") would recover it; ① (current turn) throws it away.
+ *  - **unknown** — degenerate from the start, nothing substantive anywhere (neither ① nor ② helps).
+ *
+ * Output is measurement only: a `degenerate_total{class}` counter (→ `/metrics/summary`) plus one
+ * structured log line carrying the raw signals. The aggregate a/b/unknown frequencies are what gets
+ * reported back to the core AI to decide whether ② is worth building. The repetition-boundary estimate
+ * here is for *measuring* the unique head — it is NOT the production tail-trim (that lives in core).
+ */
 import { type TaskResult } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 import type { Metrics } from "./observability/metrics.js";
@@ -5,13 +26,30 @@ import type { Logger } from "./observability/logger.js";
 export type DegenerateClass = "a" | "b" | "unknown";
 export interface DegenerateSignals {
     class: DegenerateClass;
+    /** Assistant turns since the last user message, INCLUDING the degenerate one. */
     turnsSinceUser: number;
+    /** Substantive (non-looping) assistant text before the degenerate turn, since the last user message. */
     priorChars: number;
     salvagedLen: number;
+    /** `salvagedLen` minus the estimated looped tail = how much real answer the degenerate turn carries. */
     uniquePrefixLen: number;
     repeatedTailLen: number;
 }
+/**
+ * Length of the longest periodic suffix of `text` (≥ {@link MIN_REPEATS} contiguous copies of some
+ * unit ≤ {@link MAX_UNIT}). 0 when no qualifying loop is found. Bounded to the last {@link REP_WINDOW}
+ * chars. This estimates where the degenerate repetition begins — a measurement aid, not a trimmer.
+ */
 export declare function repetitionTail(text: string): number;
+/**
+ * Classify a degenerate failure from its salvaged text + the substantive content of the assistant
+ * turns that preceded it (since the last user message). Pure — unit-tested directly.
+ */
 export declare function classifyDegenerate(salvaged: string, priorChars: number, turnsSinceUser: number): DegenerateSignals;
+/**
+ * Build the fire-and-forget instrument. Returns a sync `(result) => void` so the hot result paths
+ * (`recordTaskResult` / `recordDone`) stay unblocked; the session read + classification run in the
+ * background and never throw into the response. No-op for non-degenerate results.
+ */
 export declare function makeDegenerateInstrument(pool: Pool, metrics?: Metrics, logger?: Logger): (result: TaskResult) => void;
 //# sourceMappingURL=degenerate-instrument.d.ts.map

package/dist/degenerate-instrument.js

@@ -1,10 +1,42 @@
+/**
+ * Degenerate-repetition instrument (a/b classifier).
+ *
+ * When a task fails with `errorCode === "output.degenerate"` (core 1.59), core hands back
+ * `salvagedOutput` = the degenerate turn's **whole** text (the good head + the looped garbage tail).
+ * Core's *salvage ②* — recovering the "last substantive turn" instead of the current one — is being
+ * gated on REAL data: how often is the useful answer actually in an EARLIER turn vs. in the degenerate
+ * turn itself? This instrument answers that, per event, without changing any behaviour.
+ *
+ * Classification (since the last user message = this task's own turns):
+ *  - **a** good+garbage SAME turn — the degenerate turn carries a substantive unique head before the
+ *    loop. Whole-turn salvage ① + a tail-trim is enough; ② would add nothing.
+ *  - **b** good EARLIER / degenerate LATER — a substantive assistant turn already exists before the
+ *    degenerate one. ② ("last-substantive-turn") would recover it; ① (current turn) throws it away.
+ *  - **unknown** — degenerate from the start, nothing substantive anywhere (neither ① nor ② helps).
+ *
+ * Output is measurement only: a `degenerate_total{class}` counter (→ `/metrics/summary`) plus one
+ * structured log line carrying the raw signals. The aggregate a/b/unknown frequencies are what gets
+ * reported back to the core AI to decide whether ② is worth building. The repetition-boundary estimate
+ * here is for *measuring* the unique head — it is NOT the production tail-trim (that lives in core).
+ */
+// 🔴 core 1.403 迁移(2026-07-25):runtime 构造用法,`Session` → `StoredSession`(见 audit.ts 同款注释)。
 import { StoredSession } from "@sema-agent/core";
 import { TiDBSessionStorage } from "./plugins/tidb-session-storage.js";
+/** A "real" answer is at least this many non-looping chars (after the degenerate tail is stripped). */
 const SUBSTANTIVE_CHARS = 200;
+/** Loops live at the end — only inspect this much of the tail when hunting the repeating unit. */
 const REP_WINDOW = 8192;
+/** Need at least this many contiguous copies to call a periodic suffix a degenerate loop. */
 const MIN_REPEATS = 3;
+/** Longest repeating unit we look for (a sentence-ish block); bounds the scan. */
 const MAX_UNIT = 256;
+/** Two assistant turns are "the same turn" if their heads match (a degenerate head is distinctive). */
 const TURN_MATCH_HEAD = 120;
+/**
+ * Length of the longest periodic suffix of `text` (≥ {@link MIN_REPEATS} contiguous copies of some
+ * unit ≤ {@link MAX_UNIT}). 0 when no qualifying loop is found. Bounded to the last {@link REP_WINDOW}
+ * chars. This estimates where the degenerate repetition begins — a measurement aid, not a trimmer.
+ */
 export function repetitionTail(text) {
     const n = text.length;
     if (n < 2)
@@ -13,6 +45,7 @@ export function repetitionTail(text) {
     const maxUnit = Math.min(MAX_UNIT, Math.floor((n - start) / MIN_REPEATS));
     let best = 0;
     for (let p = 1; p <= maxUnit; p++) {
+        // How many times does the final p-char block repeat contiguously, walking backwards?
         let reps = 1;
         for (;;) {
             const blockStart = n - p * (reps + 1);
@@ -34,20 +67,26 @@ export function repetitionTail(text) {
     }
     return best;
 }
+/** Substantive (non-looping) length of one assistant turn's text. */
 function substantiveLen(text) {
     return Math.max(0, text.length - repetitionTail(text));
 }
+/**
+ * Classify a degenerate failure from its salvaged text + the substantive content of the assistant
+ * turns that preceded it (since the last user message). Pure — unit-tested directly.
+ */
 export function classifyDegenerate(salvaged, priorChars, turnsSinceUser) {
     const salvagedLen = salvaged.length;
     const repeatedTailLen = repetitionTail(salvaged);
     const uniquePrefixLen = Math.max(0, salvagedLen - repeatedTailLen);
     const cls = priorChars >= SUBSTANTIVE_CHARS
-        ? "b"
+        ? "b" // a substantive answer already existed in an earlier turn → ② would recover it
         : uniquePrefixLen >= SUBSTANTIVE_CHARS
-            ? "a"
-            : "unknown";
+            ? "a" // the degenerate turn itself carries the answer before looping → ① + tail-trim suffices
+            : "unknown"; // degenerate from the start, nothing substantive anywhere
     return { class: cls, turnsSinceUser, priorChars, salvagedLen, uniquePrefixLen, repeatedTailLen };
 }
+/** Concatenated text-block content of one (assistant) message; "" for a tool-call-only turn. */
 function turnText(msg) {
     if (msg.role !== "assistant" || !Array.isArray(msg.content))
         return "";
@@ -56,6 +95,7 @@ function turnText(msg) {
         .map((b) => b.text)
         .join("");
 }
+/** Heads match → treat as the same turn (core may or may not persist the failed degenerate turn). */
 function sameTurn(a, b) {
     if (!a || !b)
         return false;
@@ -64,6 +104,12 @@ function sameTurn(a, b) {
     const k = Math.min(TURN_MATCH_HEAD, a.length, b.length);
     return k > 0 && a.slice(0, k) === b.slice(0, k);
 }
+/**
+ * Read this task's assistant turns (since the last user message) and total the substantive text that
+ * preceded the degenerate turn. The degenerate turn is located by head-matching `salvaged`; if it was
+ * not persisted, every persisted assistant turn in the window counts as prior (and the degenerate turn
+ * is added to the count). Best-effort — returns zeros if the session can't be read.
+ */
 async function readPriorTurns(pool, sessionId, salvaged) {
     const storage = await TiDBSessionStorage.wake(pool, sessionId);
     if (!storage)
@@ -90,9 +136,15 @@ async function readPriorTurns(pool, sessionId, salvaged) {
     }
     const priorTexts = degenIdx >= 0 ? assistantTexts.slice(0, degenIdx) : assistantTexts;
     const priorChars = priorTexts.reduce((a, t) => a + substantiveLen(t), 0);
+    // turnsSinceUser counts the degenerate turn too; add 1 when it wasn't found among persisted turns.
     const turnsSinceUser = degenIdx >= 0 ? assistantTexts.length : assistantTexts.length + 1;
     return { priorChars, turnsSinceUser };
 }
+/**
+ * Build the fire-and-forget instrument. Returns a sync `(result) => void` so the hot result paths
+ * (`recordTaskResult` / `recordDone`) stay unblocked; the session read + classification run in the
+ * background and never throw into the response. No-op for non-degenerate results.
+ */
 export function makeDegenerateInstrument(pool, metrics, logger) {
     return (result) => {
         if (result.errorCode !== "output.degenerate")

package/dist/elicitation.d.ts

@@ -1,27 +1,47 @@
 import { type McpElicitRequest, type McpElicitResponse } from "@sema-agent/core";
+/** A live elicitation frame delivered to whoever is tailing this run's stream. `type` IS the SSE event name
+ *  (mirrors the named-event convention: the payload also carries `type` so a proxy that strips event names still
+ *  works). The shell renders the `elicitation` frame as a dialog and dismisses on `elicitation_complete`. */
 export interface ElicitationFrame {
     type: "elicitation" | "elicitation_complete";
     elicitationId: string;
     mcpServerName: string;
+    /** "elicitation" only: the FENCED + secret-redacted human-facing prompt. UNTRUSTED — never re-feed to a model. */
     message?: string;
+    /** "elicitation" only: the server's requested input schema. OPAQUE passthrough — never interpreted/validated;
+     *  still server-controlled UNTRUSTED, so the shell must fence it on display. */
     requestedSchema?: unknown;
+    /** "elicitation" only: always "form" in v1 (url-mode is rejected upstream). */
     mode?: "form";
+    /** "elicitation_complete" only: how it resolved. */
     action?: McpElicitResponse["action"];
 }
+/** The per-run context `onElicit` recovers via ALS. `emit` delivers a frame to the run's live stream;
+ *  `abortSignal` (the run's own cancel signal) lets a run-abort promptly cancel an elicitation parked awaiting a
+ *  human, since the MCP per-request signal may not be chained to the run abort. */
 export interface ElicitationRunContext {
     taskId: string;
     owner: string | null;
     emit: (frame: ElicitationFrame) => void | Promise<void>;
     abortSignal?: AbortSignal;
 }
+/** @deprecated design/158 N22: the root word got truncated at naming time — `ElicitationFrame` / `ElicitationThrottle` /
+ *  `ElicitationCoordinator` all spell it out; this alias was the odd one. Use {@link ElicitationRunContext}. */
 export type ElicitRunContext = ElicitationRunContext;
 export interface ElicitationThrottle {
+    /** Max concurrent in-flight elicitations per run leg (parallel tool calls can each elicit). Breach ⇒ decline. */
     maxConcurrentPerRun: number;
+    /** Max total elicitations one run leg will surface to the human. Breach ⇒ decline (flood defense). */
     maxTotalPerRun: number;
+    /** Min gap (ms) between two elicitations from the SAME server within a run. Within ⇒ decline (burst guard). */
     minIntervalMsPerServer: number;
+    /** An unanswered elicitation auto-declines after this (ms) — the human walked away; don't hold core forever. */
     ttlMs: number;
 }
 export declare const DEFAULT_ELICITATION_THROTTLE: ElicitationThrottle;
+/** Validate the respond body = core's `McpElicitResponse`. `content` is accept-only OPAQUE passthrough (core never
+ *  validates it against `requestedSchema`); we validate only the outer shape (a flat record of scalars / string[]),
+ *  never the schema. A non-accept drops content (MCP convention). */
 export declare function parseElicitationResponse(body: unknown): {
     ok: true;
     value: McpElicitResponse;
@@ -29,7 +49,16 @@ export declare function parseElicitationResponse(body: unknown): {
     ok: false;
     error: string;
 };
+/** @deprecated design/158 N22: renamed to {@link parseElicitationResponse} — unifies the HITL trio's parse-fn
+ *  vocabulary (`parseQuestionResponse` / `parseElicitationResponse` / `parseToolApprovalResponse`, all "the
+ *  human's reply body"). Kept as a compat alias. */
 export declare const parseElicitResponse: typeof parseElicitationResponse;
+/**
+ * Coordinates inbound MCP elicitations for one server instance. Process-local + same-replica (the pending map is in
+ * memory, like `steerableRuns`): a respond that lands on another replica finds nothing → 404. Present (passed into
+ * `RunnerDeps.onElicit` + the respond route) ONLY when `MCP_ELICITATION_ENABLED` — absent ⇒ core advertises no
+ * elicitation capability to any server (doubly fail-closed with the per-server `McpServerSpec.elicitation` default OFF).
+ */
 export declare class ElicitationCoordinator {
     private readonly als;
     private readonly pending;
@@ -37,12 +66,22 @@ export declare class ElicitationCoordinator {
     private readonly throttle;
     private readonly now;
     constructor(throttle?: ElicitationThrottle, now?: () => number);
+    /** Run `fn` with the per-run elicitation context ambient. On exit, cancel any still-pending elicitation for this
+     *  run (a live-only elicitation cannot outlive its leg) and drop the run's counters (no leak). The cancel covers
+     *  the case where the leg ends/throws while an elicitation is parked but the leg's own loop has already drained. */
     runWithContext<T>(ctx: ElicitationRunContext, fn: () => Promise<T>): Promise<T>;
+    /** `RunnerDeps.onElicit`. Core calls this when an opted-in server elicits the END USER mid-tool-call; the resolved
+     *  value is sent back to the server on the still-open connection. Fail-closed (`decline`/`cancel`) in every
+     *  uncertain case. Arrow property so it can be passed as `onElicit: coordinator.elicit` with `this` bound. */
     elicit: (req: McpElicitRequest, signal?: AbortSignal) => Promise<McpElicitResponse>;
+    /** `POST /v1/elicitations/:id/respond` — resolve a parked elicitation with the shell's answer. Owner-gated with a
+     *  404 (no existence oracle): a non-owner AND an unknown id (answered / expired / wrong replica) both get 404.
+     *  Returns the HTTP {status, body}; the HTTP layer owns auth (gatedPrincipal + REQUIRE_PRINCIPAL) before calling. */
     respond(id: string, principal: string | undefined, body: unknown): {
         status: number;
         body: unknown;
     };
+    /** Test/observability hook: number of currently-parked elicitations. */
     pendingCount(): number;
     private countersFor;
 }

package/dist/elicitation.js

@@ -1,6 +1,36 @@
+/**
+ * E23 (shell-host contract) — inbound-MCP-elicitation HITL flow, the SERVICE side of core 1.124.0's live-only
+ * `RunnerDeps.onElicit` seam (design/99 §E23).
+ *
+ * An opted-in MCP server (`McpServerSpec.elicitation === true`) may, MID-tool-call, ask the END USER for input.
+ * core hands that request to `onElicit` and awaits the answer SYNCHRONOUSLY on the still-open task-scoped
+ * connection (it replies to the server with whatever the promise resolves to). There is NO durable suspend —
+ * a crash/replica-change loses an in-flight elicitation (acceptable for an interactive shell; a durable variant
+ * waits on the deferred E22 longer-lived connection). So this whole flow is LIVE-ONLY + same-replica, the
+ * `steer()`-class of HITL, NOT the durable approval/checkpoint class.
+ *
+ * The service is pure WIRE glue (the abstraction is core's, §0.1): forward the request to whoever is tailing the
+ * run's stream (an `elicitation` SSE frame), park a promise, and resolve it from `POST /v1/elicitations/:id/respond`.
+ * Three responsibilities are explicitly the deployment's (core delegates them):
+ *   1. THROTTLE — core imposes no rate/count cap; an over-eager or hostile server could flood the human. We bound
+ *      concurrency + total + per-server burst per run; a breach fail-closes to `decline`.
+ *   2. FENCING — `message`/`requestedSchema` are server-controlled UNTRUSTED text; `message` is `delimitUntrusted`-
+ *      fenced + secret-redacted before it reaches a human (the shell must also fence `requestedSchema` on display).
+ *   3. FORM-MODE ONLY — v1 advertises form mode; url-mode (a phishing surface) is defensively rejected.
+ *
+ * ROUTING: `onElicit` lives on the SINGLETON runner's `RunnerDeps` and the request carries no taskId, so the run's
+ * executor establishes a per-run context (AsyncLocalStorage, like `withPrincipal`) carrying the taskId (throttle
+ * key), the owner (respond owner-gate), and an `emit` closure (durable append for background/resume legs; `res.write`
+ * for the synchronous stream leg). `node:async_hooks` propagates it through every await, so `onElicit` — invoked deep
+ * inside core's `callTool` — recovers it. No context ⇒ fail-closed `decline`.
+ */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { uuidv7, delimitUntrusted } from "@sema-agent/core";
 import { redactSecrets, redactDeep } from "./trace/redact.js";
+/** Size bounds on the UNTRUSTED server-controlled payload (the throttle bounds COUNT, these bound SIZE — an
+ *  opted-in-but-hostile server otherwise amplifies a multi-MB prompt/schema into the durable log + SSE socket).
+ *  The message is a human-facing prompt (a few KB is ample); a requestedSchema over the cap is dropped (the form
+ *  can't render an abusive schema — fail-safe to no-schema). */
 const MAX_ELICIT_MESSAGE_CHARS = 4096;
 const MAX_ELICIT_SCHEMA_BYTES = 8192;
 export const DEFAULT_ELICITATION_THROTTLE = {
@@ -9,6 +39,9 @@ export const DEFAULT_ELICITATION_THROTTLE = {
     minIntervalMsPerServer: 1_000,
     ttlMs: 5 * 60_000,
 };
+/** Validate the respond body = core's `McpElicitResponse`. `content` is accept-only OPAQUE passthrough (core never
+ *  validates it against `requestedSchema`); we validate only the outer shape (a flat record of scalars / string[]),
+ *  never the schema. A non-accept drops content (MCP convention). */
 export function parseElicitationResponse(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
         return { ok: false, error: "body must be an object" };
@@ -32,7 +65,14 @@ export function parseElicitationResponse(body) {
     }
     return { ok: true, value: { action: b.action } };
 }
+/** @deprecated design/158 N22: renamed to {@link parseElicitationResponse} — unifies the HITL trio's parse-fn
+ *  vocabulary (`parseQuestionResponse` / `parseElicitationResponse` / `parseToolApprovalResponse`, all "the
+ *  human's reply body"). Kept as a compat alias. */
 export const parseElicitResponse = parseElicitationResponse;
+/** redactDeep + size-bound an UNTRUSTED `requestedSchema` before it is persisted to the durable log / streamed
+ *  (the same redact-at-write contract every other untrusted structured field honors, e.g. tool_end.output). A JSON
+ *  Schema's free-text carriers (description/title/default/enum) can smuggle a secret. Over the byte cap ⇒ undefined
+ *  (drop — an abusive schema can't render a form); unserializable (circular) ⇒ undefined. */
 function boundSchema(schema) {
     if (schema === undefined)
         return undefined;
@@ -46,6 +86,12 @@ function boundSchema(schema) {
     }
     return redacted;
 }
+/**
+ * Coordinates inbound MCP elicitations for one server instance. Process-local + same-replica (the pending map is in
+ * memory, like `steerableRuns`): a respond that lands on another replica finds nothing → 404. Present (passed into
+ * `RunnerDeps.onElicit` + the respond route) ONLY when `MCP_ELICITATION_ENABLED` — absent ⇒ core advertises no
+ * elicitation capability to any server (doubly fail-closed with the per-server `McpServerSpec.elicitation` default OFF).
+ */
 export class ElicitationCoordinator {
     als = new AsyncLocalStorage();
     pending = new Map();
@@ -56,12 +102,16 @@ export class ElicitationCoordinator {
         this.throttle = throttle;
         this.now = now;
     }
+    /** Run `fn` with the per-run elicitation context ambient. On exit, cancel any still-pending elicitation for this
+     *  run (a live-only elicitation cannot outlive its leg) and drop the run's counters (no leak). The cancel covers
+     *  the case where the leg ends/throws while an elicitation is parked but the leg's own loop has already drained. */
     runWithContext(ctx, fn) {
         return this.als.run(ctx, async () => {
             try {
                 return await fn();
             }
             finally {
+                // Snapshot first — settle() mutates this.pending.
                 for (const [, p] of [...this.pending]) {
                     if (p.taskId === ctx.taskId)
                         p.settle({ action: "cancel" });
@@ -70,26 +120,42 @@ export class ElicitationCoordinator {
             }
         });
     }
+    /** `RunnerDeps.onElicit`. Core calls this when an opted-in server elicits the END USER mid-tool-call; the resolved
+     *  value is sent back to the server on the still-open connection. Fail-closed (`decline`/`cancel`) in every
+     *  uncertain case. Arrow property so it can be passed as `onElicit: coordinator.elicit` with `this` bound. */
     elicit = async (req, signal) => {
         const ctx = this.als.getStore();
+        // No run context to route to a human (a leg not wrapped by runWithContext — synchronous /v1/tasks, verify/cascade,
+        // or a leader sub-task) ⇒ fail-closed decline. NB on SUB-TASKS: subagent/team run on the SAME runner inside the
+        // parent's ALS frame, so a sub-task's elicitation INHERITS the top-level run's ctx — by design it routes to the
+        // top-level stream + owner and shares the per-run-tree throttle budget (one human, one budget); the frame's
+        // `mcpServerName` attributes which server asked. (Same tenant: a sub-task inherits the parent principal.)
         if (!ctx)
             return { action: "decline" };
+        // v1 FORM-MODE ONLY: defensively reject url-mode. core advertises form-only so `url` is never populated today;
+        // this is defense-in-depth so a future/hostile url can never reach a human as a phishing link.
         if (typeof req.url === "string" && req.url.length > 0)
             return { action: "decline" };
         if (signal?.aborted || ctx.abortSignal?.aborted)
             return { action: "cancel" };
+        // THROTTLE (service's job — core imposes none): bound concurrency + total + per-server burst. Breach ⇒ decline.
         const rc = this.countersFor(ctx.taskId);
         const t = this.now();
-        const last = rc.lastByServer.get(req.server);
+        const last = rc.lastByServer.get(req.server); // undefined ⇒ first elicitation from this server (no interval gate)
         if (rc.inflight >= this.throttle.maxConcurrentPerRun ||
             rc.total >= this.throttle.maxTotalPerRun ||
             (last !== undefined && t - last < this.throttle.minIntervalMsPerServer)) {
             return { action: "decline" };
         }
         const id = uuidv7();
-        rc.inflight += 1;
+        rc.inflight += 1; // reserve a concurrency slot for the await; total/interval are charged only on a successful emit
+        // FENCE + secret-redact + SIZE-bound the untrusted human-facing prompt: delimitUntrusted neutralizes
+        // <system-reminder>/fence break-out on BOTH the body and the server-name label; redactSecrets strips a secret the
+        // server echoed; the slice bounds storage/CPU. requestedSchema is redactDeep'd + size-bounded (it is persisted to
+        // the durable log + streamed, served to trace readers — fencing-on-display alone does not contain secrets).
         const message = delimitUntrusted(req.server, redactSecrets((typeof req.message === "string" ? req.message : "").slice(0, MAX_ELICIT_MESSAGE_CHARS)));
         const requestedSchema = boundSchema(req.requestedSchema);
+        // Deferred answer promise + idempotent settle (resolved by respond, the TTL timer, or an abort).
         let done = false;
         let timer;
         let resolveAnswer;
@@ -106,37 +172,55 @@ export class ElicitationCoordinator {
             rc.inflight = Math.max(0, rc.inflight - 1);
             resolveAnswer(r);
         };
+        // Both signals: the MCP per-request signal AND the run's own cancel signal (the former may not be chained to a
+        // run abort, which would otherwise leave a cancelled run parked here for the full TTL).
         const onAbort = () => settle({ action: "cancel" });
         timer = setTimeout(() => settle({ action: "decline" }), this.throttle.ttlMs);
         timer.unref?.();
         signal?.addEventListener("abort", onAbort, { once: true });
         ctx.abortSignal?.addEventListener("abort", onAbort, { once: true });
+        // Register BEFORE emitting so a (fast) respond can never miss the entry.
         this.pending.set(id, { settle, owner: ctx.owner, taskId: ctx.taskId });
+        // Emit the OPEN frame AWAITED so its durable append is ORDERED ahead of the answer/completion/terminal appends —
+        // a fire-and-forget append can commit out of seq order and be permanently skipped by the monotonic events-tail
+        // cursor (an invisible prompt that then TTL-declines). On a successful emit, charge the per-run-tree budget; a
+        // FAILED emit declines (nobody can answer) and must NOT burn maxTotal / the per-server interval.
         try {
             await ctx.emit({ type: "elicitation", elicitationId: id, mcpServerName: req.server, message, ...(requestedSchema !== undefined ? { requestedSchema } : {}), mode: "form" });
             rc.total += 1;
             rc.lastByServer.set(req.server, t);
         }
         catch {
-            settle({ action: "decline" });
+            settle({ action: "decline" }); // inflight rolled back in settle
         }
         const answer = await answerP;
+        // Completion breadcrumb (dialog dismiss) — FIRE-AND-FORGET so a slow/hung durable append can NEVER delay
+        // returning the answer to core (which replies to the MCP server on the still-open connection). Best-effort +
+        // ordering-uncritical: the shell already has the answer via respond; a late/lost dismiss is cosmetic.
         void Promise.resolve()
             .then(() => ctx.emit({ type: "elicitation_complete", elicitationId: id, mcpServerName: req.server, action: answer.action }))
             .catch(() => undefined);
         return answer;
     };
+    /** `POST /v1/elicitations/:id/respond` — resolve a parked elicitation with the shell's answer. Owner-gated with a
+     *  404 (no existence oracle): a non-owner AND an unknown id (answered / expired / wrong replica) both get 404.
+     *  Returns the HTTP {status, body}; the HTTP layer owns auth (gatedPrincipal + REQUIRE_PRINCIPAL) before calling. */
     respond(id, principal, body) {
+        // Validate the body BEFORE the lookup (steer parity): a bad body is the caller's error regardless of run state,
+        // so 400 is existence-independent (a malformed respond to ANY id → 400, never an existence oracle via 400-vs-404).
         const parsed = parseElicitationResponse(body);
         if (!parsed.ok)
             return { status: 400, body: { error: parsed.error, errorCode: "request.body_shape" } };
         const entry = this.pending.get(id);
+        // Owner-gate with 404 (no existence oracle): a non-owner AND an unknown id (answered / expired / wrong replica)
+        // both get 404, so a good-body caller can't tell another tenant's id from a nonexistent one.
         if (!entry || (entry.owner !== null && entry.owner !== principal)) {
             return { status: 404, body: { error: "no pending elicitation for this id (answered, expired, or not on this replica)", errorCode: "elicitation.not_pending" } };
         }
         entry.settle(parsed.value);
         return { status: 200, body: { elicitationId: id, delivery: "applied", action: parsed.value.action } };
     }
+    /** Test/observability hook: number of currently-parked elicitations. */
     pendingCount() {
         return this.pending.size;
     }

package/dist/env-facts.d.ts

@@ -4,13 +4,31 @@ export interface SandboxEnvFacts {
     capabilities?: string[];
     pkgSource?: string;
     egress?: "none" | "allowlist" | "full";
+    /** [820]③ scratchpad first wave: core `TaskSpec.envFacts.scratchpadDir` (field + prompt chain —
+     *  buildScratchpadSection — shipped in core 1.257.3; only this server half was missing). Core renders the
+     *  "# Scratchpad Directory" block steering temp files away from /tmp AND the user's project. Core's prompt
+     *  wording promises: session-specific, isolated from the user's project, "can generally be used without
+     *  permission prompts" — that last clause is exactly the exemption domain createFsWriteGatePolicy.exemptDirs
+     *  will honor ([819]③/[820]①), so the path is produced by the single-source {@link scratchpadDirFor} and the
+     *  1.290 wiring must reference the SAME function for exemptDirs. */
     scratchpadDir?: string;
+    /** [1467]②(core 1.360 B 半场)durable resume 铸句真值——server 按**车道能力面**填(部署静态事实,
+     *  非车道名判——[1452]③ 诚实裁:缺席字段=core 零句,绝不写死车道行为):
+     *   - e2b:VM snapshot suspend/resume ⇒ processes+scratch 双 preserved。
+     *   - k8s(s3Snapshot):resume=fresh pod+workspace untar ⇒ processes+scratch 双 lost(note 讲清
+     *     workspace 文件已从快照恢复——「scratch lost」≠「工作丢了」)。
+     *   - ssh/adb:park-only,远端 host/device 持续存在 ⇒ scratch preserved;processes 不声明(前台随
+     *     连接断,daemon 存活——不知道的不说)。
+     *   - host:同机 ⇒ scratch preserved;processes 不声明(worker 进程可能换代)。
+     *   - local-docker:容器跨 leg 存续不保证(reconnect 或有或无)⇒ 整域不声明。 */
     resumeFacts?: {
         processes?: "preserved" | "lost";
         scratch?: "preserved" | "lost";
         note?: string;
     };
 }
+/** Compose envFacts from what the deployment knows at spec-prep. Returns undefined when nothing is known
+ *  (no fact beats a vacuous one — an empty block would still spend prompt tokens). */
 export declare function buildEnvFacts(opts: {
     profile?: string | undefined;
     capabilities?: ImageCapabilities | undefined;
@@ -19,22 +37,65 @@ export declare function buildEnvFacts(opts: {
     scratchpadDir?: string | undefined;
     resumeFacts?: SandboxEnvFacts["resumeFacts"] | undefined;
 }): SandboxEnvFacts | undefined;
+/** resumeFacts 按车道能力面的单真源(部署静态;undefined=整域不声明)。取值依据见
+ *  {@link SandboxEnvFacts.resumeFacts} 的逐车道注。
+ *  codex 复审 medium:k8s 必须按**有效快照能力**分叉,不能只看车道名——s3Snapshot 未配=park-only,
+ *  resume 是全新 pod 且**工作区不恢复**,「文件已从快照恢复」那句会让模型信赖不存在的文件(比缺席
+ *  更糟的谎)。 */
 export declare function resumeFactsForLane(provider: "e2b" | "k8s" | "ssh" | "adb" | "local-docker" | "host" | undefined, caps?: {
     k8sSnapshot?: boolean;
 }): SandboxEnvFacts["resumeFacts"] | undefined;
+/** Path-safe session segment: the session id can be CALLER-SUPPLIED (body.sessionId), so it must not be able to
+ *  walk the tree ("../", separators, control bytes). Allowlist [A-Za-z0-9_-] (dots excluded so ".." cannot
+ *  survive), everything else becomes "_". Empty after sanitize → "_".
+ *
+ *  INJECTIVITY (codex F3): allowlist sanitization alone is NOT injective — "team/a" and "team?a" both map to
+ *  "team_a", so two DIFFERENT sessions (possibly different principals) would collide onto ONE scratchpad dir.
+ *  The segment is therefore `<readable prefix (sanitized, ≤24)>-<sha256(FULL ORIGINAL sessionId) hex ≤16>`:
+ *  the hash is over the raw pre-sanitize id, so distinct ids always produce distinct segments (the prefix stays
+ *  purely for human readability). Max length 24+1+16=41 (uuidv7 = 36 raw). */
 export declare function scratchpadSessionSegment(sessionId: string): string;
+/** THE scratchpad path convention: `<localDataRoot>/scratchpad/<sessionSegment>`. Session-scoped (core's
+ *  prompt says "session-specific" — every task on the session shares one dir, which is the useful semantics:
+ *  intermediate artifacts survive across turns/resume legs). Exported as the single source both the envFacts
+ *  composer (below) and the future createFsWriteGatePolicy `exemptDirs` wiring ([820]①, 1.290) must use. */
 export declare function scratchpadDirFor(localDataRoot: string, sessionId: string): string;
+/** Resolve + CREATE the session scratchpad dir (mkdir -p, idempotent). Returns the path, or undefined when
+ *  creation fails (honest-facts posture: never advertise a directory that does not exist — same class as
+ *  egress/pkgSource "don't declare what you don't know"). Lifecycle: the reaper primitives live below —
+ *  {@link purgeScratchpadDir}(session delete)+ {@link sweepStaleScratchpads}(mtime 周期扫),keyed by the
+ *  same scratchpadDirFor convention;接线(E21 DELETE purge + 周期 sweep)在 main.ts 侧(D 组)。 */
 export declare function ensureScratchpadDir(localDataRoot: string, sessionId: string): Promise<string | undefined>;
+/** G3([816] 壳侧承诺③/[820]③,[1840]§四接单):**壳供** scratchpad 路径的验收门。
+ *
+ *  壳(cli)vendored getScratchpadDir 算出 per-session scratchpad 路径随 `TaskRequest.scratchpadDir` 发来;
+ *  接受后它**优先于** server 自算(ensureScratchpadDir),喂 main.ts 的同一单点(envFacts 事实 +
+ *  fs-write gate exemptDirs + additionalDirectories 根围栏)。「没到货引擎忽略 = 无害 additive」。
+ *
+ *  信任边界:这是 exemptDirs **放宽**输入,验收 fail-closed(任何拒收形回落自算,不 fault 任务):
+ *   - 多租户(requirePrincipal)一律拒——共享 worker 盘上租户自选豁免目录=越权面;
+ *   - 仅 host-semantics lane——远程沙箱 lane 的 worker 本机路径对 hands 是谎言(honest-facts 同轴);
+ *   - 绝对路径 + ≤{@link MAX_PATH}(core 渲染上限同源,超限=core 只能给模型假路径)+ canonical
+ *     深度 ≥3(裸 /、/tmp、/home 一整块系统目录不能当豁免域;穿越形按 resolve 归一后判);
+ *   - mkdir -p 确保存在(gate 的 canonicalize 与 core 根围栏都要真目录)。
+ *  敏感路径的最后一道在 core gate 折叠里(sensitivePatterns deny 恒赢,exemptDirs 越不过)。 */
 export declare function acceptShellScratchpadDir(raw: unknown, opts: {
     requirePrincipal: boolean;
     hostSemanticsLane: boolean;
     warn: (msg: string, meta?: object) => void;
 }): Promise<string | undefined>;
+/** 删除一个 session 的 scratchpad 目录(rm -rf,幂等:目录不存在=no-op)。失败吞 warn 不抛——
+ *  清理绝不 fault 调用它的 session-delete 路径;下一轮 {@link sweepStaleScratchpads} 仍会兜到它。 */
 export declare function purgeScratchpadDir(localDataRoot: string, sessionId: string): Promise<void>;
+/** 周期 sweep:扫 `<localDataRoot>/scratchpad/` 下 mtime 早于 `olderThanMs` 且不属于 `activeSessionIds`
+ *  (先经 {@link scratchpadSessionSegment} 映射到目录名域)的目录并删除,返回删除数。逐目录失败跳过
+ *  (下一轮再兜);scratchpad 根不存在=0。mtime 取目录自身(子文件写入会碰父目录 mtime 的语义因平台而异
+ *  ——诚实边界:一个只被读的活跃 session 目录可能被判过期,activeSessionIds 排除面才是活会话的真保险)。 */
 export declare function sweepStaleScratchpads(localDataRoot: string, opts: {
     olderThanMs: number;
     activeSessionIds?: Set<string>;
 }): Promise<number>;
+/** Map the exec-lane posture to the egress fact (the model must know when downloads can't work). */
 export declare function egressForRemoteExec(remoteExec: {
     provider?: string;
     allowInternetAccess?: boolean;