@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/permission-rules.d.ts

@@ -47,7 +47,10 @@
  * The NAME lane is the same shape for the tools of `NAME_RULE_FACES` (the `Skill` tool): a `Skill(<name>)` / `Skill(<prefix>:*)`
  * deny or ask — the reference's own spelling — compiles through the same validator (the model's name grammar) and is judged on the
  * one string the call names (`nameRuleSubjectOf`) with `nameRuleAdmits`, the reader the persisted rule store uses. The parameter
- * spelling `Skill(skill:<name>)` those tools used to take is retired: refused loudly, its sentence naming the CC form.
+ * spelling `Skill(skill:<name>)` those tools used to take is retired: refused loudly, its sentence naming the CC form. A KEYED
+ * value tool (`Artifact(action:<word>)`) takes the same lane for content keyed by its own parameter (`nameGrammarReads`); its
+ * other arguments stay on the generic `param:pattern` lane. A call of it that names no value for the key as the tool reads it
+ * is refused by the key's deny or ask rule (`keyedValueAbsentReason`, the persisted lane's reading).
  *
  * 🔴 与 CC 的有意差(design/127 r2):
  *  - CC 参数级 generic 道无 allow lane(gnn 只有 deny/ask)—— 我们同样,且整个 policy 无 allow 臂。
@@ -73,7 +76,13 @@ export interface PermissionRuleIssue {
     rule: string;
     /** `invalid.*` = 语法/语义错;`unsupported.*` = CC 合法但 v1 不支持的 lane(独立
      *  分类,绝不静默 no-op —— `Bash(npm run:*)` 被当 generic 参数规则接受后永不匹配是最危险的失败形态)。 */
-    code: "invalid.empty_tool" | "invalid.paren" | "invalid.param_split" | "invalid.primary_field" | "invalid.cap_exceeded"
+    code: "invalid.empty_tool" | "invalid.paren"
+    /** A rule the rule syntax reads no rule in (`ruleSpellingOf`) whose name is the reason: blanks around the rule, a
+     *  character outside a tool name's spelling (a variation selector, a filler, a zero-width space), a blank or an invisible
+     *  character before the `(`, a leading `-`. Refused — the lenient reading would deny a tool under another spelling, or none.
+     *  Also a rule whose tool name the syntax reads as the wildcard `*` (`*`, `*()`, `*(*)`): a rule reaches the tool it
+     *  names, and `*` names none. */
+     | "invalid.tool_name" | "invalid.param_split" | "invalid.primary_field" | "invalid.cap_exceeded"
     /** An ALLOW rule (any spelling): a policy fold says deny / ask only — "this does not need asking" is the allow
      *  layer's (`TaskSpec.allowedTools`, `RunnerDeps.allowedTools`). One issue per allow rule. */
      | "unsupported.allow"
@@ -120,6 +129,9 @@ export interface PermissionRuleCaps {
      *  的热路径成本上界。 */
     maxScalarValueChars: number;
 }
+/** The caps a rule set is held to unless the caller names its own — `maxRules` is the ONE bound on how many rules a set
+ *  carries, read by the compiler here and by the org layer's list judgment (which refuses a longer list before it is copied). */
+export declare const DEFAULT_CAPS: Readonly<PermissionRuleCaps>;
 export interface PermissionRulePolicyOptions {
     /** Invalid/unsupported rules: `"throw"`(default — 部署作者写错要立刻知道)aggregates ALL issues
      *  into one error; `"skip"` drops them (pair with {@link validatePermissionRules} for a report, and/or

package/dist/core/permission-rules.js

@@ -1,10 +1,11 @@
 import { attest } from "./tool-policy.js";
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { catalogRuleFaceOf, isShellFaceToolName, pathTargetOf } from "./tool-registry.js";
-import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
-import { COMMAND_RULE_TOOL, NAME_RULE_FACES, PATH_RULE_BASE_LABEL, PATH_RULE_FACES, callPathFaceOf, isUsablePathBase, laneToolNamesOf, nameRuleAdmits, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleBasesNeeded, ruleToolGrammarOf } from "./permission-rule-model.js";
+import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
+import { COMMAND_RULE_TOOL, NAME_RULE_FACES, PATH_RULE_BASE_LABEL, PATH_RULE_FACES, callPathFaceOf, isUsablePathBase, keyedValueAbsentReason, laneToolNamesOf, nameGrammarReads, nameRuleAdmits, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleBasesNeeded } from "./permission-rule-model.js";
 import { pathFamilyOf } from "../tools/fs/safety.js";
-import { callTargetReadingOf, callTargetViewsOf } from "./effective-path-target.js";
+import { argsAsTheToolReads, callTargetReadingOf, callTargetViewsOf } from "./effective-path-target.js";
+import { canonicalize, UNCANONICALIZABLE } from "./canonical-json.js";
 import { bindPathRules, judgeRuleRows, policyAnchors, rowsWhereTheyLead } from "./path-rule-binding.js";
 import { ruleDenialSentence } from "./rule-denial-sentence.js";
 import { heldValues } from "./tool-name-readings.js";
@@ -24,7 +25,7 @@ function describeBehavior(v) {
         default: return v === null ? "null" : "an object";
     }
 }
-const DEFAULT_CAPS = {
+export const DEFAULT_CAPS = {
     maxRules: 256,
     maxRuleLength: 512,
     maxPatternLength: 256,
@@ -50,6 +51,25 @@ function countStars(s) {
             n++;
     return n;
 }
+function unreadableRuleIssue(text) {
+    const lenient = parsePermissionRule(text);
+    if (!lenient.toolName)
+        return { code: "invalid.empty_tool", message: "tool name cannot be empty" };
+    if (lenient.ruleContent === undefined && /[()\\]/.test(lenient.toolName)) {
+        return { code: "invalid.paren", message: "tool name still contains paren/escape characters — a mis-escaped rule would compile to a dead bare rule" };
+    }
+    const open = indexOfUnescaped(text, "(");
+    if (lenient.ruleContent === undefined && open !== -1) {
+        const close = lastIndexOfUnescaped(text, ")");
+        const legitimateBare = close === text.length - 1 && ["", "*"].includes(text.substring(open + 1, close));
+        if (!legitimateBare)
+            return { code: "invalid.paren", message: "malformed parentheses / trailing characters (would silently downgrade to a bare-tool rule)" };
+    }
+    return {
+        code: "invalid.tool_name",
+        message: `the tool name is a spelling no tool name can have — the rule syntax reads no rule in it (blanks around the rule, a character outside a tool name's spelling, or one before the "("), so the rule would name no tool; fix the entry`,
+    };
+}
 function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
     const faceOf = (toolName) => {
         if (ruleFaces !== undefined) {
@@ -84,24 +104,16 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
             bad(text, "invalid.cap_exceeded", `rule longer than ${caps.maxRuleLength} chars`);
             continue;
         }
-        const parsed = parsePermissionRule(text);
-        if (!parsed.toolName) {
-            bad(text, "invalid.empty_tool", "tool name cannot be empty");
+        const parsed = ruleSpellingOf(text);
+        if (parsed === undefined) {
+            const why = unreadableRuleIssue(text);
+            bad(text, why.code, why.message);
             continue;
         }
-        if (parsed.ruleContent === undefined && /[()\\]/.test(parsed.toolName)) {
-            bad(text, "invalid.paren", "tool name still contains paren/escape characters — a mis-escaped rule would compile to a dead bare rule");
+        if (parsed.toolName === "*") {
+            bad(text, "invalid.tool_name", `\`*\` names no tool — a rule reaches the tool it names, so this one would compile and never match; name the tool, or state the answer for every call no rule reaches with \`defaultAction\``);
             continue;
         }
-        if (parsed.ruleContent === undefined && indexOfUnescaped(text, "(") !== -1) {
-            const open = indexOfUnescaped(text, "(");
-            const close = lastIndexOfUnescaped(text, ")");
-            const legitimateBare = close === text.length - 1 && ["", "*"].includes(text.substring(open + 1, close));
-            if (!legitimateBare) {
-                bad(text, "invalid.paren", "malformed parentheses / trailing characters (would silently downgrade to a bare-tool rule)");
-                continue;
-            }
-        }
         const toolName = parsed.toolName;
         const parenthesised = parsed.ruleContent !== undefined || indexOfUnescaped(text, "(") !== -1;
         if (toolName.startsWith(MCP_NAMESPACE.prefix) && parenthesised) {
@@ -153,7 +165,7 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
                 continue;
             }
             const face = resolved.face;
-            if (ruleToolGrammarOf(toolName) === "name") {
+            if (nameGrammarReads(toolName, content)) {
                 const parsedName = parseRuleText(text, verb);
                 if ("reject" in parsedName) {
                     bad(text, "invalid.command_rule", `${parsedName.reject.code}: ${parsedName.reject.message}`);
@@ -231,12 +243,16 @@ export function validatePermissionRules(rules, opts) {
 function isPlainObjectArgs(args) {
     return typeof args === "object" && args !== null && !Array.isArray(args);
 }
-function matchParamRules(rules, args, maxScalarValueChars) {
+function matchParamRules(rules, req, maxScalarValueChars) {
+    const args = req.args;
     if (!isPlainObjectArgs(args))
         return undefined;
     for (const r of rules) {
-        if (!Object.hasOwn(args, r.param))
+        if (!Object.hasOwn(args, r.param)) {
+            if (readingAbsorbs(req, r.param, r.pattern))
+                return r;
             continue;
+        }
         const raw = args[r.param];
         if (raw === undefined || raw === null)
             continue;
@@ -251,6 +267,17 @@ function matchParamRules(rules, args, maxScalarValueChars) {
     }
     return undefined;
 }
+function readingAbsorbs(req, param, pattern) {
+    if (pattern.includes("*"))
+        return false;
+    try {
+        const read = canonicalize(argsAsTheToolReads(req, { ...req.args, [param]: pattern }));
+        return read !== UNCANONICALIZABLE && read === canonicalize(req.args);
+    }
+    catch {
+        return false;
+    }
+}
 function ruleDenial(req, ruleText, source) {
     return ruleDenialSentence({ source: "permission", tool: req.toolName, rule: ruleText, ...(source ? { origin: source } : {}) });
 }
@@ -376,6 +403,16 @@ export function createPermissionRulePolicy(rules, opts) {
         }
         return unreadable;
     };
+    const keylessRefusal = (entry, req) => {
+        for (const r of [...entry.content.deny, ...entry.content.ask]) {
+            if (r.parsed.match !== "name" || nameRuleSubjectOf(r.parsed.tool, req.args) !== undefined)
+                continue;
+            const absent = keyedValueAbsentReason(r.parsed.tool);
+            if (absent !== undefined)
+                return ruleDenialSentence({ source: "permission", tool: req.toolName, rule: r.ruleText, ...(r.source ? { origin: r.source } : {}), detail: absent });
+        }
+        return undefined;
+    };
     const unreadableAsk = (hit, lane, req) => ({
         action: "ask",
         message: `tool "${req.toolName}" needs approval: the call could not be read against the permission rule ${hit.rule.ruleText} (${hit.unreadable}) — a person must decide`,
@@ -422,11 +459,14 @@ export function createPermissionRulePolicy(rules, opts) {
                 return face !== undefined ? attest(denied, req, { pathDenial: { rule: contentDeny.rule.ruleText, view: contentDeny.view, face } }) : denied;
             }
             if (entry) {
-                const paramDeny = matchParamRules(entry.param.deny, req.args, caps.maxScalarValueChars);
+                const paramDeny = matchParamRules(entry.param.deny, req, caps.maxScalarValueChars);
                 if (paramDeny) {
                     return { action: "deny", message: ruleDenial(req, paramDeny.ruleText, paramDeny.source) };
                 }
             }
+            const keyless = entry !== undefined ? keylessRefusal(entry, req) : undefined;
+            if (keyless !== undefined)
+                return { action: "deny", message: keyless };
             if (contentDeny?.unreadable !== undefined)
                 return unreadableAsk({ rule: contentDeny.rule, unreadable: contentDeny.unreadable }, "content_deny", req);
             if (entry) {
@@ -447,7 +487,7 @@ export function createPermissionRulePolicy(rules, opts) {
                 return { action: "ask", message: ruleAskMessage(contentAsk.rule.ruleText, contentAsk.rule.source), matchedAskRule: contentAsk.rule.ruleText };
             }
             if (entry) {
-                const paramAsk = matchParamRules(entry.param.ask, req.args, caps.maxScalarValueChars);
+                const paramAsk = matchParamRules(entry.param.ask, req, caps.maxScalarValueChars);
                 if (paramAsk) {
                     return { action: "ask", message: ruleAskMessage(paramAsk.ruleText, paramAsk.source), matchedAskRule: paramAsk.ruleText };
                 }

package/dist/core/prompt-section-seat.d.ts

@@ -1,8 +1,8 @@
-/** The named sections whose entries the host may dispose of — a closed set. */
+import type { LegModBus } from "./mods/stations.js";
+/** The named sections whose entries the host may dispose of — a closed set (the event's `name`). */
 export declare const DISPOSABLE_PROMPT_SECTIONS: readonly ["core/discovery.mcp-instructions"];
 export type DisposablePromptSection = (typeof DISPOSABLE_PROMPT_SECTIONS)[number];
-/** One entry of a named section, as the engine computed it, before it reaches the model. A frozen copy:
- *  writing to it changes nothing. */
+/** One entry of a named section, as the engine computed it, before it reaches the model. */
 export interface PromptSectionEntry {
     readonly section: DisposablePromptSection;
     /** The entry's key within the section: the MCP server's declared name. */
@@ -12,35 +12,16 @@ export interface PromptSectionEntry {
     /** The tools this leg mounted from that server, by their namespaced names. */
     readonly mountedTools: readonly string[];
 }
-/** The host's answer. `undefined` = include the entry as computed. */
-export type PromptSectionDisposition = {
-    readonly op: "drop";
-} | {
-    readonly op: "replace";
-    readonly text: string;
-};
 /** Who wrote the text an entry carries into the model's view. */
 export type PromptSectionAuthor = "server" | "host";
-export interface PromptSectionSeat {
-    /**
-     * Answer the disposition of one entry of a named section ({@link DISPOSABLE_PROMPT_SECTIONS}): return
-     * nothing to include it, `{ op: "drop" }` to leave it out of the model's view on every lane, or
-     * `{ op: "replace", text }` to place the host's own non-blank text instead — host text, rendered
-     * without the untrusted-data fence the server's text rides in, under the same per-entry bound and the same
-     * disclosed cut. Called once each time the entry's text
-     * enters the run (a re-dial asks again). Synchronous. A throw, a Promise, or any other value includes
-     * the entry and raises a coded operator warning (`prompt.section_answer_invalid`).
-     */
-    section?(entry: PromptSectionEntry): PromptSectionDisposition | undefined;
-}
 /** One server's entry of the MCP instructions section as the run carries it, after the host's disposition. */
 export interface McpInstructionsEntry {
     readonly server: string;
     readonly text: string;
     readonly author: PromptSectionAuthor;
 }
-/** What one fold leaves in the run: the entry's text and author, absent when dropped, plus the defect
- *  sentence when the answer could not be read. */
+/** What one disposition leaves in the run: the entry's text and author, absent when dropped, plus the defect
+ *  sentence when an answer could not be taken. */
 export interface DisposedSectionEntry {
     readonly kept?: {
         readonly text: string;
@@ -48,7 +29,14 @@ export interface DisposedSectionEntry {
     };
     readonly defect?: string;
 }
-/** Read the seat's answer for one entry. Each member of the answer is read once. */
-export declare function disposeSectionEntry(seat: PromptSectionSeat | undefined, entry: PromptSectionEntry): DisposedSectionEntry;
-/** The operator warning for an answer the fold could not read. */
+/** The disposition the dial reads: one entry in, its disposition out. */
+export type PromptSectionDisposer = (entry: PromptSectionEntry) => Promise<DisposedSectionEntry>;
+/**
+ * The disposer over the leg's bus, or undefined when no handler hangs on `prompt.section` (the dial then keeps
+ * every entry as computed, with nothing raised).
+ */
+export declare function sectionDisposerOf(bus: LegModBus | undefined, signal?: AbortSignal): PromptSectionDisposer | undefined;
+/** One entry's disposition at its dial: the leg's disposer when one is wired, else the entry as the engine computed it. */
+export declare function disposeSectionEntry(disposer: PromptSectionDisposer | undefined, entry: PromptSectionEntry): Promise<DisposedSectionEntry>;
+/** The operator warning for an answer the station could not take. */
 export declare function sectionAnswerWarning(defect: string): Error;

package/dist/core/prompt-section-seat.js

@@ -1,48 +1,81 @@
-import { thrownText } from "./thrown-value.js";
+import { bandOf } from "../prompt-assembly/bands.js";
+import { lockedTextIn, receivePromptData } from "../prompt-assembly/overlay.js";
 import { inlineUntrusted } from "./untrusted-text.js";
-import { egressText } from "./untrusted-egress.js";
+import { egressThrownText, extensionWords } from "./untrusted-egress.js";
 export const DISPOSABLE_PROMPT_SECTIONS = Object.freeze(["core/discovery.mcp-instructions"]);
-const ANSWER_KEYS = { drop: ["op"], replace: ["op", "text"] };
-const FOREIGN_VALUE_MAX = 200;
-const STRAY_KEYS_NAMED = 5;
 const DEFECT_MAX = 600;
-const foreign = (s, max) => inlineUntrusted(egressText("same-principal", s), max);
-export function disposeSectionEntry(seat, entry) {
-    const computed = { text: entry.text, author: "server" };
-    if (seat?.section === undefined)
-        return { kept: computed };
-    const offered = Object.freeze({ ...entry, mountedTools: Object.freeze([...entry.mountedTools]) });
-    const where = `prompt section "${entry.section}" entry "${inlineUntrusted(entry.server, 160)}"`;
-    const unread = (why) => ({ kept: computed, defect: inlineUntrusted(`${where}: ${why} — the entry is included as the engine computed it`, DEFECT_MAX) });
-    try {
-        const answer = seat.section(offered);
-        if (answer === undefined)
-            return { kept: computed };
-        if (answer === null || typeof answer !== "object")
-            return unread(`the answer is ${answer === null ? "null" : typeof answer}, not undefined, { op: "drop" } or { op: "replace", text }`);
-        const record = answer;
-        if (typeof record["then"] === "function") {
-            void Promise.resolve(answer).catch(() => undefined);
-            return unread("the section seat returned a Promise; it is synchronous");
+function readAnswer(answer, seat) {
+    if (typeof answer !== "object" || answer === null || Array.isArray(answer))
+        return `answered ${answer === null ? "null" : Array.isArray(answer) ? "an array" : typeof answer}; prompt.section takes { text: string | null }`;
+    const received = receivePromptData(answer);
+    if ("notData" in received)
+        return `a prompt.section answer is data (plain objects, arrays, strings, booleans); it holds ${received.notData}`;
+    const data = received.value;
+    const keys = Object.keys(data);
+    const stray = keys.filter((k) => k !== "text");
+    if (stray.length > 0)
+        return `the answer carries ${stray.slice(0, 5).map((k) => JSON.stringify(extensionWords(k, 40))).join(", ")} (text only)`;
+    if (!keys.includes("text"))
+        return "the answer has no text (a string to place, null to leave the entry out)";
+    const text = data["text"];
+    const op = text === null ? "drop" : "replace";
+    if (text !== null && (typeof text !== "string" || text.trim() === ""))
+        return `text is ${typeof text === "string" ? "blank" : typeof text}; it is a non-blank string or null`;
+    const source = seat === "deployment" ? "deploy" : "task";
+    if (!bandOf("discovery").ops[source].includes(op))
+        return `a ${source} answer may not ${op} a discovery entry`;
+    if (typeof text === "string") {
+        const hits = lockedTextIn(text);
+        if (hits.length > 0)
+            return `the text contains, verbatim, the locked text of ${[...new Set(hits.map((h) => h.split("#")[0]))].join(", ")}`;
+    }
+    return { text };
+}
+export function sectionDisposerOf(bus, signal) {
+    if (bus === undefined || !bus.hasHandlers("prompt.section"))
+        return undefined;
+    return async (entry) => {
+        const computed = { text: entry.text, author: "server" };
+        const where = `prompt section "${entry.section}" entry "${inlineUntrusted(entry.server, 160)}"`;
+        const e = { name: entry.section, key: entry.server, mountedTools: Object.freeze([...entry.mountedTools]), text: entry.text };
+        const bottom = Object.freeze({ text: entry.text });
+        const taken = new WeakMap([[bottom, entry.text]]);
+        let outcome;
+        try {
+            outcome = await bus.dispatch("prompt.section", e, {
+                bottom: () => bottom,
+                ...(signal !== undefined ? { signal } : {}),
+                checkAnswer: (a, _e, by) => {
+                    if (typeof a === "object" && a !== null && taken.has(a))
+                        return undefined;
+                    const read = readAnswer(a, by.seat);
+                    if (typeof read === "string")
+                        return read;
+                    taken.set(a, read.text);
+                    return undefined;
+                },
+            });
         }
-        const op = record["op"];
-        const text = record["text"];
-        if (op !== "drop" && op !== "replace")
-            return unread(`the answer's op is ${typeof op === "string" ? `"${foreign(op, 40)}"` : typeof op}, not "drop" or "replace"`);
-        const stray = Object.keys(record).filter((k) => !ANSWER_KEYS[op].includes(k));
-        if (stray.length > 0) {
-            const named = stray.slice(0, STRAY_KEYS_NAMED).map((k) => foreign(k, 40)).join(", ");
-            return unread(`a "${op}" answer carries ${named}${stray.length > STRAY_KEYS_NAMED ? ` and ${stray.length - STRAY_KEYS_NAMED} more` : ""}`);
+        catch (err) {
+            return { kept: computed, defect: inlineUntrusted(`${where}: the station could not be raised (${inlineUntrusted(egressThrownText("same-principal", err), 200)}) — the entry is included as the engine computed it`, DEFECT_MAX) };
         }
-        if (op === "drop")
-            return {};
-        if (typeof text !== "string" || text.trim() === "")
-            return unread(`a "replace" answer needs non-blank text`);
-        return { kept: { text, author: "host" } };
-    }
-    catch (err) {
-        return unread(`the section seat (or reading its answer) threw (${foreign(thrownText(err), FOREIGN_VALUE_MAX)})`);
-    }
+        if (outcome.kind === "aborted")
+            return { kept: computed };
+        const skipped = outcome.skipped.map((s) => `extension "${extensionWords(s.registration, 80)}" ${s.cause === "violation" ? "gave an answer the station cannot take" : s.cause}: ${extensionWords(s.reason, 200)}`);
+        const defect = skipped.length > 0 ? inlineUntrusted(`${where}: ${skipped.join("; ")} — that answer is skipped; what is below it stands`, DEFECT_MAX) : undefined;
+        if (outcome.kind === "failed")
+            return { kept: computed, ...(defect !== undefined ? { defect } : {}) };
+        const answer = outcome.answer;
+        const text = typeof answer === "object" && answer !== null ? taken.get(answer) : undefined;
+        if (text === undefined) {
+            return { kept: computed, defect: inlineUntrusted(`${where}: the chain's answer is not one the station took — the entry is included as the engine computed it`, DEFECT_MAX) };
+        }
+        const disposed = text === null ? {} : typeof text === "string" && text !== entry.text ? { kept: { text, author: "host" } } : { kept: computed };
+        return { ...disposed, ...(defect !== undefined ? { defect } : {}) };
+    };
+}
+export function disposeSectionEntry(disposer, entry) {
+    return disposer === undefined ? Promise.resolve({ kept: { text: entry.text, author: "server" } }) : disposer(entry);
 }
 export function sectionAnswerWarning(defect) {
     return Object.assign(new Error(defect), { code: "prompt.section_answer_invalid" });

package/dist/core/protocol-http-auth.d.ts

@@ -3,7 +3,9 @@
  * header (`principalHeader`) — and the one rule they obey, for MCP and A2A alike: they travel only to the
  * endpoints the declaration names, and every header name has exactly one owner, compared the way HTTP
  * compares names (case-insensitively). The principal header's owner is the engine: it sends the task's
- * principal under that name, or nothing under it when the task has none.
+ * principal under that name, or nothing under it when the task has none. A static header the credential vocabulary
+ * reads as a credential is one the engine holds from the moment it resolves it: no child spawned on this host inherits
+ * a variable whose value equals it (`holdOwnCredentialValues`, src/core/secret-env.ts).
  *
  * A declaration that breaks the rule is that peer's defect: the resolver throws inside the peer's own dial,
  * so the peer is skipped with a coded warning and its siblings still mount. The MCP transport binds its

package/dist/core/protocol-http-auth.js

@@ -1,3 +1,4 @@
+import { credentialHeaderValues, holdOwnCredentialValues } from "./secret-env.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 export function headerOwnershipCollision(t) {
     const owners = new Map();
@@ -13,6 +14,7 @@ export function resolveProtocolHttpHeaders(protocol, t, principal) {
     const principalHeader = t.principalHeader;
     const declared = t.headers;
     const own = { ...(declared !== undefined ? { headers: { ...declared } } : {}), ...(principalHeader !== undefined ? { principalHeader } : {}) };
+    holdOwnCredentialValues(credentialHeaderValues(own.headers));
     const collision = headerOwnershipCollision(own);
     if (collision !== undefined) {
         throw Object.assign(new Error(`${protocol}: the declaration names the header "${inlineUntrusted(collision.first, 80)}" twice ("${inlineUntrusted(collision.second, 80)}" — header names are case-insensitive); ${principalHeader !== undefined && collision.second === principalHeader ? "the principal header is the engine's to send, so remove the static entry" : "keep one spelling"} — this peer is not dialed`), { code: "config.protocol_header_collision" });

package/dist/core/reminder-mint.d.ts

@@ -79,8 +79,8 @@ export declare function formatHookFeedback(text: string, mark?: string): string;
  * DECLARE port — the system-prompt declaration that gives the mark meaning. STRICT, single form
  * (design/319 D-2, no grace clause): reminder-shaped text without the current mark is data wherever
  * it appears — including TRUE pre-319 engine mints in a resumed transcript, a deliberate fail-safe
- * downgrade (stale guidance loses authority; forgery gains none). Composed into the `# Harness`
- * head lines when a mark is threaded (prompts/default.ts `harnessHeadLines`); a fork inherits the
+ * downgrade (stale guidance loses authority; forgery gains none). Composed as its own section
+ * (`core/harness.reminder-mark`) when a mark is threaded; a fork inherits the
  * parent's prompt bytes and therefore the parent's declaration — never a second one.
  *
  * A block carrying the current mark is the engine's own wherever it stands, tool results included:

package/dist/core/remote-env.d.ts

@@ -162,7 +162,7 @@ export interface ExecStreamOptions {
     signal?: AbortSignal;
     /**
      * Idle/liveness read timeout (ms). If no {@link OutputChunk} arrives within this window, `execStream` ends
-     * with a {@link RemoteExecutionError} (code `"timeout"`) instead of hanging. **Needed in practice for remote
+     * with a {@link RemoteExecutionError} (code `"liveness_no_output"`) instead of hanging. **Needed in practice for remote
      * backends** (design/48 §5, service [7]): E2B issue #1128 — a *streaming* call sets no read timeout (only unary
      * does), so an unreachable sandbox hangs the worker forever. Distinct from `timeout` (total wall-clock).
      *
@@ -170,8 +170,9 @@ export interface ExecStreamOptions {
      * when this is unset (a missing idle timeout MUST NOT mean "wait forever / until the env dies"), and that bound
      * MUST cover the **command-creation/handshake RPC**, not only the post-first-chunk loop — a provider hang
      * typically occurs at creation, before any chunk arrives, so an idle timer started only after the first chunk
-     * misses it. On trigger, throw {@link RemoteExecutionError} with code `"timeout"` (retryable by the caller per
-     * the command's idempotency — the adapter MUST NOT blind-retry).
+     * misses it. On trigger, throw {@link RemoteExecutionError} with code `"liveness_no_output"` (retryable by the
+     * caller per the command's idempotency — the adapter MUST NOT blind-retry). The wall-clock {@link timeout}
+     * keeps `"timeout"`: the two cuts are different words because they explain themselves with different numbers.
      */
     readTimeoutMs?: number;
     /** Per-call output cap (design/48 §5 gap 8): stop streaming after this many bytes to avoid a `find /` flooding the control plane. */
@@ -190,12 +191,22 @@ export type RemoteExecutionErrorCode =
 /** The command/stream was aborted via its `AbortSignal`. */
  | "aborted"
 /**
- * A command's wall-clock {@link ExecStreamOptions.timeout} or liveness {@link ExecStreamOptions.readTimeoutMs}
- * was exceeded — including a provider RPC hang at command creation (service [45]/[59]). **Retryable** by the
- * caller per the command's idempotency (the adapter MUST NOT blind-retry). Distinct from `"aborted"` (a
- * caller-driven `AbortSignal`) and `"connect_failed"` (workspace provisioning, not a per-command hang).
+ * A bound on elapsed time was exceeded: a command's wall-clock {@link ExecStreamOptions.timeout}, or the idle
+ * bound of a lifecycle / filesystem RPC (service [45]/[59]). **Retryable** by the caller per the op's
+ * idempotency (the adapter MUST NOT blind-retry). Distinct from `"aborted"` (a caller-driven `AbortSignal`),
+ * `"connect_failed"` (workspace provisioning, not a per-command hang) and `"liveness_no_output"` (an exec
+ * stream's silence window — below).
  */
  | "timeout"
+/**
+ * An exec stream produced no {@link OutputChunk} for its liveness window ({@link ExecStreamOptions.readTimeoutMs},
+ * or the adapter's default bound) — including a provider RPC hang at command creation, before the first chunk
+ * (service [45]/[59]). A hang detector, not a budget: it is the word for the cut that used to share `"timeout"`
+ * with the wall-clock budget, and the two explain themselves with different numbers (the window versus the
+ * budget the caller asked for), so a consumer must be able to tell them apart by code. **Retryable** by the
+ * caller per the command's idempotency (the adapter MUST NOT blind-retry), exactly as `"timeout"` is.
+ */
+ | "liveness_no_output"
 /**
  * The op is not supported by this adapter's capabilities (design/61 §9 A) — e.g. `suspendVM`/`resumeVM` on a
  * non-suspendable SSH/ADB env. Permanent for this env; check {@link RemoteExecutionEnv.capabilities} first.
@@ -235,8 +246,8 @@ export type RemoteExecutionErrorCode =
 /**
  * The RETRYABLE half of {@link RemoteExecutionErrorCode} — the codes whose own contract above says a retry
  * can succeed (`auth_transient`: retry-exactly-once after the device is authorized; `connect_failed`: the
- * workspace could not be reached/provisioned this attempt; `timeout`: a liveness bound tripped;
- * `transport_lost`: re-establish the connection). Every OTHER code is permanent for this attempt
+ * workspace could not be reached/provisioned this attempt; `timeout` / `liveness_no_output`: a time bound
+ * tripped; `transport_lost`: re-establish the connection). Every OTHER code is permanent for this attempt
  * (`auth_failed`/`unsupported`), caller-driven (`aborted`), unclassifiable (`unknown`), or
  * outcome-unknowable (`outcome_unknown` — design/380 O12: the op may have ALREADY executed, so a retry
  * re-drives committed side effects) — retrying them burns budget or, worse, re-drives a rejected
@@ -284,8 +295,8 @@ export declare class RemoteExecutionError extends Error {
  *    wall-clock would false-kill the (durable-checkpoint *命门*) path. So such ops bound on an **idle/no-heartbeat**
  *    window (reset by observable progress), not total elapsed time. Cheap control RPCs (`isRunning`, a small
  *    `connect` handshake) may use a short wall-clock. The adapter sizes the bound per op class.
- * 3. **A liveness breach surfaces as a typed, retryable error**: `RemoteExecutionError` code `"timeout"` for the
- *    lifecycle/stream ops; for the inherited filesystem ops (which return the vendored `Result<_, FileError>`),
+ * 3. **A liveness breach surfaces as a typed, retryable error**: `RemoteExecutionError` code `"liveness_no_output"`
+ *    for an exec stream's silence window and `"timeout"` for the lifecycle ops' idle bound; for the inherited filesystem ops (which return the vendored `Result<_, FileError>`),
  *    a `FileError` — but still **bounded, never an unbounded wait**. Retry is the caller's decision per the op's
  *    idempotency; the adapter MUST NOT blind-retry.
  */
@@ -418,7 +429,8 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
      * per-command timeout is **independent of the env/sandbox lifetime** and an adapter MUST NOT fall back to the
      * lifetime when none is given (else a hung provider RPC pins the worker for the whole sandbox lifetime). An
      * adapter SHOULD enforce a bounded default liveness/idle timeout that also covers the command-creation RPC, and
-     * surface a liveness/timeout breach as a typed, retryable {@link RemoteExecutionError} code `"timeout"`. See
+     * surface a silence breach as a typed, retryable {@link RemoteExecutionError} code `"liveness_no_output"` and a
+     * wall-clock breach as `"timeout"`. See
      * {@link ExecStreamOptions.timeout} / {@link ExecStreamOptions.readTimeoutMs}.
      */
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;

package/dist/core/remote-env.js

@@ -2,6 +2,7 @@ export const RETRYABLE_REMOTE_ERROR_CODES = [
     "auth_transient",
     "connect_failed",
     "timeout",
+    "liveness_no_output",
     "transport_lost",
 ];
 export function isRetryableRemoteErrorCode(code) {

package/dist/core/resume-startup-cause.d.ts

@@ -9,6 +9,10 @@
  *  · `environment` — the leg's infrastructure failed (the workspace restore, an abort): the decision is
  *    untouched, and a retry replays it;
  *  · `session_gone` — the resumed agent's transcript session is missing;
+ *  · `transcript_corrupt` — the resumed agent's transcript session is THERE but cannot be read as a session: its log
+ *    has no header its store wrote (`corrupt_session`), or its entry tree is structurally unusable — a leaf or parent
+ *    entry that is not in the log (`invalid_session`). Distinct from `session_gone`: the bytes exist, so deleting or
+ *    restoring the transcript is the remedy, not re-creating a session;
  *  · `tool_unavailable` — the approved tool is not available to the resumed leg (gone, replaced by a
  *    different contract, or an inherited tool the drive cannot hand over): this approval cannot run, and a
  *    fresh decision resolves it;
@@ -18,6 +22,7 @@
  *  · `decision_rejected` — the supplied decision does not fit the checkpoint (another gate's answer, an
  *    unsafe payload, an input the constraints refuse): correct the decision and resubmit.
  */
+import type { AssertAllKeysHandled } from "./ask-origin.js";
 /**
  * design/80 D-1: why a consumed checkpoint was {@link import("./checkpoint-store.js").CheckpointStore.reopen | reopened}
  * (resolved → pending). The reason drives re-resume validation (§3 invariant #1): an `env_failed` reopen is a SYSTEM
@@ -41,11 +46,20 @@
  */
 export declare const REOPEN_REASONS: readonly ["env_failed", "tool_unavailable", "constraint_rejected", "config_refused"];
 export type ReopenReason = (typeof REOPEN_REASONS)[number];
-export declare const RESUME_STARTUP_CAUSES: readonly ["environment", "session_gone", "tool_unavailable", "configuration", "decision_rejected"];
+export declare const RESUME_STARTUP_CAUSES: readonly ["environment", "session_gone", "transcript_corrupt", "tool_unavailable", "configuration", "decision_rejected"];
 export type ResumeStartupCause = (typeof RESUME_STARTUP_CAUSES)[number];
 /** The cause a resume failure's code names; `undefined` when the code is absent or the table does not
  *  name it. Every `config.*` code is a configuration door's refusal. */
 export declare function resumeStartupCauseOf(code: string | undefined): ResumeStartupCause | undefined;
+declare const REOPEN_REASON_OF_CAUSE: {
+    readonly environment: "env_failed";
+    readonly session_gone: "env_failed";
+    readonly transcript_corrupt: "env_failed";
+    readonly tool_unavailable: "tool_unavailable";
+    readonly configuration: "config_refused";
+    readonly decision_rejected: "constraint_rejected";
+};
+export type ReopenReasonTableCoversEveryCause = AssertAllKeysHandled<Exclude<ResumeStartupCause, keyof typeof REOPEN_REASON_OF_CAUSE>>;
 /**
  * The reason a consumed checkpoint whose approved action never started returns to pending under. A failure
  * whose cause is not known reopens as `env_failed`: the leg went away before the action ran, the human's
@@ -54,3 +68,4 @@ export declare function resumeStartupCauseOf(code: string | undefined): ResumeSt
 export declare function reopenReasonOf(cause: ResumeStartupCause | undefined): ReopenReason;
 /** What the result of a returned resume leg says after its checkpoint was reopened, per reason. */
 export declare function reopenedUnstartedSentence(reason: ReopenReason): string;
+export {};

package/dist/core/resume-startup-cause.js

@@ -1,9 +1,11 @@
 export const REOPEN_REASONS = Object.freeze(["env_failed", "tool_unavailable", "constraint_rejected", "config_refused"]);
-export const RESUME_STARTUP_CAUSES = Object.freeze(["environment", "session_gone", "tool_unavailable", "configuration", "decision_rejected"]);
+export const RESUME_STARTUP_CAUSES = Object.freeze(["environment", "session_gone", "transcript_corrupt", "tool_unavailable", "configuration", "decision_rejected"]);
 const CAUSE_OF_CODE = new Map([
     ["resume.env_failed", "environment"],
     ["checkpoint.resume_aborted", "environment"],
     ["resume.session_not_found", "session_gone"],
+    ["corrupt_session", "transcript_corrupt"],
+    ["invalid_session", "transcript_corrupt"],
     ["resume.tool_unavailable", "tool_unavailable"],
     ["resume.tool_contract_mismatch", "tool_unavailable"],
     ["checkpoint.config_refused", "configuration"],
@@ -22,6 +24,7 @@ export function resumeStartupCauseOf(code) {
 const REOPEN_REASON_OF_CAUSE = {
     environment: "env_failed",
     session_gone: "env_failed",
+    transcript_corrupt: "env_failed",
     tool_unavailable: "tool_unavailable",
     configuration: "config_refused",
     decision_rejected: "constraint_rejected",

package/dist/core/retention.js

@@ -1,3 +1,4 @@
+import { describeRejectedValue } from "./tool-search-setting.js";
 export const RETENTION_CASCADE_DOMAINS = Object.freeze(["checkpoints", "session-trees", "orphan-tool-results"]);
 export const RETENTION_CASCADE_EXEMPT = Object.freeze(["session-pollution", "session-capture-optout", "lineage.json"]);
 function codedError(code, message) {
@@ -7,8 +8,12 @@ function codedError(code, message) {
 }
 export function assertRetentionCapability(input) {
     const { policy, locked, stores } = input;
+    const declared = policy;
+    if (declared !== undefined && (typeof declared !== "object" || declared === null || Array.isArray(declared))) {
+        throw codedError("config.retention_policy", `retentionPolicy must be an object carrying maxAgeDays (got ${declared === null ? "null" : Array.isArray(declared) ? "an array" : typeof declared}).`);
+    }
     if (policy !== undefined && (!Number.isFinite(policy.maxAgeDays) || policy.maxAgeDays < 0)) {
-        throw codedError("config.retention_policy", `retentionPolicy.maxAgeDays must be a finite non-negative number of days (got ${String(policy.maxAgeDays)}).`);
+        throw codedError("config.retention_policy", `retentionPolicy.maxAgeDays must be a finite non-negative number of days (got ${describeRejectedValue(policy.maxAgeDays)}).`);
     }
     const declaredRetention = (name, store) => {
         const r = store.retention;
@@ -19,7 +24,7 @@ export function assertRetentionCapability(input) {
         throw codedError("config.retention_capability", `store "${name}" declares an unparseable retention value ${JSON.stringify(r)} — expected "managed" or "none".`);
     };
     const declarations = stores
-        .filter((s) => s.store !== undefined)
+        .filter((s) => s.store !== undefined && s.store !== null)
         .map(({ name, store }) => ({ name, retention: declaredRetention(name, store) }));
     if (!locked || policy === undefined)
         return;