@sema-agent/server 1.323.0 → 2.0.0

package/dist/http/sse-log.d.ts

@@ -1,23 +1,38 @@
+/**
+ * design/158 A9 seam —— 通用可恢复 SSE 泵(P2.8),从 `http/server.ts` 整段搬出的原文。
+ *
+ * task_run 与 image_bake 两条日志共用同一套 liveness/heartbeat/416/终态复取/15 分钟帽逻辑;域模块
+ * (routes/images.ts)与 server.ts 都要用它,所以它必须住在 http/ 叶子里(routes/* 值 import server.ts
+ * 会闭合运行时装载环)。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 export interface SseLogProvider<E extends {
     seq: number;
 }> {
+    /** The coarse terminality status + the freshness clock (`updatedAt`). Undefined/null ⇒ unknown id (the
+     *  caller already 404'd existence before opening the stream, so this is the in-flight terminal poll). */
     statusOf(id: string): Promise<{
         status: string;
         updatedAt: string;
     } | null | undefined>;
+    /** Events with seq strictly greater than `after`, ascending. */
     getEvents(id: string, after: number): Promise<E[]>;
+    /** Earliest retained seq → the 416 resume boundary. */
     retainedFrom(id: string): Promise<number>;
+    /** Map ONE event to its SSE frame (the `id:`/`event:`/`data:` lines differ per log). */
     formatEvent(ev: E): {
         id: number;
         event: string;
         data: unknown;
     };
+    /** The synthetic frame written when the log is stale (no events + `updatedAt` older than `staleMs`). */
     staleFrame(): {
         event: string;
         data: unknown;
     };
 }
+/** The shared resumable SSE pump (P2.8) — provider supplies the log-specific differences; the liveness/
+ *  heartbeat/416/terminal-re-fetch/15-min-cap logic is identical for task_run + image_bake. */
 export declare function streamSseLog<E extends {
     seq: number;
 }>(req: IncomingMessage, res: ServerResponse, provider: SseLogProvider<E>, id: string, staleMs: number): Promise<void>;

package/dist/http/sse-log.js

@@ -1,8 +1,12 @@
 import { sendJson, sendError, sseHeaders } from "./send.js";
+/** The shared resumable SSE pump (P2.8) — provider supplies the log-specific differences; the liveness/
+ *  heartbeat/416/terminal-re-fetch/15-min-cap logic is identical for task_run + image_bake. */
 export async function streamSseLog(req, res, provider, id, staleMs) {
     const lastId = Number(req.headers["last-event-id"] ?? new URL(req.url ?? "", "http://x").searchParams.get("from") ?? 0);
     let from = Number.isFinite(lastId) ? lastId : 0;
     if (from > 0) {
+        // Resume point evicted past retention → 416 so the client re-syncs, instead of a silent incomplete stream
+        // (parity with streamTaskTrace; council). Inert until retention evicts (retainedFrom stays 1 with no TTL).
         const retainedFrom = await provider.retainedFrom(id);
         if (retainedFrom > from + 1) {
             sendError(res, 416, "limit.retention_evicted", "resume point evicted past retention", { retainedFrom });
@@ -25,11 +29,20 @@ export async function streamSseLog(req, res, provider, id, staleMs) {
         }
     };
     while (!closed) {
+        // Independent reads — issue concurrently to shave the SSE poll latency. The terminal-event gap is
+        // still covered by the extra getEvents below (a `done` landing between these two is re-fetched).
         const [events, row] = await Promise.all([provider.getEvents(id, from), provider.statusOf(id)]);
         write(events);
         if (!row)
             break;
         if (row.status !== "running") {
+            // Terminal. The `done`/`failed` event is appended BEFORE the coarse status flips terminal (runs.ts +
+            // the bake terminal-write), so it can land in the gap between the getEvents and statusOf above — fetch
+            // ONCE MORE so the stream never ends before delivering the terminal event. (The ONE exception is E12's
+            // post-completion `suggestions` event, appended AFTER setTerminal once the fire-and-forget pass settles —
+            // it is intentionally NOT delivered on this live tail; a poller reads it from GET /v1/runs/:id, which is the
+            // `await result() THEN await suggestions()` contract. Releasing the session lock at `done` beats blocking it
+            // on the suggestion LLM pass just to stream a UI nicety.)
             write(await provider.getEvents(id, from));
             break;
         }
@@ -40,10 +53,13 @@ export async function streamSseLog(req, res, provider, id, staleMs) {
             break;
         }
         if (Date.now() - start > MAX_MS) {
+            // BL-16: cap reached but the run continues — emit a terminal reconnect signal (not a silent close, which
+            // a client couldn't distinguish from a completed run). Distinct from the `failed`/`done` run events.
             res.write(`event: error\ndata: ${JSON.stringify({ type: "error", code: "STREAM_MAX_DURATION", message: "stream reached its 15-minute cap — reconnect with Last-Event-ID to continue (the run is still active)" })}\n\n`);
             break;
         }
         if (events.length === 0) {
+            // Heartbeat during a long idle tail (e.g. a debate phase) so the relay's idle timeout doesn't fire.
             if (Date.now() - lastBeat > 15_000) {
                 res.write(`event: heartbeat\ndata: {}\n\n`);
                 lastBeat = Date.now();

package/dist/http/tar.d.ts

@@ -1,8 +1,17 @@
+/**
+ * 极小 ustar 写器(workspace 浏览面 #3 的 archive 端点用,[1882]/[1894])。零依赖(仓内 no-SDK 姿势,
+ * 同 s3-presign/OTLP 先例)。只写 regular file 条目:512B ustar 头(prefix 155/name 100 拆分)+
+ * 内容 512 对齐 + 两块零尾。**不做** PAX/GNU 长名扩展——快照 relPath 超过 prefix+name 可承载
+ * (>255 或不可在 "/" 处拆)属病态路径,调用方按 fail-loud 处理(archive 面 422 点名)。
+ */
+/** 把 relPath 拆成 ustar 的 (prefix ≤155, name ≤100);不可拆 ⇒ null(调用方 fail-loud)。 */
 export declare function splitTarPath(relPath: string): {
     prefix: string;
     name: string;
 } | null;
 export declare function tarHeader(relPath: string, sizeBytes: number, mtimeSec: number): Buffer;
+/** 内容块的 512 对齐尾垫(0 长内容=0 垫)。 */
 export declare function tarPadding(sizeBytes: number): Buffer;
+/** 归档终止:两块 512 零。 */
 export declare const TAR_END: Buffer<ArrayBuffer>;
 //# sourceMappingURL=tar.d.ts.map

package/dist/http/tar.js

@@ -1,14 +1,23 @@
+/**
+ * 极小 ustar 写器(workspace 浏览面 #3 的 archive 端点用,[1882]/[1894])。零依赖(仓内 no-SDK 姿势,
+ * 同 s3-presign/OTLP 先例)。只写 regular file 条目:512B ustar 头(prefix 155/name 100 拆分)+
+ * 内容 512 对齐 + 两块零尾。**不做** PAX/GNU 长名扩展——快照 relPath 超过 prefix+name 可承载
+ * (>255 或不可在 "/" 处拆)属病态路径,调用方按 fail-loud 处理(archive 面 422 点名)。
+ */
 const BLOCK = 512;
+/** 八进制右对齐 NUL 结尾字段(ustar 数字字段形)。 */
 function octal(n, width) {
     const s = n.toString(8).padStart(width - 1, "0");
     return Buffer.from(s + "\0", "ascii");
 }
+/** 把 relPath 拆成 ustar 的 (prefix ≤155, name ≤100);不可拆 ⇒ null(调用方 fail-loud)。 */
 export function splitTarPath(relPath) {
     const bytes = Buffer.byteLength(relPath, "utf8");
     if (bytes <= 100)
         return { prefix: "", name: relPath };
     if (bytes > 255)
         return null;
+    // 从右往左找一个 "/",使 name ≤100 且 prefix ≤155(按字节算——多字节字符路径保守处理)。
     for (let i = relPath.length - 1; i > 0; i--) {
         if (relPath[i] !== "/")
             continue;
@@ -19,6 +28,11 @@ export function splitTarPath(relPath) {
     }
     return null;
 }
+/** 一个 regular-file 条目的 512B ustar 头。`mtimeSec` 由调用方给(快照无 per-file mtime ⇒ 统一用
+ *  快照时刻/0——确定性输出,同輸入同字节)。 */
+/** ustar 的 size 字段是 12 字节八进制(11 位数字 + NUL)⇒ 上限 8 GiB−1。超了写进去会溢出到相邻
+ *  字段/丢末位并**静默**产出坏头(复审 F8/A-LOW 实测:2^36 解析回来是值/8)。fail-loud,与
+ *  splitTarPath 的病态路径同姿势。当前配置下不可达(快照总字节帽 256MiB),属防御纵深。 */
 const USTAR_MAX_SIZE = 8 * 1024 * 1024 * 1024 - 1;
 export function tarHeader(relPath, sizeBytes, mtimeSec) {
     if (!Number.isFinite(sizeBytes) || sizeBytes < 0 || sizeBytes > USTAR_MAX_SIZE) {
@@ -29,13 +43,13 @@ export function tarHeader(relPath, sizeBytes, mtimeSec) {
         throw new Error(`tar: path not representable in ustar (must be ≤255 bytes and splittable at "/"): ${relPath}`);
     const h = Buffer.alloc(BLOCK, 0);
     h.write(split.name, 0, 100, "utf8");
-    octal(0o644, 8).copy(h, 100);
-    octal(0, 8).copy(h, 108);
-    octal(0, 8).copy(h, 116);
+    octal(0o644, 8).copy(h, 100); // mode
+    octal(0, 8).copy(h, 108); // uid
+    octal(0, 8).copy(h, 116); // gid
     octal(sizeBytes, 12).copy(h, 124);
     octal(Math.max(0, Math.floor(mtimeSec)), 12).copy(h, 136);
-    h.fill(0x20, 148, 156);
-    h.write("0", 156, 1, "ascii");
+    h.fill(0x20, 148, 156); // chksum = spaces while summing
+    h.write("0", 156, 1, "ascii"); // typeflag: regular file
     h.write("ustar\0", 257, 6, "ascii");
     h.write("00", 263, 2, "ascii");
     h.write(split.prefix, 345, 155, "utf8");
@@ -45,9 +59,11 @@ export function tarHeader(relPath, sizeBytes, mtimeSec) {
     Buffer.from(sum.toString(8).padStart(6, "0") + "\0 ", "ascii").copy(h, 148);
     return h;
 }
+/** 内容块的 512 对齐尾垫(0 长内容=0 垫)。 */
 export function tarPadding(sizeBytes) {
     const rem = sizeBytes % BLOCK;
     return Buffer.alloc(rem === 0 ? 0 : BLOCK - rem, 0);
 }
+/** 归档终止:两块 512 零。 */
 export const TAR_END = Buffer.alloc(BLOCK * 2, 0);
 //# sourceMappingURL=tar.js.map

package/dist/http/wire-gate.d.ts

@@ -1,3 +1,12 @@
+/**
+ * D-0 (design/80 §1): the single source of truth for the `CheckpointGate.kind` values the service emits on the
+ * wire. The suspend path surfaces the gate VERBATIM (`append("suspended", { gate })`, server.ts), and the
+ * agent-client SDK renders these as typed arms (an unknown kind falls through the SDK's open `(string & {})`
+ * arm and renders generically). This explicit mirror exists so the compile-time guards below + the contract
+ * test (`test/wire-gate-contract.test.ts`) keep the wire/SDK in lockstep with core — the guarantee the SDK's
+ * own `spec.test.ts` cannot give (it hardcodes the kinds without importing core, so it would stay GREEN the
+ * moment core adds a 6th kind; design/80 §3 #10 was therefore unenforced until this).
+ */
 export declare const WIRE_GATE_KINDS: readonly ["human", "irreversible_ask", "resource_limit", "needs_review", "task_done", "plan_review"];
 export type WireGateKind = (typeof WIRE_GATE_KINDS)[number];
 //# sourceMappingURL=wire-gate.d.ts.map

package/dist/http/wire-gate.js

@@ -1,3 +1,12 @@
+/**
+ * D-0 (design/80 §1): the single source of truth for the `CheckpointGate.kind` values the service emits on the
+ * wire. The suspend path surfaces the gate VERBATIM (`append("suspended", { gate })`, server.ts), and the
+ * agent-client SDK renders these as typed arms (an unknown kind falls through the SDK's open `(string & {})`
+ * arm and renders generically). This explicit mirror exists so the compile-time guards below + the contract
+ * test (`test/wire-gate-contract.test.ts`) keep the wire/SDK in lockstep with core — the guarantee the SDK's
+ * own `spec.test.ts` cannot give (it hardcodes the kinds without importing core, so it would stay GREEN the
+ * moment core adds a 6th kind; design/80 §3 #10 was therefore unenforced until this).
+ */
 export const WIRE_GATE_KINDS = ["human", "irreversible_ask", "resource_limit", "needs_review", "task_done", "plan_review"];
 const _wireCoversCore = true;
 const _noStaleWireKind = true;

package/dist/http/wire-types.d.ts

@@ -1,3 +1,11 @@
+/**
+ * HTTP wire REQUEST types (design/158 A4) — pure type shapes of the task-submit surface, moved VERBATIM out of
+ * http/server.ts so a caller that needs only the request SHAPE (security.ts's authorizer signature; embedders via
+ * index.ts) depends on a type-only LEAF instead of the whole 10k-line route module. server.ts re-exports
+ * {@link TaskRequestBody}, so every existing import site keeps working unchanged. Conservative scope for the first
+ * cut: ONLY TaskRequestBody (its field types are inline or core imports — no other server.ts-local satellites);
+ * sibling request/response shapes can migrate here later on the same pattern.
+ */
 import type { AgentDefinition, McpServerSpec } from "@sema-agent/core";
 export interface TaskRequestBody {
     objective: string;
@@ -8,50 +16,152 @@ export interface TaskRequestBody {
     } | {
         url: string;
     }>;
+    /** D-1 通用文件上传:预上传附件的句柄数组(POST /v1/attachments 的 `id`)。提交时绑定到会话并在
+     *  执行环境工作目录 `attachments/` 下物化;objective 尾部追加告知(名字/mime/尺寸,内容不进流)。
+     *  上限 16/task;未知或他人 id → 400(fresh 腿)。⚠️ 名为 `attachmentIds` 而非 `attachments`——
+     *  后者已被系统提醒配置键占用(本接口 :464,core spec.attachments 镜像)。 */
     attachmentIds?: string[];
+    /** design/112 C1 (core 1.181): the CLIENT/gateway's view of the user — used by core to localize the env block's
+     *  date to the user's zone + surface who the agent acts for. The shell/gateway fills it from a verified user
+     *  identity (NOT the model). core validates timeZone (invalid → UTC, never mislabeled). Pass-through to
+     *  `spec.clientContext`; `locale` was removed in core 1.186 (dead field) so only timeZone+userEmail are accepted. */
     clientContext?: {
         timeZone?: string;
         userEmail?: string;
     };
+    /** Business/UX system prompt the CLIENT injects (decoupling seam): appended after the scenario's
+     *  stable base (before <user_memory>), so an integrator (e.g. OA) owns its own persona / UI markers /
+     *  workflow rules and evolves them WITHOUT a service change. Trusted: only a caller holding
+     *  SERVICE_AUTH_TOKEN reaches here (same boundary as `businessContext`). Keep it STABLE per
+     *  integrator-version (it's part of the cacheable prefix); put per-request context in `objective`. */
     systemPrompt?: string;
+    /** Append-only system prompt rider ([1476] R1 / [1478] R2 ruling): passes through to core's
+     *  `TaskSpec.appendSystemPrompt` (≈ CC `--append-system-prompt`) — a STABLE block composed after the scenario
+     *  base + `systemPrompt`, before the volatile tail (prefix-cache friendly). First-class lane for the shell's
+     *  product-knowledge block, so `settings.outputStyle` stays a real output style (a future center-issued style
+     *  block composes AFTER this field — byte-stable order, pinned by test). Same trust boundary + cap as
+     *  `systemPrompt` (token-holder only, MAX_SYSTEM_PROMPT_CHARS) — but NOT the same prompt position (codex F1,
+     *  honesty note): this lands in `core/role.append`, AFTER core's locked safety blocks, exactly where
+     *  `settings.outputStyle` has landed since 1.26 — the same principal class held this slot before this field
+     *  existed, so no new grant; whether caller riders should compose BEFORE the safety tail is core's slot-order
+     *  question (raised on the board). Rejected fail-loud when `systemPrompt` is an already-assembled prompt
+     *  (anchors detected) — that assembler arm cannot mount the rider (silent drop would belie the capability bit). */
     appendSystemPrompt?: string;
+    /** Explicit model selection (CLI `/model` picker + `run --model <ref>`). An INTENT by catalog
+     *  name (e.g. "deepseek-pro") — resolveSpec gates it against the SAME allow-list as an inline `@name` mention
+     *  (config.models keys), so it picks WHICH configured model but can never inject one. Wins over an inline
+     *  @mention; an unknown name falls through to mention/default (lenient). Never a baseUrl/apiKey. */
     model?: string;
+    /** [1479]① Cheap-model gear for within-task compaction/summarize (core design/145 `TaskSpec.compactionModel`):
+     *  a catalog INTENT like `model` (name/tier word/id), gated against the SAME expanded allow-list — picks WHICH
+     *  configured model compacts, never injects one. core clamps window-unsafe picks back to the main model with
+     *  `modelFallback` attribution on the `compacted` event. Absent ⇒ the `summarize` role / main model (status quo).
+     *  Unknown fresh-submit value → 400 (body.model posture); a RESUME replay whose ref left the catalog is dropped
+     *  + warned in resolveSpec (core's resolveModel would otherwise throw and brick the resume). */
     compactionModel?: string;
+    /** Per-task budget the caller requests (1.37). Capped server-side to the operator ceiling
+     *  (MAX_TASK_COST_USD / MAX_TASK_TOKENS) — a caller may ask for less, never more. */
     maxCostUsd?: number;
     maxTokens?: number;
+    /** Developer mode (1.44): run the task behind the adversarial verification gate (impl → independent
+     *  read-only verify → fix loop). Default off. `verifyRounds` is clamped to [1,5] (default 2). Not
+     *  supported on /v1/tasks/stream (the gate is multi-round, not a single stream). */
     verify?: boolean;
     verifyRounds?: number;
+    /** Quality-gate cascade (1.45): run cheapest→strongest (config `MODEL_CASCADE_LADDER`), escalating when
+     *  a rung fails the gate (default = it didn't complete). Default off; mutually exclusive with `verify`;
+     *  not on /v1/tasks/stream. ⚠️ each rung is a cold re-run — use for read-only / idempotent tasks. */
     cascade?: boolean;
+    /** Work-view correlation id (optional): groups the runs of one logical task across both client doors
+     *  (MCP façade / portal) so a fragmented set of runs reads as one task. Opaque to the engine — only
+     *  persisted on the run row + filterable via `GET /v1/tasks?jobId=`. ≤64 chars (matches the column). */
     jobId?: string;
+    /** Personalization seam: the caller's OWN skills for this task, threaded into core's
+     *  `TaskSpec.skills`. Merged AFTER the scenario's skills with SCENARIO-WINS on a name clash (the security
+     *  baseline can never be shadowed by user content — see mergeUserSkills). Caps: ≤10 skills, content ≤32KB
+     *  each. User skills are user-authored content in the user's OWN principal-isolated task (self-harm
+     *  surface, not privilege escalation); scenario/center skills remain the only trusted layer. */
     skills?: Array<{
         name: string;
         description: string;
         content: string;
     }>;
+    /** §7 P0.5 (用户按需选像): the sandbox image PROFILE this task wants (e.g.
+     *  "code-full" / "code-python"). An INTENT, never a digest — the service resolves it to a published digest with
+     *  the caller's principal (fail-closed visibility re-admit) and applies it per-pod. Only supported on the k8s
+     *  backend; absent ⇒ the worker-global default image. `capabilitiesNeeded` optionally requires the resolved
+     *  image to provide boolean capabilities (browser/db/nestedBuild) or the request is rejected. */
     sandboxImageProfile?: string;
     capabilitiesNeeded?: string[];
+    /** Structured-output constraint (CC `--json-schema`): a JSON Schema the model's FINAL answer
+     *  must match — threaded into core's `TaskSpec.outputSchema`, which injects a built-in `submit_output` tool and
+     *  surfaces the validated object as `TaskResult.structuredOutput` (an invalid submit retries, then fails with
+     *  `output.invalid`). A plain JSON-schema OBJECT (shape + size validated here; deep validity is core's). */
     outputSchema?: Record<string, unknown>;
+    /** Reasoning-effort selection (CC `/effort` picker, shell-host contract E7): a neutral effort tier mapped to
+     *  core's `TaskSpec.thinking` (`ThinkingLevel`). Accepted set = core's tiers (off/minimal/low/medium/high/xhigh/max);
+     *  the picker's advertised default set is `/v1/models` `supportedEffortLevels`. A provided-but-unknown value is a
+     *  400 (fail-loud, never silently dropped — the body.model silent-drop bug class). Absent ⇒ core uses the resolved
+     *  role's default thinking. NEVER `budgetTokens`/`fast_mode` (provider-neutral by omission). */
     reasoningEffort?: string;
+    /** Resume-at (shell-host contract E18): the E2 message `eventId` to rewind the conversation to — core branches the
+     *  session at that prior message before running the new objective ("rewind to this message, ask differently").
+     *  The service resolves eventId→the persisted SessionTreeEntry.id (the anchor map) in resolveSpec; an unknown
+     *  eventId is a 4xx (never silently dropped). Requires a session. Absent ⇒ continue from the current leaf. */
     resumeAt?: string;
+    /** [833] rewind exclusive mode (core 1.292 `TaskSpec.resumeAtMode`): qualifies the `resumeAt` target. `"at"`
+     *  (default when absent — zero regression) keeps the target message in the branched context; `"before"` branches at
+     *  the target's PARENT, EXCLUDING the target itself (the exclusive-rewind shape: "remove this prompt and everything
+     *  after it"). core enforces the "before" edges and the service passes its rejection codes through UNCHANGED for the
+     *  shell to render: `resume_at.before_target_not_user` (only plain user-message targets),
+     *  `resume_at.before_root_unsupported` (can't rewind past the session root — start a new session),
+     *  `rewind_snapshot.unresolvable` (rewindFiles: no snapshot at/above the "before" branch point). Only meaningful
+     *  WITH `resumeAt` — sent alone it's a 400 (fail-loud, not a silent no-op). */
     resumeAtMode?: string;
+    /** design/114 Phase3 (reuse-path warm-resume): require the `sessionId` to ALREADY exist. When `true` and the session
+     *  is genuinely missing (expired / purged / never created), the run FAILS LOUD (`resume.session_not_found`) instead
+     *  of silently starting a fresh empty session ("looks warm, actually fresh"). Absent/`false` ⇒ the historical
+     *  create-on-miss. Fails loud with NO sessionId too (nothing to resume). Rides the persisted body onto resume legs. */
     requireExistingSession?: boolean;
+    /** Prompt suggestions (shell-host contract E12): opt-in — after the task COMPLETES, core runs ONE extra LLM pass to
+     *  propose follow-up prompts the user might send. `true` = default (count 3, cheap role); an object tunes count/role.
+     *  OFF/absent ⇒ zero extra LLM. The strings are UNTRUSTED model text for the shell UI ONLY (never re-fed to a model);
+     *  the service persists them (redacted) as a `suggestions` event on the run's events tail. */
     suggestNextPrompts?: boolean | {
         count?: number;
         role?: string;
     };
+    /** Rewind-files (shell-host contract E19): opt-in — snapshot the working tree each completed turn + RESTORE it when a
+     *  `resumeAt` branch is taken ("rewind to this message" also rewinds the files). Requires a FileSnapshotStore; works for
+     *  ANY execution env since core's gate-split (1.134.0). OFF/absent ⇒ no snapshot/restore work. */
     rewindFiles?: boolean;
+    /** R8 code-only rewind (CC "Restore code" mode, core 1.166 `rewindFilesTo`): restore the working tree to the snapshot
+     *  at a prior USER message WITHOUT forking the conversation (the session leaf is untouched — only the files move). The
+     *  value is the same handle as `resumeAt` (the prompt's taskId); the service resolves it → the entry id. Honored ONLY
+     *  when `resumeAt` is ABSENT (the two modes are mutually exclusive). Requires the anchor map + a FileSnapshotStore. */
     rewindFilesTo?: string;
+    /** design/131 (core 1.246): per-task resilience INTENT flags. allowDegrade/allowFailover are caller-facing;
+     *  bypassBreaker is operator-only (resolveSpec drops it for non-operators — a permission downgrade, not a 400). */
     resilience?: {
         allowDegrade?: boolean;
         allowFailover?: boolean;
         bypassBreaker?: boolean;
     };
+    /** design/132 (core 1.249): one-shot end-game verification nudge — opt-in by the AUTONOMY caller. */
     finalVerification?: boolean;
+    /** [854]④ per-request 配速(core spec.limits 全链:timeoutSec 墙钟 + deadlineNudge/callCapByDeadline/
+     *  gracefulFinalize;maxOutputTokens = 每次模型调用的输出上限;maxTurns = 上游 parity 的回合上限)。
+     *  三键均为正整数(0 拒绝:core 侧 timeoutSec>0 才生效,放行 0 会绕过运营方封顶)。与 `maxTokens`
+     *  (per-task 总 token 预算,cappedCeiling 车道)不同物 —— maxOutputTokens 是单次调用配速。
+     *  每键各自被可选 env 上限封顶(TASK_TIMEOUT_MAX_SEC / TASK_MAX_OUTPUT_TOKENS_MAX / TASK_MAX_TURNS_MAX,
+     *  缺省不设=不封顶);timeoutSec 缺席时保持既有 tenancy 墙钟姿势(resolveTaskLimits,spec-fields.ts)。 */
     limits?: {
         timeoutSec?: number;
         maxOutputTokens?: number;
         maxTurns?: number;
     };
+    /** design/133 (core 1.251) + G1 (core 1.253): turn-boundary attachment reminders (todo / changed-files /
+     *  plan-mode) + one-shot boundary notices (post-compaction background-task recap / deferred-tools delta). */
     attachments?: {
         todoReminder?: boolean;
         changedFiles?: boolean | {
@@ -61,30 +171,107 @@ export interface TaskRequestBody {
         backgroundTasks?: boolean;
         toolsDelta?: boolean;
     };
+    /** C1 (core 1.219, subagent viewing pane): opt-in — forward a delegated child's live CONTENT events
+     *  (text_delta/reasoning_delta/tool_start/tool_end, each stamped `parentToolCallId`) onto this run's stream/durable
+     *  log, so a shell can render the child's transcript live ("enter 看详情"). Default OFF = progress-only (prior
+     *  behavior). Purely a render channel — core never merges the child stream into the parent's model context. */
     forwardSubagentEvents?: boolean;
+    /** G3([816] 壳侧承诺③/[820]③):壳供 per-session scratchpad 路径(壳 vendored getScratchpadDir 的
+     *  约定路径)。接受后优先于 server 自算,同源喂 envFacts.scratchpadDir 事实 + fs-write gate exemptDirs +
+     *  additionalDirectories 根围栏——壳提示词与 server 写门指同一个目录。验收 fail-closed(单用户 +
+     *  host-semantics lane + 绝对路径/深度/长度门,规则在 env-facts.acceptShellScratchpadDir),拒收形
+     *  warn 后回落自算——「没到货引擎忽略 = 无害 additive」的对偶:异形键忽略,任务照跑。 */
     scratchpadDir?: string;
+    /** design/122 (core 1.225): opt-in — RETAIN settled sub-agent sessions so the shell can revive one
+     *  (`POST /v1/runs/:id/subagents/:target/resume`, CC dfe parity). `true` = core defaults (30min ttl / 16 max);
+     *  an object tunes them (service-clamped: ttlMs ≤24h, max ≤64 — retention pins sessions in memory within the
+     *  run). Default OFF = throwaway children (a resume then 409s `resume.retain_off`). Run-scoped: everything is
+     *  released when the parent run ends regardless. */
     retainSubagentSessions?: boolean | {
         ttlMs?: number;
         max?: number;
     };
+    /** [876] per-task custom subagents (core 1.295 `TaskSpec.agents` — CC `.claude/agents/` parity): the shell sends
+     *  its resolved agent definitions per request. Whitelist-validated FAIL-LOUD at submit (unknown keys 400 — an
+     *  agent definition silently losing a `denyTools`/`isolation` field is a silent widening, the opposite failure
+     *  mode of the resilience "tolerate unknown keys" posture; `permissionMode` deliberately NOT accepted — core call,
+     *  separate batch). `model` must be an ALREADY-RESOLVED name or Model object (the server does no alias translation).
+     *  🔒 Honored on SINGLE-USER deployments only (multi-tenant warns + ignores until a per-tenant caps face exists —
+     *  fail-closed; advertised via capabilities.taskAgents). ≤32 per request. Rides the persisted body onto resume
+     *  legs (defensive per-item DROP there, never a brick). */
     agents?: AgentDefinition[];
+    /** [854]② (core 1.295 `TaskSpec.retainBackgroundProcesses`): opt-out of the task-end reaping of session
+     *  background processes ("keep my dev server running"). On the host lane this is a RESOURCE-RESIDENCY grant, so
+     *  it takes the same single-user gate as backgroundShell/hooks (multi-tenant warns + ignores; advertised via
+     *  capabilities.retainBackgroundProcesses). Boolean fail-loud at submit; only `true` rides the spec. */
     retainBackgroundProcesses?: boolean;
+    /** [1052]② (core 1.314 工具面控制批): roster 真卸载清单(schema 不上 wire,manifest 收窄)。wire 工具名;
+     *  tighten-only(core 继承不变量 union 进子 spawn)。数组-of-string fail-loud at submit。 */
     excludeTools?: string[];
+    /** [1052]② (core 1.314): design/36 延迟披露清单(占位上 wire,ToolSearch 激活)——cli「Workflow 默认开
+     *  不暴露」的承载位。同 excludeTools 的校验/继承姿势。 */
     deferTools?: string[];
+    /** [1144]/[1146] (core 1.328 R2): 提示词双形轴——simple(CC 212 短形,引擎缺省)| classic(长形,可按
+     *  任务/模型试分)。纯呈现轴无租户门;枚举 fail-loud at submit;缺省不挂键。 */
     promptProfile?: "simple" | "classic";
+    /** R4 (CC parity): the LIGHT top-level per-turn permission-mode intent (CC `permissionMode`). The shell sends
+     *  the RAW mode (axis-agnostic, no client-side interpretation); the SERVICE interprets it tighten-only: `plan` ⇒
+     *  read-only hands + `present_plan` (EnterPlanMode parity); `acceptEdits`/`bypassPermissions` LOOSEN → coerced to
+     *  `default` (never honored remotely; the client enforces them on its own machine). Folds onto the SAME tighten-only
+     *  governance as `settings.permissions.defaultMode` (the heavier bundle), so it's a lighter alias, not a second path. */
     permissionMode?: string;
+    /** MF-30 memory PAUSE (shell-host contract, option B per-request — clay 2026-06-27): `false` makes THIS run
+     *  read-only over long-term memory (`TaskSpec.memory.writeScope:null` — the design/138 memory ENGINE materializes/
+     *  reads but its harvest commits nothing). Absent/`true` ⇒ normal read+write. The shell's `/memory` pause carries
+     *  this per request (no stored per-session flag). Re-applies on resume (rides in the persisted body). */
     memoryWrite?: boolean;
+    /** 142-S4 projectId 线程化(design/142 §2):这个 run 归属的项目(center 登记簿键,generic lowercase
+     *  UUID — core S1 `resolveProjectId` marker 或 S3 无仓 mint 的产物;客户端只透传,零铸造权威)。是「哪个
+     *  项目」的选择器,不是身份/capability — scope 的 tenant 段永远来自 verified principal。SHAPE 门在
+     *  authorizer(PROJECT_ID_REGEX,不合形状=422 typed `invalid_project_id`)。多租户 DB 记忆面下它把派生
+     *  scope 从 user 盘切到项目盘(`proj:<tenant>/<projectId>`)并以 config.projects[projectId].defaultScopes
+     *  作 memory.scopes 种子;单用户部署忽略派生(memoryScopeFor 不变),仅 defaultScopes 种子生效。
+     *  Rides the persisted body onto resume legs(与 memoryWrite 同姿势)。 */
     projectId?: string;
+    /** [#40 / TOC cwd seam, SDK 0.0.36] The TOC client's launch directory — the agent's HOST execution-env workspace
+     *  runs HERE (CC-parity: `sema` in a project dir operates on THAT project). An ABSOLUTE host path. 🔒 honored ONLY
+     *  on the single-user `host` lane (see task-cwd.ts `cwdHonored`); IGNORED on cloud/container lanes + multi-tenant
+     *  (a caller can't point a shared/cloud worker at an arbitrary host path). Validated absolute (prepareSpec 400s a
+     *  relative cwd — it would silently resolve against the SERVICE process cwd). */
     cwd?: string;
+    /** [R3] Caller-supplied per-request MCP servers (the TOC client's local `.mcp.json`), aligned to core
+     *  `McpServerSpec`. 🔒 honored on any SINGLE-USER deployment (task-mcp.ts `mcpInjectionHonored` = `requirePrincipal!==true`)
+     *  — the requester is the super-admin of their OWN worker (CC-parity), on ANY execution lane (the stdio MCP runs on the
+     *  worker, not the exec env); IGNORED on multi-tenant deployments (can't make the shared worker run an arbitrary
+     *  command). Validated + gated downstream; the center/config baseline wins on a name clash. */
     mcpServers?: McpServerSpec[];
+    /** CC parity (Workflow super-set): per-task activation of the LLM-authored workflow engine (core `run_workflow`).
+     *  `true` → `spec.selfOrchestration` (the engine mounts run_workflow), gated on the deployment's `selfOrchestrationEnabled`
+     *  (else a harmless no-op) + core's `allowWorkflows` per-principal entitlement on multi-tenant (single-user honors
+     *  directly). Absent/false ⇒ no workflow tool this run. */
     selfOrchestration?: boolean;
+    /** §4 (CC parity, mirrors `selfOrchestration`): per-task opt-in for CC `/fork` — mount core's `Fork` tool so the
+     *  model can fork the session (a child inherits the parent's full context + shares the prompt-cache prefix). `true` →
+     *  `spec.enableFork`; core additionally requires a durable fork-capable session store (`hasSessionFork` — the TOC file
+     *  backend satisfies it), else it stays inert. Absent/false ⇒ no Fork tool this run (default). Forks the CALLER's OWN
+     *  session (owner-checked authorizer), so no cross-tenant surface. */
     enableFork?: boolean;
     [k: string]: unknown;
 }
+/** design/80 D-1: the operator-echoed decision-action binding carried on POST /v1/approvals/:id[/decide].
+ *  All optional for back-compat — a legacy BFF caller omitting them resumes on the current-pending values
+ *  exactly as before (the pre-D-1 path), tracked by a deprecation counter.
+ *  design/158 A9: hoisted VERBATIM out of `createHttpServer`'s closure so the approvals/assistant route domain
+ *  and the resume leg can name the SAME shape without a routes/* → server.ts value edge. */
 export type DecideBinding = {
+    /** The capability token the operator actually SAW (from listPending). A mismatch with the current pending
+     *  ⇒ approval_stale (they decided a superseded/resolved view). */
     checkpointToken?: string;
+    /** The pendingAction.toolCallId the operator saw — echoed into ResumeOutcome.boundCallId. */
     boundCallId?: string;
+    /** The server-minted opaque boundInputHash the operator saw — echoed VERBATIM (never recomputed here). */
     boundInputHash?: string;
+    /** design/37 edit: operator-corrected tool args, applied by core AFTER the binding check, on approve only. */
     updatedInput?: unknown;
 };
 //# sourceMappingURL=wire-types.d.ts.map

package/dist/http/workspace-content.d.ts

@@ -1,3 +1,11 @@
+/**
+ * design/158 A9 seam —— workspace 文件面的内容类型/二进制判别,从 `http/server.ts` 整段搬出的原文。
+ * routes/sessions.ts 的 workspace 腿要用它,所以住在 http/ 叶子里(routes/* 不可值 import server.ts)。
+ */
+/** workspace file 面的 content-type(#3,[1894]③):保守扩展名表——只收「浏览器渲染无歧义且
+ *  无主动内容」的类型,其余一律 octet-stream(nosniff 恒带;html/svg 等可执行内容**故意**不进表,
+ *  agent 产物=不可信,按下载处理)。 */
 export declare function workspaceContentType(relPath: string): string;
+/** 二进制判别([1894]③):首 8KiB 含 NUL 即二进制(git 同判据——快、稳、无误伤 UTF-8)。 */
 export declare function looksBinary(bytes: Uint8Array): boolean;
 //# sourceMappingURL=workspace-content.d.ts.map

package/dist/http/workspace-content.js

@@ -1,4 +1,13 @@
+/**
+ * design/158 A9 seam —— workspace 文件面的内容类型/二进制判别,从 `http/server.ts` 整段搬出的原文。
+ * routes/sessions.ts 的 workspace 腿要用它,所以住在 http/ 叶子里(routes/* 不可值 import server.ts)。
+ */
+/** workspace file 面的 content-type(#3,[1894]③):保守扩展名表——只收「浏览器渲染无歧义且
+ *  无主动内容」的类型,其余一律 octet-stream(nosniff 恒带;html/svg 等可执行内容**故意**不进表,
+ *  agent 产物=不可信,按下载处理)。 */
 export function workspaceContentType(relPath) {
+    // 🔴 复审 A-LOW:先确认**真有** `.` 再取扩展名——`lastIndexOf` 返回 -1 时 `slice(0)` 会把整个
+    // basename 当扩展名,于是一个名为 `png`/`pdf` 的任意内容文件会命中保守表按 image/png 发出。
     const base = relPath.slice(relPath.lastIndexOf("/") + 1);
     const dot = base.lastIndexOf(".");
     const ext = dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
@@ -10,6 +19,7 @@ export function workspaceContentType(relPath) {
     };
     return TABLE[ext] ?? "application/octet-stream";
 }
+/** 二进制判别([1894]③):首 8KiB 含 NUL 即二进制(git 同判据——快、稳、无误伤 UTF-8)。 */
 export function looksBinary(bytes) {
     const n = Math.min(bytes.byteLength, 8192);
     for (let i = 0; i < n; i++)

package/dist/images/bake-validate.d.ts

@@ -1,9 +1,40 @@
+/**
+ * Bake input WHITELIST + vetted-argv builder (IMAGE-API-DESIGN.md §P2.4 — the anti-RCE core).
+ *
+ * bands/profile/baseRef/bump compose a Dockerfile + a `FROM` + a `docker build` = arbitrary code on the build
+ * host. So EVERY field is validated SERVER-SIDE against a CLOSED SET *before* an argv is built; off-list → an
+ * error, never coerced. The runner only ever sees the VETTED argv this module emits (never operator free-text)
+ * and only runs `build.sh`, which composes Dockerfiles from the in-repo `bands/` via `gen-dockerfile.sh` — there
+ * is no path here to inject a raw Dockerfile or a shell command.
+ *
+ * Set membership is the gate (NOT regex): `^[a-z0-9-]+$` is belt-only — `python; rm -rf /` ∉ the frozen set →
+ * rejected, and the argv is a RAW vetted VECTOR the runner array-spawns (each element in its own argv slot, no
+ * shell), never concatenated into a command string.
+ *
+ * The frozen catalogs below MIRROR the recipe source of truth (`gen-dockerfile.sh` `profile_bands()` + the
+ * `bands/` dir). A DRIFT test (test/image-bake-validate.test.ts) asserts they still match — a silently-drifted
+ * list would either reject a valid profile or admit a removed band. Keep them in lockstep with the recipes.
+ */
+/**
+ * FROZEN profile catalog — mirrored from `e2b-template/dev-sandbox/gen-dockerfile.sh` `profile_bands()`.
+ * (db / browser-nodriver are opt-in overlays, NOT in `code-full` — `code-full-db` adds db; per design §4.)
+ */
 export declare const FROZEN_PROFILES: readonly string[];
+/** FROZEN band set — mirrored from the `e2b-template/dev-sandbox/bands/` directory (one dir per band). */
 export declare const FROZEN_BANDS: readonly string[];
+/**
+ * FROZEN bump-tool set — the toolchain identifiers a `--bump <tool>=<ver>` may target. Conservative union of the
+ * version-overridable toolchains the bands accept (`<TOOL>_VERSION` env, build.sh forwards `--bump tool=ver`).
+ * Set-membership is the gate; the value is range-checked by VER_RE. Off-list tool → 400 (never coerced).
+ */
 export declare const FROZEN_BUMP_TOOLS: readonly string[];
+/** Bump value range (P2.4d): printable version-ish tokens only, ≤40 chars — folds into the lockhash. */
 export declare const VER_RE: RegExp;
+/** Belt-only band shape (set-membership is the real gate); a defense-in-depth reject of structurally weird ids. */
 export declare const BAND_SHAPE_RE: RegExp;
+/** A digest must be an immutable sha256 ref (the allow-list check against the index is the real gate, P2.4c). */
 export declare const DIGEST_RE: RegExp;
+/** The raw, untrusted submit body fields this module validates (operator free-text). */
 export interface BakeSubmit {
     profile?: unknown;
     bands?: unknown;
@@ -12,14 +43,18 @@ export interface BakeSubmit {
     push?: unknown;
     dryRun?: unknown;
     logs?: unknown;
+    /** RFC B4: bake-time package-source profile — "cn" (default) | "global". Closed set, never coerced. */
     pkgSource?: unknown;
 }
+/** A validation rejection: the HTTP status + a stable error envelope (matches the live images-block shape). */
 export interface BakeReject {
     ok: false;
     status: number;
     error: string;
+    /** P2.14 #2 — structured band-conflict for the composer UI; null otherwise. */
     conflictBands?: string[];
 }
+/** A vetted bake: the normalized inputs + the RAW argv vector the runner array-spawns (and only this). */
 export interface BakeAccept {
     ok: true;
     profile: string;
@@ -29,11 +64,39 @@ export interface BakeAccept {
     push: boolean;
     dryRun: boolean;
     logs: boolean;
+    /** RFC B4: vetted bake-time package-source profile; null = build.sh default (cn). */
     pkgSource: "cn" | "global" | null;
+    /** The VETTED build.sh argv (NOT including `build.sh` itself) — raw vetted vector, array-spawned (no shell). */
     argv: string[];
 }
 export type BakeValidation = BakeAccept | BakeReject;
+/**
+ * Validate + normalize a `POST /v1/images/bakes` body into a vetted argv, or a typed rejection.
+ *
+ * Order is deliberate: profile XOR bands → bands set-membership (dupes/empties/shape) → bump set+range →
+ * baseRef shape (the index allow-list check is done by the caller via `baseRefAllowed`, async) → build the
+ * raw vetted argv. The output repo is server-fixed (`sema-images/<profile>`); the caller CANNOT set
+ * `--tag` (build.sh auto-computes the immutable tag — kills namespace-squat) nor an arbitrary `FROM`.
+ *
+ * `baseRefAllowed` is checked HERE for shape only; the digest-in-index allow-list is the caller's async step
+ * (it owns the TiDB index). A present-but-malformed `baseRef` is rejected before any DB hit.
+ */
 export declare function validateBake(body: BakeSubmit): BakeValidation;
+/**
+ * Build the VETTED, NORMALIZED build.sh argv from an accepted validation + the caller-resolved effective fields
+ * (the index-checked baseRef and the build-host CACHE_BASE — both runner-environment facts image-api injects,
+ * never operator free-text). The elements are RAW (no shell-quoting): the runner array-spawns build.sh so each
+ * element lands in its own argv slot (no shell can re-interpret a frozen-set value). The runner runs
+ * `build.sh <argv...>` and ONLY this.
+ *
+ * Server-fixed invariants enforced here (NOT caller-settable, P2.4d):
+ *   - `--json` always (machine output the runner parses).
+ *   - selection is `--profile <p>` XOR `--bands a,b,c` (already vetted).
+ *   - NO `--tag` (build.sh auto-computes the immutable tag — kills namespace-squat / overwrite-by-naming).
+ *   - the output repo is server-fixed `sema-images/<profile>` (build.sh's IMAGE_PREFIX default; not forwarded).
+ *   - `--base-ref` is the index-checked effective base (caller resolves the default when absent).
+ *   - `--cache-base` is the build-host promoted cache (runner env).
+ */
 export declare function buildBakeArgv(v: BakeAccept, effective: {
     baseRef: string | null;
     cacheBase: string | null;