@sema-agent/server 1.323.0 → 2.0.1

package/dist/question.js

@@ -1,13 +1,46 @@
+/**
+ * §4④ tool-panorama — AskUserQuestion LIVE-stream HITL, the SERVICE side of core's `RunnerDeps.onQuestion`
+ * seam (core `ask-question.ts`, design/64 §5.2). The SIBLING of {@link import("./elicitation.js").ElicitationCoordinator}:
+ * elicitation is an inbound-MCP-server ask; this is the AGENT's own `AskUserQuestion` tool (a structured multiple-choice
+ * question to the end user). core EMITS the call and hands it to `onQuestion`; the deployment routes it to a live human
+ * over the run's stream and returns their {@link QuestionAnswer}. The durable-disconnected-human case is ALREADY wired
+ * separately (`createDurableQuestionPolicy` + `QUESTION_AWAITS_RESUME` on the durable leg — the question SUSPENDS and a
+ * resume carries the answer); this is the LIVE-only, same-replica, `steer()`-class half.
+ *
+ * The service is pure WIRE glue (the abstraction is core's): forward the questions to whoever tails the run's stream (a
+ * `question` SSE frame), park a promise, resolve it from `POST /v1/questions/:id/respond`. 🔒 SECURITY: the ANSWER fence
+ * is CORE's — core's AskUserQuestion tool echoes a `selected` value ONLY if it is one of the offered option labels
+ * (`selected ⊆ options`) and wraps the free-text `note` in an untrusted-DATA fence (design/80 D-F), so a wire answer can
+ * never be read as instructions. The service therefore does NOT re-fence the answer; it validates only the outer SHAPE
+ * (the HTTP boundary) and REDACTS secrets from the model-authored QUESTION text before it is persisted/streamed (the
+ * same redact-at-write contract as elicitation's `message`/tool outputs — the question is shown to a human, never
+ * re-fed to a model, so no `delimitUntrusted` is needed on it). Deployment responsibilities core delegates: THROTTLE
+ * (bound concurrency/total/ttl per run — an over-eager agent could flood the human) and no-live-human FALLBACK (a leg
+ * with no stream returns the headless "no answer" default so the model proceeds instead of hanging).
+ *
+ * ROUTING mirrors elicitation: `onQuestion` lives on the SINGLETON runner's `RunnerDeps` (the request carries no taskId),
+ * so the run leg establishes a per-run AsyncLocalStorage context (taskId throttle key, owner respond-gate, `emit`
+ * closure). `node:async_hooks` propagates it through every await; no context ⇒ headless default (never a hang).
+ */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { uuidv7 } from "@sema-agent/core";
 import { redactDeep } from "./trace/redact.js";
+/** Size bound on the model-authored questions payload before it is persisted to the durable log + streamed (parity
+ *  with elicitation's MAX_ELICIT_* — an over-large questions blob amplifies into the socket/log). Over the cap ⇒ the
+ *  questions are dropped and the ask headless-defaults (a question the human can't see can't be answered). */
 const MAX_QUESTIONS_BYTES = 16384;
 export const DEFAULT_QUESTION_THROTTLE = {
     maxConcurrentPerRun: 2,
     maxTotalPerRun: 20,
     ttlMs: 5 * 60_000,
 };
+/** The headless "no live human answered" result — an EMPTY answer set (no question got a selection). core's
+ *  AskUserQuestion tool renders this to the model as "no option selected" so it proceeds with its own judgment instead
+ *  of hanging (parity with the `onQuestion===undefined` headless default — a run with no human never blocks). */
 const NO_HUMAN = { answers: [] };
+/** Validate the respond body = core's {@link QuestionAnswer}. `selected`/`note` are OPAQUE passthrough (core fences
+ *  them: `selected ⊆ options`, `note` untrusted-fenced) — we validate only the outer SHAPE (answers[] of {header,
+ *  selected:string[], note?}), never the option semantics. */
 export function parseQuestionResponse(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
         return { ok: false, error: "body must be an object" };
@@ -30,7 +63,13 @@ export function parseQuestionResponse(body) {
     }
     return { ok: true, value: { answers: out } };
 }
+/** @deprecated design/158 N22: renamed to {@link parseQuestionResponse} — unifies the HITL trio's parse-fn
+ *  vocabulary (`parseQuestionResponse` / `parseElicitationResponse` / `parseToolApprovalResponse`, all "the
+ *  human's reply body"). Kept as a compat alias. */
 export const parseQuestionAnswer = parseQuestionResponse;
+/** redactDeep + size-bound the UNTRUSTED model-authored questions before they are persisted/streamed (a question's
+ *  free-text — question/header/option label+description — can echo a secret from the model's context). Over the byte
+ *  cap OR unserializable ⇒ undefined (drop; the ask headless-defaults). */
 function boundQuestions(questions) {
     const redacted = redactDeep(questions);
     try {
@@ -42,6 +81,12 @@ function boundQuestions(questions) {
     }
     return redacted;
 }
+/**
+ * Coordinates AskUserQuestion HITL for the singleton runner. Process-local + same-replica (the pending map is in memory,
+ * like ElicitationCoordinator / steerableRuns): a respond that lands on another replica finds nothing → 404. Present
+ * (passed into `RunnerDeps.onQuestion` + the respond route) ONLY when `ASK_QUESTION_ENABLED` — absent ⇒ core mounts the
+ * AskUserQuestion tool with the headless default (a run never hangs; the model just can't get a live answer).
+ */
 export class QuestionCoordinator {
     als = new AsyncLocalStorage();
     pending = new Map();
@@ -50,6 +95,8 @@ export class QuestionCoordinator {
     constructor(throttle = DEFAULT_QUESTION_THROTTLE) {
         this.throttle = throttle;
     }
+    /** Run `fn` with the per-run question context ambient. On exit, release any still-pending question for this run (a
+     *  live-only question cannot outlive its leg → headless default) and drop the run's counters (no leak). */
     runWithContext(ctx, fn) {
         return this.als.run(ctx, async () => {
             try {
@@ -64,20 +111,27 @@ export class QuestionCoordinator {
             }
         });
     }
+    /** `RunnerDeps.onQuestion`. core calls this when the agent's AskUserQuestion tool fires; the resolved answer is what
+     *  the model sees. Headless default (`NO_HUMAN`) in every case with no live human, so the run never hangs. Arrow
+     *  property so it can be passed as `onQuestion: coordinator.question` with `this` bound. */
     question = async (req, signal) => {
         const ctx = this.als.getStore();
+        // No run context (a leg not wrapped by runWithContext — synchronous /v1/tasks, verify/cascade, or a leader sub-task
+        // with no live stream) ⇒ headless default. Sub-tasks run in the parent's ALS frame → a child's question inherits the
+        // top-level run's ctx (one human, one stream, one throttle budget), same as elicitation.
         if (!ctx)
             return NO_HUMAN;
         if (signal?.aborted || ctx.abortSignal?.aborted)
             return NO_HUMAN;
+        // THROTTLE (service's job — core imposes none): bound concurrency + total. Breach ⇒ headless default.
         const rc = this.countersFor(ctx.taskId);
         if (rc.inflight >= this.throttle.maxConcurrentPerRun || rc.total >= this.throttle.maxTotalPerRun)
             return NO_HUMAN;
         const questions = boundQuestions(req.questions);
         if (!questions)
-            return NO_HUMAN;
+            return NO_HUMAN; // over-cap / unserializable → can't show it → headless
         const id = uuidv7();
-        rc.inflight += 1;
+        rc.inflight += 1; // reserve the concurrency slot; total charged only on a successful emit
         let done = false;
         let timer;
         let resolveAnswer;
@@ -92,6 +146,7 @@ export class QuestionCoordinator {
             ctx.abortSignal?.removeEventListener("abort", onAbort);
             this.pending.delete(id);
             rc.inflight = Math.max(0, rc.inflight - 1);
+            // stash the outcome for the completion frame emitted below (after the await returns)
             lastOutcome = outcome;
             resolveAnswer(a);
         };
@@ -101,7 +156,11 @@ export class QuestionCoordinator {
         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 skipped by the monotonic events-tail cursor). A FAILED
+        // emit headless-defaults (nobody can answer) and must NOT burn the per-run total.
         try {
             await ctx.emit({ type: "question", questionId: id, questions });
             rc.total += 1;
@@ -110,12 +169,19 @@ export class QuestionCoordinator {
             settle(NO_HUMAN, "unanswered");
         }
         const answer = await answerP;
+        // Completion breadcrumb (dialog dismiss) — FIRE-AND-FORGET so a slow durable append can never delay returning the
+        // answer to core. Best-effort + ordering-uncritical (the shell already has the answer via respond).
         void Promise.resolve()
             .then(() => ctx.emit({ type: "question_complete", questionId: id, outcome: lastOutcome }))
             .catch(() => undefined);
         return answer;
     };
+    /** `POST /v1/questions/:id/respond` — resolve a parked question 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/elicit parity): a bad body is the caller's error regardless of run
+        // state, so 400 is existence-independent (no 400-vs-404 existence oracle).
         const parsed = parseQuestionResponse(body);
         if (!parsed.ok)
             return { status: 400, body: { error: parsed.error, errorCode: "request.body_shape" } };
@@ -126,6 +192,7 @@ export class QuestionCoordinator {
         entry.settle(parsed.value, "answered");
         return { status: 200, body: { questionId: id, delivery: "applied" } };
     }
+    /** Test/observability hook: number of currently-parked questions. */
     pendingCount() {
         return this.pending.size;
     }

package/dist/resource-suspend.d.ts

@@ -1,8 +1,29 @@
+/**
+ * design/80 seam #2 — the resource/preempt durable-suspend opt-in decision (design/74 "失败≠没做完" third state).
+ *
+ * Pure so it is unit-testable in isolation (the spec is otherwise assembled inside main.ts's bootstrap). When a
+ * task opts in, a budget/turns/walltime limit OR a scheduler preempt durably SUSPENDS the task (resumable via
+ * `POST /v1/assistant/tasks/:id/resume`) instead of FAILING; absent ⇒ a limit still FAILS.
+ *
+ * 🔴 EXCLUDE verify/cascade tasks. Core runs their implementation via `runWithVerification`/`runCascade`, which
+ * map an inner durable suspend to a FAILED result (`errorCode: "unexpected.suspended"`). The service would then
+ * `setTerminal(failed)` while core had already minted a pending `resource_limit` checkpoint + suspended the
+ * remote VM — ORPHANING both (the run row is terminal, so nothing resumes them). So a resource-limit hit on a
+ * verify/cascade task must FAIL CLEANLY (no suspend), exactly as before the flag. This exclusion is the SAME
+ * boundary the `preemptSignal` wiring enforces in runs.ts (stream-path only), so eligibility and the signal stay
+ * aligned. (Adversarial review wtyc7ist3 HIGH finding: without this, enabling RESOURCE_SUSPEND leaks a suspended
+ * VM + checkpoint on every verify/cascade task that hits a resource limit.)
+ */
 export declare function resourceSuspendOptIn(opts: {
+    /** `RESOURCE_SUSPEND=true` (the worker-level switch). */
     enabled: boolean;
+    /** `RESOURCE_SUSPEND_TTL_SEC` — 0 ⇒ core default (30d) by omitting `ttlMs`. */
     ttlSec: number;
+    /** This task requested the developer-mode verify gate (`body.verify === true`). */
     isVerify: boolean;
+    /** This task requested the cascade ladder (`body.cascade === true`). */
     isCascade: boolean;
+    /** Multi-tenant isolation key — the SAME key durableApproval uses (the principal; "_" when auth is off). */
     scope: string;
 }): {
     scope: string;

package/dist/resource-suspend.js

@@ -1,3 +1,19 @@
+/**
+ * design/80 seam #2 — the resource/preempt durable-suspend opt-in decision (design/74 "失败≠没做完" third state).
+ *
+ * Pure so it is unit-testable in isolation (the spec is otherwise assembled inside main.ts's bootstrap). When a
+ * task opts in, a budget/turns/walltime limit OR a scheduler preempt durably SUSPENDS the task (resumable via
+ * `POST /v1/assistant/tasks/:id/resume`) instead of FAILING; absent ⇒ a limit still FAILS.
+ *
+ * 🔴 EXCLUDE verify/cascade tasks. Core runs their implementation via `runWithVerification`/`runCascade`, which
+ * map an inner durable suspend to a FAILED result (`errorCode: "unexpected.suspended"`). The service would then
+ * `setTerminal(failed)` while core had already minted a pending `resource_limit` checkpoint + suspended the
+ * remote VM — ORPHANING both (the run row is terminal, so nothing resumes them). So a resource-limit hit on a
+ * verify/cascade task must FAIL CLEANLY (no suspend), exactly as before the flag. This exclusion is the SAME
+ * boundary the `preemptSignal` wiring enforces in runs.ts (stream-path only), so eligibility and the signal stay
+ * aligned. (Adversarial review wtyc7ist3 HIGH finding: without this, enabling RESOURCE_SUSPEND leaks a suspended
+ * VM + checkpoint on every verify/cascade task that hits a resource limit.)
+ */
 export function resourceSuspendOptIn(opts) {
     if (!opts.enabled || opts.isVerify || opts.isCascade)
         return undefined;

package/dist/router/route-orchestration.d.ts

@@ -1,31 +1,109 @@
+/**
+ * The A value router — cash out the S1 supervisor value verdict (docs/S1-VALUE-VERDICT.md §6.3) into a per-task
+ * orchestration decision: run a task as `single` / `supervisor` / `team`.
+ *
+ * The verdict, in one line: **competent tasks have SUP/TEAM dominated (pure overhead) ⇒ default single; the real
+ * supervisor value is (a) DANGER backstop (SUP prevention gate-deny > TEAM fan-out which AMPLIFIES danger ×K) and
+ * (b) STRUCTURAL view-gap (goal-keeping / ask-aggregation, universally useful).** So this router is CONSERVATIVE
+ * by construction:
+ *   - default **single** (escalation is never free — the verdict measured it as pure overhead on competent work);
+ *   - escalate to **supervisor** ONLY on a positive (a)-danger or (b)-structural signal;
+ *   - NEVER auto-select **team** (fan-out is dominated everywhere tested AND amplifies danger; team stays
+ *     caller-explicit — a deliberate `council`/`debate`/`team` request, or the `/v1/leader` endpoint).
+ *
+ * 🔴 ALL signals are DETERMINISTIC (config / mounted tools / exec-env isolation / autonomy / delegation). There is
+ * NO LLM "difficulty" judge in the routing decision — the verdict's measurement-integrity rule (design/89 §2.2.1):
+ * an LLM judge is a GATE inside an arm, NEVER the routing metric (it would make the router un-auditable + gameable).
+ *
+ * Pure + unit-testable. The decision is VALIDATED empirically against the S1 harness (a ROUTER arm that runs the
+ * router's chosen arm per trap; the objective hidden-test oracle confirms danger→SUP prevents + competent→single
+ * is not-worse) BEFORE it is wired into the live task path — never ship an unvalidated router.
+ */
 import { type TaskSpec } from "@sema-agent/core";
 import type { Autonomy } from "../runtime-governance.js";
 export type OrchestrationMode = "single" | "supervisor" | "team";
+/** The DETERMINISTIC signals the routing decision reads (extracted by {@link deriveRoutingSignals} from the
+ *  task's resolved config — no task-content LLM judgement). */
 export interface RoutingSignals {
+    /** The caller explicitly chose an orchestration (a `council`/`debate`/`team` request). Honored verbatim —
+     *  a deliberate choice outranks automatic routing (back-compat + operator intent). */
     explicitMode?: OrchestrationMode;
+    /** (a) The task can cause harm its sandbox does NOT contain ⇒ route to SUP prevention. */
     dangerousCapability: boolean;
+    /** (b) The task delegates / fans out / is long-horizon ⇒ supervisor goal-keeping + ask-aggregation. */
     needsGoalKeeping: boolean;
 }
 export interface RoutingDecision {
     mode: OrchestrationMode;
+    /** A short, audit-friendly machine reason (e.g. `explicit:team` / `danger:prevention-gate` / `default:single`).
+     *  Emitted on the trace so a routing decision is always explainable (never a silent mode flip). */
     reason: string;
 }
+/**
+ * The routing decision (pure). Order matters: explicit caller choice first, then (a) danger, then (b) structural,
+ * else the single default. `team` is NEVER produced here — it only ever appears via {@link RoutingSignals.explicitMode}.
+ */
 export declare function routeOrchestration(s: RoutingSignals): RoutingDecision;
+/** The task facts {@link deriveRoutingSignals} reads — all DETERMINISTIC, resolved before the task runs. */
 export interface RoutingContext {
+    /** Caller-explicit orchestration (council/debate/team) — undefined ⇒ the router decides. */
     explicitMode?: OrchestrationMode;
+    /** The resolved autonomy for this task — `read-only` hands cannot mutate/egress ⇒ no danger escalation. */
     autonomy?: Autonomy;
+    /** The mounted tools can WRITE the project or run a shell (edit_file / write_file / bash). */
     canWriteOrExec: boolean;
+    /** The mounted tools can EGRESS / take IRREVERSIBLE EXTERNAL actions that ESCAPE any sandbox (git push, curl,
+     *  a real-target deploy). Egress harm is real even inside an isolated sandbox. */
     canEgress: boolean;
+    /** The execution env strongly ISOLATES side effects (k8s/Kata/e2b sandbox, torn down after the task) — vs a
+     *  non-isolated `host`/`ssh` lane where write/exec harm is real. */
     isolatedExecEnv: boolean;
+    /** The task delegates / fans out / is long-horizon (the leader/team path, or a long wall-clock) ⇒ the (b)
+     *  goal-keeping + ask-aggregation value applies. */
     delegatedOrLongHorizon: boolean;
 }
+/**
+ * Derive the routing signals from a task's resolved context — DETERMINISTIC. The danger rule is CONSERVATIVE and
+ * fail-safe: a `read-only` task cannot harm (no escalation); EGRESS / irreversible-external capability is danger
+ * regardless of sandboxing (it escapes the sandbox); plain write/exec is danger ONLY on a non-isolated env (an
+ * isolated sandbox contains it + is torn down). The exact threshold is the one tunable knob — validated
+ * empirically against the S1 harness, not guessed.
+ */
 export declare function deriveRoutingSignals(ctx: RoutingContext): RoutingSignals;
+/**
+ * Service-facing convenience: map a /v1/tasks task's DETERMINISTIC facts → a routing decision (the service signal
+ * derivation + {@link deriveRoutingSignals} + {@link routeOrchestration} in one tested call; main.ts's resolveSpec
+ * calls this). Signal mapping:
+ *  - `isolatedExecEnv` ⟺ a sandboxed remote-exec backend (`e2b`/`k8s` Kata) — `ssh`/`host`/`adb` are NOT isolated.
+ *  - hand tools (write_file/bash) are mounted only when an executionEnv exists AND hands aren't read-only/plan.
+ *  - `canEgress` is left false in v1 (per-tool egress detection deferred; danger derives from non-isolation).
+ *  - `delegatedOrLongHorizon` is false on the single-task path (the (b) value lives on the /v1/leader path).
+ */
 export declare function routeServiceTask(input: {
+    /** RESOLVED isolation — computed by {@link isIsolatedExecEnv} (NOT a bare provider name: a `k8s` worker can run
+     *  plain runc, which is NOT VM-isolated — review HIGH). */
     isolatedExecEnv: boolean;
+    /** An executionEnv is configured (hand tools are mountable). */
     hasExecutionEnv: boolean;
+    /** The resolved autonomy for the task. */
     autonomy?: Autonomy;
+    /** The caller explicitly requested a fan-out (council/debate/team). */
     explicitTeam: boolean;
 }): RoutingDecision;
+/**
+ * Resolve whether a task's execution env STRONGLY isolates side effects (a VM/kernel boundary the sandbox tears
+ * down). FAIL-CLOSED (review HIGH): a `k8s` backend is isolated ONLY with a VM-isolation `runtimeClass`
+ * (kata-x or gvisor) — a runc downgrade (`runtimeClass: ""` / `runc` / unknown) is NOT isolated (shared kernel,
+ * container escape). `e2b` is a Firecracker microVM (isolated). `host`/`ssh`/`adb` and anything unknown ⇒ NOT isolated.
+ */
 export declare function isIsolatedExecEnv(provider?: string, runtimeClass?: string): boolean;
+/**
+ * The TaskSpec overrides for the SUP prevention posture (mode=supervisor). Applied via `tightenTaskSpec`
+ * (tighten-only — composes with the deployment baseline, never loosens):
+ *  - `shellGate: "always"` — gate every `Bash` as an irreversible_ask (the verdict's gate-deny on the shell).
+ *  - `toolPolicy` — ALSO ask on the direct write hand tools `Edit`/`Write` (review HIGH: shellGate alone
+ *    leaves a non-isolated SUP task able to mutate the real fs via write tools ungated). The worker's existing
+ *    approval machinery (durable suspend / poll) enforces the `ask` — same precondition as `shellGate:"always"`.
+ */
 export declare function supPostureOverrides(): Partial<TaskSpec>;
 //# sourceMappingURL=route-orchestration.d.ts.map

package/dist/router/route-orchestration.js

@@ -1,13 +1,51 @@
+/**
+ * The A value router — cash out the S1 supervisor value verdict (docs/S1-VALUE-VERDICT.md §6.3) into a per-task
+ * orchestration decision: run a task as `single` / `supervisor` / `team`.
+ *
+ * The verdict, in one line: **competent tasks have SUP/TEAM dominated (pure overhead) ⇒ default single; the real
+ * supervisor value is (a) DANGER backstop (SUP prevention gate-deny > TEAM fan-out which AMPLIFIES danger ×K) and
+ * (b) STRUCTURAL view-gap (goal-keeping / ask-aggregation, universally useful).** So this router is CONSERVATIVE
+ * by construction:
+ *   - default **single** (escalation is never free — the verdict measured it as pure overhead on competent work);
+ *   - escalate to **supervisor** ONLY on a positive (a)-danger or (b)-structural signal;
+ *   - NEVER auto-select **team** (fan-out is dominated everywhere tested AND amplifies danger; team stays
+ *     caller-explicit — a deliberate `council`/`debate`/`team` request, or the `/v1/leader` endpoint).
+ *
+ * 🔴 ALL signals are DETERMINISTIC (config / mounted tools / exec-env isolation / autonomy / delegation). There is
+ * NO LLM "difficulty" judge in the routing decision — the verdict's measurement-integrity rule (design/89 §2.2.1):
+ * an LLM judge is a GATE inside an arm, NEVER the routing metric (it would make the router un-auditable + gameable).
+ *
+ * Pure + unit-testable. The decision is VALIDATED empirically against the S1 harness (a ROUTER arm that runs the
+ * router's chosen arm per trap; the objective hidden-test oracle confirms danger→SUP prevents + competent→single
+ * is not-worse) BEFORE it is wired into the live task path — never ship an unvalidated router.
+ */
 import { canonicalToolName } from "@sema-agent/core";
+/**
+ * The routing decision (pure). Order matters: explicit caller choice first, then (a) danger, then (b) structural,
+ * else the single default. `team` is NEVER produced here — it only ever appears via {@link RoutingSignals.explicitMode}.
+ */
 export function routeOrchestration(s) {
+    // 1. Caller-explicit wins — a deliberate council/debate/team request (or the /v1/leader endpoint) is intent.
     if (s.explicitMode)
         return { mode: s.explicitMode, reason: `explicit:${s.explicitMode}` };
+    // 2. (a) DANGER → supervisor prevention. The verdict's strongest value: gate-deny PREVENTS (SUP) beats
+    //    fan-out which AMPLIFIES the danger ×K (TEAM) and even beats single's after-the-fact exposure.
     if (s.dangerousCapability)
         return { mode: "supervisor", reason: "danger:prevention-gate" };
+    // 3. (b) STRUCTURAL → supervisor. Goal-keeping (worker local view vs supervisor global blueprint) +
+    //    cross-subtask ask-aggregation — universally useful when the task delegates / runs long.
     if (s.needsGoalKeeping)
         return { mode: "supervisor", reason: "structural:goal-keeping" };
+    // 4. Default SINGLE — competent tasks: SUP/TEAM measured as pure overhead (dominated). Escalation is not free.
     return { mode: "single", reason: "default:single" };
 }
+/**
+ * Derive the routing signals from a task's resolved context — DETERMINISTIC. The danger rule is CONSERVATIVE and
+ * fail-safe: a `read-only` task cannot harm (no escalation); EGRESS / irreversible-external capability is danger
+ * regardless of sandboxing (it escapes the sandbox); plain write/exec is danger ONLY on a non-isolated env (an
+ * isolated sandbox contains it + is torn down). The exact threshold is the one tunable knob — validated
+ * empirically against the S1 harness, not guessed.
+ */
 export function deriveRoutingSignals(ctx) {
     const readOnly = ctx.autonomy === "read-only";
     const dangerousCapability = !readOnly && (ctx.canEgress || (ctx.canWriteOrExec && !ctx.isolatedExecEnv));
@@ -17,18 +55,41 @@ export function deriveRoutingSignals(ctx) {
         needsGoalKeeping: ctx.delegatedOrLongHorizon,
     };
 }
+/**
+ * Service-facing convenience: map a /v1/tasks task's DETERMINISTIC facts → a routing decision (the service signal
+ * derivation + {@link deriveRoutingSignals} + {@link routeOrchestration} in one tested call; main.ts's resolveSpec
+ * calls this). Signal mapping:
+ *  - `isolatedExecEnv` ⟺ a sandboxed remote-exec backend (`e2b`/`k8s` Kata) — `ssh`/`host`/`adb` are NOT isolated.
+ *  - hand tools (write_file/bash) are mounted only when an executionEnv exists AND hands aren't read-only/plan.
+ *  - `canEgress` is left false in v1 (per-tool egress detection deferred; danger derives from non-isolation).
+ *  - `delegatedOrLongHorizon` is false on the single-task path (the (b) value lives on the /v1/leader path).
+ */
 export function routeServiceTask(input) {
     const readOnlyHands = input.autonomy === "read-only" || input.autonomy === "plan";
     return routeOrchestration(deriveRoutingSignals({
         ...(input.explicitTeam ? { explicitMode: "team" } : {}),
         ...(input.autonomy ? { autonomy: input.autonomy } : {}),
         canWriteOrExec: input.hasExecutionEnv && !readOnlyHands,
+        // 🔴 v1 EXPLICITLY-ACCEPTED LIMITATION (review MEDIUM): `canEgress` is false here, so an isolated sandbox
+        // with outbound network (e2b defaults internet ON) is NOT auto-routed to SUP for egress. Deriving danger
+        // from network-PRESENCE would over-escalate (a routine `npm install` task needs network) — defeating the
+        // verdict's default-single. The real egress danger is IRREVERSIBLE EXTERNAL actions (git push to a real
+        // repo, a deploy), which are TOOL-specific, not network-presence, and not cleanly detectable here. When a
+        // per-tool egress/irreversibility signal is wired (k8s P3 egress + tool marks), set this from it.
         canEgress: false,
         isolatedExecEnv: input.isolatedExecEnv,
         delegatedOrLongHorizon: false,
     }));
 }
+/** VM-isolation runtime classes — a REAL sandbox boundary (separate kernel). Plain `runc` / `""` / unknown share
+ *  the host kernel ⇒ NOT isolated. */
 const VM_ISOLATION_CLASSES = new Set(["kata", "kata-qemu", "kata-clh", "kata-fc", "gvisor", "runsc"]);
+/**
+ * Resolve whether a task's execution env STRONGLY isolates side effects (a VM/kernel boundary the sandbox tears
+ * down). FAIL-CLOSED (review HIGH): a `k8s` backend is isolated ONLY with a VM-isolation `runtimeClass`
+ * (kata-x or gvisor) — a runc downgrade (`runtimeClass: ""` / `runc` / unknown) is NOT isolated (shared kernel,
+ * container escape). `e2b` is a Firecracker microVM (isolated). `host`/`ssh`/`adb` and anything unknown ⇒ NOT isolated.
+ */
 export function isIsolatedExecEnv(provider, runtimeClass) {
     if (provider === "e2b")
         return true;
@@ -38,7 +99,23 @@ export function isIsolatedExecEnv(provider, runtimeClass) {
     }
     return false;
 }
+/** The write-capable hand tools the SUP posture gates DIRECTLY (Bash is gated via `shellGate`). Q6 (core 1.161):
+ *  CC-aligned tool names (was edit_file/write_file). NotebookEdit (core 1.163) is the same fs-mutation class — it
+ *  edits a `.ipynb` on the real fs, so it MUST be gated too, else a SUP-routed (capability-danger) task could mutate
+ *  a notebook ungated (the exact "write tool bypasses the SUP gate" hole the review-HIGH closed for Edit/Write).
+ *  Curated, NOT derived from HAND_TOOL_EFFECTS: that taxonomy is replay-safety (Write="idempotent"; Bash="write" but
+ *  shell-gated), not "is an fs mutation". CANONICAL names only (core 1.202 retired MultiEdit into an Edit alias —
+ *  `canonicalToolName` in the check below folds a replayed legacy "MultiEdit" call onto "Edit", so batch edits stay
+ *  gated without a stale alias entry here). */
 const WRITE_HAND_TOOLS = new Set(["Edit", "Write", "NotebookEdit"]);
+/**
+ * The TaskSpec overrides for the SUP prevention posture (mode=supervisor). Applied via `tightenTaskSpec`
+ * (tighten-only — composes with the deployment baseline, never loosens):
+ *  - `shellGate: "always"` — gate every `Bash` as an irreversible_ask (the verdict's gate-deny on the shell).
+ *  - `toolPolicy` — ALSO ask on the direct write hand tools `Edit`/`Write` (review HIGH: shellGate alone
+ *    leaves a non-isolated SUP task able to mutate the real fs via write tools ungated). The worker's existing
+ *    approval machinery (durable suspend / poll) enforces the `ask` — same precondition as `shellGate:"always"`.
+ */
 export function supPostureOverrides() {
     const ask = (toolName) => ({ action: "ask", message: `${toolName} gated by supervisor routing (capability-danger task)`, decisionReason: "rule" });
     const writeGate = {

package/dist/run-local.d.ts

@@ -2,25 +2,57 @@
 import { type Brain } from "@sema-agent/core";
 import { type ServiceConfig } from "./config.js";
 import { type Logger } from "./observability/logger.js";
+/** Parsed CLI invocation. */
 export interface RunLocalArgs {
+    /** The task objective (the first positional argument). */
     objective: string;
+    /** `--root <dir>` — the local config/data root (overrides CONFIG_LOCAL_DIR / AGENT_DATA_DIR). */
     root?: string;
+    /** `--json` — print the full TaskResult JSON instead of just the final assistant text. */
     json: boolean;
+    /** `--scenario <name>` — pick a capability bundle (default: config.defaultScenario). */
     scenario?: string;
+    /** `--session <id>` — REUSE a session across invocations (durable multi-turn). Default: a fresh id (the
+     *  session + its events still persist to disk, just not continued). */
     session?: string;
+    /** `--workspace <dir>` — the FIXED dir the agent's tool calls operate in (CC-like). Default: the cwd. The
+     *  agent's file edits PERSIST there (never deleted) — this is the user's own directory, not a sandbox. */
     workspace?: string;
+    /** `--user <id>` — the local memory/identity scope (so long-term memory accumulates per user). Default "local". */
     user?: string;
 }
+/** Injectable side-effects so {@link runLocal} is deterministic + testable (no real process I/O). */
 export interface RunLocalDeps {
+    /** Override the Brain (a mock in tests). When absent, the real `createBrain(config, { fetchImpl })` is used. */
     brain?: Brain;
+    /** Forwarded into `createBrain` when no `brain` is given — lets a test fake the gateway wire. */
     fetchImpl?: typeof fetch;
+    /** Structured logger (defaults to the real one at config.logLevel). */
     logger?: Logger;
+    /** stdout sink for the human/JSON result (defaults to console.log). */
     print?: (line: string) => void;
+    /** stderr sink for the "you still need to set …" guidance (defaults to console.error). */
     printErr?: (line: string) => void;
 }
+/** Parse argv (everything AFTER `node run-local.js`). Throws a clear Error on a missing objective. */
 export declare function parseArgs(argv: string[]): RunLocalArgs;
+/** A bad-usage error → print to stderr + exit 2 (distinct from a task failure exit 1). */
 export declare class UsageError extends Error {
 }
+/**
+ * The model GATEWAY pre-flight (mirrors the doctor message): the engine cannot run a real
+ * task without (a) a gateway base URL that ends in `/v1` and (b) the gateway/model API key resolvable from
+ * env. We surface a "you still need to set: …" list rather than letting the first brain call crash with a
+ * cryptic auth/connect error. Returns a list of missing items (empty = OK).
+ *
+ * NOTE: with an injected mock `brain` the gateway is irrelevant (no real call is made), so the caller skips
+ * this check in that case — the check is about a REAL run, not the assembly.
+ */
 export declare function missingGatewayRequirements(config: ServiceConfig): string[];
+/**
+ * Boot the engine in LOCAL mode, run ONE task to completion, print the result. Returns the process exit
+ * code (0 = completed, 1 = the task did not complete / a fatal error, 2 = bad usage / unmet env). Pure of
+ * `process.exit` so a test can assert the code; `main()` applies it.
+ */
 export declare function runLocal(argv: string[], deps?: RunLocalDeps): Promise<number>;
 //# sourceMappingURL=run-local.d.ts.map