@sema-agent/server 7.43.0 → 7.44.0

package/dist/spec-fields.js

@@ -1,36 +1,15 @@
-/**
- * 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; // false / absent / non-object / array ⇒ off
+        return undefined;
     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;
@@ -42,20 +21,9 @@ 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)
@@ -69,9 +37,6 @@ export function normalizeAttachments(v) {
         ...(o.todoReminder === true ? { todoReminder: true } : {}),
         ...(changedFiles !== undefined ? { changedFiles } : {}),
         ...(o.planModeReminder === true ? { planModeReminder: true } : {}),
-        // core 1.253 G1 → 5.12.0 BREAKING-3:压缩后 bg 任务重述从 opt-in 翻 **DEFAULT-ON**(显式 false
-        // 恒关/缺席走默认)。literal-true 形在此翻转后就是轴B #1 的原案复刻(agentListing/skillsListing
-        // 当年同病):丢 false = 客户端显式关断被静默压成默认 ON,wire 上无法表达关闭 ⇒ 迁 boolean 透传。
         ...(typeof o.backgroundTasks === "boolean" ? { backgroundTasks: o.backgroundTasks } : {}),
         ...(o.toolsDelta === true ? { toolsDelta: true } : {}),
         ...(o.todoReminderMode === "baseline" || o.todoReminderMode === "off" ? { todoReminderMode: o.todoReminderMode } : {}),
@@ -82,30 +47,18 @@ 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; // whenToUse/whenToUseLean/observer/observerMessage
+const MAX_AGENT_TEXT_CHARS = 4_096;
 const MAX_AGENT_SYSTEM_PROMPT_CHARS = 65_536;
-const MAX_AGENT_TOOLS = 64; // allowTools/denyTools entries
+const MAX_AGENT_TOOLS = 64;
 const MAX_AGENT_TOOL_NAME_CHARS = 128;
-const MAX_AGENT_SKILLS = 10; // 与 MAX_USER_SKILLS 同轴
+const MAX_AGENT_SKILLS = 10;
 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;
@@ -113,9 +66,6 @@ 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;
@@ -129,8 +79,6 @@ 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))
@@ -160,10 +108,6 @@ const skillOk = (s) => {
     }
     return true;
 };
-/** MemorySpecInput 闭合白名单(core dist/core/memory.d.ts 亲读)。core 的 normalizeMemorySpec 会直接
- *  迭代 `scopes` —— 非数组形状(如 {scopes:{length:1}})在服务门不拦就是 core 运行期异常(cross-review 抓获)。
- *  core 5.1.0([2390]②,原 [2387] 预告):单数 `scope` 键已删,`scopes: string[]` 唯一拼法——白名单
- *  同步剔键,收了就是穿门死键(用户以为设了 scope,core 静默无视)。 */
 const memoryOk = (v) => {
     if (!plainObject(v))
         return false;
@@ -181,12 +125,6 @@ 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`,
@@ -217,12 +155,6 @@ 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";
@@ -244,9 +176,6 @@ 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";
@@ -264,14 +193,6 @@ 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;
@@ -310,19 +231,10 @@ 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;
@@ -332,61 +244,28 @@ 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)。
- *
- *  ⚠️ **这不是一条 defer 注**(#277 件⑤ 对表结论,core [4352] 同判):本段说的是 `promptProfile` 这根
- *  **呈现**轴,它与 `deferMode` / `deferTools` 的延迟披露轴**无耦合** —— 上一行提 deferTools 只是在借它
- *  的「无租户门」姿势作类比。「引擎缺省 simple」这句本身在 core 5.40.0 上仍逐字为真
- *  (`core/types.d.ts:133`:default "simple"),本批亲验未变。
- *  真正的 defer 轴对表(core 5.40.0 起 `deferMode:"auto"` 不再 sweep 内建)记在
- *  `src/capabilities/tool-defer.ts` 的头注 —— 别把两根轴的结论写到一处。
- *  DEFENSIVE(resume 重放不过 HTTP 400 门):非法值 ⇒ undefined;提交面另有 fail-loud 400(邻居姿势)。 */
 export function promptProfileFromBody(raw) {
     return raw === "simple" || raw === "classic" ? raw : undefined;
 }
-/** [2856]②(core 5.14.0 `TaskSpec.toolMaterializeStrategy`):deferred 工具激活后的 schema 供给策略。
- *  与 {@link promptProfileFromBody} 同姿势的**防御性归一**——提交面的 fail-loud 400 在 HTTP 门,这里
- *  只负责 resume 重放存量 body 时把不认识的值静默 DROP(回落 core 的 env/缺省链),而不是把它带上 spec。 */
 export function toolMaterializeStrategyFromBody(raw) {
     return raw === "static" || raw === "swap" ? raw : undefined;
 }
-/** core 5.8.0 时限重构的退役键(fresh-submit 在 HTTP 门 400 点名;resume 重放在 normalize 层 DROP)。 */
 const RETIRED_LIMIT_KEYS = ["timeoutSec", "deadlineNudge", "callCapByDeadline", "gracefulFinalize"];
-/** 在场的退役键(normalizeLimits/resolveTaskLimits 共用判据源:留痕事件的 droppedKeys 字段)。 */
 function retiredLimitKeysPresent(v) {
     if (v == null || typeof v !== "object" || Array.isArray(v))
         return [];
     const o = v;
     return RETIRED_LIMIT_KEYS.filter((k) => o[k] !== undefined);
 }
-/**
- * [854]④ — normalize `body.limits` → 请求方配速意图 {maxWalltimeMs?, maxOutputTokens?, maxTurns?}。DEFENSIVE
- * (resume 重放持久化 body 不过 HTTP 400 门):仅正的有限数字存活(floor 取整),0/负/垃圾按键 DROP —— core 侧
- * 墙钟 > 0 才生效(0=不设墙,会绕过运营方封顶)、maxTurns/maxOutputTokens 的 0 无意义。每键各自被
- * 运营方上限旋钮 clamp(Math.min;旋钮缺省不设=不封顶)。全空 ⇒ undefined。
- */
 export function normalizeLimits(v, caps, warn) {
     if (v == null || typeof v !== "object" || Array.isArray(v))
         return undefined;
-    // core 5.8.0:键集换 maxWalltimeMs(毫秒)。旧键(timeoutSec/deadline 族三 opt-out)fresh-submit 已在
-    // HTTP 门响亮 400 点名替代;本层只走 resume 重放的持久化 body——旧键 defensive DROP 但**必须留痕**
-    // (task_limits_legacy_key_dropped):丢 caller 显式时限=收窄契约,存量 suspended 体降级为默认配速时,
-    // 单用户 turnkey 无 env 墙 ⇒ 整任务无墙钟、多租 ⇒ 被延到租户墙(2400/3600s)——两向都可能长于原意图。
-    // 绝不静默换算=那是「自行兼容」,core 明令禁止。
     const dropped = retiredLimitKeysPresent(v);
     if (dropped.length > 0)
         warn?.("task_limits_legacy_key_dropped", { droppedKeys: dropped });
@@ -398,18 +277,13 @@ export function normalizeLimits(v, caps, warn) {
         return cap !== undefined ? Math.min(n, cap) : n;
     };
     const out = {
-        // caps.timeoutSec 是秒(env TASK_TIMEOUT_MAX_SEC 保名保义),封顶毫秒键时 ×1000。
         ...(() => { const n = pick(o.maxWalltimeMs, caps.timeoutSec !== undefined ? caps.timeoutSec * 1000 : undefined); return n !== undefined ? { maxWalltimeMs: 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 } : {}; })(),
-        // 166-T3:approachNotice(core 默认 ON;false=唯一关闭形,{at:[a,b]} 调阈,core 允 a<=b)。坏形整键
-        // DROP(降级为 core 默认阈,方向安全)——不 throw,resume 重放通道同门。
         ...(() => { const n = normalizeApproachNotice(o.approachNotice); return n !== undefined ? { approachNotice: n } : {}; })(),
     };
     return Object.keys(out).length > 0 ? out : undefined;
 }
-/** 166-T3 — approachNotice 单键归一(normalizeLimits/HTTP 门共用判据源):合法 ⇒ 归一值,坏形 ⇒ undefined。
- *  阈值规则对齐 core(prepare-task at 校验):二元组、(0,1] 有限数、a<=b(允许相等)。 */
 export function normalizeApproachNotice(raw) {
     if (raw === false)
         return false;
@@ -424,22 +298,9 @@ export function normalizeApproachNotice(raw) {
     const frac = (n) => typeof n === "number" && Number.isFinite(n) && n > 0 && n <= 1;
     return frac(a) && frac(b) && a <= b ? { at: [a, b] } : 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, warn) {
-    // 留痕事件在本层发(不透传给 normalizeLimits,免双发):只有装配点知道最终生效墙钟——
-    // effectiveMaxWalltimeMs: null = 整任务无墙(单用户 turnkey 无 env 墙时丢弃旧 timeoutSec 的真后果)。
     const dropped = retiredLimitKeysPresent(bodyLimits);
     const requested = normalizeLimits(bodyLimits, caps);
-    // core 5.8.0:墙钟键=maxWalltimeMs(毫秒)。taskWallClockSec 仍以秒推导(tenancy 基值+env 只抬不降,
-    // 语义原样),装配处换算一次;body 显式给了 maxWalltimeMs 则直接生效(caller 意图,可低于 env 墙)。
     const wallSec = taskWallClockSec(envTimeoutSec, requirePrincipal, big);
     const maxWalltimeMs = requested?.maxWalltimeMs ?? (wallSec !== undefined ? wallSec * 1000 : undefined);
     if (dropped.length > 0)

package/dist/store-live-probe.js

@@ -1,38 +1,4 @@
-/**
- * B1(鲁棒性批3 立案的设计件):/health 活体 store 探测的后台缓存环。
- *
- * 为什么是缓存环而不是逐请求探:/health 是 fleet center/k8s 的高频面(10-15s 一拍×N 消费方),
- * 逐请求打 DB 会把健康检查本身变成负载源、且慢 store 直接拖垮 /health 的「必须回答此刻」承诺。
- * 环产出的 state 由 /health 的 additive 键族消费(座注见 http/server.ts `storeLiveState`;
- * 键形钉在 test/health-store-live.test.ts,本环判据钉在 test/store-live-probe.test.ts)。
- *
- * 判据:
- * - 有界:单拍探针经 STORE_PROBE_TIMEOUT_MS race——挂死的 pool(半开连接)不得钉死环;
- * - 翻转披露(§M):live→dead warn `store_probe_dead`、dead→live info `store_probe_recovered`,
- *   只在翻转拍记(连续死不逐拍刷日志——down 的 DB 不该制造日志风暴);
- * - 诚实缺席:首拍落地前 state() = undefined(/health 键缺席=「还没探过」,不冒充「活」)。
- * - 面分级(#305):`state().error` 是**原始** message —— 它只喂给凭证后/本机的消费面;免鉴权的
- *   `/health` 一格由 wire 装配点过 {@link publicStoreProbeError} 换成闭集词(理由见该常量头注)。
- *
- * 探针原语:调用方给 `probe`(main.ts 传 `() => backend.dbNowMs!()`——既有 S10 时钟探针的真 DB
- * 往返,零新 SQL 面)。timer 全部 unref(环不得阻止进程退出)。
- */
-/** 单拍探针上界——挂死连接的判死时间;3s 对 15s 默认间隔留足余量(环内串行,无叠拍)。 */
 export const STORE_PROBE_TIMEOUT_MS = 3000;
-/**
- * #305(安全轴):`/health` 免鉴权面上 `storeProbe.error` 可披露的**闭集词表**。
- *
- * 为什么必须是闭集而不是「脱敏后的原文」:`/health` 排在 `http/server.ts` 的鉴权门**之前**、缺省全网卡
- * 监听 ⇒ 任何能连到这个端口的人都读得到这一格;而它此前装的是**驱动原始异常 message 逐字**,DB 驱动
- * 的连接类异常惯于把整条 DSN 回声进去(`mysql://user:pass@host:3306/db`)或带上内网主机名/账号名。
- * `trace/redact.ts` 的 `redactSecrets` **挡不住这条**:它的 URL-userinfo 规则只把口令换成 `«redacted»`,
- * **用户名与 `@` 之后的主机原样留下** —— 而本条要防的正是那两个。闭集词是严格更强的形(值恒为下列
- * 字面量之一,构造上不可能携带调用方文本),因此不再叠加脱敏/长度帽:对一个恒为字面量的返回值,那两道
- * 都只是装饰。
- *
- * 信息不丢:**完整原文走日志轴** —— 环在 live→dead 翻转拍打的 `store_probe_dead` warn 带 `{ error }`
- * 原文,运维在自己的日志/采集里读得到全文,那一面本来就是凭证后的。
- */
 export const STORE_PROBE_PUBLIC_PHRASES = [
     "probe_timeout",
     "connection_refused",
@@ -42,21 +8,12 @@ export const STORE_PROBE_PUBLIC_PHRASES = [
     "network_timeout",
     "auth_failed",
     "connection_limit",
-    /** 未识别臂 —— **刻意的**:分类不认得的异常一律丢原文取本词(fail-closed 的默认方向是「少说」,
-     *  不是「截断了再说」;截断的前 160 字恰恰是驱动最爱放 DSN 的位置)。 */
     "probe_failed",
 ];
-/**
- * 原始探针异常 message → 免鉴权面可披露的闭集词。**返回值恒是 {@link STORE_PROBE_PUBLIC_PHRASES} 的
- * 一个字面量**(返回类型即闭集,写错一个词是编译错误),永不回声入参。
- *
- * 误分类的代价是「运维读到的分类不精确」,**不是泄露** —— 所以这里的判别用宽松的子串包含即可,不必为
- * 精确性把原文碎片带出来。臂序有意义:自家的 race 超时先于泛化的 timeout 臂。
- */
 export function publicStoreProbeError(raw) {
     const t = raw.toLowerCase();
     if (t.includes("probe timed out"))
-        return "probe_timeout"; // 本环自铸的 race 超时(见 probeOnce)
+        return "probe_timeout";
     if (t.includes("econnrefused") || t.includes("connection refused"))
         return "connection_refused";
     if (t.includes("econnreset") || t.includes("connection reset"))
@@ -67,11 +24,9 @@ export function publicStoreProbeError(raw) {
         return "dns_failure";
     if (t.includes("etimedout") || t.includes("timed out") || t.includes("timeout"))
         return "network_timeout";
-    // mysql `ER_ACCESS_DENIED_ERROR` / pg `28P01 password authentication failed` / 通用 auth 措辞。
     if (t.includes("access denied") || t.includes("authentication failed") || t.includes("28p01") || t.includes("er_access_denied") || t.includes("er_dbaccess_denied")) {
         return "auth_failed";
     }
-    // mysql `ER_CON_COUNT_ERROR` / pg `53300 sorry, too many clients already` / 池耗尽措辞。
     if (t.includes("too many connections") || t.includes("too many clients") || t.includes("53300") || t.includes("er_con_count_error") || t.includes("connection slots")) {
         return "connection_limit";
     }
@@ -101,17 +56,16 @@ export function createStoreLiveProbe(opts) {
                 clearTimeout(timer);
         }
         if (stopped)
-            return; // stop() 与在飞拍竞速:停后不再改 state、不再记翻转
+            return;
         const live = error === undefined;
         const prev = last;
         last = { live, at: Date.now(), ...(error !== undefined ? { error } : {}) };
-        // 翻转披露:首拍即死也算翻转(prev undefined → dead);连续同态不刷。
         if (!live && prev?.live !== false)
             opts.logger?.warn?.("store_probe_dead", { error });
         if (live && prev?.live === false)
             opts.logger?.info?.("store_probe_recovered", { deadForMs: Date.now() - prev.at });
     };
-    void probeOnce(); // 首拍立即(不等首个 interval——启动后 15s 盲窗没有必要)
+    void probeOnce();
     const loop = setInterval(() => void probeOnce(), opts.intervalMs);
     loop.unref?.();
     return {

package/dist/task-a2a.js

@@ -1,72 +1,10 @@
-/**
- * [DESIGN-269 车1 §2.2/§2.3 — A2A client seam] — project a caller's per-request A2A peers
- * (`TaskRequest.a2aPeers`) into the engine, so a `sema` run can talk to the agents the USER declares,
- * not only the ones the deployment's config center declares. Point-for-point mirror of `task-mcp.ts`
- * (the MCP seam), because the trust question is the same question — and deliberately NOT a copy where
- * the two protocols differ (see 「A2A 比 MCP 窄」 below).
- *
- * 🔒 SECURITY — an A2A peer is a remote **AGENT**, not a data source: it acts on its own side. core ruled
- * (2026-08-03, `A2aServerSpec` doc) that every skill such a peer advertises mounts with `egress: true` +
- * `effect: "write"`, i.e.接入即引入对外写通道 — it registers the approval gate, is never auto-allowed on a
- * no-policy deployment, and its replies reach the model inside an untrusted-data fence. The trust boundary
- * is therefore the SAME one the MCP seam draws, for the same reason:
- *   - SINGLE-USER deployment (`requirePrincipal !== false`… i.e. `!== true`): the requester IS the
- *     super-admin of their own worker, so the peers they name are their own choice (CC-parity), on EVERY
- *     execution lane — an A2A call is a plain outbound HTTPS request made by the worker, so the lane where
- *     the agent's TOOL CALLS run is irrelevant (exactly the fact that decoupled the MCP gate from the lane).
- *   - MULTI-TENANT deployment (`requirePrincipal === true`): a tenant must NOT make the SHARED worker POST
- *     to a body-chosen URL (SSRF) carrying body-chosen headers, nor mount write-capable tools from an agent
- *     the operator never vetted. Gate CLOSED → body peers ignored; the fleet gets peers only through center
- *     config (`config.a2aPeers`).
- * When the gate is closed a sent `a2aPeers` is IGNORED — and SAID (`a2a_injection_ignored` + the
- * `capabilities.a2aInjection` advertisement), never silently swallowed.
- *
- * ⚠️ **A2A 的轴比 MCP 窄,这不是简化而是协议事实**:A2A has no per-skill annotation vocabulary, so there is
- * no server-hint leg to fold — `toolAxes` (the CALLER's own judgement) is the ONLY thing that can move an axis
- * off the fail-closed default. core says as much on `A2aToolAxis`: `irreversibility:"never"` / `egress:false`
- * 「appears ONLY via an explicit caller override」, enforcement ignores the loosening (tighten-only) and the
- * ask's risk-axes REPORT face consumes it. So this module carries the caller's overrides through verbatim —
- * they are a judgement, not silence — while knowing that core will not let them widen enforcement.
- *
- * ⚠️ **两票判据的词表在 core 5.36 尚未到货**(分单件 C-1/C-2,core 已认领排 5.37 后首个 A2A 窗):
- * `LockedKey` 是 `"mcp"|"toolPolicy"|"compliancePosture"|"retentionPolicy"`,`ComplianceCapability` 是
- * `"mcp_servers"|"workflows"|"web_fetch"|"org_memory_mount"` —— 两张表里都还没有 A2A 的位。本模块因此按
- * **字符串**判(server config 的 `lockedConfigKeys` 本就是 server 自己的声明面,不经 core 闭集型),
- * 判据一到货就换 core 真源、钉子逐字不用改。
- * 🔴 **今天这两票在 env 通道上还打不响**,而这是刻意如实记下的、不是被忽略的缺口:`LOCKED_CONFIG_KEYS`
- * 经 core 的 `resolveLockedKeys` 校验(未知键拒启)、`COMPLIANCE_ADDITIONAL_DENIES` 经 `COMPLIANCE_CAPABILITIES`
- * 校验(同拒),所以运维今天**写不进** `a2a` / `a2a_peers`。而且合规那一票还有第二层:即便有人绕过 boot 期
- * 校验把 `a2a_peers` 塞进档位,`resolveComplianceDenies` 对闭集外的词是**抛**(亲测 core 5.36),于是这条
- * 请求腿的失败方向是**响亮**(500)而不是安静放行 —— 方向正确,故本模块不加任何兜底。两票的代码先在场是
- * 纵深:core 词表到货那一拍这条腿自己就活了,不需要有人记得回来补;反过来(等词表到了再写判据)才是
- * 「广告了却拦不住」的那一类缺口。钉在 `test/task-a2a.test.ts`(含到货后该怎么改那一格的原地说明)。
- */
 import { resolveComplianceDenies } from "@sema-agent/core";
 import { HttpError } from "./security.js";
-/** Bound on caller-supplied peers (anti-DoS; a real declaration names a handful of agents). */
 export const MAX_REQUEST_A2A_PEERS = 32;
-/**
- * Does THIS deployment honor caller-supplied per-request A2A peers? Three vetoes, ALL of them here (this
- * predicate is the single owner — the capability bit and the request leg both read it, so there is exactly
- * one place where the answer can be wrong):
- *   ① the deployment locks the `a2a` key — a locked deployment that advertised `a2aInjection:true` would
- *      hand every consumer an affordance whose every use 400s (`config.locked_key`); "says yes ⟺ route
- *      works" breaks on the spot. Same conjunction, same reason, as `mcpInjectionHonored`'s lock veto;
- *   ② the compliance posture denies `a2a_peers` — advertised-but-refused again;
- *   ③ multi-tenant (`requirePrincipal === true`) — a tenant cannot point the shared worker at an agent.
- *
- * ⚠️ **`resolveComplianceDenies` is deliberately NOT wrapped in try/catch** (same ruling as the MCP twin):
- * it is fail-loud on a posture outside the closed set, and the posture has already been validated twice
- * before reaching here (config parse + boot assembly). If it ever throws here, someone bypassed both doors
- * and the LOUD direction (route 500) is the correct one — swallowing it into a boolean would let a
- * deployment with a broken posture keep advertising the capability (仓规:安全轴禁静默兜底).
- */
 export function a2aInjectionHonored(config) {
     if (config.lockedConfigKeys?.includes("a2a") === true)
         return false;
     if (config.compliancePosture !== undefined) {
-        // core 词表到货前的读法:闭集 Set 按 string 读(`ReadonlySet<ComplianceCapability>` 的 `has` 是方法,
-        // 结构上可当 `ReadonlySet<string>` 读)。到货后这一行换成 `.has("a2a_peers")` 的闭集形。
         const denies = resolveComplianceDenies(config.compliancePosture);
         if (denies.has("a2a_peers"))
             return false;
@@ -76,25 +14,7 @@ export function a2aInjectionHonored(config) {
 function isStringRecord(v) {
     return !!v && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
 }
-/** http(s) only — never `file://`, never a bare host. A syntactic guard on BOTH URL-shaped fields: the
- *  peer URL doubles as the well-known card origin, and `cardUrl` is dialed on its own when present. */
 const HTTP_URL_RE = /^https?:\/\//i;
-/**
- * Validate + normalize ONE caller entry to a core `A2aServerSpec`, or null if malformed (that peer is dropped
- * and NAMED in `dropped` — never fatal to the request).
- *
- * 🔴 **判据一句话:一个键在场就必须合法,否则这条 peer 整条不进** —— 不做「丢那个键、留这条 peer」。
- * (codex 对抗复审 finding 1,验真后采纳。)理由是方向性的,不是洁癖:
- *  · `allowSkills` 是**收窄**字段,而 core 把它的**缺席**解释成「不限制」。于是「丢坏键」在这条字段上
- *    等于「调用方要求只挂一条,实际挂上远端卡声明的全部技能」—— 而每条 A2A 技能默认 `egress:true` +
- *    `effect:"write"`。收窄意图坏形时退化成放行 = 仓规点名的静默 fail-open。
- *  · `toolAxes` 的**半应用**同样有害:留下 `effect:"read"` 而丢掉坏形的 `egress` 会拼出 core 明文判为
- *    矛盾的组合(「降 effect 却没清 egress」),把一个形状问题变成一条更难读的 prepare 失败。
- *  · 逐字段例外表是下一个漏洞的藏身处;一句话判据全域一致,而且与 `resolveA2aPeers`(缺任一 env 引用
- *    即整条跳过)是**同一条**纪律:绝不半配置地拨号一个远端 agent。
- * 代价明码:一个 header 打错字的调用方会整条丢掉这个 peer(带名字进 warn 日志),而不是匿名连上去。
- * 那正是更好的失败方向。
- */
 function normalizeA2aPeer(e) {
     if (!e || typeof e !== "object")
         return null;
@@ -103,9 +23,6 @@ function normalizeA2aPeer(e) {
         return null;
     if (typeof o.url !== "string" || !HTTP_URL_RE.test(o.url))
         return null;
-    // `cardUrl` in place must be WELL-FORMED — a garbage card URL is not "fall back to well-known probing"
-    // (core treats a set cardUrl as the ONLY location, deliberately: no probing behind the operator's back),
-    // so silently dropping it would change WHICH endpoint gets dialed.
     if (o.cardUrl !== undefined && (typeof o.cardUrl !== "string" || !HTTP_URL_RE.test(o.cardUrl)))
         return null;
     if (o.headers !== undefined && !isStringRecord(o.headers))
@@ -124,10 +41,6 @@ function normalizeA2aPeer(e) {
     if (Array.isArray(o.allowSkills))
         spec.allowSkills = o.allowSkills;
     if (o.toolAxes !== undefined) {
-        // 逐键形状校验(不是裸 cast):值语义仍由 caller 定(caller = 信任根),只挡畸形值直达 core。
-        // A2A 词表 = core `A2aToolAxis` 的三轴,与 MCP 同域但**没有 server-hint 腿**可折——这里收下的
-        // 就是最终值。`"never"` / `egress:false` 只可能来自这条显式覆写腿(core 原话),enforcement 忽略
-        // 这个方向的放宽(tighten-only),风险轴报告面消费它。坏形按上面那句话整条拒。
         if (!o.toolAxes || typeof o.toolAxes !== "object" || Array.isArray(o.toolAxes))
             return null;
         const axes = {};
@@ -154,10 +67,6 @@ function normalizeA2aPeer(e) {
     }
     return spec;
 }
-/**
- * Shape-check the raw `body.a2aPeers`. `null` → a non-array (caller error; the route may 400). Otherwise the
- * valid subset + the names of dropped (malformed/over-cap) entries.
- */
 export function validateRequestA2a(raw) {
     if (raw === undefined || raw === null)
         return { ok: [], dropped: [] };
@@ -169,8 +78,6 @@ export function validateRequestA2a(raw) {
         const v = normalizeA2aPeer(e);
         if (v)
             ok.push(v);
-        // 名字是**调用方文本**,而「名字超长」本身就是被丢的理由之一 —— 原样递给 logger 等于让一条被拒的
-        // 请求决定日志行有多大(自审第四镜)。限长到 name 上限的量级,截断即止。
         else
             dropped.push(e && typeof e === "object" && typeof e.name === "string" ? String(e.name).slice(0, 128) : "<malformed>");
     }
@@ -178,20 +85,6 @@ export function validateRequestA2a(raw) {
         dropped.push(`(+${raw.length - MAX_REQUEST_A2A_PEERS} over cap of ${MAX_REQUEST_A2A_PEERS})`);
     return { ok, dropped };
 }
-/**
- * DESIGN-269 §2.4 —— **同步**拒面:部署锁了 `a2a` 而请求仍带 `a2aPeers` ⇒ 400 `config.locked_key`
- * (逐字沿用 `assertRequestMcpUnlocked` 的裁定,连错误码都同一个 —— 消费端判的是「某个键被行政锁住了」,
- * 不是「哪个键」;码分裂只会让 SDK 多写一条等价分支)。
- *
- * 判据是「请求**占位**」而不是「请求的值合不合法」:锁是两态的,占了就整拒,不静默丢(静默丢正是把
- * 判决变成探针的那一形)。键缺席 / 显式 `null` 都不是占位;**空数组是占位**(调用方确实写了这个键)。
- *
- * ⚠️ **不看车道**:多租户腿本来就会忽略 body peers(`a2aInjectionHonored` 关),但锁在场时「忽略」是
- * 错的失败方向 —— operator 声明了「本部署不收任务自带 A2A peer」,那就该说出来。
- *
- * ⚠️ 参数类型是 `ReadonlySet<string>`:core 的 `LockedKey` 尚无 `a2a` 成员(见模块头),而
- * `ReadonlySet<LockedKey>` 结构上可当 `ReadonlySet<string>` 传入,所以调用点无需任何转换。
- */
 export function assertRequestA2aUnlocked(bodyA2a, lockedKeys) {
     if (!lockedKeys.has("a2a"))
         return;
@@ -201,13 +94,6 @@ export function assertRequestA2aUnlocked(bodyA2a, lockedKeys) {
         code: "config.locked_key",
     });
 }
-/**
- * Merge GATED per-request peers OVER the deployment baseline (center/config). The baseline WINS on a name
- * clash — a caller can ADD a peer but can never SHADOW a configured one. This is load-bearing on THIS lane
- * specifically: the peer name is the tool-namespace segment (`a2a__<peer>__<skill>`), so shadowing would let
- * a caller keep the tool NAMES the model was told about while swapping the agent behind them.
- * Returns the baseline unchanged when there is nothing to add.
- */
 export function mergeRequestA2a(baseline, gated) {
     if (gated.length === 0)
         return baseline;
@@ -215,18 +101,7 @@ export function mergeRequestA2a(baseline, gated) {
     const add = gated.filter((p) => !taken.has(p.name));
     return add.length === 0 ? baseline : [...(baseline ?? []), ...add];
 }
-/**
- * The single entry point the spec-builder calls: compute the effective `TaskSpec.a2a` = deployment baseline
- * (`a2aForScenario(config.a2aPeers, scenario)`) + the caller's gated per-request peers. Off the honored lane
- * (or with no caller peers) returns the baseline unchanged. Logs `a2a_injection_ignored` when a caller SENT
- * peers a closed gate dropped, so a shell never silently believes its declaration took effect (it also reads
- * `capabilities.a2aInjection`).
- */
-export function resolveRequestA2a(baseline, bodyA2a, 
-// `lockedConfigKeys` rides in with the config: `assertRequestA2aUnlocked` already refuses at the leg head,
-// so the lock veto below is unreachable in the locked shape — it stays as depth (ONE predicate owns the
-// question; two half-answers in two places is how the two drift apart).
-config, logger) {
+export function resolveRequestA2a(baseline, bodyA2a, config, logger) {
     if (bodyA2a === undefined || bodyA2a === null)
         return baseline;
     if (!a2aInjectionHonored(config)) {