@sema-agent/server 7.130.0 → 7.131.0

package/dist/task-mcp.js

@@ -1,9 +1,9 @@
 import { mcpInjectionDroppedNotice, readMcpToolAxes, resolveComplianceDenies } from "@sema-agent/core";
-import { isUsableWireName } from "./wire-name-bound.js";
+import { describeBadWireName, isUsableWireName } from "./wire-name-bound.js";
 import { HttpError, createCodedHttpError } from "./security.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
 import { CONTENT_ORIGIN_WORDS, describeBadContentOrigin, isContentOriginWord } from "./mcp-content-origin.js";
-import { readMcpSourceLabel } from "./mcp-source-label.js";
+import { MCP_SOURCE_LABEL_MAX, isMcpSourceLabel, readMcpSourceLabel } from "./mcp-source-label.js";
 import { declaresMcpAssertionHeader, describeMcpAssertionHeaderNotAString, describeMcpIdentityHeadersConflict, mcpIdentityHeadersIssue, noteMcpAssertionHeaderIgnored, noteMcpAssertionHeaderNotSent, readMcpIdentityHeaders, toCoreMcpServerSpec } from "./mcp-assertion-header.js";
 import { echoKeyName } from "./request-key-closure.js";
 import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
@@ -27,6 +27,80 @@ export function mcpInjectionHonored(config) {
 function isStringRecord(v) {
     return !!v && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
 }
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((a) => typeof a === "string");
+}
+function isElicitationFlag(v) {
+    return typeof v === "boolean";
+}
+function describeShape(v) {
+    if (v === undefined)
+        return "nothing (the key is absent)";
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "an array";
+    if (typeof v === "string")
+        return v.length === 0 ? "an empty string" : `a string of ${v.length} characters`;
+    if (typeof v === "object")
+        return "an object";
+    return `a ${typeof v}`;
+}
+function describeNotStringArray(v) {
+    return Array.isArray(v) ? "an array with a non-string element" : describeShape(v);
+}
+function describeNotStringRecord(v) {
+    return isRecord(v) ? "an object with a non-string value" : describeShape(v);
+}
+const transportBad = (path, reason) => ({ ok: false, issue: { path, reason } });
+function readRequestTransport(t) {
+    if (!t || typeof t !== "object")
+        return transportBad("transport", `must be an object with a "kind" of "stdio" or "http" — got ${describeShape(t)}`);
+    const tr = t;
+    const lost = [];
+    if (tr.kind === "stdio") {
+        if (typeof tr.command !== "string" || tr.command.length === 0)
+            return transportBad("transport.command", `must be a non-empty string (the command to run) — got ${describeShape(tr.command)}`);
+        if (tr.args !== undefined && !isStringArray(tr.args))
+            lost.push({ path: "transport.args", reason: `must be an array of strings — got ${describeNotStringArray(tr.args)}` });
+        if (tr.env !== undefined && !isStringRecord(tr.env))
+            lost.push({ path: "transport.env", reason: `must be an object of string values — got ${describeNotStringRecord(tr.env)}` });
+        return {
+            ok: true,
+            transport: {
+                kind: "stdio",
+                command: tr.command,
+                ...(isStringArray(tr.args) ? { args: tr.args } : {}),
+                ...(isStringRecord(tr.env) ? { env: tr.env } : {}),
+            },
+            lost,
+        };
+    }
+    if (tr.kind === "http") {
+        if (typeof tr.url !== "string" || !/^https?:\/\//i.test(tr.url))
+            return transportBad("transport.url", "must be an absolute http(s) URL (put credentials in transport.headers, never in the URL)");
+        const ids = readMcpIdentityHeaders(tr);
+        if (tr.headers !== undefined && !isStringRecord(tr.headers))
+            lost.push({ path: "transport.headers", reason: `must be an object of string values — got ${describeNotStringRecord(tr.headers)}` });
+        if (tr.principalHeader !== undefined && ids.principalHeader === undefined) {
+            lost.push({ path: "transport.principalHeader", reason: `must be a string (the HTTP header NAME the end-user principal is injected into) — got ${describeShape(tr.principalHeader)}` });
+        }
+        return {
+            ok: true,
+            transport: {
+                kind: "http",
+                url: tr.url,
+                ...(isStringRecord(tr.headers) ? { headers: tr.headers } : {}),
+                ...ids,
+            },
+            lost,
+        };
+    }
+    return transportBad("transport.kind", `must be "stdio" or "http" — got ${describeShape(tr.kind)}`);
+}
 const bad = (field) => ({ ok: false, field });
 const MALFORMED_NAME = "<malformed>";
 function declaredName(e) {
@@ -40,41 +114,16 @@ function normalizeServer(e, noteBadOrigin, storedToolAxes) {
     const o = e;
     if (!isUsableWireName(o.name))
         return bad("name");
-    const t = o.transport;
-    if (!t || typeof t !== "object")
-        return bad("transport");
-    const tr = t;
-    let transport;
-    if (tr.kind === "stdio") {
-        if (typeof tr.command !== "string" || tr.command.length === 0)
-            return bad("transport.command");
-        transport = {
-            kind: "stdio",
-            command: tr.command,
-            ...(Array.isArray(tr.args) && tr.args.every((a) => typeof a === "string") ? { args: tr.args } : {}),
-            ...(isStringRecord(tr.env) ? { env: tr.env } : {}),
-        };
-    }
-    else if (tr.kind === "http") {
-        if (typeof tr.url !== "string" || !/^https?:\/\//i.test(tr.url))
-            return bad("transport.url");
-        transport = {
-            kind: "http",
-            url: tr.url,
-            ...(isStringRecord(tr.headers) ? { headers: tr.headers } : {}),
-            ...readMcpIdentityHeaders(tr),
-        };
-    }
-    else {
-        return bad("transport.kind");
-    }
-    const spec = { name: o.name, transport };
+    const read = readRequestTransport(o.transport);
+    if (!read.ok)
+        return bad(read.issue.path);
+    const spec = { name: o.name, transport: read.transport };
     if (o.allowTools !== undefined) {
-        if (!Array.isArray(o.allowTools) || !o.allowTools.every((a) => typeof a === "string"))
+        if (!isStringArray(o.allowTools))
             return bad("allowTools");
         spec.allowTools = o.allowTools;
     }
-    if (typeof o.elicitation === "boolean")
+    if (isElicitationFlag(o.elicitation))
         spec.elicitation = o.elicitation;
     const axes = readMcpToolAxes(o.toolAxes);
     let judged = axes;
@@ -138,30 +187,6 @@ export function assertRequestMcpUnlocked(bodyMcp, lockedKeys) {
         code: "config.locked_key",
     });
 }
-export function assertRequestMcpContentOrigin(bodyMcp) {
-    if (!Array.isArray(bodyMcp))
-        return;
-    for (const e of bodyMcp) {
-        if (!e || typeof e !== "object" || Array.isArray(e))
-            continue;
-        const v = e.contentOrigin;
-        if (v === undefined)
-            continue;
-        if (isContentOriginWord(v))
-            continue;
-        throw new HttpError(400, `mcpServers[].contentOrigin must be one of ${CONTENT_ORIGIN_WORDS.map((w) => `"${w}"`).join(" | ")} — got ${describeBadContentOrigin(v)}` +
-            ` (omit the key entirely for the default: this server's tools classify as external content)`, { code: "request.field_invalid" });
-    }
-}
-export function assertRequestMcpIdentityHeaders(bodyMcp) {
-    if (!Array.isArray(bodyMcp))
-        return;
-    for (const e of bodyMcp) {
-        const refusal = requestEntryIdentityRefusal(e);
-        if (refusal !== undefined)
-            throw createCodedHttpError(400, refusal.errorCode, refusal.message);
-    }
-}
 export function requestEntryIdentityIssue(entry) {
     if (!entry || typeof entry !== "object" || Array.isArray(entry))
         return undefined;
@@ -170,39 +195,82 @@ export function requestEntryIdentityIssue(entry) {
         return undefined;
     return mcpIdentityHeadersIssue(t);
 }
-export function requestEntryIdentityRefusal(entry) {
+export function requestEntryIdentityRefusal(entry, at) {
     const issue = requestEntryIdentityIssue(entry);
-    if (issue === undefined)
+    if (issue === undefined || !isRecord(entry))
         return undefined;
-    const name = echoKeyName("", declaredName(entry));
     if (issue === "both_set")
-        return { errorCode: "request.body_shape", message: describeMcpIdentityHeadersConflict(name) };
-    const value = (entry.transport).assertionHeader;
-    return { errorCode: "request.field_invalid", message: describeMcpAssertionHeaderNotAString(name, value) };
+        return { errorCode: "request.body_shape", message: describeMcpIdentityHeadersConflict(echoKeyName("", declaredName(entry))) };
+    const transport = entry.transport;
+    const value = isRecord(transport) ? transport.assertionHeader : undefined;
+    return entryFieldRefusal(entry, at, { path: "transport.assertionHeader", reason: describeMcpAssertionHeaderNotAString(value) });
 }
-export function assertRequestMcpToolAxes(bodyMcp) {
+export function assertRequestMcpEntries(bodyMcp) {
     if (!Array.isArray(bodyMcp))
         return;
-    for (let i = 0; i < bodyMcp.length; i++) {
-        const refusal = requestEntryToolAxesRefusal(bodyMcp[i], `mcpServers[${i}]`);
+    for (let i = 0; i < Math.min(bodyMcp.length, MAX_REQUEST_MCP_SERVERS); i++) {
+        const refusal = requestEntryRefusal(bodyMcp[i], `mcpServers[${i}]`);
         if (refusal !== undefined)
             throw createCodedHttpError(400, refusal.errorCode, refusal.message);
     }
 }
-export function requestEntryToolAxesRefusal(entry, at) {
-    if (!entry || typeof entry !== "object" || Array.isArray(entry))
-        return undefined;
-    const read = readMcpToolAxes(entry.toolAxes);
-    if (read.ok)
-        return undefined;
+const ENTRY_KEY_JUDGES = {
+    allowTools: (o) => o.allowTools === undefined || isStringArray(o.allowTools)
+        ? undefined
+        : { path: "allowTools", reason: `must be an array of strings (omit the key to leave the server's tools unrestricted) — got ${describeNotStringArray(o.allowTools)}` },
+    contentOrigin: (o) => o.contentOrigin === undefined || isContentOriginWord(o.contentOrigin)
+        ? undefined
+        : {
+            path: "contentOrigin",
+            reason: `must be one of ${CONTENT_ORIGIN_WORDS.map((w) => `"${w}"`).join(" | ")} — got ${describeBadContentOrigin(o.contentOrigin)}` +
+                ` (omit the key for the default: this server's tools classify as external content)`,
+        },
+    elicitation: (o) => (o.elicitation === undefined || isElicitationFlag(o.elicitation) ? undefined : { path: "elicitation", reason: `must be a boolean — got ${describeShape(o.elicitation)}` }),
+    name: (o) => (isUsableWireName(o.name) ? undefined : { path: "name", reason: `must be a non-empty string within the wire-name length bound — got ${describeBadWireName(o.name)}` }),
+    source: (o) => o.source === undefined || isMcpSourceLabel(o.source)
+        ? undefined
+        : { path: "source", reason: `must be a non-empty string of at most ${MCP_SOURCE_LABEL_MAX} characters (a display label) — got ${describeShape(o.source)}` },
+    toolAxes: (o) => {
+        const read = readMcpToolAxes(o.toolAxes);
+        return read.ok ? undefined : { path: "toolAxes", reason: read.problem };
+    },
+    toolFaces: (o) => {
+        const read = readMcpToolFaces(o.toolFaces);
+        return read.ok ? undefined : { path: "toolFaces", reason: read.problem };
+    },
+    transport: (o) => {
+        const read = readRequestTransport(o.transport);
+        return read.ok ? read.lost[0] : read.issue;
+    },
+};
+const ENTRY_REFUSAL_TAIL = "The request is refused rather than mounting the server without it: a declaration that silently did not apply would leave the server running differently from what you declared. " +
+    "Fix the entry (an optional key may also be omitted).";
+function entryFieldRefusal(entry, at, issue) {
     const server = echoKeyName("", declaredName(entry));
     return {
         errorCode: "request.field_invalid",
-        message: `${at}.toolAxes (server "${server}") is not a usable declaration — ${read.problem.replace(CONTROL_AND_BIDI_STRIP_RE, "")}. ` +
-            `The whole declaration is refused: the tools that were fine are not kept and nothing is defaulted, because a toolAxes declaration is your own risk-axis judgement for this server's tools ` +
-            `(it can move a tool down or up), and a half-applied one would silently differ from what you declared. Fix the entry, or omit the key to declare nothing.`,
+        message: `${at}.${issue.path} (server "${server}") is not a usable declaration — ${issue.reason.replace(CONTROL_AND_BIDI_STRIP_RE, "")}. ${ENTRY_REFUSAL_TAIL}`,
     };
 }
+function requestEntryRefusal(entry, at) {
+    if (!isRecord(entry))
+        return undefined;
+    const identity = requestEntryIdentityRefusal(entry, at);
+    if (identity !== undefined)
+        return identity;
+    for (const key of MCP_SERVER_ENTRY_KEYS) {
+        const issue = ENTRY_KEY_JUDGES[key](entry);
+        if (issue !== undefined)
+            return entryFieldRefusal(entry, at, issue);
+    }
+    return undefined;
+}
+export function requestEntryToolAxesRefusal(entry, at) {
+    if (!isRecord(entry))
+        return undefined;
+    const issue = ENTRY_KEY_JUDGES.toolAxes(entry);
+    return issue === undefined ? undefined : entryFieldRefusal(entry, at, issue);
+}
 export function deploymentClosedMcpNames(baseline, reservedNames) {
     return new Set([...(baseline ?? []).map((s) => s.name), ...reservedNames]);
 }

package/dist/task-settings.d.ts

@@ -47,9 +47,10 @@
  *  - (`hooks` NO LONGER deferred either — 轴B #2 注释保鲜:applied 形已接线(本文件 hooks 分片 +
  *    main.ts 单用户闸),仅 malformed 才报 deferred;旧「需要 remote hook-runner」是接线前拍照。)
  */
-import { type ExecutionEnv, type TaskSpec, type ThinkingLevel, type ToolPolicy, type PromptProvider, type PermissionMode } from "@sema-agent/core";
-import type { HooksConfig } from "@sema-agent/settings-schema/hooks";
+import { type PathRuleBases, type ExecutionEnv, type TaskSpec, type ThinkingLevel, type ToolPolicy, type PromptProvider, type PermissionMode } from "@sema-agent/core";
 import { type KeyClosureIssue } from "./request-key-closure.js";
+import { type RunnableHooksConfig } from "./hooks/hook-runner.js";
+import type { StoredHooksRereadM20 } from "./stored-request-hooks-m20.js";
 import { type EntryPermissionMode } from "./runtime-governance.js";
 /**
  * 请求面 `permissionMode` 的闭集 = core `PERMISSION_MODES` **全集**(顶层 `permissionMode` / `settings.permissions.defaultMode` /
@@ -213,10 +214,10 @@ export interface ParsedTaskSettings {
      *  orthogonal axes — `thinking:"max"` (the reasoning axis) + `selfOrchestration:true` (the orchestration axis,
      *  through its existing fail-closed gate). NOT a new mechanism; just a preset that fans out to existing spec fields. */
     ultracode?: boolean;
-    /** hooks hook-runner(阶段一):registry-core 0.1.51 契约校验过的 hooks 配置。像 shellEnv 一样
+    /** hooks hook-runner(阶段一):经 `parseHooksConfig`(契约包分类器 + 服务侧上限 + 本仓会跑的条目类型)判过的 hooks 配置。像 shellEnv 一样
      *  这里只 PARSE;应用点(main.ts resolveSpec)按单用户闸(`requirePrincipal !== true`)决定翻不翻成
      *  core `TaskSpec.hooks` 回调——多租户 lane 收到只警告忽略(hook 命令跑在 worker host = class ② 能力授予)。 */
-    hooks?: HooksConfig;
+    hooks?: RunnableHooksConfig;
     /** [ref](7.77.0)—— CC settings 同名键:上下文窗口里**留给技能清单**的比例((0,1];CC 默认 0.01 = 1%)。
      *  超预算时引擎把描述裁短、再不够退成 name-only(`cli259.js` 的清单渲染算法),**从不**拒掉一条技能 ——
      *  这正是本版把技能条数/描述两条帽整条退役后的补偿面:per-turn 成本的旋钮在**渲染侧**,不在受理侧。
@@ -232,6 +233,15 @@ export interface ParseTaskSettingsResult {
     /** Sub-fields the caller SENT but this version does not wire(`env`;`hooks` 仅在 MALFORMED 时入列——valid hooks
      *  已是 applied 字段)。Empty when none. */
     deferred: string[];
+    /** 一次性迁移 M20(窗口见 `plugins/one-time-migrations.ts` 登记表):存下的 hooks 被唯一读者拒掉、经重读座剥掉点名的键后过了读者 ⇒ 本次读数里 `settings.hooks` 是重读的产物,
+     *  并带被剥的坐标(出门形)。缺席 = 没有发生重读。 */
+    hooksReread?: {
+        readonly stripped: readonly string[];
+    };
+}
+/** `parseTaskSettings` 的可选座:续跑重放腿才有的重读座(一次性迁移 M20;新提交腿与不问 hooks 的读者不递)。 */
+export interface ParseTaskSettingsSeats {
+    readonly storedHooksReread?: StoredHooksRereadM20;
 }
 /** Cap on `outputStyle` length — it lands in the system prompt, so it shares the `MAX_SYSTEM_PROMPT_CHARS` (16384)
  *  posture (an uncapped prompt body is a per-turn token-cost hole; cross review). Exported so the HTTP layer
@@ -333,7 +343,7 @@ export declare function taskHooksHonored(config: {
  * 重放也走的宽容层,一个 4xx 在这里会把存量 parked 任务永久砖死;FRESH 提交面由 {@link taskSettingsKeyIssue}
  * 在 `server.ts` prepareSpec 里 400 响亮拒 + 逐字列名。双层姿势与 outputStyle / permissionMode 两处逐字相同。
  */
-export declare function parseTaskSettings(raw: unknown): ParseTaskSettingsResult;
+export declare function parseTaskSettings(raw: unknown, seats?: ParseTaskSettingsSeats): ParseTaskSettingsResult;
 /** Defensive acceptance of the `appendSystemPrompt` rider ([ref] R2 + codex F2): the HTTP 400 gate (prepareSpec,
  *  MAX_SYSTEM_PROMPT_CHARS) only covers FRESH submits — every resume family re-enters resolveSpec on a STORED body,
  *  and a pre-1.243 store preserved unknown request keys verbatim (the field was INERT then), so an over-cap legacy
@@ -457,6 +467,32 @@ export interface FsWriteGateWiring {
      *  本 wiring 的组合点。) */
     isExempt?: (toolName: string, canonicalPath: string) => boolean | Promise<boolean>;
 }
+/**
+ * deny / ask 两桶(core 规则编译器读的收紧表)的**问序,单表**:{@link rulePolicyBucketsRefusal} 的两段循环(名字层 + 文法 · `~/` 要 home)都迭代它 ——
+ * 两桶都有坏条目时,拒点与存体预判点名同一个桶、说同一句。表里每个词同时是 core 规则的 `behavior`。
+ */
+export declare const RULE_POLICY_BUCKETS: readonly ["ask", "deny"];
+export type RulePolicyBucket = (typeof RULE_POLICY_BUCKETS)[number];
+/**
+ * deny / ask 两桶的**完整规则判**,唯一一只(拒点 {@link rejectUnmatchableSettingsNames} 与存体预判 `http/stored-body-replay.ts` 同调):
+ *  ② 按 {@link RULE_POLICY_BUCKETS} 的序逐桶问 `unmatchableToolNamesRefusal`(名字层 + core 规则文法);③ 都过了,再逐桶判 `~/` 形要 home 的那一拒。第一个坏处答 `{ bucket, message }`。
+ * 入参:桶、{@link RulePolicyBases}。**home 同源**:拒点的 home 是 `resolve-spec.ts` 的 `laneHomeBase()` 经 `executionLaneHomeDir(config)` 算出的,预判传同一个函数对同一份部署配置算出的。
+ * **声明给文法的基**只有拒点有(根 + home 的并集,执行车道才知道根):core 的规则文法对**没声明**的基不下判词(见 `config.ts` `uncompilableRuleGuidance`),所以预判什么也不声明、两腿逐字同句;
+ * 预判不能把 home 当「半个基」声明给文法 —— core 的路径族只从根推,缺根时一个合法的 Windows 形 home 会按默认族被判 `unsupported.path_base`(V6-k)。
+ * ③ 排在最后:一条同时文法不成立又带 `~/` 的规则,先说文法(补上 home 它仍被文法拒,先说 home 是误导)。
+ */
+export interface RulePolicyBases {
+    /** 声明给 core 规则文法的路径基(这条 task 的根 + home):拒点才有;存体预判不声明。 */
+    readonly declared?: PathRuleBases;
+    /** 执行环境的 home(`~/` 形规则的前提);这个部署解不出 ⇒ 缺席。 */
+    readonly home?: string;
+}
+export declare function rulePolicyBucketsRefusal(permissions: Readonly<Partial<Record<RulePolicyBucket, readonly string[]>>>, bases: RulePolicyBases): {
+    readonly bucket: RulePolicyBucket;
+    readonly message: string;
+} | undefined;
+/** 请求的 settings 编不成生效的规则 / 有永远不生效的条目 ⇒ 422 的句首(三只桶同一个出口;`resolveSpec` 的拒点与存体重放预判的 409 句子同用这一个,不各写一份)。 */
+export declare const REQUEST_SETTINGS_REFUSAL_PREFIX = "request settings cannot be applied as written: ";
 export declare function deriveSettingsPolicy(settings: ParsedTaskSettings, gate?: FsWriteGateWiring, workflowGate?: WorkflowGateWiring): {
     toolPolicy?: ToolPolicy;
 };

package/dist/task-settings.js

@@ -193,18 +193,26 @@ export function taskSettingsKeyIssue(raw) {
 export function taskHooksHonored(config) {
     return config.requirePrincipal !== true;
 }
-export function parseTaskSettings(raw) {
+export function parseTaskSettings(raw, seats = {}) {
     if (raw === null || raw === undefined || typeof raw !== "object")
         return { deferred: [] };
     const s = raw;
     const deferred = [];
     let hooksConfig;
+    let hooksReread;
     if (s.hooks !== undefined && s.hooks !== null) {
         const parsedHooks = parseHooksConfig(s.hooks);
         if (parsedHooks.config)
             hooksConfig = parsedHooks.config;
-        else
-            deferred.push("hooks");
+        else {
+            const reread = seats.storedHooksReread?.(s.hooks);
+            if (reread !== undefined) {
+                hooksConfig = reread.config;
+                hooksReread = { stripped: reread.stripped };
+            }
+            else
+                deferred.push("hooks");
+        }
     }
     const shellEnv = cleanEnvMap(s.env);
     if (s.env !== undefined && s.env !== null && shellEnv === undefined)
@@ -252,7 +260,7 @@ export function parseTaskSettings(raw) {
     const maxDesc = s.skillListingMaxDescChars;
     if (skillListingMaxDescOk(maxDesc))
         out.skillListingMaxDescChars = maxDesc;
-    return { settings: Object.keys(out).length > 0 ? out : undefined, deferred };
+    return { settings: Object.keys(out).length > 0 ? out : undefined, deferred, ...(hooksReread !== undefined ? { hooksReread } : {}) };
 }
 export function hasConstitutionAnchors(text) {
     return typeof text === "string" && text.includes(CYBER_RISK) && text.includes(URL_SAFETY) && text.includes(HARNESS_SECTION_ANCHOR);
@@ -321,33 +329,39 @@ function createWorkflowAskPolicy(isExempt) {
     };
 }
 function rejectUnmatchableSettingsNames(perms, pathBases) {
-    if (pathBases?.home === undefined) {
-        for (const [field, names, behavior] of [
-            ["permissions.ask", perms.ask, "ask"],
-            ["permissions.deny", perms.deny, "deny"],
-        ]) {
-            for (const name of names ?? []) {
-                const parsed = parseRuleText(name, behavior);
+    const refused = rulePolicyBucketsRefusal(perms, { ...(pathBases !== undefined ? { declared: pathBases } : {}), ...(pathBases?.home !== undefined ? { home: pathBases.home } : {}) });
+    if (refused !== undefined)
+        throw new Error(refused.message);
+}
+export const RULE_POLICY_BUCKETS = ["ask", "deny"];
+export function rulePolicyBucketsRefusal(permissions, bases) {
+    for (const bucket of RULE_POLICY_BUCKETS) {
+        const names = permissions[bucket];
+        if (!names)
+            continue;
+        const unmatchable = unmatchableToolNamesRefusal(`permissions.${bucket}`, names, { consumer: "rule-policy", behavior: bucket, ...(bases.declared !== undefined ? { pathBases: bases.declared } : {}) });
+        if (unmatchable !== undefined)
+            return { bucket, message: unmatchable.message };
+    }
+    if (bases.home === undefined) {
+        for (const bucket of RULE_POLICY_BUCKETS) {
+            const field = `permissions.${bucket}`;
+            for (const name of permissions[bucket] ?? []) {
+                const parsed = parseRuleText(name, bucket);
                 if ("rule" in parsed && ruleToolGrammarOf(parsed.rule.tool) === "path" && parsed.rule.command.startsWith("~/")) {
-                    throw new Error(`${field} has a home-relative path rule (${name}) but this deployment cannot resolve the EXECUTION environment's home directory — ` +
-                        `the engine never guesses one: without a home base the rule resolves to "unreadable" and every matching call stops to ask, so it guards nothing. ` +
-                        `Spell the path absolutely (${"Edit(//abs/path/**)"} form), declare the lane's home with REMOTE_EXEC_HOME_DIR, or run the task on a lane whose home this worker knows.`);
+                    return {
+                        bucket,
+                        message: `${field} has a home-relative path rule (${name}) but this deployment cannot resolve the EXECUTION environment's home directory — ` +
+                            `the engine never guesses one: without a home base the rule resolves to "unreadable" and every matching call stops to ask, so it guards nothing. ` +
+                            `Spell the path absolutely (${"Edit(//abs/path/**)"} form), declare the lane's home with REMOTE_EXEC_HOME_DIR, or run the task on a lane whose home this worker knows.`,
+                    };
                 }
             }
         }
     }
-    const judgments = [
-        ["permissions.ask", perms.ask, { consumer: "rule-policy", behavior: "ask", ...(pathBases !== undefined ? { pathBases } : {}) }],
-        ["permissions.deny", perms.deny, { consumer: "rule-policy", behavior: "deny", ...(pathBases !== undefined ? { pathBases } : {}) }],
-    ];
-    for (const [field, names, judgment] of judgments) {
-        if (!names)
-            continue;
-        const unmatchable = unmatchableToolNamesRefusal(field, names, judgment);
-        if (unmatchable !== undefined)
-            throw new Error(unmatchable.message);
-    }
+    return undefined;
 }
+export const REQUEST_SETTINGS_REFUSAL_PREFIX = "request settings cannot be applied as written: ";
 export function deriveSettingsPolicy(settings, gate, workflowGate) {
     const perms = settings.permissions;
     if (!perms)

package/dist/trace/core-keyset-guard.d.ts

@@ -148,9 +148,9 @@ type ParkArmQueueExcluded = "kind" | "args" | "batchToolCallIds" | "completedCal
 type _GuardParkArmQueue = AssertAllKeysHandled<Exclude<ParkArmKeys, ParkArmQueueProjected | ParkArmQueueExcluded>>;
 type _GuardParkArmQueueReverse = AssertAllKeysHandled<Exclude<ParkArmQueueProjected | ParkArmQueueExcluded, ParkArmKeys>>;
 type _NoDoubleBookParkArmQueue = AssertAllKeysHandled<Extract<ParkArmQueueProjected, ParkArmQueueExcluded>>;
-type TaskSpecWired = "objective" | "principal" | "images" | "sessionId" | "requireExistingSession" | "oneShot" | "clientContext" | "resumeAt" | "resumeAtMode" | "model" | "compactionModel" | "thinking" | "systemPrompt" | "appendSystemPrompt" | "promptProvider" | "memory" | "suggestNextPrompts" | "restoreFiles" | "acceptPartialRestore" | "rewindFilesTo" | "tools" | "excludeTools" | "deferTools" | "toolMaterializeStrategy" | "promptProfile" | "toolPolicy" | "onAsk" | "onQuestion" | "hooks" | "durableApproval" | "resourceSuspend" | "resilience" | "finalVerification" | "checkpointStore" | "handsReadOnly" | "memoryPersistenceCapable" | "additionalDirectories" | "additionalReadDirectories" | "enablePlanMode" | "interactiveTools" | "enableFork" | "shellGate" | "approvalReach" | "writeFace" | "mcp" | "a2a" | "skills" | "backgroundScope" | "envFacts" | "limits" | "configOverrides" | "forwardSubagentEvents" | "retainSubagentSessions" | "retainBackgroundProcesses" | "outputSchema" | "outputRetries" | "compaction" | "attachments" | "selfOrchestration" | "getApiKeyAndHeaders" | "interactionPosture" | "agents" | "permissionMode" | "taskId" | "signal" | "preemptSignal" | "maxSuspends" | "skillListingBudgetFraction" | "skillListingMaxDescChars" | "excludeAllTools" | "fileHistory" | "userInvokedSkills" | "outputStyle" | "allowedTools" | "allowTools";
+type TaskSpecWired = "objective" | "principal" | "images" | "sessionId" | "requireExistingSession" | "oneShot" | "clientContext" | "resumeAt" | "resumeAtMode" | "model" | "compactionModel" | "thinking" | "systemPrompt" | "appendSystemPrompt" | "promptProvider" | "memory" | "suggestNextPrompts" | "restoreFiles" | "acceptPartialRestore" | "rewindFilesTo" | "tools" | "excludeTools" | "deferTools" | "toolMaterializeStrategy" | "promptProfile" | "toolPolicy" | "onAsk" | "onQuestion" | "hooks" | "durableApproval" | "resourceSuspend" | "resilience" | "finalVerification" | "checkpointStore" | "handsReadOnly" | "memoryPersistenceCapable" | "additionalDirectories" | "additionalReadDirectories" | "enablePlanMode" | "interactiveTools" | "enableFork" | "shellGate" | "approvalReach" | "writeFace" | "mcp" | "a2a" | "skills" | "backgroundScope" | "envFacts" | "limits" | "configOverrides" | "forwardSubagentEvents" | "retainSubagentSessions" | "retainBackgroundProcesses" | "outputSchema" | "outputRetries" | "compaction" | "attachments" | "selfOrchestration" | "getApiKeyAndHeaders" | "interactionPosture" | "agents" | "permissionMode" | "taskId" | "signal" | "preemptSignal" | "maxSuspends" | "skillListingBudgetFraction" | "skillListingMaxDescChars" | "excludeAllTools" | "fileHistory" | "userInvokedSkills" | "outputStyle" | "allowedTools" | "allowTools" | "userAttachments";
 /** 导出:请求体键闭集门(`request-key-closure.ts`)据它锁「本仓记为未接线的引擎座,提交口不许受理」—— 两处分类只能同向。 */
-export type TaskSpecUnwired = "actor" | "roles" | "lspManager" | "tracer" | "readFace" | "readDenyPatterns" | "interactiveQuestionFallback" | "alwaysLoadTools" | "restoreGatedTools" | "deferSelfResolve" | "basePolicyForResumeEdit" | "lspDiagnostics" | "streamingToolExecution" | "toolResultThresholdChars" | "peerPresence" | "writeProtectedAdditions" | "complianceAdditionalDenies" | "modelRole" | "enableBlockedReport" | "userAttachments";
+export type TaskSpecUnwired = "actor" | "roles" | "lspManager" | "tracer" | "readFace" | "readDenyPatterns" | "interactiveQuestionFallback" | "alwaysLoadTools" | "restoreGatedTools" | "deferSelfResolve" | "basePolicyForResumeEdit" | "lspDiagnostics" | "streamingToolExecution" | "toolResultThresholdChars" | "peerPresence" | "writeProtectedAdditions" | "complianceAdditionalDenies" | "modelRole" | "enableBlockedReport";
 type _GuardTaskSpec = AssertAllKeysHandled<Exclude<keyof TaskSpec, TaskSpecWired | TaskSpecUnwired>>;
 type _GuardTaskSpecReverse = AssertAllKeysHandled<Exclude<TaskSpecWired | TaskSpecUnwired, keyof TaskSpec>>;
 type TaskResultForwarded = "taskId" | "runId" | "sessionId" | "terminal" | "model" | "effectiveReasoning" | "result" | "salvagedOutput" | "remoteEnvFailures" | "apiFailure" | "retryAfterMs" | "degraded" | "structuredOutput" | "rewindNotes" | "haltedOnUserRejection" | "haltedByUser" | "strandedHumanAnswers" | "pendingApproval" | "approvalWaitedMs" | "effectiveReadFace" | "effectiveReadDenyPatterns" | "effectiveWriteFace" | "effectiveMemoryScopes" | "stats" | "editedFiles" | "responseModel" | "compaction";

package/dist/trace/ledger-sink.d.ts

@@ -104,6 +104,35 @@ export declare function createSerialLedgerAppend(appendEvent: (seq: number, type
  * 返回 `.catch` 用的处理器(产物是函数 ⇒ `create*`)。
  */
 export declare function createForwardAppendFailedNote(type: string): (err: unknown) => void;
+/**
+ * 人在环帧(`question` / `question_complete`、`elicitation` / `elicitation_complete`)的**账本孪生投递口**。
+ *
+ * 一条律:**凡进 run 流的 HITL 帧都有账本孪生;腿只决定「还要不要同时直写 socket」**。后台腿没有 live 面,
+ * 它的投递口就是账本追加本身(`runs.ts`);同步流腿有 live SSE,走本函数 —— 同一只帧对象先落账、再按需直写,
+ * 于是两条腿对同一只帧的落法只差「直写要不要」,不差「账本有没有」。
+ *
+ * 顺序与失败语义(与后台腿同一条):
+ *  · **先账本后直写**。账本落不下 ⇒ 本次投递**失败**(抛),帧不上 socket —— 一只没有孪生的帧不许单独露面
+ *    (否则壳看见一张重载就丢的卡)。调用方(协调器)按「开帧投递失败」处理:这一问结算 `unavailable`、记一次既有的
+ *    P-DEBT 留痕;消卡帧则落「面包屑丢失」的 F 类留痕。
+ *  · **seq 不自造**:孪生走 `sink.append` —— 本腿账本唯一的那条串行链(与 text / tool / done 行同一个计数器)。
+ *  · **直写口已不可达**(客户端离开,而 run 因 detach 继续)⇒ 账本孪生即送达,不再触碰那条已死的连接
+ *    (不抛、也不记「丢帧」—— 帧没丢,在账本里)。
+ *  · **本腿没有账本**(无 durable run 行的部署:`sink` 缺席)⇒ 直写就是全部投递,死流姿态由 `writeLive` 自己带
+ *    (question 抛、elicitation 静默记账),字节逐字同孪生落地之前。
+ *
+ * 命名(CLAUDE.md 工厂命名律):`create*` —— 返回的是捕获了两个口的闭包,不是纯数据。
+ */
+export declare function createLedgerTwinEmit<F extends {
+    type: LedgerEventType;
+}>(opts: {
+    /** 本腿的账本(sync 腿 = 有 durable run 行才有;缺席 ⇒ 无孪生可落)。只用 `append`:seq 由它那条链铸。 */
+    sink: Pick<LedgerSink, "append"> | undefined;
+    /** 本腿的直写口(sync 腿 = 一个具名 SSE 事件)。 */
+    writeLive: (frame: F) => void;
+    /** 直写面此刻可达吗 —— 与协调器问「这条腿还够得着人吗」的是**同一只**谓词(`QuestionRunContext.deliverable`)。 */
+    liveReachable: () => boolean;
+}): (frame: F) => Promise<void>;
 export declare function createLedgerSink(opts: {
     /** The seq-stamped durable append — typically `(seq, type, data) => runStore.appendEvent(taskId, seq, type, data)`. */
     appendEvent: (seq: number, type: LedgerEventType, data: unknown) => Promise<void>;

package/dist/trace/ledger-sink.js

@@ -17,6 +17,17 @@ export function createSerialLedgerAppend(appendEvent, startSeq) {
 export function createForwardAppendFailedNote(type) {
     return (err) => recordFailOpen("server.ledger.forward-append-failed", `type=${type} err=${err instanceof Error ? err.message : String(err)}`);
 }
+export function createLedgerTwinEmit(opts) {
+    return async (frame) => {
+        if (opts.sink !== undefined) {
+            const { type, ...data } = frame;
+            await opts.sink.append(type, data);
+            if (!opts.liveReachable())
+                return;
+        }
+        opts.writeLive(frame);
+    };
+}
 export function createLedgerSink(opts) {
     const keys = opts.notifiedKeys ?? new NotifiedKeys();
     let seq = 0;

package/dist/trace/project.d.ts

@@ -851,6 +851,11 @@ export declare function wiringManifestFaceEventData(ev: {
  *    `[from …]` 渲染就是靠它决定加不加 `(unverified)`),剥掉它比剥掉 id 更坏:剩下一个看不出真假的名字。
  *  · `principal` —— **刻意不投影**(与 ToolApprovalFrame 的 `principal` 同裁):帧本就经 owner-scoped 流
  *    投递,租户身份不必再由帧自述。要它请先提消费需求,别顺手加。
+ *  · `attachments[]`(core 7.50.0,只在声明了附件的目标那一帧 `applied` 上)—— 逐成员挑四键:`ordinal`(引擎铸的序号)/
+ *    `kind`(引擎认出的种类,闭集词;读不出种类时缺席)/ `outcome`(引擎的结局词,闭集)⇒ verbatim;`label` = 调用方**自己声明的**
+ *    路径或名字(引擎原样回声,不是解析后的落点 —— 多租户沙箱车道上它是这次 run 自己工作区里的相对 / 绝对路径串,帧上不出现任何别的租户
+ *    或宿主盘的信息),与已展示的工具实参 / `workspace_changed.cwd` 同一信任级(UNTRUSTED 的路径串)⇒ 过 `redactSecrets`。长度界由引擎定
+ *    (`USER_ATTACHMENT_LABEL_MAX`),本仓不另截。非对象的成员丢、集外的成员键不投(同 `actor` 的白名单理由)。
  *
  * `actor` 逐键挑(禁 spread):core 已声明 `ActorAssertion` 是冻结三键形,但白名单的意义正是「core 加第
  * 四键时由人处置」——身份对象上多出来的键裸上线是本文件反复登记的病族。
@@ -866,6 +871,7 @@ export declare function humanInputEventData(ev: {
     actor?: unknown;
     principal?: unknown;
     entryId?: unknown;
+    attachments?: unknown;
     eventId?: unknown;
     parentToolCallId?: unknown;
 }): Record<string, unknown>;

package/dist/trace/project.js

@@ -665,6 +665,16 @@ export function wiringManifestFaceEventData(ev, operatorFace, instructions) {
 export function humanInputEventData(ev) {
     const str = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
     const a = typeof ev.actor === "object" && ev.actor !== null && !Array.isArray(ev.actor) ? { ...ev.actor } : {};
+    const attachments = Array.isArray(ev.attachments)
+        ? ev.attachments
+            .filter((m) => typeof m === "object" && m !== null && !Array.isArray(m))
+            .map((m) => ({
+            ...(typeof m.ordinal === "number" && Number.isFinite(m.ordinal) ? { ordinal: m.ordinal } : {}),
+            ...(str(m.kind) !== undefined ? { kind: m.kind } : {}),
+            ...(str(m.outcome) !== undefined ? { outcome: m.outcome } : {}),
+            ...(str(m.label) !== undefined ? { label: redactSecrets(String(m.label)) } : {}),
+        }))
+        : undefined;
     const actor = {
         ...(str(a.id) !== undefined ? { id: redactSecrets(String(a.id)) } : {}),
         ...(typeof a.hostAsserted === "boolean" ? { hostAsserted: a.hostAsserted } : {}),
@@ -679,6 +689,7 @@ export function humanInputEventData(ev) {
         ...(str(ev.issuer) !== undefined ? { issuer: redactSecrets(String(ev.issuer)) } : {}),
         ...(Object.keys(actor).length > 0 ? { actor } : {}),
         ...(str(ev.entryId) !== undefined ? { entryId: ev.entryId } : {}),
+        ...(attachments !== undefined ? { attachments } : {}),
         ...identityFields(ev),
     };
 }

package/dist/trace/wire-projection-faces.d.ts

@@ -161,7 +161,7 @@ export declare const WIRE_PROJECTION_FACES: {
     readonly human_input: {
         readonly projector: "humanInputEventData";
         readonly coreType: string;
-        readonly excluded: readonly ["principal", "attachments"];
+        readonly excluded: readonly ["principal"];
         readonly minted: readonly [];
     };
     readonly task_notification: {

package/dist/trace/wire-projection-faces.js

@@ -30,7 +30,7 @@ export const WIRE_PROJECTION_FACES = {
     context_usage: { projector: "contextUsageEventData", coreType: arm("context_usage"), excluded: [], minted: [] },
     turn_end: { projector: "turnEndEventData", coreType: arm("turn_end"), excluded: [], minted: [] },
     compaction_outcome: { projector: "compactionOutcomeEventData", coreType: arm("compaction_outcome"), excluded: [], minted: [] },
-    human_input: { projector: "humanInputEventData", coreType: arm("human_input"), excluded: ["principal", "attachments"], minted: [] },
+    human_input: { projector: "humanInputEventData", coreType: arm("human_input"), excluded: ["principal"], minted: [] },
     task_notification: {
         projector: "taskNotificationEventData",
         coreType: `TaskNotificationPayload & ${arm("task_notification")}`,

package/dist/user-authored-text.d.ts

@@ -28,4 +28,11 @@ export declare function buildObjectivePreview(text: string, chars: number): stri
 export declare const RUN_OBJECTIVE_PREVIEW_CHARS = 120;
 /** run 行的预览:用户写的那段 → 脱敏 → 截 {@link RUN_OBJECTIVE_PREVIEW_CHARS};没有用户正文 ⇒ `""`(列写空串 = 有记录、剥空)。 */
 export declare function buildRunObjectivePreview(objective: string): string;
+/**
+ * 这条消息是不是**附件帧**(core 7.50.0 请求层附件:目标声明的每只文件由引擎铸成一条自己的 user 消息,紧跟目标提交)。
+ * 判据 = 引擎写在消息上的送达记录 `attachment` **在场**(core:那只记录是「这条消息是附件帧」的唯一来源,文本从不判)。坏形记录同样算在场 ——
+ * 两个读者都往「不是人写的话」那一侧落(预览走下一条;会话视图按文件字节脱敏),那是安全的一侧。
+ * 一个事实一个读法:会话视图的处置表(`audit.ts`)与本地会话列表的预览(`plugins/local-session-store.ts`)同调这一只。
+ */
+export declare function isAttachmentFrame(message: unknown): boolean;
 //# sourceMappingURL=user-authored-text.d.ts.map

package/dist/user-authored-text.js

@@ -15,4 +15,7 @@ export const RUN_OBJECTIVE_PREVIEW_CHARS = 120;
 export function buildRunObjectivePreview(objective) {
     return buildObjectivePreview(objective, RUN_OBJECTIVE_PREVIEW_CHARS);
 }
+export function isAttachmentFrame(message) {
+    return typeof message === "object" && message !== null && Object.hasOwn(message, "attachment");
+}
 //# sourceMappingURL=user-authored-text.js.map