@sema-agent/core 5.49.0 → 5.50.0

package/dist/brain/reasoning.js

@@ -10,28 +10,52 @@ const RANK = {
 export function isThinkingLevel(v) {
     return typeof v === "string" && Object.prototype.hasOwnProperty.call(RANK, v);
 }
+export function reasoningRequestCarried(model, reasoning) {
+    return !!model.reasoning && isThinkingLevel(reasoning) && reasoning !== "off";
+}
 export function rankOf(level) {
     return RANK[level];
 }
 export const DEFAULT_EFFORT_LEVELS = ["minimal", "low", "medium", "high"];
 const BINARY_FORMATS = new Set(["qwen", "zai", "qwen-chat-template"]);
 export const RESPONSES_APIS = new Set(["openai-responses", "azure-openai-responses", "openai-chatgpt-responses"]);
-export function resolveReasoning(requested, model) {
-    const resolved = dispatchReasoning(requested, model);
-    if (requested !== "off" && !model.reasoning) {
+export const MIN_THINKING_TOKENS = 1024;
+export function budgetCapSkipsThinking(outputCapTokens, hardCap) {
+    return hardCap && outputCapTokens < MIN_THINKING_TOKENS * 2;
+}
+export function declaredEffortLevels(v) {
+    return Array.isArray(v) && v.length > 0 ? v : undefined;
+}
+export function mintEffortWireValue(requested, model, allowed) {
+    const resolution = resolveEffort(requested, allowed ?? DEFAULT_EFFORT_LEVELS);
+    let wireValue = resolution.effective;
+    const mapped = model.thinkingLevelMap?.[resolution.effective];
+    if (mapped === null)
+        wireValue = undefined;
+    else if (mapped !== undefined)
+        wireValue = mapped;
+    return { resolution, wireValue };
+}
+export function resolveReasoning(requested, model, facts) {
+    const resolved = dispatchReasoning(requested, model, facts);
+    if (requested !== "off" && !reasoningRequestCarried(model, requested)) {
         return { requested, effective: "off", graded: false, clamped: true, format: resolved.format, endpoint: resolved.endpoint, dropped: true };
     }
     return resolved;
 }
-function effortTierUnmapped(requested, effective, model) {
-    return requested !== "off" && model.thinkingLevelMap?.[effective] === null;
-}
-function dispatchReasoning(requested, model) {
+function dispatchReasoning(requested, model, facts) {
     const endpoint = model.api ?? "unknown";
     const compat = (model.compat ?? {});
     if (model.api === "anthropic-messages") {
-        if (compat.effortLevels && compat.effortLevels.length > 0) {
-            return { ...resolveEffort(requested, compat.effortLevels), format: "effort", endpoint };
+        const declaredAnthropic = declaredEffortLevels(compat.effortLevels);
+        if (declaredAnthropic !== undefined) {
+            return { ...resolveEffort(requested, declaredAnthropic), format: "effort", endpoint };
+        }
+        if (requested !== "off" &&
+            compat.thinkingMode !== "adaptive" &&
+            facts !== undefined &&
+            budgetCapSkipsThinking(facts.outputCapTokens, facts.hardOutputCap)) {
+            return { requested, effective: "off", graded: false, clamped: true, format: "budget", endpoint, dropped: true };
         }
         return { requested, effective: requested, graded: true, clamped: false, format: "budget", endpoint };
     }
@@ -39,11 +63,11 @@ function dispatchReasoning(requested, model) {
         if (compat.supportsReasoningEffort === false) {
             return { requested, effective: requested, graded: false, clamped: false, format: "responses", endpoint };
         }
-        const responsesResolved = resolveEffort(requested, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS);
-        if (effortTierUnmapped(requested, responsesResolved.effective, model)) {
+        const responsesMint = mintEffortWireValue(requested, model, compat.reasoningEffortLevels);
+        if (requested !== "off" && responsesMint.wireValue === undefined) {
             return { requested, effective: requested, graded: false, clamped: false, format: "responses", endpoint };
         }
-        return { ...responsesResolved, format: "responses", endpoint };
+        return { ...responsesMint.resolution, format: "responses", endpoint };
     }
     const format = compat.thinkingFormat ?? "openai";
     if (BINARY_FORMATS.has(format)) {
@@ -53,11 +77,11 @@ function dispatchReasoning(requested, model) {
     if (!supportsEffort && format !== "openrouter") {
         return { requested, effective: requested, graded: false, clamped: false, format, endpoint };
     }
-    const resolved = resolveEffort(requested, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS);
-    if (effortTierUnmapped(requested, resolved.effective, model)) {
+    const mint = mintEffortWireValue(requested, model, compat.reasoningEffortLevels);
+    if (requested !== "off" && mint.wireValue === undefined) {
         return { requested, effective: requested, graded: false, clamped: false, format, endpoint };
     }
-    return { ...resolved, format, endpoint };
+    return { ...mint.resolution, format, endpoint };
 }
 export function resolveEffort(requested, allowed = DEFAULT_EFFORT_LEVELS) {
     const declared = Array.isArray(allowed) ? allowed.filter((lvl) => isThinkingLevel(lvl) && lvl !== "off") : [];

package/dist/brain/request-params.d.ts

@@ -23,7 +23,7 @@ export declare function reservedFor(api: string): ReadonlySet<string>;
  */
 export declare function applyExtraBody(body: Record<string, unknown>, extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): Record<string, unknown>;
 /**
- * [1282] per-call auth REPLACES construction-time auth: drop every auth-bearing header
+ * Per-call auth REPLACES construction-time auth: drop every auth-bearing header
  * (case-insensitive `authorization` / `x-api-key`) from an already-merged header bag. Called by a
  * brain's buildRequest ONLY when a per-call `options.apiKey` is present — the brain then re-emits
  * the credential in its own wire posture (anthropic `x-api-key`, openai `Bearer`), making the
@@ -33,6 +33,42 @@ export declare function applyExtraBody(body: Record<string, unknown>, extraBody:
  * folds duplicates into one comma-joined value — broken auth both ways).
  */
 export declare function stripAuthHeaders(headers: Record<string, string>): void;
+/**
+ * #343 — the shared USER-HEADER merge layer (`model.headers` → construction `config.headers` →
+ * per-call `options.headers`, later bag wins), CASE-FOLD deduplicated: HTTP header field names are
+ * case-insensitive (RFC 9110), but the plain-object spread the three brains used
+ * (`{...model.headers, ...config.headers, ...options.headers}`) keyed by exact spelling — a
+ * `X-Tenant` in one bag and `x-tenant` in another BOTH survived and both went on the wire, where
+ * fetch's Headers folds them into one comma-joined value ("a, b"): neither writer's value, and the
+ * later layer's documented override silently defeated. Now a later bag's entry replaces an earlier
+ * case-variant; the WINNER'S spelling and value survive (a single-spelling config — every existing
+ * deployment — is byte-identical on the wire).
+ *
+ * EXEMPT: the auth carriers (`authorization` / `x-api-key`, any case) pass through with the exact
+ * legacy spread semantics (same-spelling override only, no case-fold dedup) — their case handling is
+ * {@link stripAuthHeaders}' pinned jurisdiction (the per-call-replaces flow and the
+ * header-only ANTHROPIC_AUTH_TOKEN shape, which must survive under its own capital-A spelling), and
+ * this layer must not become a second, subtly different auth authority.
+ */
+/**
+ * #343 (review r4) — assign a STRUCTURAL locked header under its canonical lowercase name, deleting
+ * every case-variant spelling first. The brains hard-lock `content-type` / `anthropic-version` AFTER
+ * the user-bag merge precisely so they "can NEVER be overridden" (council design/40) — but a valid
+ * user bag carrying `Content-Type: text/plain` survived BESIDE the lowercase lock, and the platform
+ * `Headers` fold turns the pair into `text/plain, application/json` on the wire: the lock decided
+ * nothing. Auth carriers are deliberately NOT routed through here (per-call replacement + the
+ * header-only boot flow are {@link stripAuthHeaders}' pinned jurisdiction).
+ */
+export declare function lockHeader(headers: Record<string, string>, lowerName: string, value: string): void;
+/**
+ * #343 (review r4) — case-fold READ-AND-CLAIM for an AUGMENTABLE structural header (`anthropic-beta`):
+ * returns the current value under whatever spelling the user bag carried and deletes that spelling,
+ * so the caller's canonical lowercase write REPLACES it instead of duplicating beside it (the
+ * read-modify-write used to key the read by the exact lowercase name and miss `Anthropic-Beta`,
+ * losing the user's betas from the merge AND double-sending the header).
+ */
+export declare function takeHeaderCasefold(headers: Record<string, string>, lowerName: string): string | undefined;
+export declare function mergeHeaders(...bags: Array<Record<string, string> | undefined>): Record<string, string>;
 /**
  * The output-cap key(s) each lane's wire form uses. A lane's set is exactly the keys THAT lane's
  * endpoint reads — a stray cap key belonging to another wire form is inert there and must not be

package/dist/brain/request-params.js

@@ -54,13 +54,51 @@ export function applyExtraBody(body, extraBody, reserved) {
     }
     return { ...passthrough, ...body };
 }
+const AUTH_CARRIER_NAMES = new Set(["authorization", "x-api-key"]);
 export function stripAuthHeaders(headers) {
     for (const k of Object.keys(headers)) {
-        const lower = k.toLowerCase();
-        if (lower === "authorization" || lower === "x-api-key")
+        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
             delete headers[k];
     }
 }
+export function lockHeader(headers, lowerName, value) {
+    for (const k of Object.keys(headers)) {
+        if (k !== lowerName && k.toLowerCase() === lowerName)
+            delete headers[k];
+    }
+    headers[lowerName] = value;
+}
+export function takeHeaderCasefold(headers, lowerName) {
+    for (const k of Object.keys(headers)) {
+        if (k.toLowerCase() === lowerName) {
+            const v = headers[k];
+            delete headers[k];
+            return v;
+        }
+    }
+    return undefined;
+}
+export function mergeHeaders(...bags) {
+    const out = {};
+    const spellingByFold = new Map();
+    for (const bag of bags) {
+        if (!bag)
+            continue;
+        for (const [name, value] of Object.entries(bag)) {
+            const fold = name.toLowerCase();
+            if (AUTH_CARRIER_NAMES.has(fold)) {
+                out[name] = value;
+                continue;
+            }
+            const prior = spellingByFold.get(fold);
+            if (prior !== undefined && prior !== name)
+                delete out[prior];
+            spellingByFold.set(fold, name);
+            out[name] = value;
+        }
+    }
+    return out;
+}
 export const OUTPUT_CAP_KEYS = {
     openai: ["max_tokens", "max_completion_tokens"],
     anthropic: ["max_tokens"],

package/dist/core/mcp.d.ts

@@ -193,7 +193,10 @@ export interface McpRefreshResult {
      *  DOMAIN for the swap (review F4: a prefix domain is self-healing and decoupled from the diff
      *  baseline, which advances even when a consumer skips a swap). Present on every entry. */
     prefix: string;
-    status: "refreshed" | "not_connected" | "failed";
+    /** `"revoked"` (design/338): the host ledger marks this server revoked — the refresh did NOT
+     *  contact it (no tools/list round trip; the engine must not hand a severed server a request
+     *  channel or splice its post-revocation text into the model catalog). */
+    status: "refreshed" | "not_connected" | "failed" | "revoked";
     toolCount: number;
     added: string[];
     removed: string[];
@@ -467,6 +470,9 @@ export declare function materializeMcpTools(specs: McpServerSpec[], principal?:
 reminderDisclosure?: {
     reminderMark?: string;
     counts?: ReminderDisclosureCounts;
+}, mcpRevocations?: {
+    isRevoked(serverName: string): boolean;
+    onProbeFailure?: (error: unknown) => void;
 }): Promise<MaterializedMcp>;
 /**
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.

package/dist/core/mcp.js

@@ -650,7 +650,30 @@ export function mcpToolSchemaProblem(schema) {
     }
     return undefined;
 }
-export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure) {
+export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations) {
+    let revocationProbeFailed = false;
+    const isServerRevoked = (serverName) => {
+        if (mcpRevocations === undefined)
+            return false;
+        try {
+            const r = mcpRevocations.isRevoked(serverName);
+            if (typeof r !== "boolean") {
+                throw new Error(`isRevoked returned ${r instanceof Promise ? "a Promise — the ledger seat is SYNCHRONOUS by contract" : `a non-boolean (${typeof r})`}`);
+            }
+            return r;
+        }
+        catch (e) {
+            if (!revocationProbeFailed) {
+                revocationProbeFailed = true;
+                try {
+                    mcpRevocations.onProbeFailure?.(e);
+                }
+                catch {
+                }
+            }
+            return false;
+        }
+    };
     const mcpDisclosure = reminderDisclosure?.reminderMark !== undefined
         ? { mark: reminderDisclosure.reminderMark, windows: new Map(), ...(reminderDisclosure.counts !== undefined ? { counts: reminderDisclosure.counts } : {}) }
         : undefined;
@@ -665,7 +688,7 @@ 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)));
+    const settled = await Promise.allSettled(specs.map((spec) => connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked)));
     try {
         for (let i = 0; i < specs.length; i++) {
             const r = settled[i];
@@ -701,7 +724,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 statuses.push({ name: spec.name, status: "failed", error: namedMcpFailureText(r.reason) });
             }
         }
-        const resourceTools = buildResourceTools(resourceServers);
+        const resourceTools = buildResourceTools(resourceServers, isServerRevoked);
         tools.push(...resourceTools.tools);
         toolAxes.push(...resourceTools.axes);
     }
@@ -729,10 +752,14 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     results.push({ server: h.name, prefix: prefixOf(h.name), status: "not_connected", toolCount: 0, added: [], removed: [] });
                     continue;
                 }
+                if (isServerRevoked(h.name)) {
+                    results.push({ server: h.name, prefix: prefixOf(h.name), status: "revoked", toolCount: 0, added: [], removed: [], error: "server revoked by the operator — the refresh did not contact it" });
+                    continue;
+                }
                 try {
                     const listed = await listToolsLenient(h.client);
                     cacheMcpToolMetadata(h.client, listed.tools);
-                    const { serverTools, serverAxes, dropped } = intakeListedTools(listed, h.spec, h.client, h.health, imageResizer, mcpDisclosure);
+                    const { serverTools, serverAxes, dropped } = intakeListedTools(listed, h.spec, h.client, h.health, imageResizer, mcpDisclosure, isServerRevoked);
                     const newNames = serverTools.map((t) => t.name);
                     const added = newNames.filter((n) => !h.toolNames.includes(n));
                     const removed = h.toolNames.filter((n) => !newNames.includes(n));
@@ -882,7 +909,7 @@ function renderDirChildren(server, uri, children, flags) {
         terminate: false,
     };
 }
-function buildResourceTools(resourceServers) {
+function buildResourceTools(resourceServers, isServerRevoked = () => false) {
     const listable = resourceServers.filter((rs) => rs.listAllowed);
     const readable = resourceServers.filter((rs) => rs.readAllowed);
     if (listable.length === 0 && readable.length === 0)
@@ -910,6 +937,11 @@ function buildResourceTools(resourceServers) {
                 const all = [];
                 const errors = [];
                 for (const rs of targets) {
+                    if (isServerRevoked(rs.server)) {
+                        errors.push({ server: rs.server, error: "server revoked by the operator mid-session (request not sent)" });
+                        sections.push(`[${rs.server}] Error: server revoked by the operator — its resources are unavailable this turn.`);
+                        continue;
+                    }
                     if (rs.health.dead) {
                         errors.push({ server: rs.server, error: "server disconnected (transport closed earlier in this task)" });
                         sections.push(`[${rs.server}] Error: server disconnected — its resources are unavailable.`);
@@ -970,6 +1002,14 @@ function buildResourceTools(resourceServers) {
                 if (!rs)
                     return { content: [{ type: "text", text: `Error: no MCP server ${inlineUntrusted(server)} with readable resources. Available: ${serverNames(readable)}.` }], details: undefined, terminate: false };
                 const what = `The read of resource ${inlineUntrusted(uri)}`;
+                if (isServerRevoked(server)) {
+                    return {
+                        content: [{ type: "text", text: `${what} was refused: MCP server "${server}" was revoked by the operator mid-session. The request was NOT sent. The tool list updates at the next turn.` }],
+                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", server },
+                        terminate: false,
+                        isError: true,
+                    };
+                }
                 if (rs.health.dead)
                     throwDeadServer(server, what);
                 const timeoutMs = mcpToolTimeoutMs();
@@ -1021,6 +1061,14 @@ function buildResourceTools(resourceServers) {
                 if (!rs)
                     return { content: [{ type: "text", text: `Error: no MCP server ${inlineUntrusted(server)} with listable resources. Available: ${serverNames(listable)}.` }], details: undefined, terminate: false };
                 const what = `The directory listing of ${inlineUntrusted(uri)}`;
+                if (isServerRevoked(server)) {
+                    return {
+                        content: [{ type: "text", text: `${what} was refused: MCP server "${server}" was revoked by the operator mid-session. The request was NOT sent. The tool list updates at the next turn.` }],
+                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", server },
+                        terminate: false,
+                        isError: true,
+                    };
+                }
                 if (rs.health.dead)
                     throwDeadServer(server, what);
                 const timeoutMs = mcpToolTimeoutMs();
@@ -1123,7 +1171,7 @@ const LENIENT_CALL_TOOL_RESULT_SCHEMA = { safeParse: parseCallToolResultLenient
 async function listToolsLenient(client, options) {
     return client.request({ method: "tools/list", params: {} }, LenientListToolsResultSchema, options);
 }
-async function connectServer(spec, principal, onElicit, imageResizer, reminderDisclosure) {
+async function connectServer(spec, principal, onElicit, imageResizer, reminderDisclosure, isServerRevoked) {
     const elicitOn = spec.elicitation === true && onElicit !== undefined;
     const health = { dead: false, pendingElicitations: 0, lastElicitationClosedAt: 0 };
     const client = new Client({ name: `sema-core/${spec.name}`, version: "0.1.0" }, { capabilities: elicitOn ? { elicitation: { form: {} } } : {} });
@@ -1159,7 +1207,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         };
         const listed = await listToolsLenient(client, startupOpts);
         cacheMcpToolMetadata(client, listed.tools);
-        const { serverTools, serverAxes, dropped } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure);
+        const { serverTools, serverAxes, dropped } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked);
         const caps = client.getServerCapabilities();
         const resourceInfo = caps?.resources
             ? {
@@ -1192,7 +1240,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         throw err;
     }
 }
-function intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure) {
+function intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked) {
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
@@ -1235,6 +1283,14 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             ...(mcpAlwaysLoad ? { mcpAlwaysLoad: true } : {}),
             execute: async (_toolCallId, params, signal) => {
                 const what = `The call to tool ${inlineUntrusted(remoteName)}`;
+                if (isServerRevoked?.(spec.name) === true) {
+                    return {
+                        content: [{ type: "text", text: `The call to MCP server "${spec.name}" was refused: the server was revoked by the operator mid-session. The call was NOT sent, so the server did not execute it. The tool list updates at the next turn.` }],
+                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", server: spec.name },
+                        terminate: false,
+                        isError: true,
+                    };
+                }
                 if (health.dead)
                     throwDeadServer(spec.name, what);
                 const timeoutMs = mcpToolTimeoutMs();

package/dist/core/memory-engine/engine.d.ts

@@ -849,6 +849,11 @@ export declare class MemoryEngine {
      *  the deleted disk file WAS the backend's storage). Zero-copy skips getByIds: its read-side scan
      *  cannot see a deleted file, and calling it mid-harvest would sync-adopt in-session edits. */
     private committedContentFor;
+    /** {@link committedContentFor} with the FAULT axis preserved: `fault: true` means the backend
+     *  read THREW and no shadow answered — "could not read" — which consumers that make destructive
+     *  decisions on absence (the projection-debt settlement clears a row on "entry gone") must
+     *  distinguish from a clean miss. The 8 non-destructive read sites keep the folded face. */
+    private committedContentOrFault;
     /**
      * design/336 §2.2 (r4-9) — the COMMITTED frontmatter an origin carry-forward is computed against.
      * Deliberately NOT {@link committedContentFor}'s non-zero-copy leg: that one calls the backend's
@@ -910,8 +915,32 @@ export declare class MemoryEngine {
     /** Persist the canonical projection back to the session file (id minting / frontmatter completion).
      *  C-F6 (S2-0): called ONLY after the backend transaction committed — never ahead of the journal
      *  commit point. Skips the write when the disk already holds the canonical bytes (zero-copy: the
-     *  journal's own execute step wrote them, making this an idempotent no-op). */
+     *  journal's own execute step wrote them, making this an idempotent no-op). Returns whether the
+     *  disk now holds the canonical bytes — the ordinary completion family stays best-effort on a
+     *  `false` (the next materialize re-projects), but the id-COMPLETION family's caller reads it to
+     *  keep the #366 projection-debt row standing (an id-less plane file must re-bind to its
+     *  committed id at the next harvest, never re-admit as a duplicate). */
     private writeBackProjection;
+    /**
+     * #366 — repair an id-less-but-committed seat IN PLACE (the failed write-back's retry): write the
+     * committed canonical bytes over the seat and settle the debt row on success. Callers have
+     * already proven the seat carries no unadmitted edit (rev equality against its baseline), so the
+     * overwrite is content-preserving — it restores the id line, the completed frontmatter and any
+     * carried marker, nothing else. A refused read/write leaves the row standing (retried next pass;
+     * the next materialize's projection loop repairs and settles it too).
+     */
+    private repairProjectionSeat;
+    /**
+     * #366 — validate a projection-debt row against the COMMITTED state (side-effect-free read: the
+     * retrievalView face in copy-out, never the File backend's adopting `getByIds`). Three-valued on
+     * purpose: `valid` binds, `stale` clears the row (the seat claim dissolved — entry gone, moved or
+     * renamed), and `unknown` (committed state unreadable) makes the caller DEFER the file fail-closed
+     * — treating a transient read fault as "stale" would clear the row and mint the very duplicate
+     * the account exists to close. Zero-copy answers `stale` by construction: there the backend's own
+     * commit writes the id into the plane file, so any standing row is a leftover, and the plain
+     * `getByIds` there would sync-adopt mid-harvest.
+     */
+    private debtCommittedProjection;
     /** Sibling scope subdir names under `dir` (excluded from a scope-tree walk when `dir` is the root —
      *  a root-owning layer's chmod/restore must never touch another scope's home). */
     private siblingScopeDirNames;