@sema-agent/server 1.323.0 → 2.0.0

package/dist/spec-fields.js

@@ -1,15 +1,36 @@
+/**
+ * Request-body → TaskSpec field normalizers (shell-host contract). Kept out of main.ts (which auto-runs the service
+ * on import) so they are unit-testable in isolation. Each is DEFENSIVE: a RESUME re-runs resolveSpec from the stored
+ * body WITHOUT the HTTP-layer 400 validation, so a malformed value must fall back to a safe default, never throw.
+ */
 import { isThinkingLevel } from "@sema-agent/core";
 import { taskWallClockSec } from "./task-workflow.js";
+/**
+ * E12 — normalize `body.suggestNextPrompts` → `TaskSpec.suggestNextPrompts`. `true` = on with core defaults
+ * (count 3, cheap role); an object tunes `count` (clamped 1..10) / `role` (a free string — core validates it against
+ * `ModelRole`, an unknown role falls back to the task model). `false` / absent / non-object / garbage ⇒ undefined (off).
+ */
 export function normalizeSuggestNextPrompts(v) {
     if (v === true)
         return true;
     if (v == null || typeof v !== "object" || Array.isArray(v))
-        return undefined;
+        return undefined; // false / absent / non-object / array ⇒ off
     const o = v;
+    // DROP a non-finite or <1 count (treat as absent → core's default), matching the HTTP layer which 400s count<1 — so
+    // submit-reject and resume-normalize never diverge into an unintended count. Clamp a large count down to 10.
     const count = typeof o.count === "number" && Number.isFinite(o.count) && o.count >= 1 ? Math.min(10, Math.floor(o.count)) : undefined;
     const role = typeof o.role === "string" && o.role ? o.role : undefined;
     return { ...(count !== undefined ? { count } : {}), ...(role ? { role } : {}) };
 }
+/**
+ * design/131 (core 1.246) — normalize `body.resilience` → `TaskSpec.resilience`. INTENT flags only:
+ * `allowDegrade:false` / `allowFailover:false` let a bench/eval or critical task say "fail rather than fall back".
+ * `bypassBreaker` is OPERATOR-FACING (不给 wire 用户直开 — it punches through a shared circuit breaker,
+ * which exists to protect the provider): honored only when the request principal is an explicit operator; silently
+ * dropped otherwise (not a 4xx — resume re-runs this without HTTP validation, and a stripped intent flag degrades
+ * to today's behavior, core's own "all absent = byte-compat" posture). Only literal booleans pass; all-empty ⇒
+ * undefined (never an empty object — keeps the spec byte-identical for non-users).
+ */
 export function normalizeResilience(v, operator) {
     if (v == null || typeof v !== "object" || Array.isArray(v))
         return undefined;
@@ -21,9 +42,20 @@ export function normalizeResilience(v, operator) {
     };
     return Object.keys(out).length > 0 ? out : undefined;
 }
+/**
+ * design/133 (core 1.251) — normalize `body.attachments` → `TaskSpec.attachments`. Core's contract is
+ * literal-true unions ("关闭=删 key,勿传 false"): only `true` (or, for changedFiles, an object with a sane
+ * `maxFiles`) survives; `false`/garbage per key is DROPPED, not forwarded. maxFiles clamped 1..100 (core caps its
+ * own stat cost at 20 by default; the clamp only guards against a resume replaying a wild persisted value).
+ * All-empty ⇒ undefined. NB resume audit: our persisted body is the FULL request JSON and resolveSpec
+ * is the single translation point, so consuming the field here IS the whitelist inclusion — nothing else to add.
+ */
 export function normalizeAttachments(v) {
     if (v == null || typeof v !== "object" || Array.isArray(v))
         return undefined;
+    // 历史复审轴B #1(1.254):白名单曾落后 core 五键——尤其 agentListing/skillsListing 是 core DEFAULT-ON
+    // (explicit false 才关),旧名单静默丢 false = wire 上唯一无法表达关闭的面(调用方 200 以为生效)。
+    // 两键按 boolean 透传(含 false);budgetUsd/mcpInstructions literal-true 同族;todoReminderMode 枚举。
     const o = v;
     let changedFiles;
     if (o.changedFiles === true)
@@ -37,6 +69,8 @@ export function normalizeAttachments(v) {
         ...(o.todoReminder === true ? { todoReminder: true } : {}),
         ...(changedFiles !== undefined ? { changedFiles } : {}),
         ...(o.planModeReminder === true ? { planModeReminder: true } : {}),
+        // core 1.253 G1: post-compaction background-task recap + deferred-tools boundary notice —
+        // same literal-true contract as the rest of the family (both are one-shot/opt-in on the core side).
         ...(o.backgroundTasks === true ? { backgroundTasks: true } : {}),
         ...(o.toolsDelta === true ? { toolsDelta: true } : {}),
         ...(o.todoReminderMode === "baseline" || o.todoReminderMode === "off" ? { todoReminderMode: o.todoReminderMode } : {}),
@@ -47,18 +81,30 @@ export function normalizeAttachments(v) {
     };
     return Object.keys(out).length > 0 ? out : undefined;
 }
+/**
+ * [833] rewind exclusive mode (core 1.292) — normalize `body.resumeAtMode` → `TaskSpec.resumeAtMode`. DEFENSIVE
+ * (the resume path re-runs resolveSpec WITHOUT the HTTP 400 gate): only the two enum values survive, and only when
+ * the resume-at handle actually RESOLVED (core ignores the field without `resumeAt`; keep the spec tight instead of
+ * shipping a dangling qualifier). Absent/garbage ⇒ undefined = core default "at" (zero regression).
+ */
 export function normalizeResumeAtMode(v, resumeAtResolved) {
     if (!resumeAtResolved)
         return undefined;
     return v === "at" || v === "before" ? v : undefined;
 }
+// ─── [876] per-task subagents(core 1.295 `TaskSpec.agents`)──────────────────────────────────────────────
+/** [876] 防御上限:一份请求最多带多少个 agent 定义。core 侧无上限;这里封一个防御值 —— 每个定义都进
+ *  系统提示(whenToUse/skills/systemPrompt 全是 prompt 载荷),不设界就是 per-turn token 成本洞(与
+ *  MAX_USER_SKILLS 同轴)。32 足够覆盖 CC 式 `.claude/agents/` 全家桶还有余量。 */
 export const MAX_TASK_AGENTS = 32;
+// [876] 每字段防御上限(cross-review 抓获:无上限的 prompt 载荷字段=32 条帽封不住的 per-turn token 成本洞,
+// maxTurns 无顶=运行成本洞)。skill 三上限与 server.ts validateUserSkills 同值(64/1024/1MiB,engine 同一载荷面)。
 const MAX_AGENT_NAME_CHARS = 64;
-const MAX_AGENT_TEXT_CHARS = 4_096;
+const MAX_AGENT_TEXT_CHARS = 4_096; // whenToUse/whenToUseLean/observer/observerMessage
 const MAX_AGENT_SYSTEM_PROMPT_CHARS = 65_536;
-const MAX_AGENT_TOOLS = 64;
+const MAX_AGENT_TOOLS = 64; // allowTools/denyTools entries
 const MAX_AGENT_TOOL_NAME_CHARS = 128;
-const MAX_AGENT_SKILLS = 10;
+const MAX_AGENT_SKILLS = 10; // 与 MAX_USER_SKILLS 同轴
 const MAX_AGENT_SKILL_CONTENT_CHARS = 1_048_576;
 const MAX_AGENT_MAX_TURNS = 1_000;
 const boundedString = (max) => (v) => typeof v === "string" && v.length <= max;
@@ -66,6 +112,9 @@ const toolList = (v) => Array.isArray(v) &&
     v.length <= MAX_AGENT_TOOLS &&
     v.every((x) => typeof x === "string" && x.length > 0 && x.length <= MAX_AGENT_TOOL_NAME_CHARS);
 const plainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** SkillSpec 闭合白名单(core dist/core/types.d.ts:169:name/description/content 必填 + manifest?/files?)。
+ *  files 条目必须 {path, content} 双 string —— core synthetic-tools 直接迭代 `f.path`,一个 null 条目就是
+ *  运行期 crash(cross-review 抓获);未知键整条拒(与 agent 键同姿势)。 */
 const skillOk = (s) => {
     if (!plainObject(s))
         return false;
@@ -79,6 +128,8 @@ const skillOk = (s) => {
         return false;
     if (typeof s.content !== "string" || s.content.length === 0 || s.content.length > MAX_AGENT_SKILL_CONTENT_CHARS)
         return false;
+    // SkillManifest 闭合(core types.d.ts:163:allowTools+lineageId 必填)—— 空对象/畸形 allowTools 会晚失败
+    // 在 core 激活技能时 `manifest.allowTools.map(...)`(round-2 cross-review)。
     if (s.manifest !== undefined) {
         const m = s.manifest;
         if (!plainObject(m))
@@ -108,6 +159,8 @@ const skillOk = (s) => {
     }
     return true;
 };
+/** MemorySpecInput 闭合白名单(core dist/core/memory.d.ts:92 亲读)。core 的 normalizeMemorySpec 会直接
+ *  迭代 `scopes` —— 非数组形状(如 {scopes:{length:1}})在服务门不拦就是 core 运行期异常(cross-review 抓获)。 */
 const memoryOk = (v) => {
     if (!plainObject(v))
         return false;
@@ -127,6 +180,12 @@ const memoryOk = (v) => {
         return false;
     return true;
 };
+/** [876] AgentDefinition 白名单字段表(core 1.295 dist/core/types.d.ts:113 亲读)+ 每字段的形状谓词。
+ *  ⚠️ `permissionMode` 有意不纳(core 拍,独立批)—— body 里出现按未知键拒,见 taskAgentIssue。
+ *  `model` 收「已解析真名 string 或带非空 string `id` 的 Model 对象」—— server 不做词表翻译(壳侧已解析,
+ *  [879]④ 契约);core 对对象形 Model 原样信任不校验(dist/core/roles.js 亲读),空对象 `{}` 会晚失败在
+ *  引擎深处,所以最低限 `id` 在门上验。保留名(如与委派工具同名)不在这里镜像 —— core prepare 侧
+ *  fail-loud `config.agent.reserved_name`(镜像 core 私有清单=漂移风险)。 */
 const TASK_AGENT_FIELD_SHAPES = {
     name: {
         desc: `a non-empty string of at most ${MAX_AGENT_NAME_CHARS} characters`,
@@ -157,6 +216,12 @@ const TASK_AGENT_FIELD_SHAPES = {
     observer: { desc: `a string of at most ${MAX_AGENT_TEXT_CHARS} characters`, ok: boundedString(MAX_AGENT_TEXT_CHARS) },
     observerMessage: { desc: `a string of at most ${MAX_AGENT_TEXT_CHARS} characters`, ok: boundedString(MAX_AGENT_TEXT_CHARS) },
 };
+/** [876] 单条 agent 定义的形状裁决:null=合法;否则一句可 400 的英文错误(不带索引,调用方自己加)。
+ *  白名单外键 fail-loud —— 与 resilience/limits 的「容忍未知键」相反:agents 是能力定义,静默丢字段 =
+ *  定义被悄悄削(一个丢掉的 isolation 就是放宽),比 400 更危险,故整条拒。⚠️ 已知残账(core 半场):
+ *  core 只对 allowTools 未知项 fail-loud,denyTools 未知项(如 typo)静默失效 —— 已上板请 core 镜像。
+ *  ⚠️ 键判断必须 Object.hasOwn:`in` 走原型链,JSON 里的 "toString"/"constructor"/"__proto__" 键会被
+ *  误判为白名单字段,随后 SHAPES[k].ok 不是函数 ⇒ TypeError(fresh 500 / resume 砖;cross-review 复现)。 */
 export function taskAgentIssue(item) {
     if (item === null || typeof item !== "object" || Array.isArray(item))
         return "each agent must be an object";
@@ -178,6 +243,9 @@ export function taskAgentIssue(item) {
     }
     return null;
 }
+/** [876] HTTP 门(fresh submit,server.ts prepareSpec):body.agents 在场必须是非空数组、每条过
+ *  {@link taskAgentIssue}、name 数组内唯一、条数 ≤ {@link MAX_TASK_AGENTS}。返回 400 错误串或 null。
+ *  RESUME 重放不过这道门 —— {@link taskAgentsFromBody} defensive(按条 DROP+warn,不砖 resume)。 */
 export function validateTaskAgents(v) {
     if (!Array.isArray(v) || v.length === 0)
         return "agents must be a non-empty array of agent definitions";
@@ -195,6 +263,14 @@ export function validateTaskAgents(v) {
     }
     return null;
 }
+/** [876] body.agents → `TaskSpec.agents`(resolveSpec 的唯一装配点;main.ts 只 spread)。两层门:
+ *   - 🔒 TOB 租户门:多租户(requirePrincipal===true)暂不放行 —— [876] 原文「TOB 面按租户 caps 门」,
+ *     当前没有 per-tenant caps 面可挂,先 fail-closed 关多租(warn `task_agents_ignored`,capabilities
+ *     的 `taskAgents` 同步 advertise false);单机/单用户直通(caller 是自己 worker 的 super-admin,
+ *     与 mcpInjection/hooks 同一姿势)。
+ *   - defensive 归一化(RESUME 重放持久化 body 不过 HTTP 400 门):非法项按条 DROP + warn
+ *     `task_agent_dropped`(绝不 throw 砖 resume);重名后到者 DROP;超上限截断。幸存字段按白名单拷贝
+ *     (不透传未知键 —— 非法项已整条 drop,这里只是让持久化 body 的杂键不上 spec)。全空 ⇒ undefined。 */
 export function taskAgentsFromBody(raw, requirePrincipal, warn) {
     if (raw === undefined)
         return undefined;
@@ -233,10 +309,19 @@ export function taskAgentsFromBody(raw, requirePrincipal, warn) {
     }
     return out.length > 0 ? out : undefined;
 }
+/** [876] main.ts resolveSpec 的 agents 装配片段(可 import 真 fold,[1.211 codex L]:此前 main.ts 用内联
+ *  闭包,测试只能 SOURCE PIN 文本+重写同构表达式——文本锚可被「移出 resolveSpec 但保留同文」静默骗过;
+ *  现在行为测试直接调这个真出口,main.ts 只剩一次调用点可锚)。语义=taskAgentsFromBody 的条件 spread:
+ *  有幸存 agents 才挂键(absent/全 drop ⇒ 空对象,spec byte-compat)。 */
 export function taskAgentsSpecFragment(raw, requirePrincipal, warn) {
     const agents = taskAgentsFromBody(raw, requirePrincipal, warn);
     return agents ? { agents } : {};
 }
+/** [854]② — body.retainBackgroundProcesses → `TaskSpec.retainBackgroundProcesses`。core 语义(1.295
+ *  runtask/task-registry dist 亲读):`=== true` 时任务收尾不主动收割 session 后台进程 —— host lane 上是
+ *  资源驻留授予,与 backgroundShell 同款单用户闸:多租户 warn 忽略(`task_retain_bg_ignored`,capability
+ *  同步 advertise false)。只 literal `true` 上 spec(false=core 缺省,不挂键保持 byte-compat);非 boolean
+ *  由 HTTP 门 400,resume 重放这里 defensive DROP(不 throw)。 */
 export function retainBackgroundProcessesFromBody(raw, requirePrincipal, warn) {
     if (raw !== true)
         return undefined;
@@ -246,15 +331,31 @@ export function retainBackgroundProcessesFromBody(raw, requirePrincipal, warn) {
     }
     return true;
 }
+/** [1052]② — body.{excludeTools,deferTools} → `TaskSpec.{excludeTools,deferTools}`(core 1.314 工具面
+ *  控制批)。语义:excludeTools=roster 真卸载(schema 字节不上 wire,manifest 如实收窄);deferTools=
+ *  design/36 延迟披露(占位上 wire,ToolSearch 激活 materialize)。两位 tighten-only(core 继承不变量:
+ *  union 进全部子 spawn 路径),per-run 工具面收窄无跨租户面 ⇒ 无租户门(interactiveTools 同姿势)。
+ *  DEFENSIVE(resume 重放不过 HTTP 400 门):非数组 ⇒ undefined;项非非空字符串 ⇒ 逐项 DROP;空数组 ⇒
+ *  undefined(不挂键=core 缺省,byte-compat)。HTTP 门另有 fail-loud 400(提交面邻居姿势)。 */
 export function toolNameListFromBody(raw) {
     if (!Array.isArray(raw))
         return undefined;
     const names = raw.filter((v) => typeof v === "string" && v.length > 0);
     return names.length > 0 ? names : undefined;
 }
+/** [1144]/[1146] — body.promptProfile → `TaskSpec.promptProfile`(core 1.328 R2 主件,CC LT(model_id)
+ *  同构双形轴)。语义:纯呈现轴不碰策略(simple=CC 212 短形面缺省;classic=长形面,可按任务/模型试分)
+ *  ⇒ 无租户门(deferTools 同姿势);全委托树继承由 core 管。缺省不挂键(引擎缺省 simple,byte-compat)。
+ *  DEFENSIVE(resume 重放不过 HTTP 400 门):非法值 ⇒ undefined;提交面另有 fail-loud 400(邻居姿势)。 */
 export function promptProfileFromBody(raw) {
     return raw === "simple" || raw === "classic" ? raw : undefined;
 }
+/**
+ * [854]④ — normalize `body.limits` → 请求方配速意图 {timeoutSec?, maxOutputTokens?, maxTurns?}。DEFENSIVE
+ * (resume 重放持久化 body 不过 HTTP 400 门):仅正的有限数字存活(floor 取整),0/负/垃圾按键 DROP —— core 侧
+ * `timeoutSec > 0` 才生效(0=不设墙,会绕过运营方封顶)、maxTurns/maxOutputTokens 的 0 无意义。每键各自被
+ * 运营方上限旋钮 clamp(Math.min;旋钮缺省不设=不封顶)。全空 ⇒ undefined。
+ */
 export function normalizeLimits(v, caps) {
     if (v == null || typeof v !== "object" || Array.isArray(v))
         return undefined;
@@ -269,12 +370,23 @@ export function normalizeLimits(v, caps) {
         ...(() => { const n = pick(o.timeoutSec, caps.timeoutSec); return n !== undefined ? { timeoutSec: n } : {}; })(),
         ...(() => { const n = pick(o.maxOutputTokens, caps.maxOutputTokens); return n !== undefined ? { maxOutputTokens: n } : {}; })(),
         ...(() => { const n = pick(o.maxTurns, caps.maxTurns); return n !== undefined ? { maxTurns: n } : {}; })(),
+        // 历史复审轴B #4(1.254):deadline 族三个 **opt-out**(design/128/130,timeoutSec 在场即默认 ON;
+        // server 恒注 tenancy 墙钟 ⇒ 此前恒开且 wire 无法关)。只认 literal false(纯关闭旋钮,零扩权面)。
         ...(o.deadlineNudge === false ? { deadlineNudge: false } : {}),
         ...(o.callCapByDeadline === false ? { callCapByDeadline: false } : {}),
         ...(o.gracefulFinalize === false ? { gracefulFinalize: false } : {}),
     };
     return Object.keys(out).length > 0 ? out : undefined;
 }
+/**
+ * [854]④ — body.limits 与 env 墙钟的合成规则(resolveSpec 的唯一 limits 装配点;run-local 无 body 车道不经此):
+ *  - `timeoutSec`:body 给了就用 body(caller 明确配速;已在 normalizeLimits 里被 TASK_TIMEOUT_MAX_SEC 封顶)。
+ *    body 缺席保持既有姿势 = tenancy 墙钟 + env `TASK_TIMEOUT_SEC` 只抬不降(taskWallClockSec 内 Math.max,
+ *    误配低值不能砍 council 预算)。注意两条纪律不叠加:「只抬不降」是 env 对内建缺省墙的规则,body 是
+ *    caller 的显式意图,直接生效(可低于 env 墙 —— 交互短任务要更紧的配速正是本件诉求)。
+ *  - `maxOutputTokens` / `maxTurns`:直透传(各自可选 env 上限已 clamp)。
+ * 全空 ⇒ undefined(spec 不挂 limits 键,byte-compat)。
+ */
 export function resolveTaskLimits(bodyLimits, caps, envTimeoutSec, requirePrincipal, big) {
     const requested = normalizeLimits(bodyLimits, caps);
     const timeoutSec = requested?.timeoutSec ?? taskWallClockSec(envTimeoutSec, requirePrincipal, big);

package/dist/task-cwd.d.ts

@@ -1,21 +1,71 @@
+/** Cap on a cwd path length (defensive — a row/path label bound; a real path is far shorter). */
 export declare const MAX_CWD_CHARS = 4096;
+/** Is this a structurally-valid absolute host path? Rejects: non-strings, relative paths (TOC review #12 — a
+ *  relative cwd would resolve against the SERVICE process cwd, not the user's project = silent wrong-dir), empty,
+ *  over-long, and NUL-byte injection. NOT an existence check (the env surfaces a missing dir at first tool use).
+ *  Defense-in-depth (double-review LOW): `path.isAbsolute` is SYNTACTIC — `/a/../../etc` is "absolute" yet contains
+ *  `..` traversal that the host env would `path.resolve` away. Single-user host lane = the caller's own machine (no
+ *  cross-tenant escape), but we reject any path with a `..` segment so the honored cwd is the literal path sent. */
 export declare function isValidCwd(cwd: unknown): cwd is string;
+/**
+ * The deployment-level gate: does THIS deployment honor a caller-supplied `cwd`? TRUE only for the single-user
+ * `host` lane (see module header). All cloud/container lanes + any multi-tenant deployment → FALSE (cwd ignored).
+ */
 export declare function cwdHonored(config: {
     remoteExec?: {
         provider?: string;
     };
     requirePrincipal?: boolean;
 }): boolean;
+/**
+ * [851]P3a — the OTHER host-semantics lane: provider UNSET = the in-process single-user lane. It has NO shell
+ * hands (core prepare-task: no factory/executionEnv ⇒ StubExecutionEnv), so the perSession cwd/env registries
+ * have no consumer there — but PROCESS-level consumers (hooks commands, the C4 projectContext local read) still
+ * see the engine's own `process.cwd()`/`process.env`. When the shell spawned the engine in the caller's own
+ * dir/env, a caller override is often ALREADY satisfied by that process state, and a per-task "ignored" warn
+ * contradicts it (飞轮双平台观测). Signal-truth split: satisfied ⇒ debug, real mismatch ⇒ warn. True per-session
+ * honoring remains `REMOTE_EXEC=host`. Multi-tenant excluded for the same reason as {@link cwdHonored}.
+ */
 export declare function inProcessSingleUserLane(config: {
     remoteExec?: {
         provider?: string;
     };
     requirePrincipal?: boolean;
 }): boolean;
+/** Is a requested cwd ALREADY the engine process's working dir? realpath BOTH sides (macOS `/tmp` →
+ *  `/private/tmp`-class symlinks); either side failing to resolve ⇒ treated as a mismatch (warn — never a
+ *  false downgrade). `realpath`/`cwd` are parameters for testability; production passes `fs.realpathSync`. */
 export declare function satisfiedByProcessCwd(requested: string, realpath: (p: string) => string, cwd?: () => string): boolean;
+/** How many requested shellEnv entries the engine process env does NOT already carry (value-exact compare).
+ *  0 ⇒ satisfied by the inherited process state (debug, not "ignored"). Callers must log only this COUNT —
+ *  never env values (secret-class), and not key names either (a name can itself carry sensitive semantics). */
 export declare function shellEnvMismatchCount(requested: Record<string, string>, procEnv: Record<string, string | undefined>): number;
+/** Cap on the number of `--add-dir` entries a caller may attach (bounds a pathological allowlist blast). */
 export declare const MAX_ADDITIONAL_DIRS = 64;
+/**
+ * design/119 (CC `--add-dir` parity): validate an untrusted `body.additionalDirectories` — extra host dirs the
+ * FILE tools may access beyond the containment root (core canonicalizes each into its allowlist + lists them in the
+ * `# Environment` block). Gated identically to {@link cwdHonored}: these are the caller's OWN-machine paths, so they
+ * only make sense — and are only safe — on the single-user host lane (on a cloud/container lane a file-tool root is
+ * the sandbox fs, and a multi-tenant lane must never let one caller widen containment onto operator/other-tenant
+ * host paths). Each element gets the SAME structural check as `cwd` (absolute, no `..` traversal, no NUL, capped);
+ * malformed entries are dropped (never throw), the count is bounded, and duplicates collapse. Returns undefined when
+ * nothing valid remains (so the spec field stays absent rather than an empty array). NOT an existence check.
+ */
 export declare function parseAdditionalDirectories(raw: unknown): string[] | undefined;
+/**
+ * core 1.219 `ExecutionEnvFactoryContext.parentCwd` (dogfood: sub-agents landed in an EMPTY
+ * sandbox — "当前工作目录为空"): resolve the HOST lane's effective workspace for a task. Precedence:
+ *   1. the session's explicitly-registered `cwd` (the caller's own launch dir, the cwd seam) — an explicit
+ *      per-session choice always wins;
+ *   2. the TRUSTED `ctx.parentCwd` (core threads the PARENT task's working root via `RunInternals` when this
+ *      task is a delegated child — never a TaskSpec field), UNLESS the child asked for `isolation:"worktree"`
+ *      (core contract: worktree wins — an isolated fan-out child must not share the parent's mutable dir);
+ *   3. undefined → the factory's ephemeral per-task dir (top-level task with no registered cwd).
+ * CC parity: a Task sub-agent inherits the main session's cwd. Trust: `parentCwd` comes from core's trusted
+ * run-internals channel (same posture as `isolation`), so no tenancy gate is needed here — but the HOST lane
+ * itself is single-user by deployment shape, and container lanes (k8s/e2b/local-docker) never consult this.
+ */
 export declare function effectiveHostWorkspace(sessionCwd: string | undefined, ctx: {
     isolation?: string;
     parentCwd?: string;

package/dist/task-cwd.js

@@ -1,5 +1,29 @@
+/**
+ * TOC cwd seam — project the TOC client's launch directory (`TaskRequest.cwd`, SDK 0.0.36) onto the agent's
+ * HOST execution-env workspace, so `sema` run from a project dir operates on THAT project (CC-parity), instead of
+ * the persistent local engine's (default port 47362) fixed/ephemeral workspace (TOC adversarial review CRITICAL: the HTTP path conveyed NO
+ * project context — the agent always landed in an empty temp dir).
+ *
+ * 🔒 SECURITY (workflow): `cwd` is a HOST PATH supplied by the caller. Honoring it is a sandbox/
+ * filesystem-root choice, so it is gated HARD:
+ *   - ONLY the `host` execution lane (run-on-this-machine, no container) reads it — every OTHER lane (k8s / e2b /
+ *     ssh / adb / local-docker) has its own factory that NEVER consults the cwd registry, so cwd is ignored there
+ *     by construction (a tenant can't point a shared/cloud worker at an arbitrary host path).
+ *   - AND only a SINGLE-USER deployment (`requirePrincipal === false`) — a multi-tenant host lane must NOT let one
+ *     caller's cwd steer the agent into another tenant's / the operator's files (cross-tenant host-path access).
+ * Same trust boundary as the deferred per-task `env` (TaskSpec deliberately has no per-task env for untrusted
+ * callers). When the gate is closed, a sent `cwd` is IGNORED (not honored) — advertised via capabilities so the
+ * shell never pretends it took effect.
+ */
 import path from "node:path";
+/** Cap on a cwd path length (defensive — a row/path label bound; a real path is far shorter). */
 export const MAX_CWD_CHARS = 4_096;
+/** Is this a structurally-valid absolute host path? Rejects: non-strings, relative paths (TOC review #12 — a
+ *  relative cwd would resolve against the SERVICE process cwd, not the user's project = silent wrong-dir), empty,
+ *  over-long, and NUL-byte injection. NOT an existence check (the env surfaces a missing dir at first tool use).
+ *  Defense-in-depth (double-review LOW): `path.isAbsolute` is SYNTACTIC — `/a/../../etc` is "absolute" yet contains
+ *  `..` traversal that the host env would `path.resolve` away. Single-user host lane = the caller's own machine (no
+ *  cross-tenant escape), but we reject any path with a `..` segment so the honored cwd is the literal path sent. */
 export function isValidCwd(cwd) {
     return (typeof cwd === "string" &&
         cwd.length > 0 &&
@@ -8,12 +32,28 @@ export function isValidCwd(cwd) {
         path.isAbsolute(cwd) &&
         !cwd.split(/[/\\]/).includes(".."));
 }
+/**
+ * The deployment-level gate: does THIS deployment honor a caller-supplied `cwd`? TRUE only for the single-user
+ * `host` lane (see module header). All cloud/container lanes + any multi-tenant deployment → FALSE (cwd ignored).
+ */
 export function cwdHonored(config) {
     return config.remoteExec?.provider === "host" && config.requirePrincipal !== true;
 }
+/**
+ * [851]P3a — the OTHER host-semantics lane: provider UNSET = the in-process single-user lane. It has NO shell
+ * hands (core prepare-task: no factory/executionEnv ⇒ StubExecutionEnv), so the perSession cwd/env registries
+ * have no consumer there — but PROCESS-level consumers (hooks commands, the C4 projectContext local read) still
+ * see the engine's own `process.cwd()`/`process.env`. When the shell spawned the engine in the caller's own
+ * dir/env, a caller override is often ALREADY satisfied by that process state, and a per-task "ignored" warn
+ * contradicts it (飞轮双平台观测). Signal-truth split: satisfied ⇒ debug, real mismatch ⇒ warn. True per-session
+ * honoring remains `REMOTE_EXEC=host`. Multi-tenant excluded for the same reason as {@link cwdHonored}.
+ */
 export function inProcessSingleUserLane(config) {
     return config.remoteExec === undefined && config.requirePrincipal !== true;
 }
+/** Is a requested cwd ALREADY the engine process's working dir? realpath BOTH sides (macOS `/tmp` →
+ *  `/private/tmp`-class symlinks); either side failing to resolve ⇒ treated as a mismatch (warn — never a
+ *  false downgrade). `realpath`/`cwd` are parameters for testability; production passes `fs.realpathSync`. */
 export function satisfiedByProcessCwd(requested, realpath, cwd = process.cwd) {
     try {
         return realpath(requested) === realpath(cwd());
@@ -22,10 +62,24 @@ export function satisfiedByProcessCwd(requested, realpath, cwd = process.cwd) {
         return false;
     }
 }
+/** How many requested shellEnv entries the engine process env does NOT already carry (value-exact compare).
+ *  0 ⇒ satisfied by the inherited process state (debug, not "ignored"). Callers must log only this COUNT —
+ *  never env values (secret-class), and not key names either (a name can itself carry sensitive semantics). */
 export function shellEnvMismatchCount(requested, procEnv) {
     return Object.keys(requested).filter((k) => procEnv[k] !== requested[k]).length;
 }
+/** Cap on the number of `--add-dir` entries a caller may attach (bounds a pathological allowlist blast). */
 export const MAX_ADDITIONAL_DIRS = 64;
+/**
+ * design/119 (CC `--add-dir` parity): validate an untrusted `body.additionalDirectories` — extra host dirs the
+ * FILE tools may access beyond the containment root (core canonicalizes each into its allowlist + lists them in the
+ * `# Environment` block). Gated identically to {@link cwdHonored}: these are the caller's OWN-machine paths, so they
+ * only make sense — and are only safe — on the single-user host lane (on a cloud/container lane a file-tool root is
+ * the sandbox fs, and a multi-tenant lane must never let one caller widen containment onto operator/other-tenant
+ * host paths). Each element gets the SAME structural check as `cwd` (absolute, no `..` traversal, no NUL, capped);
+ * malformed entries are dropped (never throw), the count is bounded, and duplicates collapse. Returns undefined when
+ * nothing valid remains (so the spec field stays absent rather than an empty array). NOT an existence check.
+ */
 export function parseAdditionalDirectories(raw) {
     if (!Array.isArray(raw))
         return undefined;
@@ -35,12 +89,25 @@ export function parseAdditionalDirectories(raw) {
         if (out.length >= MAX_ADDITIONAL_DIRS)
             break;
         if (!isValidCwd(entry) || seen.has(entry))
-            continue;
+            continue; // reuse the cwd structural gate; collapse dups
         seen.add(entry);
         out.push(entry);
     }
     return out.length > 0 ? out : undefined;
 }
+/**
+ * core 1.219 `ExecutionEnvFactoryContext.parentCwd` (dogfood: sub-agents landed in an EMPTY
+ * sandbox — "当前工作目录为空"): resolve the HOST lane's effective workspace for a task. Precedence:
+ *   1. the session's explicitly-registered `cwd` (the caller's own launch dir, the cwd seam) — an explicit
+ *      per-session choice always wins;
+ *   2. the TRUSTED `ctx.parentCwd` (core threads the PARENT task's working root via `RunInternals` when this
+ *      task is a delegated child — never a TaskSpec field), UNLESS the child asked for `isolation:"worktree"`
+ *      (core contract: worktree wins — an isolated fan-out child must not share the parent's mutable dir);
+ *   3. undefined → the factory's ephemeral per-task dir (top-level task with no registered cwd).
+ * CC parity: a Task sub-agent inherits the main session's cwd. Trust: `parentCwd` comes from core's trusted
+ * run-internals channel (same posture as `isolation`), so no tenancy gate is needed here — but the HOST lane
+ * itself is single-user by deployment shape, and container lanes (k8s/e2b/local-docker) never consult this.
+ */
 export function effectiveHostWorkspace(sessionCwd, ctx) {
     return sessionCwd ?? (ctx.isolation !== "worktree" ? ctx.parentCwd : undefined);
 }

package/dist/task-mcp.d.ts

@@ -1,13 +1,60 @@
+/**
+ * [TOC MCP seam, R3] — project the TOC client's local
+ * `.mcp.json` (`TaskRequest.mcpServers`) into the engine, so a `sema` run honors the user's own MCP servers
+ * (CC-parity "配置即用" local-first), instead of ONLY the center-config MCP. Mirrors the `cwd` seam (task-cwd.ts).
+ *
+ * 🔒 SECURITY — per-request MCP is the constitutional "untrusted-client tool injection" red line, because an MCP
+ * server is a TOOL SOURCE and an stdio transport is **arbitrary command execution**. The decisive fact (verified):
+ * core materializes stdio MCP with `StdioClientTransport`, which spawns the command as a child of **the WORKER
+ * (core's process), NOT the execution env** — so an stdio MCP runs on the worker host REGARDLESS of the exec lane
+ * (host/e2b/docker). Therefore the trust boundary is NOT "the host execution lane" (that's where the agent's TOOL
+ * CALLS run, irrelevant to MCP) — it is **"is the worker single-user, i.e. is the requester the super-admin?"** =
+ * `requirePrincipal !== true`. core's ruling (R3): the SERVICE is core's caller-trust-root; body→`TaskSpec.mcp` is a
+ * trust decision the service makes, never a passthrough.
+ *   - SINGLE-USER deployment (`requirePrincipal===false`): the requester IS the super-admin of their own worker, so
+ *     their `.mcp.json` is authoritative — exactly what CC does on the user's machine. This holds across EVERY
+ *     execution lane (host / E2B / k8s / local-docker), so a TOC user who switches execution local↔cloud keeps their
+ *     MCP honored seamlessly (TOC↔cloud is a spectrum, not a wall — clay 2026-06-29: TOB = single-user + people-mgmt).
+ *     The caller being the trust root, `toolAxes` (authoritative effect overrides) + `elicitation` are their own choices.
+ *   - MULTI-TENANT deployment (`requirePrincipal===true`): a tenant must NOT make the SHARED worker run an arbitrary
+ *     command (RCE) or connect to a body-chosen URL (SSRF). Gate CLOSED → body MCP ignored; the fleet gets MCP only
+ *     through center config refs. Per-principal http-remote injection (a center `allowMcpInjection` entitlement via
+ *     `runtimeCapsResolver`) is a DEFERRED v2.
+ * When the gate is closed, a sent `mcpServers` is IGNORED (advertised via `capabilities.mcpInjection`).
+ */
 import type { McpServerSpec } from "@sema-agent/core";
+/** Bound on caller-supplied servers (anti-DoS; a real local `.mcp.json` has a handful). */
 export declare const MAX_REQUEST_MCP_SERVERS = 32;
+/**
+ * Does THIS deployment honor caller-supplied per-request MCP servers? TRUE for a SINGLE-USER deployment
+ * (`requirePrincipal !== true`) — the requester is the super-admin of their own worker, so their `.mcp.json` is
+ * authoritative (CC-parity), on ANY execution lane (the stdio command runs on the worker, not the exec env, so the
+ * lane is irrelevant — see module header). FALSE on a multi-tenant deployment (a tenant can't make the shared worker
+ * run an arbitrary command / connect to an arbitrary URL).
+ */
 export declare function mcpInjectionHonored(config: {
     requirePrincipal?: boolean;
 }): boolean;
+/**
+ * Shape-check the raw `body.mcpServers`. `null` → a non-array (caller error; the route may 400). Otherwise the
+ * valid subset + the names of dropped (malformed/over-cap) entries.
+ */
 export declare function validateRequestMcp(raw: unknown): {
     ok: McpServerSpec[];
     dropped: string[];
 } | null;
+/**
+ * Merge GATED per-request MCP servers OVER the deployment baseline (center/config). The baseline WINS on a name
+ * clash — a caller can ADD servers but can never SHADOW a configured one (the security baseline is authoritative,
+ * same posture as `mergeUserSkills`). Returns the baseline unchanged when there is nothing to add.
+ */
 export declare function mergeRequestMcp(baseline: McpServerSpec[] | undefined, gated: McpServerSpec[]): McpServerSpec[] | undefined;
+/**
+ * The single entry point the spec-builder calls: compute the effective `TaskSpec.mcp` = deployment baseline + the
+ * caller's gated per-request servers. Off the honored lane (or with no caller servers) returns the baseline
+ * unchanged. Logs an `mcp_injection_ignored` when a caller SENT servers a closed gate dropped (so the shell never
+ * silently believes its `.mcp.json` took effect — it also reads `capabilities.mcpInjection`).
+ */
 export declare function resolveRequestMcp(baseline: McpServerSpec[] | undefined, bodyMcp: unknown, config: {
     remoteExec?: {
         provider?: string;

package/dist/task-mcp.js

@@ -1,10 +1,19 @@
+/** Bound on caller-supplied servers (anti-DoS; a real local `.mcp.json` has a handful). */
 export const MAX_REQUEST_MCP_SERVERS = 32;
+/**
+ * Does THIS deployment honor caller-supplied per-request MCP servers? TRUE for a SINGLE-USER deployment
+ * (`requirePrincipal !== true`) — the requester is the super-admin of their own worker, so their `.mcp.json` is
+ * authoritative (CC-parity), on ANY execution lane (the stdio command runs on the worker, not the exec env, so the
+ * lane is irrelevant — see module header). FALSE on a multi-tenant deployment (a tenant can't make the shared worker
+ * run an arbitrary command / connect to an arbitrary URL).
+ */
 export function mcpInjectionHonored(config) {
     return config.requirePrincipal !== true;
 }
 function isStringRecord(v) {
     return !!v && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
 }
+/** Validate + normalize ONE caller entry to a core `McpServerSpec`, or null if malformed (dropped, not fatal). */
 function normalizeServer(e) {
     if (!e || typeof e !== "object")
         return null;
@@ -27,6 +36,7 @@ function normalizeServer(e) {
         };
     }
     else if (tr.kind === "http") {
+        // http(s) only — never file://, never a bare host (a syntactic guard; cloud http injection is still gated off-lane).
         if (typeof tr.url !== "string" || !/^https?:\/\//i.test(tr.url))
             return null;
         transport = {
@@ -42,14 +52,18 @@ function normalizeServer(e) {
     const spec = { name: o.name, transport };
     if (Array.isArray(o.allowTools) && o.allowTools.every((a) => typeof a === "string"))
         spec.allowTools = o.allowTools;
+    // caller-trust-root (host-lane single-user): the user's own effect/elicitation choices are kept (CC-parity).
     if (typeof o.elicitation === "boolean")
         spec.elicitation = o.elicitation;
     if (o.toolAxes && typeof o.toolAxes === "object" && !Array.isArray(o.toolAxes)) {
+        // 轴B #6(1.254):裸 cast 换 per-key 形状校验——单用户 caller-trust-root 姿势不变(值语义仍由 caller
+        // 定),只挡畸形值直达 core(非对象条目/未知枚举字段值静默剔除,诚实收窄不 400)。
         const axes = {};
         for (const [tool, ax] of Object.entries(o.toolAxes)) {
             if (!ax || typeof ax !== "object" || Array.isArray(ax))
                 continue;
             const a = ax;
+            // 真域对齐 core types(自查纠偏:egress 是 boolean、irreversibility 是 "always"|"never")
             const entry = {
                 ...(a.effect === "read" || a.effect === "write" || a.effect === "idempotent" ? { effect: a.effect } : {}),
                 ...(typeof a.egress === "boolean" ? { egress: a.egress } : {}),
@@ -63,6 +77,10 @@ function normalizeServer(e) {
     }
     return spec;
 }
+/**
+ * Shape-check the raw `body.mcpServers`. `null` → a non-array (caller error; the route may 400). Otherwise the
+ * valid subset + the names of dropped (malformed/over-cap) entries.
+ */
 export function validateRequestMcp(raw) {
     if (raw === undefined || raw === null)
         return { ok: [], dropped: [] };
@@ -81,6 +99,11 @@ export function validateRequestMcp(raw) {
         dropped.push(`(+${raw.length - MAX_REQUEST_MCP_SERVERS} over cap of ${MAX_REQUEST_MCP_SERVERS})`);
     return { ok, dropped };
 }
+/**
+ * Merge GATED per-request MCP servers OVER the deployment baseline (center/config). The baseline WINS on a name
+ * clash — a caller can ADD servers but can never SHADOW a configured one (the security baseline is authoritative,
+ * same posture as `mergeUserSkills`). Returns the baseline unchanged when there is nothing to add.
+ */
 export function mergeRequestMcp(baseline, gated) {
     if (gated.length === 0)
         return baseline;
@@ -88,6 +111,12 @@ export function mergeRequestMcp(baseline, gated) {
     const add = gated.filter((s) => !taken.has(s.name));
     return add.length === 0 ? baseline : [...(baseline ?? []), ...add];
 }
+/**
+ * The single entry point the spec-builder calls: compute the effective `TaskSpec.mcp` = deployment baseline + the
+ * caller's gated per-request servers. Off the honored lane (or with no caller servers) returns the baseline
+ * unchanged. Logs an `mcp_injection_ignored` when a caller SENT servers a closed gate dropped (so the shell never
+ * silently believes its `.mcp.json` took effect — it also reads `capabilities.mcpInjection`).
+ */
 export function resolveRequestMcp(baseline, bodyMcp, config, logger) {
     if (bodyMcp === undefined || bodyMcp === null)
         return baseline;