@sema-agent/core 5.58.0 → 5.60.0

package/dist/core/context-edit.js

@@ -1,7 +1,11 @@
+import { createHash } from "node:crypto";
 import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "../internal/harness.js";
 import { isToolResult } from "./message-utils.js";
-import { offloadPagebackHint } from "./tool-result-store.js";
+import { PERSISTED_OUTPUT_PREFIX, offloadPagebackHint } from "./tool-result-store.js";
 const CLEARED_MARKER = "[tool result cleared to save context]";
+const CC_CLEARED_MARKER = "[Old tool result content cleared]";
+const LEGACY_CLEARED_EXTENDED_PREFIX = "[tool result cleared to save context —";
+const CC_CLEARED_EXTENDED_PREFIX = "[Old tool result content cleared —";
 const refNote = (ref) => offloadPagebackHint(ref, "cleared");
 const mediaNote = (blocks) => {
     const byType = new Map();
@@ -17,9 +21,10 @@ const mediaNote = (blocks) => {
     const breakdown = [...byType].map(([t, c]) => `${c} ${t}`).join(", ");
     return `${n} attachments (${breakdown}) no longer visible after this clear`;
 };
-const clearedMarker = (notes) => {
+const clearedMarker = (notes, machine = "legacy") => {
     const present = notes.filter((n) => n !== undefined);
-    return present.length > 0 ? `[tool result cleared to save context — ${present.join("; ")}]` : CLEARED_MARKER;
+    const [plain, extendedPrefix] = machine === "cc" ? [CC_CLEARED_MARKER, CC_CLEARED_EXTENDED_PREFIX] : [CLEARED_MARKER, LEGACY_CLEARED_EXTENDED_PREFIX];
+    return present.length > 0 ? `${extendedPrefix} ${present.join("; ")}]` : plain;
 };
 export const EDIT_FRACTION = 0.7;
 export const CONTEXT_OUTPUT_RESERVE_TOKENS = 20000;
@@ -28,13 +33,16 @@ export function contextEditFrontier(window) {
     return Math.max(window - (CONTEXT_OUTPUT_RESERVE_TOKENS + COMPACTION_TRIGGER_BUFFER_TOKENS), Math.floor(window * EDIT_FRACTION));
 }
 export const DEFAULT_KEEP_RECENT_TOOL_RESULTS = 3;
+export const CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS = 5;
+export const MIN_CLEAR_SAVINGS_TOKENS = 20000;
+const MEDIA_BLOCK_SAVINGS_TOKENS = 2000;
 export const MIN_KEEP_RECENT_TOOL_RESULTS = 1;
-function resolveKeepRecentToolResults(value) {
+function resolveKeepRecentToolResults(value, defaultValue) {
     if (value === undefined)
-        return DEFAULT_KEEP_RECENT_TOOL_RESULTS;
+        return defaultValue;
     if (!Number.isSafeInteger(value) || value < 0) {
         throw new TypeError(`keepRecentToolResults must be a non-negative safe integer (got ${String(value)}); ` +
-            `omit it for the default ${DEFAULT_KEEP_RECENT_TOOL_RESULTS}`);
+            `omit it for the default ${defaultValue}`);
     }
     return Math.max(MIN_KEEP_RECENT_TOOL_RESULTS, value);
 }
@@ -49,12 +57,29 @@ export const COMPACTABLE_TOOLS = new Set([
     "Edit",
     "Write",
 ]);
-function isCleared(m) {
+function soleMarkerText(m) {
     const content = m.content;
     if (!Array.isArray(content) || content.length !== 1)
-        return false;
+        return undefined;
     const text = content[0].text;
-    return text === CLEARED_MARKER || (typeof text === "string" && text.startsWith("[tool result cleared to save context —"));
+    return typeof text === "string" ? text : undefined;
+}
+function isCleared(m, recognizeCcForms = false) {
+    const text = soleMarkerText(m);
+    if (text === undefined)
+        return false;
+    if (text === CLEARED_MARKER || text.startsWith(LEGACY_CLEARED_EXTENDED_PREFIX))
+        return true;
+    return recognizeCcForms && (text === CC_CLEARED_MARKER || text.startsWith(CC_CLEARED_EXTENDED_PREFIX));
+}
+function isCcCleared(m) {
+    if (isCleared(m, true))
+        return true;
+    const content = m.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return false;
+    const first = content[0];
+    return first?.type === "text" && typeof first.text === "string" && first.text.startsWith(PERSISTED_OUTPUT_PREFIX);
 }
 export function dropEmptyFailureAssistants(messages) {
     const isJunk = (m) => {
@@ -67,8 +92,56 @@ export function dropEmptyFailureAssistants(messages) {
     };
     return messages.some(isJunk) ? messages.filter((m) => !isJunk(m)) : messages;
 }
+function structuralClearSavings(target) {
+    const content = Array.isArray(target.content) ? target.content : [];
+    let saved = 0;
+    for (const c of content) {
+        const block = c;
+        if (block?.type === "text") {
+            saved += typeof block.text === "string" ? Math.round(block.text.length / 4) : 0;
+        }
+        else {
+            saved += MEDIA_BLOCK_SAVINGS_TOKENS;
+        }
+    }
+    return saved;
+}
+function clearOneResult(target, offload, machine) {
+    const rawContent = Array.isArray(target.content) ? target.content : [];
+    let ref;
+    if (offload) {
+        const fullText = rawContent
+            .filter((c) => c?.type === "text" && typeof c.text === "string")
+            .map((c) => c.text)
+            .join("\n");
+        if (target.toolCallId && fullText.trim().length > 0) {
+            try {
+                ref = refNote(offload.persist(target.toolCallId, fullText));
+            }
+            catch {
+                ref = undefined;
+            }
+        }
+    }
+    const mediaBlocks = rawContent.filter((c) => c?.type !== "text");
+    const marker = clearedMarker([ref, mediaBlocks.length > 0 ? mediaNote(mediaBlocks) : undefined], machine);
+    return { ...target, content: [{ type: "text", text: marker }] };
+}
+function reportCleared(onCleared, clears, tokensSavedEstimate) {
+    if (!onCleared || clears.length === 0)
+        return;
+    try {
+        onCleared({ clears, tokensSavedEstimate });
+    }
+    catch {
+    }
+}
 export function clearStaleToolResults(messages, opts) {
     const cpt = opts.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+    const machine = opts.machine ?? "legacy";
+    if (machine !== "legacy" && machine !== "cc") {
+        throw new TypeError(`machine must be "legacy" | "cc" (got ${String(machine)}); omit it for the default "legacy"`);
+    }
     const anchored = opts.anchoredTotalTokens !== undefined;
     let total;
     let anchorIdx = -1;
@@ -85,48 +158,190 @@ export function clearStaleToolResults(messages, opts) {
     if (total <= opts.budgetTokens) {
         return messages;
     }
-    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults);
+    if (machine === "cc") {
+        return clearStaleToolResultsCc(messages, opts);
+    }
+    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults, DEFAULT_KEEP_RECENT_TOOL_RESULTS);
     const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
-    const toolResultCandidates = messages.flatMap((m, i) => isToolResult(m) && !isCleared(m) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
+    const toolResultCandidates = messages.flatMap((m, i) => isToolResult(m) && !isCleared(m, opts.recognizeCcMarkers === true) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
     const clearable = toolResultCandidates.slice(0, Math.max(0, toolResultCandidates.length - keep));
     if (clearable.length === 0) {
         return messages;
     }
     const out = messages.slice();
     let current = total;
+    const clears = [];
+    let savedEstimate = 0;
     for (const { idx, target } of clearable) {
         if (current <= opts.budgetTokens) {
             break;
         }
         const before = estimateTokens(target, cpt);
-        const rawContent = Array.isArray(target.content) ? target.content : [];
-        let ref;
-        if (opts.offload) {
-            const fullText = rawContent
-                .filter((c) => c?.type === "text" && typeof c.text === "string")
-                .map((c) => c.text)
-                .join("\n");
-            if (target.toolCallId && fullText.trim().length > 0) {
-                try {
-                    ref = refNote(opts.offload.persist(target.toolCallId, fullText));
-                }
-                catch {
-                    ref = undefined;
-                }
-            }
-        }
-        const mediaBlocks = rawContent.filter((c) => c?.type !== "text");
-        const marker = clearedMarker([ref, mediaBlocks.length > 0 ? mediaNote(mediaBlocks) : undefined]);
-        const cleared = { ...target, content: [{ type: "text", text: marker }] };
+        const cleared = clearOneResult(target, opts.offload, "legacy");
         out[idx] = cleared;
-        current -= idx > anchorIdx ? before - estimateTokens(cleared, cpt) : 0;
+        clears.push({ index: idx });
+        const delta = before - estimateTokens(cleared, cpt);
+        savedEstimate += delta;
+        current -= idx > anchorIdx ? delta : 0;
     }
+    reportCleared(opts.onCleared, clears, savedEstimate);
     return out;
 }
+function clearStaleToolResultsCc(messages, opts) {
+    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults, CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS);
+    const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
+    const candidates = messages.flatMap((m, i) => isToolResult(m) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
+    const beyondKeep = candidates.slice(0, Math.max(0, candidates.length - keep));
+    const clearable = beyondKeep.filter(({ target }) => !isCcCleared(target));
+    if (clearable.length === 0) {
+        return messages;
+    }
+    const tokensSaved = clearable.reduce((sum, { target }) => sum + structuralClearSavings(target), 0);
+    if (tokensSaved < MIN_CLEAR_SAVINGS_TOKENS) {
+        return messages;
+    }
+    const out = messages.slice();
+    const clears = [];
+    for (const { idx, target } of clearable) {
+        const src = opts.clearSource?.[idx];
+        const source = src !== undefined && isToolResult(src) && src.toolCallId === target.toolCallId ? src : target;
+        out[idx] = clearOneResult(source, opts.offload, "cc");
+        clears.push({ index: idx });
+    }
+    reportCleared(opts.onCleared, clears, tokensSaved);
+    return out;
+}
+export function resolveTriggerWindow(model) {
+    const physical = model.contextTokens ?? model.contextWindow;
+    const declared = model.autoCompactTokens;
+    if (declared !== undefined &&
+        Number.isFinite(declared) &&
+        declared > 0 &&
+        Number.isFinite(physical) &&
+        physical > 0 &&
+        declared > physical) {
+        return { window: physical, clamped: true, declaredAutoCompactTokens: declared, physicalWindow: physical };
+    }
+    return { window: declared ?? physical, clamped: false };
+}
 export function editBudget(model) {
-    const window = model.autoCompactTokens ?? model.contextTokens ?? model.contextWindow;
+    const window = resolveTriggerWindow(model).window;
     if (!Number.isFinite(window) || window <= 0) {
         return Number.POSITIVE_INFINITY;
     }
     return contextEditFrontier(window);
 }
+export function fingerprintToolResultOccurrence(m) {
+    const content = Array.isArray(m.content)
+        ? (m.content)
+        : [];
+    const canonical = content.map((c) => {
+        const block = c;
+        if (block?.type === "text" && typeof block.text === "string") {
+            return ["text", block.text];
+        }
+        return [block?.type ?? "?", block?.mimeType ?? "", typeof block?.data === "string" ? block.data : ""];
+    });
+    return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+export function createClearedProjectionLedger() {
+    return { entries: new Map() };
+}
+const OCCURRENCE_KEY_SEP = String.fromCharCode(0);
+function occurrenceGroupId(m) {
+    return `${m.toolCallId}${OCCURRENCE_KEY_SEP}${m.timestamp ?? 0}`;
+}
+export function planRejectionClears(messages, opts) {
+    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults, CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS);
+    const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
+    const candidates = messages.flatMap((m) => (isToolResult(m) && compactable.has(m.toolName) ? [m] : []));
+    const beyondKeep = candidates.slice(0, Math.max(0, candidates.length - keep));
+    const clearable = beyondKeep.flatMap((m) => {
+        if (isCcCleared(m))
+            return [];
+        const at = opts.keyOf(m);
+        return at === undefined ? [] : [{ m, at }];
+    });
+    if (clearable.length === 0)
+        return { declined: "no_candidates" };
+    const tokensSavedEstimate = clearable.reduce((sum, { m }) => sum + structuralClearSavings(m), 0);
+    if (tokensSavedEstimate < MIN_CLEAR_SAVINGS_TOKENS)
+        return { declined: "below_min_savings" };
+    const cleared = clearable.map(({ m, at }) => {
+        const source = at.occurrence !== undefined && isToolResult(at.occurrence) ? at.occurrence : m;
+        const clearedMsg = clearOneResult(source, opts.offload, "cc");
+        return { key: at.key, groupCount: at.groupCount, marker: clearedMsg.content[0]?.text ?? CC_CLEARED_MARKER, fp: at.fp };
+    });
+    return { cleared, tokensSavedEstimate };
+}
+export function replayClearedProjection(messages, ledger) {
+    const groups = new Map();
+    const byIndex = new Map();
+    const byObject = new WeakMap();
+    messages.forEach((m, i) => {
+        if (!isToolResult(m))
+            return;
+        const g = occurrenceGroupId(m);
+        const list = groups.get(g) ?? [];
+        byIndex.set(i, { group: g, dupIdx: list.length });
+        byObject.set(m, { group: g, dupIdx: list.length });
+        list.push(i);
+        groups.set(g, list);
+    });
+    const mintKey = (hit) => {
+        if (hit === undefined)
+            return undefined;
+        const list = groups.get(hit.group) ?? [];
+        const occurrenceIdx = list[hit.dupIdx];
+        return {
+            key: `${hit.group}${OCCURRENCE_KEY_SEP}${hit.dupIdx}`,
+            groupCount: list.length,
+            fp: occurrenceIdx === undefined ? "" : fingerprintToolResultOccurrence(messages[occurrenceIdx]),
+            ...(occurrenceIdx === undefined ? {} : { occurrence: messages[occurrenceIdx] }),
+        };
+    };
+    const index = {
+        keyAt: (i) => mintKey(byIndex.get(i)),
+        keyOf: (m) => {
+            const direct = byObject.get(m);
+            if (direct !== undefined)
+                return mintKey(direct);
+            if (!isToolResult(m))
+                return undefined;
+            const g = occurrenceGroupId(m);
+            const list = groups.get(g);
+            return list !== undefined && list.length === 1 ? mintKey({ group: g, dupIdx: 0 }) : undefined;
+        },
+    };
+    if (ledger.entries.size === 0) {
+        return { messages, index };
+    }
+    let out;
+    const rekeyed = new Map();
+    for (const [key, entry] of ledger.entries) {
+        const sep = key.lastIndexOf(OCCURRENCE_KEY_SEP);
+        const group = key.slice(0, sep);
+        const dupIdx = Number(key.slice(sep + 1));
+        const list = groups.get(group);
+        if (list === undefined)
+            continue;
+        const m = list.length;
+        const shrink = Math.max(0, entry.groupCount - m);
+        const mapped = dupIdx - shrink;
+        if (mapped < 0 || mapped >= m)
+            continue;
+        const targetIdx = list[mapped];
+        const target = messages[targetIdx];
+        if (soleMarkerText(target) !== entry.marker) {
+            if (fingerprintToolResultOccurrence(target) !== entry.fp)
+                continue;
+            out = out ?? messages.slice();
+            out[targetIdx] = { ...target, content: [{ type: "text", text: entry.marker }] };
+        }
+        rekeyed.set(`${group}${OCCURRENCE_KEY_SEP}${mapped}`, { marker: entry.marker, groupCount: m, fp: entry.fp });
+    }
+    ledger.entries.clear();
+    for (const [k, v] of rekeyed)
+        ledger.entries.set(k, v);
+    return { messages: out ?? messages, index };
+}

package/dist/core/governance-codes.d.ts

@@ -68,15 +68,42 @@ export type RuleSyncDropReason = keyof typeof RULE_SYNC_DROP_CODES;
  *  fence arm / local screening). `own_actor_forged` is inbound-only by construction. */
 export type RuleQuarantineReason = Exclude<RuleSyncDropReason, "own_actor_forged">;
 /**
- * The presentation-tier registry (the server's wire whitelist retires into this
- * table once shipped): WHO a notice code is for. `"user"` = a session-scoped disclosure the end
- * user of that session should see (safe to project onto the session's event stream); `"operator"`
- * = a deployment/config/ops fact for whoever runs the process. Presentation tier is a property of
- * the CODE (closed set, one code one tier) — never of an individual emission, which is why this is
- * a registry and not an EngineNotice field. Codes absent from the table read as `"operator"`
- * (the conservative default: never push an unclassified code at an end user).
- * Orthogonal to {@link NON_GOVERNANCE_MEMORY_CODES} (a retry-semantics table, not presentation).
+ * WHO a notice code is for. `"user"` = a session-scoped disclosure the end user of that session is
+ * entitled to see (safe to project onto that session's event stream); `"operator"` = a
+ * deployment/config/ops fact for whoever runs the process.
+ *
+ * Two values, deliberately. "Can this notice be routed to a session" is NOT an audience value — it
+ * is the presence of `EngineNotice.sessionId`, a per-EMISSION fact. A third value would fold a
+ * routing property into an entitlement vocabulary, and the two answer different questions: several
+ * codes below carry a session attribution while the person entitled to the fact is still the
+ * operator (a failed offload write, a routing fallback, a consolidation recommendation).
+ */
+export type NoticeAudience = "user" | "operator";
+/**
+ * The CLOSED catalog of EngineNotice codes this engine mints — the enumeration half of the
+ * presentation registry below, and the thing a consumer's own audience table can be diffed against
+ * (that is the point of exporting it: a downstream table with a row missing, or a row for a code
+ * this engine no longer mints, is a mechanically detectable disagreement rather than an argument).
+ *
+ * Kept in LOCKSTEP with {@link NOTICE_AUDIENCE} by the compiler (`satisfies Record<EngineNoticeCode,
+ * …>` below: a catalog entry with no audience row, or an audience row for a non-member, is a tsc
+ * error — a mirrored enumeration that is only checked at runtime is a mirror that drifts). The
+ * other half — "is the catalog itself still complete?" — cannot be a type: `EngineNotice.code` is
+ * declared `string` (a host may forward its own), so the gate test (governance-codes.test.ts) scans
+ * src/ for notice mint shapes and names any code that is minted but unregistered, or registered but
+ * no longer minted.
+ */
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.read_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "delegation.transcript_integrity", "mcp.revocation_probe_failed", "workflow.governance_key_stripped", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "route.fallback_to_primary", "route.base_url_changed_key_unchanged", "task.user_steer_undrained", "task.user_followup_undrained", "task.injection_priority_unimplemented", "tool_result.offload_put_failed"];
+/** A code this engine mints (see {@link ENGINE_NOTICE_CODES}). NOT the type of
+ *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
+ *  sink is a supported shape, and narrowing that field would break it. */
+export type EngineNoticeCode = (typeof ENGINE_NOTICE_CODES)[number];
+/**
+ * The presentation-tier registry — see {@link NOTICE_AUDIENCE_TABLE} for the per-row judgment.
+ * The exported TYPE stays the open `Record<string, …>` on purpose: a consumer indexing it with a
+ * runtime string (a code off a wire, a host's own) must keep compiling. The lockstep with
+ * {@link ENGINE_NOTICE_CODES} is enforced on the table above, where narrowing costs nobody anything.
  */
-export declare const NOTICE_AUDIENCE: Readonly<Record<string, "user" | "operator">>;
+export declare const NOTICE_AUDIENCE: Readonly<Record<string, NoticeAudience>>;
 /** The audience for `code` — table lookup with the conservative `"operator"` default. */
-export declare function noticeAudienceOf(code: string): "user" | "operator";
+export declare function noticeAudienceOf(code: string): NoticeAudience;

package/dist/core/governance-codes.js

@@ -17,6 +17,7 @@ export const NON_GOVERNANCE_MEMORY_CODES = new Set([
     "memory.session_polluted",
     "memory.harvest_quarantined",
     "memory.delegation_static_mark_waived",
+    "memory.content_class_declared",
     "memory.consolidation_driver_superseded",
     "memory.challenge_sweep_failed",
     "memory.lineage_settle_failed",
@@ -84,14 +85,69 @@ export const RULE_SYNC_DROP_CODES = {
     below_gc_frontier: "local-quarantined",
     server_rejected: "local-quarantined",
 };
-export const NOTICE_AUDIENCE = {
+export const ENGINE_NOTICE_CODES = [
+    "config.autocompact_window_clamped",
+    "config.env_timeout_discarded",
+    "config.materialize_env_discarded",
+    "config.models_swapped",
+    "config.read_face_deployment_clamped",
+    "config.tool_model_gate_removed",
+    "config.tool_model_gate_unknown_class",
+    "config.tool_model_gate_env_invalid",
+    "delegation.transcript_integrity",
+    "mcp.revocation_probe_failed",
+    "workflow.governance_key_stripped",
+    "memory.session_polluted",
+    "memory.harvest_quarantined",
+    "memory.delegation_static_mark_waived",
+    "memory.content_class_declared",
+    "memory.hold_opened",
+    "memory.hold_released",
+    "memory.hold_disposed",
+    "memory.consolidation_recommended",
+    "memory.consolidation_committed",
+    "memory.consolidation_conflict",
+    "memory.consolidation_incomplete",
+    "memory.consolidation_refused",
+    "route.fallback_to_primary",
+    "route.base_url_changed_key_unchanged",
+    "task.user_steer_undrained",
+    "task.user_followup_undrained",
+    "task.injection_priority_unimplemented",
+    "tool_result.offload_put_failed",
+];
+const NOTICE_AUDIENCE_TABLE = {
     "memory.session_polluted": "user",
     "memory.harvest_quarantined": "user",
     "memory.delegation_static_mark_waived": "user",
     "memory.hold_opened": "user",
     "memory.hold_released": "user",
     "memory.hold_disposed": "user",
+    "task.user_steer_undrained": "user",
+    "task.user_followup_undrained": "user",
+    "config.autocompact_window_clamped": "operator",
+    "config.env_timeout_discarded": "operator",
+    "config.materialize_env_discarded": "operator",
+    "config.models_swapped": "operator",
+    "config.read_face_deployment_clamped": "operator",
+    "config.tool_model_gate_removed": "operator",
+    "config.tool_model_gate_unknown_class": "operator",
+    "config.tool_model_gate_env_invalid": "operator",
+    "delegation.transcript_integrity": "operator",
+    "mcp.revocation_probe_failed": "operator",
+    "workflow.governance_key_stripped": "operator",
+    "memory.content_class_declared": "operator",
+    "memory.consolidation_recommended": "operator",
+    "memory.consolidation_committed": "operator",
+    "memory.consolidation_conflict": "operator",
+    "memory.consolidation_incomplete": "operator",
+    "memory.consolidation_refused": "operator",
+    "route.fallback_to_primary": "operator",
+    "route.base_url_changed_key_unchanged": "operator",
+    "task.injection_priority_unimplemented": "operator",
+    "tool_result.offload_put_failed": "operator",
 };
+export const NOTICE_AUDIENCE = NOTICE_AUDIENCE_TABLE;
 export function noticeAudienceOf(code) {
     return NOTICE_AUDIENCE[code] ?? "operator";
 }

package/dist/core/locked-config.d.ts

@@ -1,4 +1,4 @@
-import type { RunnerDeps, TaskSpec } from "./types.js";
+import type { McpServerSpec, RunnerDeps, TaskSpec } from "./types.js";
 import type { ToolPolicy } from "./tool-policy.js";
 /** The closed set of administratively lockable configuration keys. Adding a member is a deliberate
  *  edit HERE (tsc forces the registry row), never a free-form string. */
@@ -38,9 +38,12 @@ export interface LockedConfig {
 export interface LockedPreflight {
     /** The validated lock set (empty when the deployment declares none). */
     lockedKeys: ReadonlySet<LockedKey>;
-    /** Effective MCP server list for this task: `spec.mcp` when the key is unlocked; with `mcp`
-     *  locked a spec-supplied value has already been refused, so this is always `undefined` (core has
-     *  no deployment-level MCP seat — a locked deployment mounts no task-supplied servers). */
+    /** Effective MCP server list for this task: a validated, frozen SNAPSHOT of `spec.mcp` when the
+     *  key is unlocked (see {@link snapshotAndValidateMcpEntries} — the content-class declaration is read once
+     *  and judged here, so no mint site downstream can be handed a different value than the door
+     *  approved); with `mcp` locked a spec-supplied value has already been refused, so this is always
+     *  `undefined` (core has no deployment-level MCP seat — a locked deployment mounts no
+     *  task-supplied servers). */
     mcp: TaskSpec["mcp"];
     /** Effective caller tool policy: the same `spec.toolPolicy ?? deps.toolPolicy` slot the gate has
      *  always enforced, resolved ONCE here. With `toolPolicy` locked, the deployment's own
@@ -61,6 +64,35 @@ export interface LockedPreflight {
  * then fails the first prepare instead of silently guarding nothing).
  */
 export declare function resolveLockedKeys(config: LockedConfig | undefined): ReadonlySet<LockedKey>;
+/**
+ * design/378 — turn a caller-owned MCP entry list into FROZEN PLAIN DATA, reading every own property
+ * exactly once.
+ *
+ * WHY A COPY. `McpServerSpec.contentOrigin` decides whether a server's tools mark the session's
+ * memory, and the entry objects travel a long way: the preparation door validates them, then
+ * `materializeMcpTools` connects them, then every mid-task refresh re-reads the same object. A value
+ * read off a LIVE object is only true for as long as the object holds still, and the fail-open
+ * direction is the reachable one — so both boundaries consume data instead.
+ *
+ * The read discipline is the load-bearing part, and it is why this is a spread rather than
+ * "read the property, then copy the object": a getter answering ALTERNATING LEGAL values would
+ * satisfy any number of re-reads (`"external"` to a validator, `"local"` to a mint site), and no
+ * vocabulary guard anywhere has purchase on a legal value. One spread evaluates every own property
+ * EXACTLY ONCE and materializes the result as plain data; every later reader — validator, connect,
+ * refresh — then sees the same byte. Frozen so nothing downstream rewrites it.
+ *
+ * Boundary, stated: the copy is one level deep — nested option objects (transport, headers, env,
+ * toolAxes) stay shared with the caller's entry exactly as before, because the axis this owns is the
+ * content class; readers of the nested shapes normalize their own values (the transport DISCRIMINATOR
+ * is derived, never echoed raw). Own ENUMERABLE properties only: an entry whose fields live on a
+ * prototype was never the plain configuration record this type describes, and its absent class reads
+ * fail-closed like any other absence.
+ *
+ * Exported because the SECOND boundary needs the identical guarantee: `materializeMcpTools` is public
+ * and a library caller reaches it without passing any door, so it snapshots its own input through
+ * this same function (idempotent over an already-frozen entry). One spelling, both entrances.
+ */
+export declare function snapshotMcpEntries(entries: readonly McpServerSpec[]): McpServerSpec[];
 /**
  * The single preflight resolver: validate the lock declaration, refuse a spec that tries to occupy
  * a locked slot (`config.locked_key`, two-state — the whole prepare is rejected, nothing is

package/dist/core/locked-config.js

@@ -1,3 +1,5 @@
+import { isToolContentOrigin, TOOL_CONTENT_ORIGINS } from "./memory-engine/content-origin.js";
+import { inlineUntrusted } from "./untrusted-text.js";
 export const LOCKED_KEY_REGISTRY = {
     mcp: { specFields: ["mcp"] },
     toolPolicy: { specFields: ["toolPolicy", "basePolicyForResumeEdit"] },
@@ -23,6 +25,37 @@ export function resolveLockedKeys(config) {
     }
     return keys;
 }
+export function snapshotMcpEntries(entries) {
+    return entries.map((entry) => Object.freeze({ ...entry }));
+}
+function describeDeclared(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        try {
+            return String(value);
+        }
+        catch {
+            return `[unrepresentable ${typeof value}]`;
+        }
+    }
+}
+function snapshotAndValidateMcpEntries(entries) {
+    const copies = snapshotMcpEntries(entries);
+    for (const copy of copies) {
+        const declared = copy.contentOrigin;
+        if (declared !== undefined && !isToolContentOrigin(declared)) {
+            throw codedError("config.mcp_content_class", `MCP server ${inlineUntrusted(typeof copy.name === "string" ? JSON.stringify(copy.name) : describeDeclared(copy.name), 80)} declares contentOrigin ` +
+                `${inlineUntrusted(describeDeclared(declared), 80)}, which is not one of ` +
+                `${TOOL_CONTENT_ORIGINS.map((v) => `"${v}"`).join(" | ")}. The declaration decides whether this server's tools ` +
+                `mark the session's memory externally exposed — a value this engine cannot read is refused at the door rather ` +
+                `than folded to a class, because folding it would let a deployment believe a declaration is in force while every ` +
+                `call keeps writing a one-way durable mark.`);
+        }
+    }
+    return copies;
+}
 export function preflightLockedConfig(spec, deps) {
     const lockedKeys = resolveLockedKeys(deps.lockedConfig);
     for (const key of lockedKeys) {
@@ -36,7 +69,7 @@ export function preflightLockedConfig(spec, deps) {
     }
     return {
         lockedKeys,
-        mcp: lockedKeys.has("mcp") ? undefined : spec.mcp,
+        mcp: lockedKeys.has("mcp") || spec.mcp === undefined ? undefined : snapshotAndValidateMcpEntries(spec.mcp),
         toolPolicy: lockedKeys.has("toolPolicy") ? deps.toolPolicy : (spec.toolPolicy ?? deps.toolPolicy),
         basePolicyForResumeEdit: lockedKeys.has("toolPolicy") ? deps.basePolicyForResumeEdit : (spec.basePolicyForResumeEdit ?? deps.basePolicyForResumeEdit),
     };

package/dist/core/mcp.js

@@ -14,6 +14,7 @@ import { truncateError } from "./tool-errors.js";
 import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { discloseReminderShaped, observeReminderMarkEcho } from "./reminder-disclosure.js";
 import { withContentOrigin } from "./memory-engine/content-origin.js";
+import { snapshotMcpEntries } from "./locked-config.js";
 import { validateJsonSchemaShape } from "./runner/strict-output-schema.js";
 export const MCP_PREFIX = MCP_NAMESPACE.prefix;
 const MCP_OUTPUT_TOKENS_DEFAULT = 25_000;
@@ -753,8 +754,9 @@ export function mcpToolSchemaProblem(schema) {
     return undefined;
 }
 export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations) {
+    const entries = snapshotMcpEntries(specs);
     {
-        const collision = findNamespacePrefixCollision(MCP_NAMESPACE, specs.map((s) => s.name));
+        const collision = findNamespacePrefixCollision(MCP_NAMESPACE, entries.map((s) => s.name));
         if (collision) {
             const [a, b] = collision.peers;
             const e = new Error(a === b
@@ -801,11 +803,11 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
     const droppedTools = [];
     let disposing = false;
     const serverHandles = [];
-    const settled = await Promise.allSettled(specs.map((spec) => connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked)));
+    const settled = await Promise.allSettled(entries.map((spec) => connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked)));
     try {
-        for (let i = 0; i < specs.length; i++) {
+        for (let i = 0; i < entries.length; i++) {
             const r = settled[i];
-            const spec = specs[i];
+            const spec = entries[i];
             if (r.status === "fulfilled") {
                 const s = r.value;
                 clients.push(s.client);
@@ -1513,6 +1515,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
     }
 }
 function intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked) {
+    const declaredContentOrigin = spec.contentOrigin;
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
@@ -1576,7 +1579,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
         const mcpToolMeta = t._meta;
         const mcpMaxResultSizeChars = resolveMcpDeclaredResultSize(mcpToolMeta);
         const mcpAlwaysLoad = mcpToolMeta?.["anthropic/alwaysLoad"] === true;
-        serverTools.push({
+        const mounted = {
             name: namespacedName,
             description: capMcpToolDescription(effectiveDescription ?? `MCP tool ${inlineUntrusted(sanitizeMcpModelFacingText(remoteName))} from ${spec.name}`),
             label: `${spec.name}:${remoteName}`,
@@ -1678,7 +1681,8 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
                     return { content, details: { type: "mcp", structuredContent: sc }, terminate: false };
                 return { content, details: res, terminate: false };
             },
-        });
+        };
+        serverTools.push(declaredContentOrigin !== undefined ? withContentOrigin(mounted, declaredContentOrigin) : mounted);
     }
     return { serverTools, serverAxes, dropped, advisories };
 }