@mono-agent/agent-runtime 0.18.2 → 0.19.0

package/MIGRATION.md

@@ -17,6 +17,14 @@ the configuration schema.
 
 ---
 
+## 0.19.0
+
+- **Oversized `Read` images:** raster image results with an edge above 8,000
+  pixels are now normalized before provider embedding. Source files are never
+  modified; safe images retain their exact bytes, resized GIF/WebP input keeps
+  its animation, and resized BMP input becomes PNG. Undecodable image data now
+  fails before the runtime creates an image content block.
+
 ## 0.18.2
 
 - **Normalized native-subagent activity:** Claude SDK/CLI and Codex app-server
@@ -482,7 +490,7 @@ a compatibility subpath.
 
 ## Version
 
-This guide describes the published `0.18.x` package contract. Keep
+This guide describes the published `0.19.x` package contract. Keep
 `@mono-agent/agent-runtime`, `@mono-agent/runtime-adapter`, and other
 `@mono-agent/*` packages on the same lockstep version when upgrading. The paired
 runtime adapter no longer exposes `piReasoningSummary` in its run-options type.

package/README.md

@@ -1094,6 +1094,8 @@ The kernel's tool-bloat guard (`agent/tool-bloat.js`, internal) enforces a 256 K
 
 Hosts that don't supply `persistArtifact` get the truncation summary but no on-disk capture.
 
+Before that byte cap runs, the builtin `Read` tool normalizes raster images with an edge longer than 8,000 px to fit within an 8,000 × 8,000 px box. Resizing preserves aspect ratio and the source format (resized BMP input becomes PNG), retains GIF/WebP animation, and never modifies the source file. Images already within the limit are embedded byte-for-byte unchanged.
+
 ### Context compaction
 
 The sole pi bridge runs on pi-agent-core's native `AgentHarness`. pi performs **no**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, Pi SDK, and ACP v1 bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -144,9 +144,11 @@
     "@mozilla/readability": "0.6.0",
     "@opencode-ai/sdk": "^1.15.13",
     "@vscode/ripgrep": "1.18.0",
+    "bmp-ts": "1.0.9",
     "cross-spawn": "^7.0.6",
     "defuddle": "0.19.2",
     "linkedom": "0.18.13",
+    "sharp": "0.35.3",
     "unpdf": "1.8.0",
     "zod": "^4.3.6"
   },

package/src/agent/tools/read.js

@@ -1,5 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { extname } from "node:path";
+import { decode as decodeBmp } from "bmp-ts";
+import sharp from "sharp";
 import {
   DEFAULT_MAX_READ_CHARS,
   DEFAULT_READ_LINES,
@@ -20,6 +22,82 @@ const IMAGE_MIME_BY_EXT = {
   ".bmp": "image/bmp",
 };
 
+// Anthropic rejects images with an edge longer than 8,000 px. Normalize Read
+// results to that shared provider-safe ceiling before the tool-result byte cap
+// runs, while leaving the source file untouched.
+const MAX_INLINE_IMAGE_EDGE_PX = 8_000;
+const ANIMATED_IMAGE_MIME_TYPES = new Set(["image/gif", "image/webp"]);
+const OUTPUT_MIME_BY_FORMAT = {
+  png: "image/png",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+};
+
+/**
+ * @param {string} target
+ * @param {string} filePath
+ * @param {string} imageMime
+ */
+async function readImageForModel(target, filePath, imageMime) {
+  const source = readFileSync(target);
+  const inputOptions = { animated: ANIMATED_IMAGE_MIME_TYPES.has(imageMime) };
+
+  try {
+    let width;
+    let height;
+    let createPipeline;
+
+    if (imageMime === "image/bmp") {
+      // The prebuilt Sharp binaries do not include a BMP loader. Decode to raw
+      // RGBA first, then let Sharp handle the provider-safe resize and PNG output.
+      const decoded = decodeBmp(source, { toRGBA: true });
+      width = decoded.width;
+      height = Math.abs(decoded.height);
+      createPipeline = () => sharp(decoded.data, {
+        raw: { width, height, channels: 4 },
+      });
+    } else {
+      const metadata = await sharp(source, inputOptions).metadata();
+      width = metadata.width;
+      // Sharp exposes animated images as a vertical stack internally. Providers
+      // care about the dimensions of each frame, not the height of that stack.
+      height = metadata.pageHeight ?? metadata.height;
+      createPipeline = () => sharp(source, inputOptions);
+    }
+
+    if (!Number.isInteger(width) || width <= 0 || !Number.isInteger(height) || height <= 0) {
+      throw new Error("could not determine positive pixel dimensions");
+    }
+
+    if (width <= MAX_INLINE_IMAGE_EDGE_PX && height <= MAX_INLINE_IMAGE_EDGE_PX) {
+      return { data: source, mimeType: imageMime };
+    }
+
+    let pipeline = createPipeline()
+      .autoOrient()
+      .resize({
+        width: MAX_INLINE_IMAGE_EDGE_PX,
+        height: MAX_INLINE_IMAGE_EDGE_PX,
+        fit: "inside",
+        withoutEnlargement: true,
+      });
+
+    // Sharp cannot emit BMP, so resized BMP input becomes lossless PNG.
+    if (imageMime === "image/bmp") pipeline = pipeline.png();
+
+    const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+    const mimeType = OUTPUT_MIME_BY_FORMAT[info.format];
+    if (mimeType === undefined) {
+      throw new Error(`unsupported normalized image format: ${info.format}`);
+    }
+    return { data, mimeType };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { error: `Error: Unable to read image ${filePath}: ${reason}` };
+  }
+}
+
 /**
  * @param {{file_path: string, offset?: number, start_line?: number, limit?: number, max_output_chars?: number, workdir?: string}} params
  * @param {{sandboxPolicy?: any, ctx?: any}} [options]
@@ -34,7 +112,9 @@ export async function readToolImpl({ file_path, offset = 0, start_line, limit, m
   // capped by the shared tool-result bloat guard.
   const imageMime = IMAGE_MIME_BY_EXT[extname(target).toLowerCase()];
   if (imageMime !== undefined) {
-    return { kind: "image", data: readFileSync(target).toString("base64"), mimeType: imageMime };
+    const image = await readImageForModel(target, file_path, imageMime);
+    if (image.error !== undefined) return image.error;
+    return { kind: "image", data: image.data.toString("base64"), mimeType: image.mimeType };
   }
   const content = readFileSync(target, "utf8");
   let lines = content.split("\n");

package/src/ai/providers/pi-native/result-builder.js

@@ -323,6 +323,8 @@ export function buildDiagnostics(params) {
     lastToolName,
     structuredRetry,
     contextCompactionDiagnostics,
+    transportErrorCode,
+    transportErrorSource,
   } = params;
   return {
     provider_session_id: providerSessionId,
@@ -335,6 +337,15 @@ export function buildDiagnostics(params) {
     pi_max_retries: maxRetries,
     pi_transport_requested: piTransport,
     ...(lastToolName ? { last_tool_name: lastToolName } : {}),
+    // Present only when an opaque transport failure was resolved to a real
+    // reason. `provider_transport_error_source` says whether that came from the
+    // error's own cause chain (exact) or from process-wide correlation.
+    ...(transportErrorCode
+      ? {
+        provider_transport_error_code: transportErrorCode,
+        provider_transport_error_source: transportErrorSource,
+      }
+      : {}),
     ...structuredOutputRetryDiagnostics(
       structuredRetry.attempts,
       structuredRetry.reason,

package/src/ai/providers/pi-native.js

@@ -44,6 +44,7 @@ import {
 } from "./pi-messages.js";
 import { emitCaptured } from "./pi-events.js";
 import { normalizePiErrorMessage } from "./pi-errors.js";
+import { annotateProviderErrorMessage, installTransportErrorProbe } from "./transport-errors.js";
 import {
   runStructuredOutputFinalizationRetry,
   shouldRetryStructuredOutputFinalization,
@@ -252,6 +253,10 @@ function splitUserContent(content) {
 }
 
 export async function generatePiNativeResponse(systemPrompt, options = {}) {
+  // Idempotent; arms the undici diagnostics-channel probe so a transport
+  // failure during this run can be resolved back to a real reason even after
+  // an intermediate layer flattens the Error to its message.
+  installTransportErrorProbe();
   const resolved = options.model;
   const start = Date.now();
   const events = [];
@@ -682,7 +687,15 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
         : (stopReason === "error" || stopReason === "aborted"
           ? lastAssistant?.errorMessage || runError?.message || "Pi agent aborted before final output"
           : (runError ? runError.message || String(runError) : null));
-    const errorMessage = normalizePiErrorMessage(rawErrorMessage);
+    // pi-agent-core stores `error.message` on the failure assistant message and
+    // discards the cause, so `runError` is usually the only object still
+    // carrying one. When neither has a cause, fall back to the correlated
+    // transport probe rather than surfacing a bare "terminated".
+    const annotatedError = annotateProviderErrorMessage(
+      normalizePiErrorMessage(rawErrorMessage),
+      runError,
+    );
+    const errorMessage = annotatedError.message;
 
     const structuredRetry = {
       attempts: structuredOutputFinalizationRetryAttempts,
@@ -702,6 +715,8 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
       lastToolName: runState.lastToolName,
       structuredRetry,
       contextCompactionDiagnostics: runState.compaction.diagnostics,
+      transportErrorCode: annotatedError.causeCode,
+      transportErrorSource: annotatedError.causeSource,
     });
     const errorDetails = buildErrorDetails({
       errorMessage,
@@ -812,7 +827,12 @@ export async function generatePiNativeResponse(systemPrompt, options = {}) {
     // leaf for host/runtime-side throws that landed after the harness already
     // mutated the live session (guards preserved in cleanupSessionOnThrow).
     await cleanupSessionOnThrow(runState, { durableRepo });
-    const errorMessage = normalizePiErrorMessage(err?.message || String(err));
+    // The throw path still holds the original Error, so its cause chain is the
+    // authoritative source here — no correlation guesswork needed.
+    const errorMessage = annotateProviderErrorMessage(
+      normalizePiErrorMessage(err?.message || String(err)),
+      err,
+    ).message;
     const isRetryable = retryableProviderFailureInfo({
       errorText: errorMessage,
       failureKind: "provider_unavailable",

package/src/ai/providers/transport-errors.js

@@ -0,0 +1,154 @@
+// Recover the real reason behind opaque provider transport failures.
+//
+// Node's fetch (undici) reports a cut response body as `TypeError: terminated`
+// with the actual reason — UND_ERR_BODY_TIMEOUT, ECONNRESET, "other side
+// closed" — only on `error.cause`. Several layers between the socket and us
+// flatten errors to `error.message`, most notably pi-agent-core's
+// `handleRunFailure`, which stores `error.message` and drops the cause before
+// any mono-agent code sees the Error object. The result is a run that fails
+// with the single uninformative word "terminated".
+//
+// Two recovery paths, in order of trustworthiness:
+//
+//   1. `describeErrorCause` walks the cause chain of an Error we still hold.
+//      Exact, but only available where the original object survives.
+//   2. `recentTransportErrorCode` reads a bounded ring of `undici:request:error`
+//      diagnostics-channel events. This sees the error before any library
+//      flattens it, at the cost of attribution: the channel is process-wide, so
+//      with concurrent requests in flight we cannot prove which run a given
+//      socket error belongs to. Correlation is reported as such, and a window
+//      containing conflicting codes reports ambiguity instead of guessing.
+
+import diagnosticsChannel from "node:diagnostics_channel";
+
+// Messages that carry no diagnostic content on their own. Annotating only these
+// keeps already-descriptive provider errors untouched.
+const OPAQUE_ERROR_RE = /^(?:terminated|fetch failed|connection error\.?|network error|socket hang up|premature close|other side closed)$/i;
+
+const MAX_RECORDED = 32;
+// A stream cut is observed on the socket within milliseconds of the rejection
+// surfacing. Anything older is a different request's failure.
+const DEFAULT_CORRELATION_WINDOW_MS = 5_000;
+const MAX_CAUSE_DEPTH = 5;
+
+/** @type {{code: string, at: number, origin: string|null}[]} */
+const recorded = [];
+let installed = false;
+
+function codeFromError(error) {
+  if (!error || typeof error !== "object") return null;
+  const code = error.code ?? error.errno;
+  if (typeof code === "string" && code.trim()) return code.trim();
+  // Undici's timeout errors expose a stable `name` even when `code` is absent.
+  const name = typeof error.name === "string" ? error.name.trim() : "";
+  if (name && name !== "Error" && name !== "TypeError") return name;
+  return null;
+}
+
+/**
+ * Walk an error's `cause` chain and return the first transport-level code found.
+ * Returns null when the chain carries no code (i.e. nothing worth appending).
+ * @param {unknown} error
+ * @returns {string|null}
+ */
+export function describeErrorCause(error) {
+  /** @type {any} */
+  let current = error;
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH && current; depth += 1) {
+    // Skip the outermost error: its code (if any) is what the caller already
+    // has. We want the reason underneath it.
+    if (depth > 0) {
+      const code = codeFromError(current);
+      if (code) return code;
+    }
+    current = current?.cause;
+  }
+  return null;
+}
+
+/**
+ * Subscribe to undici's request-error channel. Idempotent and safe to call on
+ * every run; a Node build without the channel simply records nothing.
+ */
+export function installTransportErrorProbe() {
+  if (installed) return;
+  installed = true;
+  try {
+    diagnosticsChannel.subscribe("undici:request:error", (/** @type {any} */ message) => {
+      const error = message?.error;
+      const code = codeFromError(error) || describeErrorCause(error);
+      if (!code) return;
+      /** @type {string|null} */
+      let origin = null;
+      try {
+        const raw = message?.request?.origin;
+        origin = typeof raw === "string" ? raw : (raw?.origin ?? null);
+      } catch {
+        origin = null;
+      }
+      recorded.push({ code, at: Date.now(), origin });
+      if (recorded.length > MAX_RECORDED) recorded.splice(0, recorded.length - MAX_RECORDED);
+    });
+  } catch {
+    // Channel unavailable on this runtime: fall back to cause-chain walking only.
+    installed = false;
+  }
+}
+
+/**
+ * Most recent transport error code seen within the correlation window.
+ * `ambiguous` is true when the window holds more than one distinct code, in
+ * which case attribution to a specific run would be a guess.
+ * @param {{withinMs?: number, now?: number}} [opts]
+ * @returns {{code: string, ambiguous: boolean}|null}
+ */
+export function recentTransportErrorCode(opts = {}) {
+  const withinMs = Number.isFinite(Number(opts.withinMs))
+    ? Number(opts.withinMs)
+    : DEFAULT_CORRELATION_WINDOW_MS;
+  const now = Number.isFinite(Number(opts.now)) ? Number(opts.now) : Date.now();
+  const fresh = recorded.filter((entry) => now - entry.at <= withinMs);
+  if (fresh.length === 0) return null;
+  const distinct = new Set(fresh.map((entry) => entry.code));
+  return { code: fresh[fresh.length - 1].code, ambiguous: distinct.size > 1 };
+}
+
+/**
+ * Append the underlying transport reason to an otherwise contentless provider
+ * error. Descriptive messages, and messages that already name their cause, are
+ * returned unchanged.
+ *
+ * @param {string|null} message normalized provider error text
+ * @param {unknown} [error] the original Error, when it survived
+ * @returns {{message: string|null, causeCode: string|null, causeSource: "cause_chain"|"transport_probe"|null}}
+ */
+export function annotateProviderErrorMessage(message, error) {
+  const text = String(message || "").trim();
+  if (!text) return { message: message ?? null, causeCode: null, causeSource: null };
+  if (!OPAQUE_ERROR_RE.test(text)) return { message: text, causeCode: null, causeSource: null };
+
+  const fromChain = describeErrorCause(error);
+  if (fromChain) {
+    return { message: `${text} (${fromChain})`, causeCode: fromChain, causeSource: "cause_chain" };
+  }
+
+  const correlated = recentTransportErrorCode();
+  if (correlated && !correlated.ambiguous) {
+    return {
+      message: `${text} (${correlated.code}, correlated)`,
+      causeCode: correlated.code,
+      causeSource: "transport_probe",
+    };
+  }
+  return { message: text, causeCode: null, causeSource: null };
+}
+
+/** Test seam: drop recorded transport errors. */
+export function resetTransportErrorProbeForTests() {
+  recorded.length = 0;
+}
+
+/** Test seam: record a transport error without a real socket. */
+export function recordTransportErrorForTests(code, at = Date.now()) {
+  recorded.push({ code, at, origin: null });
+}

package/types/ai/providers/transport-errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Walk an error's `cause` chain and return the first transport-level code found.
+ * Returns null when the chain carries no code (i.e. nothing worth appending).
+ * @param {unknown} error
+ * @returns {string|null}
+ */
+export function describeErrorCause(error: unknown): string | null;
+/**
+ * Subscribe to undici's request-error channel. Idempotent and safe to call on
+ * every run; a Node build without the channel simply records nothing.
+ */
+export function installTransportErrorProbe(): void;
+/**
+ * Most recent transport error code seen within the correlation window.
+ * `ambiguous` is true when the window holds more than one distinct code, in
+ * which case attribution to a specific run would be a guess.
+ * @param {{withinMs?: number, now?: number}} [opts]
+ * @returns {{code: string, ambiguous: boolean}|null}
+ */
+export function recentTransportErrorCode(opts?: {
+    withinMs?: number;
+    now?: number;
+}): {
+    code: string;
+    ambiguous: boolean;
+} | null;
+/**
+ * Append the underlying transport reason to an otherwise contentless provider
+ * error. Descriptive messages, and messages that already name their cause, are
+ * returned unchanged.
+ *
+ * @param {string|null} message normalized provider error text
+ * @param {unknown} [error] the original Error, when it survived
+ * @returns {{message: string|null, causeCode: string|null, causeSource: "cause_chain"|"transport_probe"|null}}
+ */
+export function annotateProviderErrorMessage(message: string | null, error?: unknown): {
+    message: string | null;
+    causeCode: string | null;
+    causeSource: "cause_chain" | "transport_probe" | null;
+};
+/** Test seam: drop recorded transport errors. */
+export function resetTransportErrorProbeForTests(): void;
+/** Test seam: record a transport error without a real socket. */
+export function recordTransportErrorForTests(code: any, at?: number): void;