@mmerterden/multi-agent-toolkit-mcp 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -15,8 +15,95 @@ Releases before this file exists are recorded in the git tags and commit history
 
 ---
 
+## 3.1.1
+
+### Fixed
+
+- `android_launch_time` reported `cold_start: true` on every call. It force-stops
+  the package first, which kills the process but leaves the page cache warm, so
+  the start it measures is cold only some of the time. Android 10 replaced
+  `ThisTime` with `LaunchState` (COLD, WARM, HOT, UNKNOWN), which is the
+  platform's own verdict on the start it just performed, and the tool was
+  ignoring it while asserting the answer itself. The result now carries
+  `launch_state` and derives `cold_start` from it. Below Android 10 nothing
+  reports a launch state, so `cold_start` is `null` there rather than a claim
+  nothing checked. A failed launch now surfaces its `Error:` line instead of
+  returning null timings that read like a measurement.
+- The parser moved to `tools/launch-time/` with a suite covering the Android 10+
+  and pre-10 output shapes, a warm start, a failed launch and non-string input.
+  It could not be tested where it was: `index.js` connects its transport at
+  import time, so nothing in it is reachable from a test.
+
 ## Unreleased
 
+## 3.1.0
+
+One new tool and the offload path behind it. Minor rather than patch because the
+tool surface grew: pipeline-side minimums that need `agent_query_output` should
+declare `>= 3.1.0`.
+
+### Added
+
+- **`agent_query_output` (tool 84) and large-result offload.** A UI tree, a
+  logcat window or an xcresult dump can be tens of thousands of lines. The
+  server met that with two lossy caps: `spawnCollect` dropped the OLDEST chunks
+  at `SPAWN_OUTPUT_CAP`, and error text was cut at 600 chars. For a build log or
+  a test run the interesting part is the END, so "truncated" often meant the
+  failure was gone; `ios_get_ui_tree` could write a file, but only when the
+  caller thought to pass `path`.
+
+  Prose payloads over 24 KB are now written whole to
+  `~/.claude/logs/multi-agent-toolkit/<tool>-<timestamp>.txt`, and the tool
+  returns a head + tail window with the line count and the path.
+  `agent_query_output {pattern, path?, context_lines?, max_matches?,
+  ignore_case?}` searches that file and returns matching lines with numbered
+  context, so a follow-up question does not mean re-running an expensive tool -
+  and for a UI dump a second run is not even the same evidence.
+
+  Only prose is offloaded: a tool that declares an `outputSchema` answers with
+  JSON the host parses as `structuredContent`, and a summary would break that
+  parse. A write failure falls back to returning the payload whole, because
+  spending context is recoverable and dropping the tail is not. Bad regex,
+  missing file and nothing-offloaded are reported as `ERROR:` strings, never
+  thrown.
+
+  Pattern source: the multi-agent pipeline's own Phase 4 Step 1.9 (cap the
+  diff, write the full copy to `.review-diff.txt`, leave a marker in the
+  prompt), which is the same shape yamadashy/repomix uses for packed output.
+  Logic lives in `tools/offload/` with 17 unit tests covering the threshold,
+  byte-for-byte preservation, tail retention, retrieval of content the inline
+  window omitted, the match cap, and every failure mode.
+
+### Fixed (same release, found by reviewing the above)
+
+- **The failure path kept none of this.** `run()` / `runAsync()` cut a failed
+  command's output to `ERROR_MAX_CHARS` (600) at the source, and the CallTool
+  handler returns on `isFailure` before the offload branch - so the case the
+  offload was justified by (xcodebuild puts the failing assertion and the
+  compiler error at the END) was untouched, and only successful large outputs
+  were saved. `truncateError` now offloads the full text and returns a
+  character-window head + tail with the path; the old head-only cut remains
+  only as the fallback when the write fails.
+- **`agent_query_output` accepted any absolute path.** It resolved
+  `args.path` unvalidated, which made a tool whose purpose is "read back what
+  this server saved" into an arbitrary-file reader - the opposite direction from
+  the 2.26.0 hardening. A caller-supplied path is now confined to the offload
+  directory, and confinement is checked BEFORE existence so the refusal cannot
+  be used as an existence oracle for paths outside it. The path this server
+  recorded itself needs no check: it wrote it.
+- **The offload directory had no retention owner.** It grew without bound at
+  24 KB per entry; the pipeline's `prune-logs` targets a different path and an
+  MCP-only user has no pipeline at all. A successful write now prunes the
+  directory to the newest 50 files and drops anything older than 7 days, with
+  non-`.txt` files and unreadable directories left alone. The file just written
+  is never pruned regardless of the retention numbers - review round 1 found
+  that a `keepFiles` of 0 deleted it while the returned text still promised its
+  path, which is the payload loss this module exists to prevent.
+- **`agent_query_output` carried no `readOnlyHint`.** It was absent from
+  `READ_ONLY_TOOLS`, and the test asserting its contract said "read-only" in its
+  name while checking only the input schema. Both fixed; the annotation is now
+  asserted.
+
 ## 2.26.0
 
 Security-hardening release from a multi-agent refactor audit. No tool added or

package/README.md

@@ -7,7 +7,7 @@
 
 🇹🇷 Türkçe: [README.tr.md](./README.tr.md)
 
-**83 tools** for iOS Simulator, Android Emulator, and headless web control. MCP server that lets your AI coding assistant see, interact with, and audit your mobile apps - plus drive browsers, run an 18-rule App Store compliance audit, and orchestrate multi-step batch flows.
+**84 tools** for iOS Simulator, Android Emulator, and headless web control. MCP server that lets your AI coding assistant see, interact with, and audit your mobile apps - plus drive browsers, run an 18-rule App Store compliance audit, and orchestrate multi-step batch flows.
 
 Distributed on the **public npm registry** - `npx @mmerterden/multi-agent-toolkit-mcp` resolves with no auth, no token, no `~/.npmrc` setup.
 
@@ -22,7 +22,7 @@ That distinction is worth keeping straight. This line once called five hosts "th
 - **Store Compliance** (5 tools) - App Store / Play Store readiness; **18-rule deep `ios_app_store_audit`** cross-references Apple ITMS error codes + App Store Review Guidelines (privacy manifest, required-reason API, Info.plist, code signing, entitlements, embedded SDK, IPv6, debug-tool leak, ...)
 - **Web Automation** (8 tools) - Playwright-powered: goto, click (CSS selectors), type, eval JS, wait for selector, extract text, screenshot. Chromium / WebKit / Firefox engines. **Requires `playwright` peer dependency.**
 - **Design Audit** (6 tools) - mock-mode vs Figma conformance: scenario inventory, mock detection, mock launch, live UI geometry, pixel/geometry/typography compare, and the HTML/PDF report with its coverage gate
-- **Autonomous Agent DSL** (1 tool) - `agent_run_steps` executes a batch array of {tool, args, continue_on_error?, wait_ms?} steps in one MCP round trip. Ideal for scripted login flows, form fills, multi-step QA paths.
+- **Autonomous Agent DSL** (2 tools) - `agent_run_steps` executes a batch array of {tool, args, continue_on_error?, wait_ms?} steps in one MCP round trip. Ideal for scripted login flows, form fills, multi-step QA paths. `agent_query_output` searches the full output of an earlier call that was too large to return inline, so a follow-up question does not mean re-running an expensive tool.
 
 ## Quick Start
 

package/README.tr.md

@@ -7,7 +7,7 @@
 
 🇬🇧 English: [README.md](./README.md)
 
-iOS Simulator, Android Emulator ve headless web kontrolü için **83 araç**. AI kodlama asistanının mobil uygulamalarını görmesini, onlarla etkileşime girmesini ve denetlemesini sağlayan bir MCP sunucusu - ayrıca tarayıcıları sürer, 18-kurallık bir App Store uyumluluk denetimi çalıştırır ve çok-adımlı batch akışlarını orkestre eder.
+iOS Simulator, Android Emulator ve headless web kontrolü için **84 araç**. AI kodlama asistanının mobil uygulamalarını görmesini, onlarla etkileşime girmesini ve denetlemesini sağlayan bir MCP sunucusu - ayrıca tarayıcıları sürer, 18-kurallık bir App Store uyumluluk denetimi çalıştırır ve çok-adımlı batch akışlarını orkestre eder.
 
 **Public npm registry** üzerinden dağıtılır - `npx @mmerterden/multi-agent-toolkit-mcp`, auth'suz, token'sız, `~/.npmrc` ayarı gerekmeden çözülür.
 
@@ -22,7 +22,7 @@ Bu ayrımı net tutmakta fayda var. Bu satır bir zamanlar beş host'u "multi-ag
 - **Store Compliance** (5 araç) - App Store / Play Store hazırlığı; **18-kurallık derin `ios_app_store_audit`**, Apple ITMS hata kodları + App Store Review Guidelines'a çapraz referans verir (privacy manifest, required-reason API, Info.plist, code signing, entitlements, gömülü SDK, IPv6, debug-tool sızıntısı, ...)
 - **Web Automation** (8 araç) - Playwright-destekli: goto, click (CSS selector'lar), type, JS eval, selector bekleme, metin çıkarma, screenshot. Chromium / WebKit / Firefox motorları. **`playwright` peer dependency'si gerektirir.**
 - **Design Audit** (6 araç) - mock-mode vs Figma uygunluğu: scenario envanteri, mock tespiti, mock launch, canlı UI geometrisi, piksel/geometri/tipografi karşılaştırması, ve coverage kapısıyla birlikte HTML/PDF rapor
-- **Autonomous Agent DSL** (1 araç) - `agent_run_steps`, tek bir MCP round trip'inde {tool, args, continue_on_error?, wait_ms?} adımlarından oluşan bir batch dizisini çalıştırır. Scriptlenmiş login akışları, form doldurma, çok-adımlı QA yolları için ideal.
+- **Autonomous Agent DSL** (2 araç) - `agent_run_steps`, tek bir MCP round trip'inde {tool, args, continue_on_error?, wait_ms?} adımlarından oluşan bir batch dizisini çalıştırır. Scriptlenmiş login akışları, form doldurma, çok-adımlı QA yolları için ideal. `agent_query_output`, satır içi dönemeyecek kadar büyük olan önceki bir çağrının tam çıktısını arar; böylece bir takip sorusu pahalı aracı yeniden koşturmak anlamına gelmez.
 
 ## Hızlı Başlangıç
 

package/index.js

@@ -28,8 +28,14 @@ import {
   validateApp,
 } from "./tools/ios-testflight/index.js";
 import { DESIGN_TOOLS, handleDesign } from "./tools/design-check/index.js";
+import { parseLaunchOutput } from "./tools/launch-time/index.js";
 import { interactiveElements } from "./tools/ui-inspect/index.js";
 import { selectCrashReports } from "./tools/crash-logs/index.js";
+import {
+  offloadLargeText,
+  queryOffloadedOutput,
+  offloadedErrorSummary,
+} from "./tools/offload/index.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SCREENSHOT_DIR = join(process.env.TMPDIR || "/tmp", "mobile-dev-mcp");
@@ -47,9 +53,16 @@ const ERROR_PREFIX = "ERROR: ";
 // head of the message.
 const ERROR_MAX_CHARS = 600;
 
+// A long failure is the case where the dropped part matters most: xcodebuild
+// puts the failing assertion and the compiler error at the END of its output, so
+// cutting at ERROR_MAX_CHARS deleted the answer and kept the banner. The full
+// text now goes to disk and the caller gets a head + tail window with the path.
+// Only the fallback - when the write fails - is the old head-only truncation.
 function truncateError(msg) {
   const flat = String(msg).trim();
   if (flat.length <= ERROR_MAX_CHARS) return flat;
+  const { offloaded, path } = offloadLargeText("error", flat, { minChars: ERROR_MAX_CHARS });
+  if (offloaded) return offloadedErrorSummary(flat, path);
   return `${flat.slice(0, ERROR_MAX_CHARS)}\n... [${flat.length - ERROR_MAX_CHARS} more chars truncated]`;
 }
 
@@ -817,7 +830,7 @@ const ANDROID_TOOLS = [
   { name: "android_open_url", description: "Open URL or deep link on Android", inputSchema: { type: "object", properties: { url: { type: "string" }, device_id: { type: "string" } }, required: ["url"] } },
   { name: "android_clear_app_data", description: "Clear all data for Android app", inputSchema: { type: "object", properties: { package_name: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
   { name: "android_accessibility_audit", description: "Audit Android app accessibility: missing contentDescription, small touch targets (<48dp), missing resource-id. Use scope to filter by resource-id prefix.", inputSchema: { type: "object", properties: { device_id: { type: "string" }, scope: { type: "string", description: "Filter: only audit elements whose resource-id contains this prefix (e.g. 'login_', 'com.example:id/login_'). Omit to audit all." } } } },
-  { name: "android_launch_time", description: "Measure Android app cold launch time (TotalTime in ms)", inputSchema: { type: "object", properties: { package_name: { type: "string" }, activity: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
+  { name: "android_launch_time", description: "Measure Android app launch time: force-stops the package, starts it with am start -W, and reports TotalTime/WaitTime in ms plus the platform's own LaunchState (COLD/WARM/HOT). Below Android 10 there is no LaunchState and cold_start is null rather than assumed.", inputSchema: { type: "object", properties: { package_name: { type: "string" }, activity: { type: "string" }, device_id: { type: "string" } }, required: ["package_name"] } },
   { name: "android_apk_audit", description: "Audit APK/AAB for Play Store compliance: debug flag, target SDK, permissions, signing, ProGuard", inputSchema: { type: "object", properties: { apk_path: { type: "string", description: "Path to .apk file" } }, required: ["apk_path"] } },
   { name: "android_list_crashes", description: "Dump the Android crash log buffer (`adb logcat -b crash -d`), tail-bounded. Empty output means no crashes since the buffer was last cleared.", inputSchema: { type: "object", properties: { lines: { type: "number", description: "Max lines returned, from the end (default 200)" }, device_id: { type: "string" } } } },
   { name: "android_set_orientation", description: "Rotate the Android screen to portrait or landscape. Disables accelerometer rotation and pins user_rotation, so the device stays put until rotation is re-enabled. Accounts for the device's natural orientation (detected via wm size), so landscape-natural tablets rotate correctly too. No iOS counterpart: simctl exposes no rotation lever.", inputSchema: { type: "object", properties: { orientation: { type: "string", enum: ["portrait", "landscape"] }, device_id: { type: "string" } }, required: ["orientation"] } },
@@ -1008,9 +1021,19 @@ async function handleAndroid(name, args, ctx = {}) {
       run(`adb ${df} shell am force-stop ${sanitizeId(args.package_name)}`);
       const activity = sanitizeId(args.activity || `${args.package_name}/.MainActivity`);
       const result = run(`adb ${df} shell am start -W -n ${activity} 2>&1`);
-      const totalTime = result.match(/TotalTime:\s*(\d+)/)?.[1];
-      const waitTime = result.match(/WaitTime:\s*(\d+)/)?.[1];
-      return JSON.stringify({ package: args.package_name, cold_start: true, total_time_ms: totalTime ? parseInt(totalTime) : null, wait_time_ms: waitTime ? parseInt(waitTime) : null, raw: result }, null, 2);
+      const parsed = parseLaunchOutput(result);
+      return JSON.stringify({
+        package: args.package_name,
+        // The platform's own verdict, not ours: force-stop kills the process but
+        // leaves the page cache warm, so this is a cold start only sometimes.
+        // null means the device is below Android 10 and never reported one.
+        launch_state: parsed.launchState,
+        cold_start: parsed.coldStart,
+        total_time_ms: parsed.totalTimeMs,
+        wait_time_ms: parsed.waitTimeMs,
+        error: parsed.error,
+        raw: result,
+      }, null, 2);
     }
     case "android_apk_audit": {
       const p = args.apk_path;
@@ -1197,6 +1220,20 @@ const AGENT_TOOLS = [
       required: ["steps"],
     },
   },
+  {
+    name: "agent_query_output",
+    description: "Search the full output of a previous tool call that was too large to return inline. When a tool's payload is offloaded, its text ends with the path of the saved file; this reads that file (the most recent one by default) and returns only the matching lines with context. Use it instead of re-running an expensive tool - re-running a UI dump gives a different tree, so a second call is not the same evidence.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: "JavaScript regular expression, matched per line. Omit to get the file's head." },
+        path: { type: "string", description: "Which offloaded file to read. Defaults to the most recent one this server wrote." },
+        context_lines: { type: "number", description: "Lines of context around each match. Default 2." },
+        max_matches: { type: "number", description: "Stop after this many matches. Default 50." },
+        ignore_case: { type: "boolean", description: "Case-insensitive match. Default false." },
+      },
+    },
+  },
 ];
 
 // design_* is dispatched here too: the tool description offers it, and a design
@@ -1221,6 +1258,7 @@ async function dispatchStep(tool, stepArgs) {
 }
 
 async function handleAgent(name, args) {
+  if (name === "agent_query_output") return queryOffloadedOutput(args, ERROR_PREFIX);
   if (name !== "agent_run_steps") return null;
   const steps = Array.isArray(args.steps) ? args.steps : [];
   const stopOnError = args.stop_on_first_error !== false;
@@ -1341,6 +1379,7 @@ function validateArgs(name, args) {
 // for deciding what may run unattended, so the classification lives here in one
 // auditable place rather than inline on every tool literal.
 const READ_ONLY_TOOLS = new Set([
+  "agent_query_output",
   "ios_list_devices", "ios_screenshot", "ios_list_apps", "ios_get_ui_tree", "ios_get_app_container",
   "ios_accessibility_audit", "ios_archive_audit", "ios_app_store_audit", "ios_xcresult", "ios_visual_diff",
   "ios_list_crashes",
@@ -1700,6 +1739,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     if (isFailure(result)) {
       return { content: [{ type: "text", text: String(result) }], isError: true };
     }
+    // Prose payloads only: a tool with an outputSchema answers with JSON the
+    // caller parses, and a head+tail summary would break that parse. The query
+    // tool is exempt for the obvious reason.
+    if (!OUTPUT_SCHEMAS[name] && name !== "agent_query_output") {
+      const { text, offloaded } = offloadLargeText(name, String(result));
+      if (offloaded) return { content: [{ type: "text", text }] };
+      return withStructured(name, text);
+    }
     return withStructured(name, String(result));
   } catch (e) {
     return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mmerterden/multi-agent-toolkit-mcp",
-  "version": "3.0.0",
-  "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 83 tools: device automation (tap/swipe/type), accessibility audits, visual diff, crash logs, App Store / Play Store pre-submission compliance. Runs standalone over stdio with any MCP client.",
+  "version": "3.1.1",
+  "description": "MCP server for iOS Simulator, Android Emulator and headless web control. 84 tools: device automation (tap/swipe/type), accessibility audits, visual diff, crash logs, App Store / Play Store pre-submission compliance. Runs standalone over stdio with any MCP client.",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "node --test tools/design-check/__tests__/design-check.test.mjs tools/design-check/__tests__/plan-determinism.test.mjs tools/ios-app-store-audit/__tests__/app-store-audit.test.mjs tools/ios-testflight/__tests__/testflight.test.mjs tools/ui-inspect/__tests__/ui-inspect.test.mjs tools/crash-logs/__tests__/crash-logs.test.mjs __tests__/server-tools.test.mjs __tests__/injection.test.mjs",
+    "test": "node --test tools/design-check/__tests__/design-check.test.mjs tools/design-check/__tests__/plan-determinism.test.mjs tools/ios-app-store-audit/__tests__/app-store-audit.test.mjs tools/ios-testflight/__tests__/testflight.test.mjs tools/ui-inspect/__tests__/ui-inspect.test.mjs tools/crash-logs/__tests__/crash-logs.test.mjs tools/launch-time/__tests__/launch-time.test.mjs tools/offload/__tests__/offload.test.mjs __tests__/server-tools.test.mjs __tests__/injection.test.mjs",
     "gates": "bash scripts/gates.sh"
   },
   "keywords": [

package/tools/launch-time/index.js

@@ -0,0 +1,53 @@
+/**
+ * launch-time - parse `am start -W` output.
+ *
+ * Lives here rather than inline in index.js because index.js connects its
+ * transport at import time and cannot be loaded by a test.
+ *
+ * The handler force-stops the package first, which kills the process but leaves
+ * the page cache warm, so it produces a cold start only some of the time. The
+ * tool used to report `cold_start: true` unconditionally, which is an assertion
+ * about something the platform already measures: Android 10 replaced `ThisTime`
+ * with `LaunchState`, one of COLD, WARM, HOT or UNKNOWN, and that is the
+ * system's own verdict on the start it just performed. Below Android 10 there is
+ * no LaunchState line, and the honest answer there is "unknown" rather than a
+ * claim nothing checked.
+ */
+
+const LAUNCH_STATES = new Set(["COLD", "WARM", "HOT", "UNKNOWN"]);
+
+/**
+ * @param {string} raw - stdout+stderr of `am start -W -n <activity>`
+ * @returns {{status: string|null, launchState: string|null, coldStart: boolean|null,
+ *            activity: string|null, totalTimeMs: number|null, waitTimeMs: number|null,
+ *            error: string|null}}
+ */
+export function parseLaunchOutput(raw) {
+  const text = typeof raw === "string" ? raw : "";
+  const field = (name) => text.match(new RegExp(`^\\s*${name}:\\s*(.+?)\\s*$`, "m"))?.[1] ?? null;
+  const intField = (name) => {
+    const v = text.match(new RegExp(`^\\s*${name}:\\s*(\\d+)\\s*$`, "m"))?.[1];
+    return v === undefined ? null : parseInt(v, 10);
+  };
+
+  const rawState = field("LaunchState");
+  const launchState = rawState && LAUNCH_STATES.has(rawState.toUpperCase())
+    ? rawState.toUpperCase()
+    : null;
+
+  // `am start` reports a failure on a line of its own and still exits 0, so a
+  // missing TotalTime with an Error line is a failed launch, not a parse miss.
+  const errorLine = text.match(/^\s*Error:\s*(.+?)\s*$/m)?.[1] ?? null;
+
+  return {
+    status: field("Status"),
+    launchState,
+    // COLD is the only state that is a cold start. Below Android 10 nothing
+    // reports it, so null means "not measured", never "no".
+    coldStart: launchState === null ? null : launchState === "COLD",
+    activity: field("Activity"),
+    totalTimeMs: intField("TotalTime"),
+    waitTimeMs: intField("WaitTime"),
+    error: errorLine,
+  };
+}

package/tools/offload/index.js

@@ -0,0 +1,201 @@
+// Large-result offload.
+//
+// A UI tree, a logcat window or an xcresult dump can be tens of thousands of
+// lines. Returning it whole spends the caller's whole context; truncating it in
+// place - which is what this server used to do, dropping the oldest chunks at
+// SPAWN_OUTPUT_CAP and cutting error text at 600 chars - throws the tail away,
+// and the tail is where the assertion failure and the crash frame live.
+//
+// So: write the payload to a file, return a head + tail window plus the path,
+// and let the caller pull what it needs with agent_query_output. The pipeline
+// already solved the same problem this way in Phase 4 Step 1.9 (diff cap, full
+// diff to `.review-diff.txt`, marker in the prompt); this is that pattern.
+//
+// Only prose payloads are offloaded by the caller. A tool that declares an
+// outputSchema answers with JSON the host parses as structuredContent, and
+// replacing that with a summary would break the parse.
+
+import { writeFileSync, readFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync } from "fs";
+import { join, resolve, sep } from "path";
+import { homedir } from "os";
+
+export const OFFLOAD_DIR = join(homedir(), ".claude", "logs", "multi-agent-toolkit");
+export const OFFLOAD_MIN_CHARS = 24 * 1024;
+const HEAD_LINES = 40;
+const TAIL_LINES = 20;
+
+// Retention lives with the writer, not with an external cleaner. An MCP-only
+// user has no pipeline installed, so "some other tool prunes it" would mean
+// nobody does, and these files are 24 KB and up. Newest-N plus an age cut, both
+// applied after a successful write, cost one readdir.
+export const OFFLOAD_KEEP_FILES = 50;
+export const OFFLOAD_KEEP_DAYS = 7;
+
+// `keep` is the file the caller just wrote. It is never deleted, whatever the
+// retention numbers say: the returned text promises that path to the caller, and
+// this module exists precisely because losing the payload is the failure mode. A
+// keepFiles of 0 must bound the directory, not break the answer.
+export function pruneOffloadDir(dir, opts = {}) {
+  const keepFiles = opts.keepFiles ?? OFFLOAD_KEEP_FILES;
+  const keepDays = opts.keepDays ?? OFFLOAD_KEEP_DAYS;
+  const now = opts.now ?? Date.now();
+  const keep = typeof opts.keep === "string" ? resolve(opts.keep) : null;
+  const cutoff = now - keepDays * 24 * 60 * 60 * 1000;
+  let removed = 0;
+  try {
+    const entries = readdirSync(dir)
+      .filter((n) => n.endsWith(".txt"))
+      .map((n) => {
+        const full = join(dir, n);
+        try {
+          return { full, mtime: statSync(full).mtimeMs };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.mtime - a.mtime);
+
+    for (let i = 0; i < entries.length; i++) {
+      if (keep && resolve(entries[i].full) === keep) continue;
+      const tooOld = entries[i].mtime < cutoff;
+      const tooMany = i >= keepFiles;
+      if (!tooOld && !tooMany) continue;
+      try {
+        unlinkSync(entries[i].full);
+        removed++;
+      } catch {
+        // A file another process holds open is skipped, not fatal.
+      }
+    }
+  } catch {
+    // No directory yet, or an unreadable one: nothing to prune.
+  }
+  return removed;
+}
+
+let lastOffload = null;
+
+export function lastOffloadRecord() {
+  return lastOffload;
+}
+
+export function resetOffloadState() {
+  lastOffload = null;
+}
+
+// Errors arrive as one or two long lines, so the line-based window degenerates:
+// head and tail would both be the whole message. This builds the equivalent
+// window in characters and is used by the failure path.
+export function offloadedErrorSummary(text, path, headChars = 400, tailChars = 250) {
+  if (text.length <= headChars + tailChars) return text;
+  const omitted = text.length - headChars - tailChars;
+  return (
+    `${text.slice(0, headChars)}\n... [${omitted} chars omitted. Full output at ${path} - ` +
+    `read it with agent_query_output {pattern: "..."} ] ...\n${text.slice(-tailChars)}`
+  );
+}
+
+export function offloadLargeText(tool, text, opts = {}) {
+  const dir = opts.dir ?? OFFLOAD_DIR;
+  const minChars = opts.minChars ?? OFFLOAD_MIN_CHARS;
+  const stamp = opts.stamp ?? new Date().toISOString().replace(/[:.]/g, "-");
+  if (text.length < minChars) return { text, offloaded: false };
+
+  let path;
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    path = join(dir, `${tool}-${stamp}.txt`);
+    writeFileSync(path, text);
+  } catch {
+    // A write failure must not lose the payload: fall back to returning it
+    // whole. Spending context is recoverable; dropping the tail is not.
+    return { text, offloaded: false };
+  }
+
+  pruneOffloadDir(dir, { ...opts, keep: path });
+
+  const lines = text.split("\n");
+  lastOffload = { tool, path, lines: lines.length, bytes: text.length };
+  const head = lines.slice(0, HEAD_LINES).join("\n");
+  const tail = lines.slice(-TAIL_LINES).join("\n");
+  const hidden = Math.max(0, lines.length - HEAD_LINES - TAIL_LINES);
+  return {
+    offloaded: true,
+    path,
+    text:
+      `${head}\n\n[... ${hidden} line(s) not shown. Full output (${lines.length} lines, ` +
+      `${text.length} bytes) saved to ${path} - search it with ` +
+      `agent_query_output {pattern: "..."} instead of re-running this tool ...]\n\n${tail}`,
+  };
+}
+
+// A caller-supplied path is confined to the offload directory. The tool's whole
+// purpose is "read back the file this server just wrote", and accepting any
+// absolute path made it an arbitrary-file reader - which contradicts the 2.26.0
+// hardening pass rather than extending it. The path this server itself recorded
+// needs no check: it wrote it.
+function pathAllowed(candidate, allowedDirs) {
+  const target = resolve(candidate);
+  return allowedDirs.some((dir) => {
+    const root = resolve(dir);
+    return target === root || target.startsWith(root + sep);
+  });
+}
+
+// Reads back an offloaded payload. Returns matching lines with context rather
+// than the file, so a 40k-line UI tree answers a question without becoming the
+// answer. A bad regex is reported, never thrown: the caller can fix a pattern
+// but cannot fix a crashed server.
+export function queryOffloadedOutput(args = {}, errorPrefix = "ERROR: ", opts = {}) {
+  const allowedDirs = opts.allowedDirs ?? [OFFLOAD_DIR];
+  const asked = typeof args.path === "string" && args.path ? args.path : null;
+  if (asked && !pathAllowed(asked, allowedDirs)) {
+    return `${errorPrefix}path outside the offload directory is refused: ${asked}. This tool reads only what this server saved under ${allowedDirs.join(", ")}.`;
+  }
+  const path = asked ?? lastOffload?.path;
+  if (!path) {
+    return `${errorPrefix}no offloaded output to search: nothing has been saved in this session, and no path was given`;
+  }
+  if (!existsSync(path)) {
+    return `${errorPrefix}offloaded output not found at ${path}`;
+  }
+  let body;
+  try {
+    body = readFileSync(path, "utf8");
+  } catch (e) {
+    return `${errorPrefix}cannot read ${path}: ${e.message}`;
+  }
+
+  const lines = body.split("\n");
+  const contextLines = Number.isFinite(args.context_lines)
+    ? Math.max(0, Math.trunc(args.context_lines))
+    : 2;
+  const maxMatches = Number.isFinite(args.max_matches) ? Math.max(1, Math.trunc(args.max_matches)) : 50;
+
+  if (typeof args.pattern !== "string" || args.pattern === "") {
+    return `${path} (${lines.length} lines)\n\n${lines.slice(0, 60).join("\n")}`;
+  }
+
+  let re;
+  try {
+    re = new RegExp(args.pattern, args.ignore_case ? "i" : "");
+  } catch (e) {
+    return `${errorPrefix}invalid pattern: ${e.message}`;
+  }
+
+  const blocks = [];
+  let matches = 0;
+  for (let i = 0; i < lines.length && matches < maxMatches; i++) {
+    if (!re.test(lines[i])) continue;
+    matches++;
+    const from = Math.max(0, i - contextLines);
+    const to = Math.min(lines.length - 1, i + contextLines);
+    const chunk = [];
+    for (let j = from; j <= to; j++) chunk.push(`${j + 1}${j === i ? ":" : "-"} ${lines[j]}`);
+    blocks.push(chunk.join("\n"));
+  }
+  if (!matches) return `${path}: no line matches /${args.pattern}/ (${lines.length} lines searched)`;
+  const capped = matches >= maxMatches ? ` (stopped at max_matches=${maxMatches})` : "";
+  return `${path}: ${matches} match(es)${capped}\n\n${blocks.join("\n--\n")}`;
+}