@sema-agent/core 5.52.0 → 5.53.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 5.53.0 — 2026-08-21
+
+### Fixed
+- **An MCP refresh no longer rewrites the cacheable tool prefix** (#375 root fix): `RefreshMcpTools`
+  re-inserted the server's tool domain at the TAIL of the mount array — the wire order — so a
+  byte-identical listing still displaced the whole domain past every later tool, a full provider
+  prefix-cache re-bill the model itself was told to trigger ("refresh when a listing looks stale").
+  The domain now re-enters at its anchor (the lowest index it occupied): an unchanged listing
+  produces a byte-identical array. First-time mounts still append.
+- **Thinking replay survives strict gateways and non-streaming rewrites** (#374 adjacent):
+  the replay judge is shape-based (only a non-empty string counts as a signature — a JSON-roundtrip
+  `null`/number can no longer ride onto the wire), `signature_delta` refuses non-string coercion,
+  and an inlined `content_block_start` thinking block (the compat-gateway SSE-rewrite form) is now
+  fully captured — text and signature — instead of being dropped from every subsequent request.
+- **The cache-break detector tells the truth about reorders** (#376): an order-preserving hash
+  now attributes a pure reorder to `tool-set` with its own wording (previously it fell through to
+  "server-or-ttl … not a client-side prefix bug" — actively misleading, and the exact shape #375
+  just fixed); the low-hit-rate summary discriminates "prefix keeps changing" from "this route
+  reports no caching" using cacheWrite facts instead of guessing.
+- **The MCP refresh region is transactional and collision-gated** (#377): tool effect records are
+  reset before the fold (a refreshed read-only tool no longer silently degrades to write), a
+  rejected listing restores both non-monotone tables, two servers whose names normalize to the
+  same prefix refuse at connect (`config.mcp_server_name_collision`, both original spellings
+  named), and a single listing minting two identical tool names keeps the first with a disclosed
+  drop.
+- Behavior narrowings (named): colliding server configs from "silent shared domain" to a loud
+  connect refusal; same-listing name collisions from "both mounted under one name" to
+  "first kept, drop disclosed".
+
+- **Pre-release scan dispositions (three, fixed in-tree before publish)**: the protocol-name
+  reservation now covers ALIASES (a `__`-shaped caller alias refuses at prepare with the same loud
+  code — it was a dispatchable name sitting inside a server's prefix domain, which the refresh
+  region would classify and clear as remote); the refresh receipt states each drop's OWN reason
+  (a fixed "invalid schema" label lied about the collision lane); the A2A mount gains the same
+  normalized-prefix collision gate as MCP (`config.a2a_peer_name_collision`), making the
+  protocol-naming contract's engine-wide claim true.
+- Behavior narrowing (named): a caller tool alias containing `__` from "accepted" to a loud
+  prepare refusal; colliding A2A peer names from "silent shared domain" to a connect refusal.
+
+### Notes
+- Residuals ticketed: #379 (open-responses presence judge, inline text-block sibling, two-phase
+  refresh observation). #378 resolved by the alias-reservation fix above.
+
 ## 5.52.0 — 2026-08-21
 
 ### Added

package/dist/brain/anthropic.js

@@ -66,7 +66,8 @@ function toAnthropicMessages(ctx, model) {
             for (const c of m.content) {
                 if (c.type === "thinking") {
                     const tc = c;
-                    const sig = tc.thinkingSignature;
+                    const sigRaw = tc.thinkingSignature;
+                    const sig = typeof sigRaw === "string" && sigRaw.length > 0 ? sigRaw : undefined;
                     if (tc.redacted) {
                         if (sig)
                             blocks.push({ type: "redacted_thinking", data: sig });
@@ -377,9 +378,19 @@ export function createAnthropicBrain(config = {}) {
                                     acc.redacted = true;
                                     acc.signature = cb.data ?? "";
                                 }
+                                else {
+                                    if (typeof cb.thinking === "string" && cb.thinking !== "")
+                                        acc.text = cb.thinking;
+                                    if (typeof cb.signature === "string" && cb.signature !== "")
+                                        acc.startSignature = cb.signature;
+                                }
                                 acc.pb = { type: "thinking", thinking: "" };
                                 partial.content = [acc.pb];
                                 out.push({ type: "thinking_start", contentIndex: idx, partial: { ...partial } });
+                                if (acc.text !== "") {
+                                    acc.pb.thinking = acc.text;
+                                    out.push({ type: "thinking_delta", contentIndex: idx, delta: acc.text, partial: { ...partial } });
+                                }
                             }
                             else if (cb.type === "tool_use") {
                                 acc.type = "tool_use";
@@ -418,6 +429,7 @@ export function createAnthropicBrain(config = {}) {
                                 }
                             }
                             else if (d.type === "thinking_delta" && d.thinking) {
+                                acc.startSignature = undefined;
                                 acc.text += d.thinking;
                                 if (acc.pb && acc.pb.type === "thinking")
                                     acc.pb.thinking = acc.text;
@@ -430,7 +442,7 @@ export function createAnthropicBrain(config = {}) {
                                     }
                                 }
                             }
-                            else if (d.type === "signature_delta" && d.signature) {
+                            else if (d.type === "signature_delta" && typeof d.signature === "string" && d.signature.length > 0) {
                                 acc.signature += d.signature;
                             }
                             else if (d.type === "input_json_delta" && d.partial_json) {
@@ -536,8 +548,9 @@ export function createAnthropicBrain(config = {}) {
                                 if (acc.text.length > 0 || acc.redacted === true)
                                     reasoningSeen = true;
                                 const block = { type: "thinking", thinking: acc.text };
-                                if (acc.signature)
-                                    block.thinkingSignature = acc.signature;
+                                const sig = acc.signature || acc.startSignature;
+                                if (sig)
+                                    block.thinkingSignature = sig;
                                 if (acc.redacted)
                                     block.redacted = true;
                                 finalContent.push(block);

package/dist/core/a2a.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { A2A_TASK_STATES } from "./a2a-task-state.js";
 import { describeHttpTransportFailure, resolveProtocolHttpHeaders } from "./mcp.js";
-import { mintNamespacePrefix, mintNamespacedToolName } from "./protocol-naming.js";
+import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName } from "./protocol-naming.js";
 import { A2A_NAMESPACE } from "./protocol-table.js";
 import { delimitUntrusted, inlineUntrusted } from "./untrusted-text.js";
 const A2A_REQUEST_TIMEOUT_MS = 30_000;
@@ -575,6 +575,17 @@ function asPeerWarning(spec, err) {
     return warning;
 }
 export async function materializeA2aTools(specs, principal, signal) {
+    if (specs.length > 0) {
+        const collision = findNamespacePrefixCollision(A2A_NAMESPACE, specs.map((s) => s.name));
+        if (collision) {
+            const [a, b] = collision.peers;
+            const e = new Error(a === b
+                ? `A2A peer "${a}" is declared twice — each peer needs its own name (both mount under "${collision.prefix}").`
+                : `A2A peer names "${a}" and "${b}" both mount under "${collision.prefix}" — the namespaced tool name keeps only [a-zA-Z0-9_-], so they are the same domain to this engine. Rename one.`);
+            e.code = "config.a2a_peer_name_collision";
+            throw e;
+        }
+    }
     const lifecycle = { disposed: false };
     const tools = [];
     const toolAxes = [];

package/dist/core/cache-break-detector.js

@@ -27,6 +27,7 @@ export class CacheBreakDetector {
             systemHash: fnv1a(input.systemPrompt),
             perToolHash: new Map(input.tools.map((t) => [t.name, fnv1a(`${t.name}\0${t.description}\0${stableStringify(t.parameters)}`)])),
             toolSetHash: fnv1a([...input.tools.map((t) => t.name)].sort().join(",")),
+            toolOrderHash: fnv1a(input.tools.map((t) => t.name).join(",")),
             modelKey: input.modelKey,
             cacheRead: input.cacheRead,
             at: Date.now(),
@@ -59,7 +60,11 @@ export class CacheBreakDetector {
             }
             else if (snap.toolSetHash !== prev.toolSetHash) {
                 cause = "tool-set";
-                detail = "the tool set changed (a tool was added/removed/reordered)";
+                detail = "the tool set changed (a tool was added or removed)";
+            }
+            else if (snap.toolOrderHash !== prev.toolOrderHash) {
+                cause = "tool-set";
+                detail = "the tool ORDER changed (same tools, different positions) — a reordered tool list is a byte-different prefix from the first moved tool onward, so the provider re-bills the whole tail";
             }
             else if (snap.systemHash !== prev.systemHash) {
                 cause = "system-prefix";
@@ -68,10 +73,11 @@ export class CacheBreakDetector {
             else {
                 const gapMs = snap.at - prev.at;
                 cause = "server-or-ttl";
+                const checked = "nothing this detector fingerprints (system prefix, tool set + order, model)";
                 detail =
                     gapMs < SERVER_GAP_MS
-                        ? `nothing in the prefix changed and the gap was ${Math.round(gapMs / 1000)}s — likely a server-side miss, not a client-side prefix bug`
-                        : `nothing changed but the gap was ${Math.round(gapMs / 60_000)}min — likely a normal TTL expiry (cold cache), not a bug`;
+                        ? `${checked} changed and the gap was ${Math.round(gapMs / 1000)}s — most likely a server-side miss; the message history is not fingerprinted, so volatile content early in the conversation would also land here`
+                        : `${checked} changed and the gap was ${Math.round(gapMs / 60_000)}min — most likely a normal TTL expiry (cold cache)`;
             }
         }
         return { turn: input.turn, cacheReadBefore: before, cacheReadAfter: after, cause, detail };

package/dist/core/mcp.js

@@ -1,5 +1,5 @@
 import { MCP_NAMESPACE } from "./protocol-table.js";
-import { mintNamespacePrefix, mintNamespacedToolName, normalizeNameSegment } from "./protocol-naming.js";
+import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName, normalizeNameSegment } from "./protocol-naming.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -663,6 +663,17 @@ export function mcpToolSchemaProblem(schema) {
     return undefined;
 }
 export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations) {
+    {
+        const collision = findNamespacePrefixCollision(MCP_NAMESPACE, specs.map((s) => s.name));
+        if (collision) {
+            const [a, b] = collision.peers;
+            const e = new Error(a === b
+                ? `MCP server "${inlineUntrusted(a, 120)}" is declared twice — each server needs its own name (both mount under "${collision.prefix}", so their tools would shadow each other and a refresh of one would unmount the other's).`
+                : `MCP server names "${inlineUntrusted(a, 120)}" and "${inlineUntrusted(b, 120)}" both mount under "${collision.prefix}" — the namespaced tool name keeps only [a-zA-Z0-9_-], so they are the same domain to this engine (their tools would shadow each other and a refresh of one would unmount the other's). Rename one.`);
+            e.code = "config.mcp_server_name_collision";
+            throw e;
+        }
+    }
     let revocationProbeFailed = false;
     const isServerRevoked = (serverName) => {
         if (mcpRevocations === undefined)
@@ -1256,6 +1267,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
+    const mintedNames = new Set();
     for (const t of listed.tools) {
         if (spec.allowTools && !spec.allowTools.includes(t.name)) {
             continue;
@@ -1278,6 +1290,14 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
         }
         const remoteName = t.name;
         const namespacedName = mintNamespacedToolName(MCP_NAMESPACE, spec.name, remoteName);
+        if (mintedNames.has(namespacedName)) {
+            dropped.push({
+                tool: inlineUntrusted(t.name),
+                reason: `name collides with an earlier tool of this server: both mount as "${namespacedName}" after namespacing (only [a-zA-Z0-9_-] survives), and one name cannot denote two tools`,
+            });
+            continue;
+        }
+        mintedNames.add(namespacedName);
         const hintAxis = mcpAxisFor(namespacedName, t.annotations);
         const axis = applyCallerAxisOverride(namespacedName, hintAxis, spec.toolAxes?.[remoteName]);
         if (axis)

package/dist/core/protocol-naming.d.ts

@@ -12,8 +12,11 @@ export declare const MINTED_TOOL_SEGMENT_MIN_CHARS = 16;
  * `mcp__<server>__<tool>` (services/mcp/normalization.ts `normalizeNameForMCP` + mcpStringUtils.ts
  * `buildMcpToolName`), so a peer advertising a dotted/spaced/unicode name can't mint a name the provider
  * rejects. NOTE: only the MODEL-FACING namespaced name is normalized — the raw remote name still goes on
- * the wire and still keys the caller-facing maps (`allowTools`/`toolAxes`). Same known collision property
- * as CC: two remote names that normalize to the same string collide (rare; CC accepts this).
+ * the wire and still keys the caller-facing maps (`allowTools`/`toolAxes`). The collision property is
+ * inherent (two remote names that normalize to the same string mint the same string; CC accepts this at
+ * the same layer) — what this engine does NOT accept is two PEERS colliding, because a peer prefix is a
+ * live domain key here (the refresh splice). That case is decided by
+ * {@link findNamespacePrefixCollision} and refused at the mount, loudly; the mint stays total.
  *
  * RB-83 (2026-07-25, red probe): the pattern this enforces is `{1,64}`, and only the charset half was
  * enforced. Both other halves matter for the same reason the charset does — an over-long or empty segment
@@ -37,6 +40,26 @@ export declare function clampNameSegment(seg: string, max?: number): string;
  * (ticket #10), and the property test holds the two legs to the identical law.
  */
 export declare function mintNamespacePrefix(ns: ProtocolNamespace, peer: string): string;
+/**
+ * The first pair of peers in `peers` that mint the SAME {@link mintNamespacePrefix} — i.e. that would
+ * register into one indistinguishable namespace domain — or `undefined` when every peer owns its own.
+ *
+ * Two spellings collide whenever charset normalization, the length clamp or the separator fold maps
+ * them together: `"prod.db"` and `"prod_db"` both mint `mcp__prod_db__`, and the same name listed twice
+ * collides trivially. The mint itself cannot refuse (its input is deployment/remote data and a dotted
+ * name must not become a materialization failure — see {@link normalizeNameSegment}), so the refusal
+ * belongs to the MOUNT, which is the layer that knows the whole peer list. This function is that
+ * layer's decision procedure: pure name arithmetic, decidable before any I/O.
+ *
+ * Why a collision cannot be tolerated downstream: the prefix IS the domain key. A refresh splices
+ * `name.startsWith(prefix)` out and re-inserts only the refreshed peer's listing, so refreshing one of
+ * two colliding peers silently unmounts the other's tools; equal tool names additionally shadow each
+ * other last-write-wins in the harness map. Both failures are invisible at the moment they happen.
+ */
+export declare function findNamespacePrefixCollision(ns: ProtocolNamespace, peers: readonly string[]): {
+    prefix: string;
+    peers: [string, string];
+} | undefined;
 /**
  * The full registered name for `(peer, tool)` in `ns`. Always starts with {@link mintNamespacePrefix}'s
  * answer for the same peer (the invariant ticket #9's pins hold), and never exceeds

package/dist/core/protocol-naming.js

@@ -26,6 +26,17 @@ export function mintNamespacePrefix(ns, peer) {
     const peerBudget = Math.max(1, TOOL_NAME_MAX_CHARS - ns.prefix.length - NAME_SEP.length - MINTED_TOOL_SEGMENT_MIN_CHARS);
     return `${ns.prefix}${settlePeerSegment(clampNameSegment(normalizeNameSegment(peer), peerBudget))}${NAME_SEP}`;
 }
+export function findNamespacePrefixCollision(ns, peers) {
+    const seen = new Map();
+    for (const peer of peers) {
+        const prefix = mintNamespacePrefix(ns, peer);
+        const first = seen.get(prefix);
+        if (first !== undefined)
+            return { prefix, peers: [first, peer] };
+        seen.set(prefix, peer);
+    }
+    return undefined;
+}
 export function mintNamespacedToolName(ns, peer, tool) {
     const prefix = mintNamespacePrefix(ns, peer);
     return `${prefix}${clampNameSegment(normalizeNameSegment(tool), Math.max(1, TOOL_NAME_MAX_CHARS - prefix.length))}`;

package/dist/core/runner/prepare-safety-scan.js

@@ -19,6 +19,13 @@ export function prepareSafetyScan(input) {
             e.code = "config.tool_name_invalid";
             throw e;
         }
+        for (const alias of t.aliases ?? []) {
+            if (alias.includes("__")) {
+                const e = new Error(`Tool alias "${alias}" (of "${t.name}") is invalid: "__" is reserved for the engine's protocol tool namespaces (${NAMESPACED_NAME_SHAPES}) and must not appear in a caller tool alias.`);
+                e.code = "config.tool_name_invalid";
+                throw e;
+            }
+        }
         if (t.effect) {
             toolEffects.set(t.name, t.effect);
         }

package/dist/core/runner/prepare-task.js

@@ -1221,22 +1221,43 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         const excludedSet = new Set(toolFaceSnapshot.exclude ?? []);
                         const pushable = r.tools.filter((t) => !excludedSet.has(t.name));
                         const excludedNow = r.tools.filter((t) => excludedSet.has(t.name)).map((t) => t.name);
+                        const domainSnapshot = (m) => new Map([...m].filter(([name]) => name.startsWith(r.prefix)));
+                        const restoreDomain = (m, snap) => {
+                            for (const name of [...m.keys()])
+                                if (name.startsWith(r.prefix))
+                                    m.delete(name);
+                            for (const [name, v] of snap)
+                                m.set(name, v);
+                        };
+                        const priorDomainEffects = domainSnapshot(toolEffects);
+                        const priorDomainNegatives = domainSnapshot(axisExplicitNegatives);
+                        for (const name of priorDomainEffects.keys())
+                            toolEffects.delete(name);
+                        for (const name of priorDomainNegatives.keys())
+                            axisExplicitNegatives.delete(name);
                         try {
                             foldProtocolAxes((r.axes ?? []).filter((a) => !excludedSet.has(a.name)), "MCP");
                         }
                         catch (foldErr) {
+                            restoreDomain(toolEffects, priorDomainEffects);
+                            restoreDomain(axisExplicitNegatives, priorDomainNegatives);
                             lines.push(`${r.server}: failed (${foldErr instanceof Error ? foldErr.message : String(foldErr)})`);
                             anyActiveFailure = true;
                             continue;
                         }
+                        let domainAnchor = -1;
                         for (let i = tools.length - 1; i >= 0; i--) {
                             const t = tools[i];
                             if (t.name.startsWith(r.prefix)) {
-                                toolEffects.delete(t.name);
+                                domainAnchor = i;
                                 tools.splice(i, 1);
                             }
                         }
-                        tools.push(...pushable.map((t) => remoteToolOffload(t)));
+                        const refreshedMounts = pushable.map((t) => remoteToolOffload(t));
+                        if (domainAnchor >= 0)
+                            tools.splice(domainAnchor, 0, ...refreshedMounts);
+                        else
+                            tools.push(...refreshedMounts);
                         changed = true;
                         const detail = [];
                         const shownAdded = r.added.filter((n) => !excludedSet.has(n));
@@ -1247,7 +1268,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         if (excludedNow.length > 0)
                             detail.push(`excluded by deployment config (not mounted): ${excludedNow.join(", ")}`);
                         if ((r.dropped?.length ?? 0) > 0)
-                            detail.push(`dropped (invalid schema): ${r.dropped.map((d) => d.tool).join(", ")}`);
+                            detail.push(`dropped: ${r.dropped.map((d) => `${d.tool} (${d.reason.length > 90 ? `${d.reason.slice(0, 90)}…` : d.reason})`).join("; ")}`);
                         lines.push(`${r.server}: refreshed — ${pushable.length} tool${pushable.length === 1 ? "" : "s"}${detail.length > 0 ? ` (${detail.join("; ")})` : ""}`);
                     }
                     if (changed)

package/dist/core/runner/runtask.js

@@ -3473,9 +3473,12 @@ export class Runner {
                 }
                 stats.cacheHitRate = Math.min(1, rawHit);
                 if (!rs.telemetry.cacheBreakReported && stats.turns >= 2 && stats.totalInputTokens >= 8000 && stats.cacheHitRate < 0.15) {
+                    const cacheWritten = stats.cacheWriteTokens + stats.cacheWriteTokensLong;
                     const cause = rs.degrade.degraded
                         ? `a mid-task model switch (${rs.degrade.degraded.from} → ${rs.degrade.degraded.to}, degradation) reset the prefix cache — this is the likely cause`
-                        : `the cacheable prefix looks unstable. Keep volatile content (memory/timestamps/ids) out of the prompt prefix and tool order stable, or it's a server-side/TTL miss`;
+                        : cacheWritten > 0
+                            ? `this task reported ${cacheWritten} cache-write tokens across its calls (compaction included) but served almost none back as reads — consistent with a prompt prefix that CHANGES between turns (client-side: volatile content up front, or per-turn tool churn/reorder) and, less often, with server-side eviction. Keep volatile content (memory/timestamps/ids) out of the prefix and the tool list stable in membership AND order`
+                            : `no call in this task reported any cache-write tokens — and this API family may not report them at all (an openai-shaped usage row carries cached READS only), so the write side is no evidence here; check that the prompt prefix (system prompt + tool list, membership AND order) is byte-stable across turns and that this route caches this model`;
                     this.deps.onError?.(new Error(`prompt-cache: low prefix-cache hit rate ${(stats.cacheHitRate * 100).toFixed(0)}% over ${stats.turns} turns (${stats.totalInputTokens} prompt tokens) — ${cause}. See design/09.`), { phase: "prompt-cache", sessionId: prepared.sessionId });
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.52.0",
+  "version": "5.53.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",