@sema-agent/core 5.5.0 → 5.6.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 5.6.0 (2026-08-03)
+
+_A hardening tail: numeric knobs refuse what they cannot honor, the binary gate reads bytes instead of trusting statistics, and the MCP SDK takes its last zero-cost step before the v2 jump._
+
+### Fixed
+
+- Stall-timeout knobs (`connectTimeoutMs` / `firstTokenTimeoutMs` / `idleTimeoutMs`) refuse invalid numbers loudly (`config.stall_timeout_invalid`) instead of silently disarming — a NaN (units fumble: `"120s"` → `Number` → NaN) used to read as "unset", switching every watchdog OFF exactly when a deployment meant to tighten them. `0` stays legal as an explicit off; absent stays absent.
+
+- Read's binary-extension list gains magic-byte criteria of its own (~40 formats, one data-driven signature table): a file whose bytes carry a real binary header (ZIP/gzip/7z/ELF/tar/RIFF…) is now refused by CONTENT even when printable padding used to slip it past the statistical sniffer as mojibake "text". Names still never decide: a `.zip` holding plain text still reads. The Edit/Write/NotebookEdit read-refusal texts all name the same escape route (one constant; NotebookEdit used to render the bare sentence with no hint at all).
+
+### Changed
+
+- `@modelcontextprotocol/sdk` 1.29.0 → 1.30.0 (exact pin). Public surface is purely additive upstream (stdio `maxBufferSize`, SSE `keepAliveMs`); `types` is byte-identical; the only behavior delta is a richer zod parse-error message the engine never pins on. Groundwork for the v2 three-package migration (spiked, GO, waiting out the first patch release).
+
 ## 5.5.0 (2026-08-03)
 
 _Three follow-through items: the deferred-placeholder wrong-guess round trip halves, durable cron jobs survive their creating session, and the redaction findings channel closes its last three audit gaps._

package/dist/brain/stream-engine.js

@@ -2,7 +2,7 @@ import { createAssistantMessageEventStream, } from "../internal/llm.js";
 import { BrainError, classifyHttp, describeNetworkError } from "./errors.js";
 import { retryBackoffMs } from "./retry.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
-import { createConnectController } from "./timeout.js";
+import { createConnectController, resolveStallTimeoutMs } from "./timeout.js";
 import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
 const DEFAULT_MAX_RETRIES = 10;
 const MAX_RETRIES_ENV_CEILING = 15;
@@ -113,9 +113,9 @@ export function runStreamingBrain(args) {
         const req = buildRequest();
         const maxRetries = resolveMaxRetries(config.maxRetries);
         const baseDelay = config.retryDelayMs ?? 500;
-        const firstTokenTimeoutMs = config.firstTokenTimeoutMs ?? stallTimeouts?.firstTokenMs;
-        const idleTimeoutMs = config.idleTimeoutMs ?? stallTimeouts?.idleMs;
-        const connectTimeoutMs = config.connectTimeoutMs ?? stallTimeouts?.connectMs;
+        const firstTokenTimeoutMs = resolveStallTimeoutMs(config.firstTokenTimeoutMs ?? stallTimeouts?.firstTokenMs, "firstTokenTimeoutMs");
+        const idleTimeoutMs = resolveStallTimeoutMs(config.idleTimeoutMs ?? stallTimeouts?.idleMs, "idleTimeoutMs");
+        const connectTimeoutMs = resolveStallTimeoutMs(config.connectTimeoutMs ?? stallTimeouts?.connectMs, "connectTimeoutMs");
         let attempt = 0;
         let thinkingRetries = 0;
         let startEmitted = false;

package/dist/brain/timeout.d.ts

@@ -1,4 +1,5 @@
 import type { StreamFn } from "../internal/llm.js";
+export declare function resolveStallTimeoutMs(value: number | undefined, knob: string): number | undefined;
 export interface BrainTimeoutConfig {
     connectTimeoutMs?: number;
     firstTokenTimeoutMs?: number;

package/dist/brain/timeout.js

@@ -1,3 +1,13 @@
+export function resolveStallTimeoutMs(value, knob) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isFinite(value) || value < 0) {
+        const e = new Error(`${knob} must be a non-negative finite number of milliseconds (got ${String(value)})`);
+        e.code = "config.stall_timeout_invalid";
+        throw e;
+    }
+    return value;
+}
 export function createConnectController(connectTimeoutMs, outerSignal, deadlineAtMs) {
     const ac = new AbortController();
     let timedOut = false;

package/dist/tools/fs/fs-read.js

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, violationDetails, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, } from "./safety.js";
+import { sha256, resolveKey, violationText, violationDetails, binaryMagicFormat, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, } from "./safety.js";
 import { decodeTextBytes } from "./encoding.js";
 import { isNotebookPath, parseNotebookCells, renderNotebookCells, stripNotebookImageData, NOTEBOOK_IMAGE_BASE64_BUDGET } from "./notebook.js";
 import { MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE } from "../../core/mcp.js";
@@ -166,6 +166,11 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             if (pdfMagicMatches(readBin.value)) {
                 return pdfResultToToolReturn(await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, readBin.value, pdfCapabilities));
             }
+            const magicFormat = binaryMagicFormat(readBin.value);
+            if (magicFormat !== undefined) {
+                return errorResult(`Error (Read): "${path}" appears to be a binary file (${magicFormat}, identified by its file signature — whatever its extension says); ` +
+                    `this tool reads UTF-8 and BOM-marked UTF-16LE text only. Inspect or convert it with bash instead.`);
+            }
             const decoded = decodeTextBytes(readBin.value);
             if (decoded.malformed) {
                 return errorResult(`Error (Read): "${path}" has a UTF-16 BOM but a truncated (odd-length) body — the file is corrupt or mis-labelled; repair/convert it with bash (e.g. \`iconv\`) first.`);

package/dist/tools/fs/fs-write.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT, } from "./safety.js";
+import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
 import { MAX_EDIT_BYTES, formatByteSize, decodeEditBytes, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, } from "./fs-shared.js";
 async function gateToolWrite(hook, tool, path, key, content) {
@@ -136,7 +136,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                 return errorResult(ipynb);
             const notRead = requireRead(state, r.key);
             if (notRead)
-                return errorResult(await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal));
+                return errorResult(await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT));
             const readBin = await env.readBinaryFile(r.key, ctx.signal);
             if (!readBin.ok)
                 return errorResult(`Error (Edit): cannot read "${path}": ${readBin.error.message}`);
@@ -249,7 +249,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             if (exists.value) {
                 const notRead = requireRead(state, r.key);
                 if (notRead) {
-                    return errorResult(await notReadRefusalText(env, "Write", r.key, notRead, ctx.signal, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT));
+                    return errorResult(await notReadRefusalText(env, "Write", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT));
                 }
                 const readBin = await env.readBinaryFile(r.key, ctx.signal);
                 if (!readBin.ok)
@@ -334,7 +334,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 return errorResult(violationText("NotebookEdit", r.violation), violationDetails(r.violation));
             const notRead = requireRead(state, r.key);
             if (notRead)
-                return errorResult(await notReadRefusalText(env, "NotebookEdit", r.key, notRead, ctx.signal));
+                return errorResult(await notReadRefusalText(env, "NotebookEdit", r.key, notRead, ctx.signal, READ_REFUSED_ESCAPE_HINT));
             const readBin = await env.readBinaryFile(r.key, ctx.signal);
             if (!readBin.ok)
                 return errorResult(`Error (NotebookEdit): cannot read "${notebook_path}": ${readBin.error.message}`);

package/dist/tools/fs/safety.d.ts

@@ -30,6 +30,16 @@ export declare function foldRedundantPathSegments(p: string): string;
 export declare function hasBinaryExtension(path: string): boolean;
 export declare function imageMimeForRead(path: string): string | undefined;
 export declare function imageMagicMatches(bytes: Uint8Array, mimeType: string): boolean;
+export interface BinaryMagicSegment {
+    readonly offset: number;
+    readonly bytes: readonly number[];
+}
+export interface BinaryMagicSignature {
+    readonly format: string;
+    readonly segments: readonly BinaryMagicSegment[];
+}
+export declare const BINARY_MAGIC_SIGNATURES: readonly BinaryMagicSignature[];
+export declare function binaryMagicFormat(bytes: Uint8Array): string | undefined;
 export declare function isBinaryContent(sample: string): boolean;
 export declare function isUncPath(path: string): boolean;
 export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, path: string, signal?: AbortSignal, baseCwd?: string, additionalRootsCanonical?: readonly string[], exactFileReadExemption?: (canonicalKey: string) => boolean): Promise<{
@@ -59,7 +69,7 @@ export declare const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to t
 export declare function requireRead(state: ReadFileState, key: string): FsViolation | undefined;
 export declare const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused \u2014 read it in slices with explicit offset/limit to satisfy the read-first rule, or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
 export declare const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view \u2014 the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
-export declare const WRITE_ENCODING_DEADLOCK_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead \u2014 e.g. `rm` + rewrite, or `iconv`.)";
+export declare const READ_REFUSED_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead \u2014 e.g. `rm` + rewrite, or `iconv`.)";
 export declare function checkNoChange(oldString: string, newString: string): FsViolation | undefined;
 export declare function checkStale(entry: ReadEntry | undefined, currentHash: string): FsViolation | undefined;
 export declare function countOccurrences(haystack: string, needle: string): number;

package/dist/tools/fs/safety.js

@@ -150,6 +150,89 @@ export function imageMagicMatches(bytes, mimeType) {
             return false;
     }
 }
+const asciiBytes = (s) => Array.from(s, (c) => c.charCodeAt(0));
+export const BINARY_MAGIC_SIGNATURES = [
+    { format: "ZIP archive", segments: [{ offset: 0, bytes: [0x50, 0x4b, 0x03, 0x04] }] },
+    { format: "ZIP archive", segments: [{ offset: 0, bytes: [0x50, 0x4b, 0x05, 0x06] }] },
+    { format: "ZIP archive", segments: [{ offset: 0, bytes: [0x50, 0x4b, 0x07, 0x08] }] },
+    { format: "gzip archive", segments: [{ offset: 0, bytes: [0x1f, 0x8b, 0x08] }] },
+    ...[0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39].map((level) => ({
+        format: "bzip2 archive",
+        segments: [{ offset: 0, bytes: [0x42, 0x5a, 0x68, level] }],
+    })),
+    { format: "xz archive", segments: [{ offset: 0, bytes: [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00] }] },
+    { format: "zstd archive", segments: [{ offset: 0, bytes: [0x28, 0xb5, 0x2f, 0xfd] }] },
+    { format: "lz4 archive", segments: [{ offset: 0, bytes: [0x04, 0x22, 0x4d, 0x18] }] },
+    { format: "compress archive", segments: [{ offset: 0, bytes: [0x1f, 0x9d] }] },
+    { format: "7-Zip archive", segments: [{ offset: 0, bytes: [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c] }] },
+    { format: "RAR archive", segments: [{ offset: 0, bytes: [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07, 0x00] }] },
+    { format: "RAR archive", segments: [{ offset: 0, bytes: [0x52, 0x61, 0x72, 0x21, 0x1a, 0x07, 0x01, 0x00] }] },
+    { format: "tar archive", segments: [{ offset: 257, bytes: asciiBytes("ustar") }] },
+    { format: "ar archive (static library or Debian package)", segments: [{ offset: 0, bytes: asciiBytes("!<arch>\n") }] },
+    { format: "RPM package", segments: [{ offset: 0, bytes: [0xed, 0xab, 0xee, 0xdb] }] },
+    { format: "ISO 9660 disc image", segments: [{ offset: 32769, bytes: asciiBytes("CD001") }] },
+    { format: "PNG image", segments: [{ offset: 0, bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] }] },
+    { format: "JPEG image", segments: [{ offset: 0, bytes: [0xff, 0xd8, 0xff] }] },
+    { format: "GIF image", segments: [{ offset: 0, bytes: asciiBytes("GIF87a") }] },
+    { format: "GIF image", segments: [{ offset: 0, bytes: asciiBytes("GIF89a") }] },
+    { format: "TIFF image", segments: [{ offset: 0, bytes: [0x49, 0x49, 0x2a, 0x00] }] },
+    { format: "TIFF image", segments: [{ offset: 0, bytes: [0x4d, 0x4d, 0x00, 0x2a] }] },
+    { format: "BMP image", segments: [{ offset: 0, bytes: asciiBytes("BM") }, { offset: 6, bytes: [0x00, 0x00, 0x00, 0x00] }] },
+    { format: "ICO image", segments: [{ offset: 0, bytes: [0x00, 0x00, 0x01, 0x00] }] },
+    { format: "Photoshop document", segments: [{ offset: 0, bytes: asciiBytes("8BPS") }] },
+    { format: "WebP image", segments: [{ offset: 0, bytes: asciiBytes("RIFF") }, { offset: 8, bytes: asciiBytes("WEBP") }] },
+    { format: "RIFF audio (WAV)", segments: [{ offset: 0, bytes: asciiBytes("RIFF") }, { offset: 8, bytes: asciiBytes("WAVE") }] },
+    { format: "RIFF video (AVI)", segments: [{ offset: 0, bytes: asciiBytes("RIFF") }, { offset: 8, bytes: asciiBytes("AVI ") }] },
+    { format: "AIFF audio", segments: [{ offset: 0, bytes: asciiBytes("FORM") }, { offset: 8, bytes: asciiBytes("AIFF") }] },
+    { format: "Ogg container", segments: [{ offset: 0, bytes: asciiBytes("OggS") }, { offset: 4, bytes: [0x00] }] },
+    { format: "FLAC audio", segments: [{ offset: 0, bytes: asciiBytes("fLaC") }] },
+    ...[0x02, 0x03, 0x04].map((major) => ({
+        format: "MP3 audio (ID3 tag)",
+        segments: [{ offset: 0, bytes: [0x49, 0x44, 0x33, major] }],
+    })),
+    { format: "ISO base media container (MP4/MOV/HEIC)", segments: [{ offset: 4, bytes: asciiBytes("ftyp") }] },
+    { format: "Matroska/WebM container", segments: [{ offset: 0, bytes: [0x1a, 0x45, 0xdf, 0xa3] }] },
+    { format: "ASF container (WMV/WMA)", segments: [{ offset: 0, bytes: [0x30, 0x26, 0xb2, 0x75, 0x8e, 0x66, 0xcf, 0x11, 0xa6, 0xd9, 0x00, 0xaa, 0x00, 0x62, 0xce, 0x6c] }] },
+    { format: "FLV video", segments: [{ offset: 0, bytes: [0x46, 0x4c, 0x56, 0x01] }] },
+    { format: "MPEG program stream", segments: [{ offset: 0, bytes: [0x00, 0x00, 0x01, 0xba] }] },
+    { format: "MPEG video stream", segments: [{ offset: 0, bytes: [0x00, 0x00, 0x01, 0xb3] }] },
+    { format: "ELF binary", segments: [{ offset: 0, bytes: [0x7f, 0x45, 0x4c, 0x46] }] },
+    { format: "Mach-O binary", segments: [{ offset: 0, bytes: [0xfe, 0xed, 0xfa, 0xce] }] },
+    { format: "Mach-O binary", segments: [{ offset: 0, bytes: [0xfe, 0xed, 0xfa, 0xcf] }] },
+    { format: "Mach-O binary", segments: [{ offset: 0, bytes: [0xce, 0xfa, 0xed, 0xfe] }] },
+    { format: "Mach-O binary", segments: [{ offset: 0, bytes: [0xcf, 0xfa, 0xed, 0xfe] }] },
+    { format: "Java class file or Mach-O universal binary", segments: [{ offset: 0, bytes: [0xca, 0xfe, 0xba, 0xbe] }] },
+    { format: "WebAssembly module", segments: [{ offset: 0, bytes: [0x00, 0x61, 0x73, 0x6d] }] },
+    { format: "OLE compound document (Office 97-2003 or MSI)", segments: [{ offset: 0, bytes: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1] }] },
+    { format: "SQLite database", segments: [{ offset: 0, bytes: [...asciiBytes("SQLite format 3"), 0x00] }] },
+    { format: "WOFF font", segments: [{ offset: 0, bytes: asciiBytes("wOFF") }] },
+    { format: "WOFF2 font", segments: [{ offset: 0, bytes: asciiBytes("wOF2") }] },
+    { format: "OpenType font", segments: [{ offset: 0, bytes: asciiBytes("OTTO") }] },
+    { format: "TrueType font", segments: [{ offset: 0, bytes: [0x00, 0x01, 0x00, 0x00] }] },
+    { format: "TrueType font collection", segments: [{ offset: 0, bytes: asciiBytes("ttcf") }] },
+];
+export function binaryMagicFormat(bytes) {
+    for (const signature of BINARY_MAGIC_SIGNATURES) {
+        let matched = true;
+        for (const segment of signature.segments) {
+            if (bytes.length < segment.offset + segment.bytes.length) {
+                matched = false;
+                break;
+            }
+            for (let i = 0; i < segment.bytes.length; i++) {
+                if (bytes[segment.offset + i] !== segment.bytes[i]) {
+                    matched = false;
+                    break;
+                }
+            }
+            if (!matched)
+                break;
+        }
+        if (matched)
+            return signature.format;
+    }
+    return undefined;
+}
 export function isBinaryContent(sample) {
     if (sample.length === 0)
         return false;
@@ -297,7 +380,7 @@ export function requireRead(state, key) {
 }
 export const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused — read it in slices with explicit offset/limit to satisfy the read-first rule, or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
 export const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view — the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
-export const WRITE_ENCODING_DEADLOCK_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead — e.g. `rm` + rewrite, or `iconv`.)";
+export const READ_REFUSED_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead — e.g. `rm` + rewrite, or `iconv`.)";
 export function checkNoChange(oldString, newString) {
     if (oldString === newString) {
         return { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -67,7 +67,7 @@
     "gate:single-mint": "node scripts/verify-single-mint.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "typebox": "1.1.39"
   },
   "optionalDependencies": {