Give stale cursors an actionable message instead of a dead end

A consumed or unknown tool-output cursor previously fell through to
the generic blob-URI branch, so a live blobReader's "Blob not found
for key: tool-output:///<uuid>" error named neither the original file
nor an offset -- the model's only recovery was to recall the path
itself and re-read from scratch, reproducing exactly one instance of
the same-path repeat this mechanism exists to eliminate.

Consumed cursor records now survive (bounded, oldest evicted past 200
entries) instead of being deleted on use. A replay of an already-used
cursor is now distinguished from a genuinely unknown tool-output URI:
it gets a message naming the original source and the exact offset to
resume from, so recovery is one targeted call instead of a blind
re-read of the whole file.

Author: TheGreatAxios

src/plugins/read-file-guard-plugin.test.ts

@@ -331,8 +331,11 @@ describe("readFileGuardPlugin", () => {
     expect(pathsRead.filter((p) => p === "huge.txt").length).toBe(1);
   });
 
-  test("a stale (already-consumed) cursor is rejected rather than silently re-served", async () => {
-    await fixture("stale.txt", Array.from({ length: 10 }, (_, i) => `line-${i}`).join("\n"));
+  test("a stale (already-consumed) cursor names the original path and offset instead of a dead end", async () => {
+    const absolutePath = await fixture(
+      "stale.txt",
+      Array.from({ length: 10 }, (_, i) => `line-${i}`).join("\n"),
+    );
     const plugin = readFileGuardPlugin(dir, {});
     const middleware = plugin.middleware!(fallback);
     const first = await middleware(
@@ -344,13 +347,68 @@ describe("readFileGuardPlugin", () => {
     const cursorPath = (match as RegExpExecArray)[1] as string;
 
     await middleware({ id: "s2", name: "read_file", arguments: { path: cursorPath } }, neverAbort());
-    // Second use of the same, already-consumed cursor: no blob reader is
-    // configured, so it falls through to the direct tool-output-URI path
-    // and reports the honest error rather than fabricating stale content.
+    // Second use of the same, already-consumed cursor: distinct from a
+    // generic missing-blob error, this must name a followable next step —
+    // the original source and the offset to resume from — rather than
+    // leaving the model to re-read the whole file from scratch.
     const replay = await middleware(
       { id: "s3", name: "read_file", arguments: { path: cursorPath } },
       neverAbort(),
     );
     expect(replay.isError).toBe(true);
+    expect(String(replay.content)).toContain("already used");
+    expect(String(replay.content)).toContain(absolutePath);
+    expect(String(replay.content)).toMatch(/offset=4\b/);
+  });
+
+  test("an unknown tool-output URI against a real blobReader gets the production 'blob not found' error, not a stale-cursor message", async () => {
+    const blobReader = {
+      async read(uri: string): Promise<Uint8Array> {
+        throw new Error(`Blob not found for key: ${uri}`);
+      },
+    };
+    const result = await run(
+      { id: "u1", name: "read_file", arguments: { path: "tool-output:///never-minted" } },
+      blobReader,
+    );
+    expect(result.isError).toBe(true);
+    expect(String(result.content)).toContain("Blob not found for key");
+    // Never a cursor's own wording, since this ID was never one of ours.
+    expect(String(result.content)).not.toContain("already used");
+  });
+
+  test("a stale cursor short-circuits before reaching a real blobReader's production 'blob not found' error", async () => {
+    const encoder = new TextEncoder();
+    const body = Array.from({ length: 8_000 }, (_, i) => `row-${i}`).join("\n");
+    const blobReader = {
+      async read(uri: string): Promise<Uint8Array> {
+        if (uri === "tool-output:///spill-1") return encoder.encode(body);
+        throw new Error(`Blob not found for key: ${uri}`);
+      },
+    };
+    const plugin = readFileGuardPlugin(dir, { blobReader });
+    const middleware = plugin.middleware!(fallback);
+
+    const first = await middleware(
+      { id: "b1", name: "read_file", arguments: { path: "tool-output:///spill-1", limit: 5 } },
+      neverAbort(),
+    );
+    const match = /Use path="(tool-output:\/\/\/[^"]+)"/.exec(String(first.content));
+    expect(match).not.toBeNull();
+    const cursorPath = (match as RegExpExecArray)[1] as string;
+
+    await middleware({ id: "b2", name: "read_file", arguments: { path: cursorPath } }, neverAbort());
+    // Replaying the consumed cursor must not fall through to blobReader.read()
+    // (which would throw the opaque "Blob not found" error naming only the
+    // random cursor UUID) -- it must short-circuit to the actionable message
+    // naming the real spill URI and the offset to resume from.
+    const replay = await middleware(
+      { id: "b3", name: "read_file", arguments: { path: cursorPath } },
+      neverAbort(),
+    );
+    expect(replay.isError).toBe(true);
+    expect(String(replay.content)).toContain("already used");
+    expect(String(replay.content)).toContain("tool-output:///spill-1");
+    expect(String(replay.content)).not.toContain("Blob not found");
   });
 });

src/plugins/read-file-guard-plugin.ts

@@ -59,11 +59,27 @@ export interface ReadFileGuardPluginOptions {
 // claims discarded bytes are retrievable; it just remembers where to resume
 // a fresh bounded read.
 type ReadCursor =
-  | { kind: "file"; absolutePath: string; offset: number }
-  | { kind: "blob"; uri: string; offset: number };
+  | { kind: "file"; absolutePath: string; offset: number; consumed: boolean }
+  | { kind: "blob"; uri: string; offset: number; consumed: boolean };
+
+// A cursor is single-use, but the record survives consumption (bounded by
+// MAX_CURSOR_HISTORY below) so a stale replay -- consumed already, or a
+// second process/turn racing the first -- can be told exactly where to
+// resume instead of hitting an opaque "blob not found" dead end that names
+// neither the file nor an offset and leaves re-reading from scratch (the
+// original path, no offset) as the model's only move.
+const MAX_CURSOR_HISTORY = 200;
 
 const CONTINUE_OFFSET_RE = /Use offset=(\d+) to continue\.\]$/;
 
+function pruneCursorHistory(cursors: Map<string, ReadCursor>): void {
+  while (cursors.size > MAX_CURSOR_HISTORY) {
+    const oldest = cursors.keys().next().value;
+    if (oldest === undefined) break;
+    cursors.delete(oldest);
+  }
+}
+
 function mintCursor(
   content: string,
   cursors: Map<string, ReadCursor>,
@@ -76,15 +92,40 @@ function mintCursor(
   cursors.set(
     cursorId,
     source.kind === "file"
-      ? { kind: "file", absolutePath: source.absolutePath, offset }
-      : { kind: "blob", uri: source.uri, offset },
+      ? { kind: "file", absolutePath: source.absolutePath, offset, consumed: false }
+      : { kind: "blob", uri: source.uri, offset, consumed: false },
   );
+  pruneCursorHistory(cursors);
   return content.replace(
     CONTINUE_OFFSET_RE,
     `Use path="${TOOL_OUTPUT_URI_PREFIX}///${cursorId}" (same tool, no offset needed) to continue reading the remainder — a fresh, working handle, not the original path.]`,
   );
 }
 
+// Bound the source shown in a stale-cursor message: an adversarial or
+// pathological path must not blow past a reasonable notice size.
+const STALE_CURSOR_SOURCE_MAX = 300;
+
+function displaySource(source: string): string {
+  return source.length > STALE_CURSOR_SOURCE_MAX
+    ? `${source.slice(0, STALE_CURSOR_SOURCE_MAX)}…`
+    : source;
+}
+
+/**
+ * Message for a cursor that is known but already used (or is being replayed
+ * from a stale/compacted turn). Distinct from "blob not found": it names the
+ * original source and the exact offset to resume from, so recovery is a
+ * single new call rather than a re-read from scratch of the whole file.
+ */
+function staleCursorMessage(cursor: ReadCursor): string {
+  const source = cursor.kind === "file" ? cursor.absolutePath : cursor.uri;
+  return (
+    `this read_file continuation handle was already used (each cursor is single-use). ` +
+    `Resume with read_file, path="${displaySource(source)}", offset=${cursor.offset}.`
+  );
+}
+
 function numArg(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
@@ -365,10 +406,16 @@ export function readFileGuardPlugin(
 
         const cursorId = uri.startsWith(cursorUriPrefix) ? uri.slice(cursorUriPrefix.length) : "";
         const cursor = cursorId.length > 0 ? cursors.get(cursorId) : undefined;
+        if (cursor !== undefined && cursor.consumed) {
+          // Known cursor, already used -- distinct from a genuine missing
+          // blob: name the original source and offset so recovery is one
+          // targeted call, not a from-scratch re-read of the whole file.
+          return { callId: call.id, content: staleCursorMessage(cursor), isError: true };
+        }
         if (cursor !== undefined) {
           // A cursor is authoritative on position: the model passes only the
           // handle (and optionally a limit), never an offset back into it.
-          cursors.delete(cursorId);
+          cursor.consumed = true;
           try {
             signal.throwIfAborted();
             if (cursor.kind === "file") {