mixdog 1.3.1 → 1.3.3

package/src/runtime/agent/orchestrator/tools/code-graph/constants.mjs

@@ -38,12 +38,16 @@ export const CODE_GRAPH_DISK_MEMORY_MAX_BYTES = Math.max(
 // Younger .tmp files may belong to an in-flight persist still holding the sibling .lock;
 // DEFAULT_LOCK_TIMEOUT_MS is 8s — 120s is a safe margin for large graph JSON writes.
 export const ORPHAN_TMP_MIN_AGE_MS = 120_000;
-export const RE_CACHE_TMP = /^\.[0-9a-f]{16}\.json\.[0-9a-f]{24}\.tmp$/i;
-export const RE_MANIFEST_TMP = /^\.manifest\.json\.[0-9a-f]{24}\.tmp$/i;
+// Atomic writer temp name: `<basename>.mixdog-tmp-<16hex>`; the dot-prefixed
+// `.<basename>.<24hex>.tmp` is what older builds left behind.
+export const RE_CACHE_TMP =
+  /^(?:\.[0-9a-f]{16}\.json\.[0-9a-f]{24}\.tmp|[0-9a-f]{16}\.json\.mixdog-tmp-[0-9a-f]{16,24})$/i;
+export const RE_MANIFEST_TMP = /^(?:\.manifest\.json\.[0-9a-f]{24}\.tmp|manifest\.json\.mixdog-tmp-[0-9a-f]{16,24})$/i;
 export const RE_CACHE_LOCK = /^[0-9a-f]{16}\.json\.lock$/i;
 // Same debris, for the `<hash>.calls.json` call-site sidecar written beside
-// each entry (atomic writer temp name: `.<basename>.<24hex>.tmp`).
-export const RE_CALLS_CACHE_TMP = /^\.[0-9a-f]{16}\.calls\.json\.[0-9a-f]{24}\.tmp$/i;
+// each entry.
+export const RE_CALLS_CACHE_TMP =
+  /^(?:\.[0-9a-f]{16}\.calls\.json\.[0-9a-f]{24}\.tmp|[0-9a-f]{16}\.calls\.json\.mixdog-tmp-[0-9a-f]{16,24})$/i;
 export const RE_CALLS_CACHE_LOCK = /^[0-9a-f]{16}\.calls\.json\.lock$/i;
 export const CODE_GRAPH_MEMORY_MAX_ENTRIES = Math.max(
   1,

package/src/runtime/agent/orchestrator/tools/lib/shell-descendants.mjs

@@ -62,9 +62,9 @@ const identityKey = (entry) => `${entry.pid}:${entry.token ?? ''}`;
  *  leave the process group). `observe()` takes one strict table read and
  *  answers 'running', 'gone' or 'unknown':
  *    - the root is alive (same identity)                     → running
- *    - no complete pre-exit capture exists                   → unknown
  *    - a tracked identity, a descendant still linked to one,
  *      or (POSIX) a member of the command's group is alive   → running
+ *    - no complete pre-exit capture exists                   → unknown
  *    - a tracked process without a creation token is present → unknown
  *  A failed table read rejects; callers treat it as unknown. */
 export function createProcessTreeTracker({ pid, members = [], exitObserved = false } = {}) {
@@ -137,9 +137,9 @@ export function createProcessTreeTracker({ pid, members = [], exitObserved = fal
     /** Pre-termination snapshot; call while the root still runs. */
     async capture({ rootExited = false } = {}) {
       if (rootPid <= 0) return false;
-      let table = await readProcessTable({ shared: true });
-      // A shared read may have begun before this root was spawned.
-      if (!table.tokenOf.has(rootPid)) table = await readProcessTable();
+      // Even if an in-flight read saw the root, children may have appeared
+      // since it began. Join the next fresh read before parent links break.
+      const table = await readProcessTable();
       absorb(table, rootIsAlive(table, rootExited));
       return complete;
     },
@@ -159,7 +159,6 @@ export function createProcessTreeTracker({ pid, members = [], exitObserved = fal
         live = [{ pid: rootPid, token: rootToken, name: table.nameOf.get(rootPid) || '' }];
         return 'running';
       }
-      if (!complete) return 'unknown';
       let unknown = false;
       for (const entry of tracked.values()) {
         const state = present(table, entry);
@@ -167,7 +166,9 @@ export function createProcessTreeTracker({ pid, members = [], exitObserved = fal
         else if (state === null) unknown = true;
       }
       if (live.length > 0) return 'running';
-      return unknown ? 'unknown' : 'gone';
+      // Known survivors can still be swept after an incomplete capture, but
+      // their absence cannot prove that an unobserved descendant is gone.
+      return !complete || unknown ? 'unknown' : 'gone';
     },
   };
 }
@@ -196,21 +197,13 @@ function sweepLiveIdentities(tracker) {
  *  `sweep` (a killed tree): a pass that finds captured identities alive
  *  terminates them and observes again in the same pass, so a cancellation
  *  ends with the tree gone instead of a held folder over live processes.
- *
- *  `ownerClosed`: once the owning session has closed and the root has
- *  exited, a tree without a complete pre-kill snapshot is observed after
- *  exit (what is still linked to the root) instead of answering 'unknown'
- *  forever — no one is left to release it, and the close must end in a
- *  definitive state. `onSurvivors(pids)` reports the pids a pass that is
- *  not 'gone' found alive, whenever that set changes, so out-of-process
- *  readers can tell a live hold from a stale one. */
+ *  A missing pre-kill capture stays unknown even if the owning session
+ *  closes: its lifetime is not evidence that every descendant has exited. */
 export function watchTermination({
   tracker,
   rootExited = () => true,
   onTerminated,
   onUnconfirmed = null,
-  onSurvivors = null,
-  ownerClosed = null,
   releaseRequested = null,
   intervalMs = TERMINATION_RECHECK_MS,
   sweep = false,
@@ -218,7 +211,6 @@ export function watchTermination({
   let timer = null;
   let stopped = false;
   let reportedUnconfirmed = false;
-  let survivorKey = null;
   const stop = () => {
     stopped = true;
     if (timer) clearTimeout(timer);
@@ -234,7 +226,6 @@ export function watchTermination({
     if (releaseRequested?.()) state = 'gone';
     else
       try {
-        if (!tracker.complete && rootExited() && ownerClosed?.()) tracker.acceptExitObservation();
         observation = tracker.observe({ rootExited: rootExited() });
         observation.catch(() => {});
         // A pass that has not answered by the next cadence tick is unknown.
@@ -262,18 +253,6 @@ export function watchTermination({
         /* presentation only */
       }
     }
-    if (state !== 'gone' && onSurvivors) {
-      const pids = tracker.live.map((entry) => entry.pid);
-      const key = pids.join(',');
-      if (key !== survivorKey) {
-        survivorKey = key;
-        try {
-          onSurvivors(pids);
-        } catch {
-          /* presentation only */
-        }
-      }
-    }
     if (state === 'gone') {
       try {
         await onTerminated();

package/src/runtime/agent/orchestrator/tools/lib/shell-run-settle.mjs

@@ -8,8 +8,6 @@ import { unregisterOwnedShellTree } from './owned-shell-trees.mjs';
 import {
   adoptShellWorkspaceAdmission,
   clearTerminationHold,
-  isShellOwnerSessionClosed,
-  noteShellJobSurvivors,
   registerTerminationHold,
   takeReleaseRequest,
 } from '../builtin/lib/shell-job-records.mjs';
@@ -28,13 +26,24 @@ import {
 // it follows confirmed termination only (see below).
 const UNCONFIRMED_KILL_CLEANUP_CEILING_MS = 60_000;
 
+/** Settles once a held run's whole tree is confirmed gone (or its hold was
+ *  force-released): what its result left in use defers to this. */
+function treeSettled(run) {
+  if (!run.treeSettled) {
+    run.treeSettled = new Promise((resolve) => {
+      run.resolveTreeSettled = resolve;
+    });
+  }
+  return run.treeSettled;
+}
+
 /** Lifecycle completion of a run whose result is already reported: release
  *  `run.workspaceAdmission` and retire the live record only once the root AND
  *  every descendant identity captured before the kill are confirmed gone. One
  *  observation loop at the termination cadence; running, unknown (incomplete
  *  snapshot, failed table read) and a failing release all re-check, and no
  *  timer ever releases on its own. */
-export function releaseAdmissionOnConfirmedTermination(run, { markNow = true } = {}) {
+export function releaseAdmissionOnConfirmedTermination(run, { markNow = true, sweep = run.killed === true } = {}) {
   const { child } = run;
   if (!child || run.stopTerminationWatch) return;
   // Visible as "termination unconfirmed" until the lifecycle ends, with an
@@ -42,12 +51,14 @@ export function releaseAdmissionOnConfirmedTermination(run, { markNow = true } =
   // kill is marked at once; an owner-cancelled tree whose root is already
   // gone only once its first observation is not 'gone'.
   if (markNow) keepTerminationUnconfirmedRecord(run);
+  treeSettled(run);
   const release = () => {
     run.workspaceAdmission?.();
     run.workspaceAdmission = null;
     run.stopTerminationWatch?.();
     clearTerminationHold(run.foregroundRecordId);
     clearForegroundRecord(run);
+    run.resolveTreeSettled();
   };
   registerTerminationHold(run.foregroundRecordId, {
     ownerSessionId: run.foregroundRecordInput?.ownerSessionId || null,
@@ -59,11 +70,9 @@ export function releaseAdmissionOnConfirmedTermination(run, { markNow = true } =
     tracker: run.terminationTracker,
     rootExited: () => child.exitCode != null || child.signalCode != null,
     // A killed run is not over while processes it started still run.
-    sweep: run.killed === true,
+    sweep,
     onTerminated: release,
     onUnconfirmed: markNow ? null : () => keepTerminationUnconfirmedRecord(run),
-    onSurvivors: (pids) => void noteShellJobSurvivors(run.foregroundRecordId, pids),
-    ownerClosed: () => isShellOwnerSessionClosed(run.foregroundRecordInput?.ownerSessionId),
     releaseRequested: () => takeReleaseRequest(run.foregroundRecordId),
   });
 }
@@ -202,17 +211,19 @@ export function createSettle(run, releasePromotedCapture) {
     // The test compares captured BYTES, not rendered UTF-16 length: a CJK
     // head+tail holds ~1/3 the char count of its byte size and under a
     // length test would delete the very file its own marker names.
+    const dropCapture =
+      !run.killUnconfirmed && taskOutput.spilled && taskOutput.totalDiskBytes() <= SHELL_OUTPUT_INLINE_CAP;
     if (run.killUnconfirmed) {
       // Never confirmed dead: deleting the capture files or handing back the
       // lease now would release resources a live process still owns. The
       // spilled paths therefore survive and travel with the result below, and
       // the workspace admission stays held until termination is confirmed.
       deferCleanupToChildExit(run);
-    } else if (taskOutput.spilled && taskOutput.totalDiskBytes() <= SHELL_OUTPUT_INLINE_CAP) {
-      taskOutput.deleteFiles();
-      void releaseResourceLease(run);
     } else {
-      taskOutput.closeFds();
+      const releaseCapture = () => (dropCapture ? taskOutput.deleteFiles() : taskOutput.closeFds());
+      // A captured descendant of a killed tree may still write the capture.
+      if (confirmKill) void treeSettled(run).then(releaseCapture);
+      else releaseCapture();
       void releaseResourceLease(run);
     }
     let descendants = null;
@@ -256,9 +267,9 @@ export function createSettle(run, releasePromotedCapture) {
         timedOut: run.timedOut,
         killed: run.killed,
         killCause: run.killCause,
-        stdoutPath: taskOutput.spilled ? taskOutput.stdoutPath : null,
+        stdoutPath: taskOutput.spilled && !dropCapture ? taskOutput.stdoutPath : null,
         stdoutFileSize: taskOutput.stdoutFileSize,
-        stderrPath: taskOutput.spilled ? taskOutput.stderrPath : null,
+        stderrPath: taskOutput.spilled && !dropCapture ? taskOutput.stderrPath : null,
         stderrFileSize: taskOutput.stderrFileSize,
         taskId: run.taskId,
         partialOutput: run.partialOutput,
@@ -266,6 +277,7 @@ export function createSettle(run, releasePromotedCapture) {
         failurePhase: run.failurePhase,
         failureReason: run.failureReason,
         descendants,
+        settled: run.treeSettled,
       })
     );
   };

package/src/runtime/agent/orchestrator/tools/lib/shell-run-spawn.mjs

@@ -289,8 +289,9 @@ export async function spawnShellChild(input) {
         if (!detail || !['completed', 'failed', 'cancelled'].includes(detail.nativeStatus)) {
           throw new Error('The child termination could not be confirmed; workspace admission is retained.');
         }
-        input.run.workspaceAdmission?.();
-        input.run.workspaceAdmission = null;
+        // The root is gone, but not necessarily what it started: the
+        // reservation follows the captured tree, swept like any killed one.
+        releaseAdmissionOnConfirmedTermination(input.run, { markNow: false, sweep: true });
       } catch (cleanupError) {
         input.run.killUnconfirmed = true;
         // No settle will ever run for this run; the reservation is released

package/src/runtime/agent/orchestrator/tools/lib/shell-run-state.mjs

@@ -104,8 +104,9 @@ export function createShellRun({ abortSignal, resolve, jobId = null }) {
     // `settled`: whichever transition wins first wins for good.
     autoBackgrounded: false,
     autoBackgroundJobId: null,
-    // [exitCode, signal] of a 'close' that arrived while promotion was in
-    // flight; a promotion that then fails settles the run with it.
+    // [exitCode, signal] of a 'close' (or an expired drain grace) that arrived
+    // while promotion was in flight; a promotion that then fails settles the
+    // run with it.
     promotionClose: null,
     autoBgTimer: null,
     killUnconfirmed: false,
@@ -125,6 +126,9 @@ export function createShellRun({ abortSignal, resolve, jobId = null }) {
     // observation loop that holds the workspace until they are gone.
     terminationTracker: null,
     stopTerminationWatch: null,
+    // Settles when that loop ends (lib/shell-run-settle.mjs treeSettled).
+    treeSettled: null,
+    resolveTreeSettled: null,
   };
 }
 

package/src/runtime/agent/orchestrator/tools/patch/delete-quarantine.mjs

@@ -41,7 +41,8 @@ function quarantinePathFor(fullPath) {
   const dir = dirname(fullPath);
   const name = basename(fullPath).slice(0, 80);
   for (let attempt = 0; attempt < 8; attempt++) {
-    const candidate = join(dir, `.${name}.mixdog-delete-${randomBytes(8).toString('hex')}`);
+    // No leading dot: sync-drive folders (e.g. Naver MYBOX) refuse dot-prefixed names.
+    const candidate = join(dir, `${name}.mixdog-delete-${randomBytes(8).toString('hex')}`);
     try {
       lstatSync(candidate);
     } catch (err) {

package/src/runtime/agent/orchestrator/tools/patch/replay-capture.mjs

@@ -1,7 +1,8 @@
 // Patch replay capture: every apply_patch failure is frozen (args + target
 // file snapshots) for `npm run patch:replay`. Best-effort throughout — a
 // capture problem never changes the tool result.
-import { readdirSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { readdirSync, mkdirSync, rmSync } from 'node:fs';
+import { writeJsonAtomicSync } from '../../../../shared/atomic-file.mjs';
 import { resolve as pathResolve, isAbsolute, join as pathJoin } from 'node:path';
 import {
   createSnapshotBudget,
@@ -203,7 +204,8 @@ export function maybeCapturePatchReplay(capture, errorText) {
         ? { file_snapshot_meta: capture.fileSnapshotMeta }
         : {}),
     };
-    writeFileSync(pathJoin(dir, `${id}.json`), JSON.stringify(record, null, 2), { mode: 0o600 });
+    // Whole-file publication; `patch:replay` skips a record it cannot parse.
+    writeJsonAtomicSync(pathJoin(dir, `${id}.json`), record, { mode: 0o600 });
     // Retention: keep the newest 40 captures. The id prefix is Date.now() in
     // base36 (fixed width until ~2059), so a lexicographic sort is
     // chronological and the oldest records sort first.

package/src/runtime/agent/orchestrator/tools/patch/rollback-state.mjs

@@ -8,7 +8,17 @@
 // { existed: true, content: null, omitted: true, size, mode }. Omitted is not
 // empty content — restore never writes it, and only reports it untouched when
 // the file provably still is.
-import { chmodSync, existsSync, statSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 import { dirname as pathDirname } from 'node:path';
 import {
   createSnapshotBudget,
@@ -83,6 +93,27 @@ function omittedSnapshotIssue(snapshot) {
   return `${what}; the file changed and cannot be restored`;
 }
 
+// Filesystems that refuse fsync answer with one of these; durability is
+// best-effort there and must not fail the restore.
+const FSYNC_TOLERATED = new Set(['EPERM', 'ENOTSUP', 'EINVAL']);
+
+// The restore rewrites a file of the user's project in place: flush it through
+// the handle that wrote it, like the write tool does, so a crash cannot leave
+// the restored file with its size committed and every byte NUL.
+function writeRestoredFile(path, content) {
+  const fd = openSync(path, 'w');
+  try {
+    writeFileSync(fd, content);
+    try {
+      fsyncSync(fd);
+    } catch (err) {
+      if (!FSYNC_TOLERATED.has(err?.code)) throw err;
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
 export function restorePatchRollbackState(snapshots, readStateScope) {
   const errors = [];
   const paths = [];
@@ -96,7 +127,7 @@ export function restorePatchRollbackState(snapshots, readStateScope) {
     try {
       if (snapshot.existed) {
         mkdirSync(pathDirname(snapshot.fullPath), { recursive: true });
-        writeFileSync(snapshot.fullPath, snapshot.content);
+        writeRestoredFile(snapshot.fullPath, snapshot.content);
         if (snapshot.mode != null) chmodSync(snapshot.fullPath, snapshot.mode);
       } else if (existsSync(snapshot.fullPath)) {
         rmSync(snapshot.fullPath, { force: true });

package/src/runtime/agent/orchestrator/tools/patch-manifest.json

@@ -1,30 +1,30 @@
 {
-  "version": "0.7.33",
+  "version": "0.7.34",
   "_comment": "Rewritten by .github/workflows/patch-release.yml on each tagged release. assets maps platformKey (process.platform-process.arch, e.g. win32-x64, linux-x64, darwin-arm64) to { url, sha256 } of the mixdog-patch binary on the GitHub release. A local cargo build under native/mixdog-patch/target/release always takes precedence; otherwise the binary is fetched per this manifest into the data dir (apply is native-only — no JS apply engine).",
   "assets": {
     "darwin-arm64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.33/mixdog-patch-darwin-arm64",
-      "sha256": "c2cb3b4a7e519aa9ddf97537578cf31eae48c371453f46b4501f46b16311c0a5"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.34/mixdog-patch-darwin-arm64",
+      "sha256": "b7e2bd6649ae64801d7f2720fea11fdd8e52ca2fcc21fedb717691cc6f8e6341"
     },
     "darwin-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.33/mixdog-patch-darwin-x64",
-      "sha256": "a4a138765dfc76b39fa3ea20638c0526eb857a19f6d8ea59b0e02f3f552bbaf8"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.34/mixdog-patch-darwin-x64",
+      "sha256": "d0d11eda8b65ee34a3b510eb9f3a57970e977076cd9c8854bf336ec62e3f6d23"
     },
     "linux-arm64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.33/mixdog-patch-linux-arm64",
-      "sha256": "8ba081125ab7658a3353ced9dd487d393dc8b252ac98636da3b8745724798e68"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.34/mixdog-patch-linux-arm64",
+      "sha256": "cb3a530dd68e18edef1cc01025ee89c1b4296f847b76a8f6ea8110710b66912e"
     },
     "linux-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.33/mixdog-patch-linux-x64",
-      "sha256": "bec7bdfc1129d5e99d15c7bc961a2b865868a68e0163a65b506be2aa70ad0bff"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.34/mixdog-patch-linux-x64",
+      "sha256": "4743bb6b23db574f282df0a2744ca4b5b2a7e5049533cf00bc26b93ce235231c"
     },
     "win32-arm64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.33/mixdog-patch-win32-arm64.exe",
-      "sha256": "85374d85f5e966f9ba82f52ed58c799339d591a1afa32a4902ae0c8715506cb5"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.34/mixdog-patch-win32-arm64.exe",
+      "sha256": "626496b0a2f804f769c20f8d1f6d35d9caab89b8ddb38c5e320ba1d146bf84f6"
     },
     "win32-x64": {
-      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.33/mixdog-patch-win32-x64.exe",
-      "sha256": "b0826bb2e7462d072fdc2250fc42662d7da80589d0589a4c4781decc1fd5f008"
+      "url": "https://github.com/tribgames/mixdog/releases/download/patch-v0.7.34/mixdog-patch-win32-x64.exe",
+      "sha256": "03c73fe9895dad6684060e7b0155bb41a8dc96ad75c49c9c9b550cbec27afd1d"
     }
   }
 }

package/src/runtime/agent/orchestrator/tools/shell-command.mjs

@@ -421,15 +421,17 @@ function attachChildExit(run, releasePromotedCapture) {
   child.once('exit', (code, signal) => {
     if (!run.rootExitAtMs) run.rootExitAtMs = Date.now();
     const grace = setTimeout(() => {
-      if (run.settled) return;
+      if (run.settled || run.promotionClose) return;
+      run.partialOutput = true;
       if (run.autoBackgrounded) {
         // A promoted child whose 'close' never arrives (grandchild holding
         // the stdio) would otherwise keep its spill descriptors forever:
-        // 'exit' is the only terminal event this path gets.
+        // 'exit' is the only terminal event this path gets. A promotion that
+        // is still pending and then fails settles the run with it.
+        run.promotionClose = [code == null ? 1 : code, signal];
         releasePromotedCapture();
         return;
       }
-      run.partialOutput = true;
       run.settle(code == null ? 1 : code, signal);
     }, 3000);
     if (grace.unref) grace.unref();

package/src/runtime/agent/orchestrator/tools/shell-exec-output.mjs

@@ -637,7 +637,9 @@ export class ExecResult {
     this.backgrounded = opts.backgrounded === true;
     this.jobId = opts.jobId || null;
     // A command queued behind a saturated shell lane is no shell job; this
-    // promise settles when the queued run finishes.
+    // promise settles when the queued run finishes. A foreground result
+    // reported while its tree may still run (a kill, unverified descendants)
+    // carries the promise that settles once that tree is gone.
     this.settled = opts.settled || null;
     this.backgroundMessage = opts.backgroundMessage || null;
     // Survivors observed AFTER the shell process exited (process group on

package/src/runtime/attachments/attachment-reference.mjs

@@ -0,0 +1,155 @@
+/**
+ * Attachments sent by reference instead of inline.
+ *
+ * A PDF or image the user attached already lives in the content-addressed
+ * store on this machine. When inlining it would crowd the context window, the
+ * message carries a short text part instead: the file's name, size, page count
+ * and text-layer status, and the path the model reads it from — so the model
+ * pulls in only the pages the request needs (read with `pages`). The part keeps
+ * the attachment's `attachmentRef` (nested, so it is not itself a stored-text
+ * reference) and the store's census keeps the bytes as long as the message
+ * names them.
+ */
+import { inlineFileKind } from '../shared/inline-file-kind.mjs';
+import { attachmentFilePath, isAttachmentReference, storeInlineDocumentPart, storeInlineImagePart } from './store.mjs';
+
+/** Up to this many pages per read call; the read tool enforces the same cap. */
+export const READ_PDF_MAX_PAGES_PER_CALL = 20;
+
+function sizeLabel(bytes) {
+  const value = Number(bytes) || 0;
+  if (value >= 1024 * 1024) return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+  if (value >= 1024) return `${Math.max(1, Math.round(value / 1024))} KB`;
+  return `${value} bytes`;
+}
+
+function quotedName(name, fallback) {
+  const base = String(name || '')
+    .split(/[\\/]/)
+    .pop()
+    .replace(/["\r\n]/g, '')
+    .trim();
+  return `"${base || fallback}"`;
+}
+
+/** How much of a PDF reads as text, in words the model can act on. */
+export function textLayerLabel(pageCount, textPages) {
+  const pages = Number(pageCount);
+  const withText = Number(textPages);
+  if (!(pages > 0) || !Number.isFinite(withText) || withText < 0) return 'text layer not checked';
+  if (withText === 0) return 'no text layer (scanned pages)';
+  if (withText >= pages) return 'text layer on every page';
+  return `text layer on ${withText} of ${pages} pages; the rest are scanned`;
+}
+
+function pdfReferenceText(info, path) {
+  const plural = info.pageCount === 1 ? '' : 's';
+  const pages = info.pageCount > 0 ? `${info.pageCount} page${plural}, ` : '';
+  return [
+    `[Attachment kept on disk, not inlined: ${quotedName(info.filename, 'document.pdf')} ` +
+      `(PDF, ${pages}${textLayerLabel(info.pageCount, info.textPages)}, ${sizeLabel(info.sizeBytes)})`,
+    `Path: ${path}`,
+    `Read only what the request needs: read this path with pages, e.g. pages="1-5" (up to ` +
+      `${READ_PDF_MAX_PAGES_PER_CALL} pages per call). Pages with a text layer come back as text; ` +
+      'scanned pages come back as page images, or as OCR text when the model is text-only.]',
+  ].join('\n');
+}
+
+function imageReferenceText(info, path) {
+  return [
+    `[Image kept on disk, not inlined: ${quotedName(info.filename, 'image')} ` +
+      `(${info.mimeType || 'image'}, ${sizeLabel(info.sizeBytes)})`,
+    `Path: ${path}`,
+    'View it with read on this path when the request needs it.]',
+  ].join('\n');
+}
+
+// The stored form of a media part that can travel by reference, or null. An
+// inline payload is written to the store first so it gets a path too.
+function storedMediaPart(part) {
+  if (!part || typeof part !== 'object') return null;
+  if (part.type === 'image') {
+    if (isAttachmentReference(part)) return part;
+    return storeInlineImagePart(part);
+  }
+  if (part.type === 'file' || part.type === 'document') {
+    const stored = isAttachmentReference(part) ? part : storeInlineDocumentPart(part);
+    if (!stored) return null;
+    const mimeType = String(stored.mimeType || stored.mediaType || '');
+    return inlineFileKind(mimeType, '') === 'pdf' ? stored : null;
+  }
+  return null;
+}
+
+/** Whether `part` is a media part this module can turn into a reference. */
+export function isReferencableMediaPart(part) {
+  if (!part || typeof part !== 'object') return false;
+  if (part.type === 'image') {
+    return isAttachmentReference(part) || typeof part.data === 'string' || part.source?.type === 'base64';
+  }
+  if (part.type === 'document') return part.source?.type === 'base64';
+  if (part.type !== 'file') return false;
+  const mimeType = String(part.mimeType || part.mediaType || 'application/pdf');
+  return inlineFileKind(mimeType, isAttachmentReference(part) ? '' : part.data || '', part.filename) === 'pdf';
+}
+
+/** Whether `part` is a reference this module produced. */
+export function isMediaReferencePart(part) {
+  return Boolean(part && part.type === 'text' && part.attachmentReference && typeof part.text === 'string');
+}
+
+/**
+ * The reference text part standing for one media part, or null when the part
+ * cannot travel by reference (a URL image, a non-PDF file, a store failure).
+ */
+export function mediaPartToReference(part) {
+  let stored;
+  try {
+    stored = storedMediaPart(part);
+  } catch {
+    return null;
+  }
+  if (!stored) return null;
+  const kind = stored.type === 'image' ? 'image' : 'pdf';
+  const pageCount = Math.floor(Number(part.pageCount ?? stored.pageCount)) || 0;
+  const textPagesRaw = part.textPages ?? stored.textPages;
+  const info = {
+    attachmentRef: stored.attachmentRef,
+    kind,
+    filename: String(part.filename || part.title || part.name || stored.filename || ''),
+    mimeType: String(stored.mimeType || stored.mediaType || (kind === 'pdf' ? 'application/pdf' : 'image/png')),
+    sizeBytes: Number(stored.sizeBytes) || 0,
+    ...(pageCount > 0 ? { pageCount } : {}),
+    ...(Number.isFinite(Number(textPagesRaw)) && textPagesRaw !== null ? { textPages: Number(textPagesRaw) } : {}),
+  };
+  const path = attachmentFilePath(info.attachmentRef);
+  return {
+    type: 'text',
+    text: kind === 'pdf' ? pdfReferenceText(info, path) : imageReferenceText(info, path),
+    attachmentReference: info,
+  };
+}
+
+/**
+ * A user `message` with every referencable media part of its own content
+ * replaced by its reference text (other roles, tool results and nested content
+ * stay as they are).
+ * Returns the same message when nothing changed.
+ */
+export function referenceMessageMedia(message) {
+  if (message?.role !== 'user' || !Array.isArray(message.content)) return message;
+  let changed = false;
+  const content = message.content.map((part) => {
+    if (!isReferencableMediaPart(part)) return part;
+    const reference = mediaPartToReference(part);
+    if (!reference) return part;
+    changed = true;
+    return reference;
+  });
+  return changed ? { ...message, content } : message;
+}
+
+/** Whether the message's own content still carries referencable media. */
+export function messageHasReferencableMedia(message) {
+  return Array.isArray(message?.content) && message.content.some(isReferencableMediaPart);
+}