@sema-agent/server 7.43.0 → 7.44.0

package/dist/task-cwd.js

@@ -1,29 +1,5 @@
-/**
- * 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 &&
@@ -32,67 +8,16 @@ 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;
 }
-/**
- * #295(F-1,[4512] 修向 (b')):卡批「不再询问」落盘规则的 **project root** —— 「这次授权是在哪个
- * 工作目录里点的」。取值与既有 cwd 语义同源,不新造坐标系:
- *   1. session 显式注册的 cwd(cwd seam,host lane;与 {@link effectiveHostWorkspace} 第 1 优先级同源)
- *      —— **今天唯一真的会命中的那一臂**;⚠️ 它**不含 lane 判据**,lane 语义完全依赖「`perSessionCwd`
- *      只在 `cwdHonored` 为真时被写」这条跨文件外部不变量(写侧唯一入口 boot/resolve-spec.ts)。这是
- *      刻意的单写者惯用法,不是疏漏:在消费端补第二道闸 = 把一条不变量拆给两个属主(同族消费者
- *      {@link effectiveHostWorkspace} 形状完全相同)。机器背书 = test/task-cwd.test.ts 的 A-054.2 两格。
- *   2. 🔴 **前瞻/防御臂,本仓当前装配下零命中**(A-054.21,2026-08-19 合并重扫 partial,存活断言):
- *      in-process 单用户 lane({@link inProcessSingleUserLane})取引擎自身 `process.cwd()`。它读起来像在
- *      服务一个真部署形,其实到不了 —— 该 lane 的 `remoteExec` 未设 ⇒ boot/execution-env.ts 六条工厂臂全
- *      不命中 ⇒ core 落 `StubExecutionEnv` ⇒ `handsEnabled=false` ⇒ 不挂 Bash ⇒ 未知工具在 agent-loop 走
- *      `tool.not_found`(**不进审批座**)⇒ 无 `ruleSuggestions` ⇒ 本函数在规则车道上根本不被调用;同 lane
- *      第 1 臂也因写侧闸只在 `cwdHonored` 下开而恒空。危害口径按 refuter **降级**:死枝 ≡ 落第 3 臂
- *      `undefined` ≡ core global 缺省 ≡ #295 修前行为,**今天零用户可见伤害**,不是「恒不命中」类缺陷。
- *      🚧 **给将来接手的人的红线**:这条 lane 若哪天真接上 hands,root 必须取 `executionEnv.cwd`(core 的
- *      `taskRootFinal` 就是它),**不是** `process.cwd()` —— 两者在静态 env 装配形下可以完全不同,照现注
- *      直接接线会铸出一个真的歪 root。真正的本地开箱形(`CONFIG_PROVIDER=local`)被 config 默认成
- *      **host** lane,受益的是第 1 臂;本臂不是「#295 的本地形受益臂」。
- *   3. 其余(远程沙箱 / REMOTE_EXEC=host 未注册 / 多租户)⇒ `undefined`:root 在 server 坐标系里
- *      不可知,调用方**不铸 scope**,落 core 的 global 缺省(= #295 修前行为,恒不更宽;也绝不铸一个
- *      与规则判定时 cwd 不同坐标系的 root —— 那会静默把「不再询问」变成恒不命中)。
- *
- * 🔴 出口 = `path.resolve(原字节)`,**禁 realpath**(A-054.F-A,2026-08-19 合并重扫 confirmed high):
- * core 判定这条规则时喂进 `scopeCoversCwd` 的 cwd = `executionEnv.cwd` = host env 构造里的
- * `path.resolve(同一条注册原字节)`(remote-env-host.ts),比较是**纯串**(`pathWithinRoot`,零
- * realpath)。初版这里走 realpath(据 core `PersistedAllowRule.scope` JSDoc「root 由构造方
- * canonicalize」)——但 JSDoc 说的是义务、实现行才是事实([3578] 宪法):core 自己喂进匹配的 cwd
- * 恰恰**未** canonicalize,单侧规范化=两坐标系分叉,注册 cwd 含符号链接段时(macOS `/tmp`、
- * `~/work→/mnt/...`)落盘规则**永不命中**,「不再询问」恒失效。正解=root 与判定坐标出自**同一条
- * 串、同一种规范化**;将来 core 若把判定面改 canonicalize,这里必须同批跟(端到端钉在
- * test/task-cwd.test.ts 的 A-054.F-A 格,靠真 `scopeCoversCwd` 咬住两侧任何一侧的单独漂移)。
- * `path.resolve` 不抛 ⇒ 初版的 realpath 失败 F 类兜底臂(`rule-scope-root-unresolvable`)随之退役
- * (census 行同批销,fail-open.ts)。
- */
 export function cardRuleScopeRoot(registeredCwd, config, cwd = process.cwd) {
     const raw = registeredCwd ?? (inProcessSingleUserLane(config) ? cwd() : undefined);
     return raw === undefined ? undefined : path.resolve(raw);
 }
-/** 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());
@@ -101,24 +26,10 @@ 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;
@@ -128,25 +39,12 @@ export function parseAdditionalDirectories(raw) {
         if (out.length >= MAX_ADDITIONAL_DIRS)
             break;
         if (!isValidCwd(entry) || seen.has(entry))
-            continue; // reuse the cwd structural gate; collapse dups
+            continue;
         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.js

@@ -1,52 +1,9 @@
-/**
- * [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 { resolveComplianceDenies } from "@sema-agent/core";
 import { HttpError } from "./security.js";
-/** 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) {
-    // design/170 件C(codex 对抗复审 F2,验真后采纳):**锁也是这条轴的一票否决**。旧谓词只看租户轴,
-    // 于是「单用户 + `mcp` 锁」的部署会广告 `mcpInjection:true`,而每一个照此渲出 affordance 的调用方发过
-    // 来都吃 `config.locked_key` 400 —— 本仓 capabilities 面的立面承诺(「says yes ⟺ route works」)当场破。
-    // 判据合取在这里而不是在能力位那行,是因为这只谓词是**唯一**属主(能力位与请求腿都读它)。
     if (config.lockedConfigKeys?.includes("mcp") === true)
         return false;
-    // 件B 同族(R2-F2):合规档位禁了 `mcp_servers` 时,core 对**带 spec.mcp 的每一条腿**整拒 prepare
-    // (`config.compliance_denied`,亲核 prepare-task 的 compliance 段)。同样是「广告了却用不了」,同样一票否决。
-    //
-    // ⚠️ **刻意不 catch**(#191 门② SHAPE C 当场逮到的那一版已撤):`resolveComplianceDenies` 对闭集外的值
-    // 是 fail-loud 的,而这个档位在到这里之前已经被验过两遍(config 解析层 + boot 装配层),所以它在本站点
-    // 抛不出来。真抛了 = 有人绕过那两道门往 config 里塞了一个解析不了的档位 —— 那种时候**响亮**(路由 500)
-    // 才是对的方向,吞成一个布尔位等于让一台档位坏掉的部署继续对外广告能力位(安全轴禁静默兜底)。
     if (config.compliancePosture !== undefined && resolveComplianceDenies(config.compliancePosture).has("mcp_servers"))
         return false;
     return config.requirePrincipal !== true;
@@ -54,7 +11,6 @@ export function mcpInjectionHonored(config) {
 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;
@@ -77,7 +33,6 @@ 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 = {
@@ -91,27 +46,19 @@ function normalizeServer(e) {
         return null;
     }
     const spec = { name: o.name, transport };
-    // #272(#269 车1 codex F1 的孪生修,2026-08-16):`allowTools` 是**收窄**字段,core 把缺席解释成
-    // 「不限制」——旧形「坏形丢键、server 照挂」= 调用方要求只挂一条,实际挂上远端全部工具(每条还可能
-    // 带 write 语义),收窄意图坏形时退化成放行。判据与 task-a2a.ts 同一句:**一个键在场就必须合法,
-    // 否则这条 server 整条不进**(null ⇒ 上层记 dropped 带名)。缺席仍合法=真「不限制」。
     if (o.allowTools !== undefined) {
         if (!Array.isArray(o.allowTools) || !o.allowTools.every((a) => typeof a === "string"))
             return null;
         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 } : {}),
@@ -125,10 +72,6 @@ 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: [] };
@@ -147,23 +90,6 @@ export function validateRequestMcp(raw) {
         dropped.push(`(+${raw.length - MAX_REQUEST_MCP_SERVERS} over cap of ${MAX_REQUEST_MCP_SERVERS})`);
     return { ok, dropped };
 }
-/**
- * design/170 件C §4.3 —— **同步**拒面:部署锁了 `mcp` 而请求仍带 `mcpServers` ⇒ 400 `config.locked_key`。
- *
- * 为什么在这里也拒一次(与 core 的 prepare 门不是「两处裁决」):设计稿把裁决点定在 server 治理层,
- * core 的 preflight 执行的是**同一条**判据的引擎侧终局形。二者语义等价、位置不同 —— 一个请求根本不该
- * 进 core 才发现自己被锁,而消费端拿到一条同步 4xx 比拿到一个跑起来又终态失败的任务可诊断得多。
- *
- * 判据是「请求**占位**」而不是「请求的值合不合法」:锁是两态的,占了就整拒,不静默丢(静默丢正是
- * design/170 §2.3 讲的那种把判决变成探针的形)。键缺席 / 显式 `null` 都不是占位。
- *
- * ⚠️ **不看车道**:多租户腿本来就会忽略 body MCP(`mcpInjectionHonored` 关),但锁在场时忽略是错的
- * 失败方向 —— operator 声明了「本部署不收任务自带 MCP」,那就该说出来,而不是安静地当没看见。
- *
- * ⚠️ **resume 腿同拒,这是刻意的**(与本仓「4xx 会砖存量 task」的一般姿势有意分歧):锁上之后,一条存量
- * 任务的 body 里带着 mcpServers 就再也过不了 core 的 preflight —— 放它进去只会换来一个跑起来又终态失败的
- * 任务。同样是失败,同步 400 至少是**立刻可诊断**的那一种,而且拒得出理由(锁在哪、怎么改)。
- */
 export function assertRequestMcpUnlocked(bodyMcp, lockedKeys) {
     if (!lockedKeys.has("mcp"))
         return;
@@ -173,11 +99,6 @@ export function assertRequestMcpUnlocked(bodyMcp, lockedKeys) {
         code: "config.locked_key",
     });
 }
-/**
- * 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;
@@ -185,16 +106,7 @@ 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, 
-// `lockedConfigKeys` 随 config 一并进(design/170 件C):`assertRequestMcpUnlocked` 已在腿首整拒,所以
-// 这里的 honored 判据在锁形下不可达 —— 保留它是纵深(判据只有一只谓词,不许两处各判一半)。
-config, logger) {
+export function resolveRequestMcp(baseline, bodyMcp, config, logger) {
     if (bodyMcp === undefined || bodyMcp === null)
         return baseline;
     const honored = mcpInjectionHonored(config);