@animalabs/agent-framework 0.13.0 → 0.15.0

package/dist/src/framework.js

@@ -25,6 +25,7 @@ import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import { toolResultDataToHistoryString, truncateForHistory, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS, } from './tool-result-history.js';
+import { TOOL_IMAGE_REF_RE, ToolImageLedger, formatPreservedImageSlots, parseImagePlaceholders, sha256Hex, splitPreservingImageSlots, } from './tool-image-ledger.js';
 import { randomUUID } from 'node:crypto';
 import { PyRunner, buildInjectedTools } from './code-execution/py-runner.js';
 import { buildCodeExecutionToolDefinition, CODE_EXECUTION_TOOL_NAME, } from './code-execution/tool-definition.js';
@@ -673,6 +674,11 @@ export class AgentFramework {
      *  framework state like the core runtime settings and restored at create
      *  (antra + Sol, 08-06); reset clears it back to the residence default. */
     toolResultInlineMaxCharsOverride = new Map();
+    /** Per-agent retention of tool-result images with provenance (issue
+     *  #104). In-memory and bounded by design: history keeps only the
+     *  placeholder; this is what lets `save_recent_image` reach the bytes the
+     *  resident actually saw — or fail at that exact index when they're gone. */
+    toolImageLedgers = new Map();
     /** Durable residence-configured inline cap from
      *  FrameworkConfig.toolResultInlineMaxChars; null → house default. */
     toolResultInlineMaxCharsConfig = null;
@@ -885,8 +891,17 @@ export class AgentFramework {
                 privilegedUsersPath: config.gate.privilegedUsersPath,
                 emitTrace: (e) => framework.emitTrace(e),
                 addMessage: (p, c, m, forAgent) => framework.addMessage(p, c, m, forAgent ? { forAgent } : undefined),
-                requestInference: (agentName, reason, source) => {
-                    framework.pendingRequests.push({ agentName, reason, source, timestamp: Date.now() });
+                requestInference: (agentName, reason, source, provenance) => {
+                    framework.pendingRequests.push({
+                        agentName, reason, source, timestamp: Date.now(),
+                        // gate-requested wakes carry where/who (EventGate wakeProvenance)
+                        // as TELEMETRY fields — the host's stamp reads them; the turn's
+                        // speech locus (channelId / addressed) is deliberately NOT set
+                        // here, so a batched wake routes exactly as it did before.
+                        ...(provenance?.channelId ? { wakeChannelId: provenance.channelId } : {}),
+                        ...(provenance?.counterparty ? { counterparty: provenance.counterparty } : {}),
+                        ...(provenance?.at ? { wakeAt: provenance.at } : {}),
+                    });
                 },
                 getAgentNames: () => [...framework.agents.keys()].filter((n) => n !== framework.subconsciousAgentName),
             });
@@ -1046,6 +1061,9 @@ export class AgentFramework {
             record.runner.dispose();
         }
         this.backgroundScripts.clear();
+        // Retained tool images are per-process by design; a retained stopped
+        // framework must not keep up to the whole ledger budget referenced.
+        this.toolImageLedgers.clear();
         // A stopped host must never hang behind its own cooldown.
         this.cancelProviderAdmission();
         // Cancel all active streams
@@ -2248,6 +2266,7 @@ export class AgentFramework {
                 this.eventGate?.onInferenceEnded(agent.name);
                 this.agents.delete(agent.name);
             }
+            this.toolImageLedgers.delete(agent.name);
             // Spawn-and-dispose bookkeeping (main, d453165/fee96a7): without this,
             // ephemeral agents leave checkpoint-tree keys and diagnostics map
             // entries behind for the life of the store/session.
@@ -2490,11 +2509,18 @@ export class AgentFramework {
     static SAVE_IMAGE_TOOL = {
         name: 'save_recent_image',
         description: 'Save one or more recent images from your own context to workspace files. ' +
-            'Images are counted back from the most recent (index 0). A single image is ' +
+            'Images are counted back from the most recent (index 0), across BOTH ' +
+            'attachments in messages and images returned by tools (their history ' +
+            'placeholder shows a ref like `[image: image/png, ~691KB, ref img_k7x3q2_7]`; pass ' +
+            '`ref` to save that exact image regardless of position). A single image is ' +
             'written to `path` as given (e.g. "project/photos/cat.png"); when `count` > 1 ' +
             'the range index..index+count-1 is saved with numeric suffixes ' +
-            '("cat-0.png", "cat-1.png", …; 0 = the newest of the range). Saved files are ' +
-            'visible via workspace tools and the /files/ endpoint.',
+            '("cat-0.png", "cat-1.png", …; 0 = the newest of the range). If the image at ' +
+            'the requested position is no longer retained (evicted, or from before a ' +
+            'restart) the call fails and writes nothing — it never substitutes an older ' +
+            'image. When other tool calls in the same batch are still running, the save ' +
+            'waits for them so their images are counted. Receipts carry source tool call, MIME, byte size and SHA-256. Saved ' +
+            'files are visible via workspace tools and the /files/ endpoint.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -2510,6 +2536,11 @@ export class AgentFramework {
                     type: 'number',
                     description: 'How many images to save, starting at `index` and going further back. Default 1.',
                 },
+                ref: {
+                    type: 'string',
+                    description: 'Save a specific tool-result image by its history ref (e.g. "img_k7x3q2_7", as shown in its placeholder in your context) instead of by position. ' +
+                        'Mutually exclusive with `index`/`count`.',
+                },
             },
             required: ['path'],
         },
@@ -3745,7 +3776,7 @@ export class AgentFramework {
                     // history copy and the live wire copy below — the two must stay
                     // byte-matched (the window stores what the membrane sends;
                     // divergence breaks the compile prefix).
-                    const { blocks: toolResultContent, spilled } = await this.buildStoredToolResultContent(currentState.toolResults, maxChars);
+                    const { blocks: toolResultContent, spilled } = await this.buildStoredToolResultContent(agent.name, currentState.toolResults, maxChars);
                     agent.getContextManager().addMessage('user', toolResultContent);
                     // Flush any messages that were deferred while this turn was in
                     // flight. Route to the PRIMARY agent — deferred messages are
@@ -4342,6 +4373,7 @@ export class AgentFramework {
         const channelId = this.conversationAgentHomes.get(agentName);
         const agent = this.agents.get(agentName);
         this.agents.delete(agentName);
+        this.toolImageLedgers.delete(agentName);
         this.agentConfigs.delete(agentName);
         this.conversationAgentHomes.delete(agentName);
         this.evictTurnCheckpoints(agentName);
@@ -4772,6 +4804,19 @@ export class AgentFramework {
                     addressedReq = r;
             }
             const channelReq = addressedReq ?? ambientReq;
+            // Telemetry provenance (who/where woke the agent): from the routing
+            // winner when it carries one; else from the most recent request that
+            // does (gate wakes name a counterparty without setting a locus),
+            // ordered by the event's own time (wakeAt) rather than flush order.
+            let provReq = channelReq?.counterparty || channelReq?.wakeChannelId ? channelReq : undefined;
+            if (!provReq) {
+                for (const r of requests) {
+                    if (!r.counterparty && !r.wakeChannelId)
+                        continue;
+                    if (!provReq || (r.wakeAt ?? r.timestamp) >= (provReq.wakeAt ?? provReq.timestamp))
+                        provReq = r;
+                }
+            }
             await this.startAgentStream(agent, {
                 ...trigger,
                 channelId: channelReq?.channelId,
@@ -4780,7 +4825,9 @@ export class AgentFramework {
                 // the channel for routing but names no author — the restart is its
                 // own cause, and borrowing another request's author would be false
                 // provenance.
-                counterparty: budgetRestart ? undefined : channelReq?.counterparty,
+                counterparty: budgetRestart ? undefined : provReq?.counterparty,
+                wakeChannelId: budgetRestart ? undefined : provReq?.wakeChannelId,
+                wakeAt: budgetRestart ? undefined : provReq?.wakeAt,
             });
         }
     }
@@ -5218,6 +5265,23 @@ export class AgentFramework {
                         this.releasePrimaryProviderGate(agent.name);
                         return;
                     }
+                    // The scheduler's turn-alive test passed BEFORE the park; the wait
+                    // is the one gap in which another turn-alive holder can take the
+                    // agent (puppetToolCall's reservation, #145). Never replace its
+                    // token — the re-entry would set ours over it, and a short turn
+                    // here ends and flushes before the puppeted tool returns, leaving
+                    // its pair queued behind a flush that already happened. Give
+                    // admission back and hand the wake to the scheduler, which keeps
+                    // it queued while the agent is turn-alive and starts it normally
+                    // once the holder releases.
+                    if (this.activeTurnTokens.has(agent.name)) {
+                        this.releasePrimaryProviderGate(agent.name);
+                        this.pendingRequests.push(trigger ?? {
+                            agentName: agent.name, reason: 'provider-admission:requeue', source: 'scheduler', timestamp: Date.now(),
+                        });
+                        console.error(`[provider-admission] ${agent.name}: turn-alive while parked — wake requeued, not started`);
+                        return;
+                    }
                     await this.startAgentStream(agent, trigger, attempt, true);
                 }).catch((error) => {
                     this.releasePrimaryProviderGate(agent.name);
@@ -5918,7 +5982,7 @@ export class AgentFramework {
                             // one door a giant blob still walks through).
                             const readyState = agent.state;
                             if (readyState.status === 'ready') {
-                                const { blocks: toolResultContent } = await this.buildStoredToolResultContent(readyState.toolResults, this.resolveToolResultInlineCap(agent).cap);
+                                const { blocks: toolResultContent } = await this.buildStoredToolResultContent(agent.name, readyState.toolResults, this.resolveToolResultInlineCap(agent).cap);
                                 agent.getContextManager().addMessage('user', toolResultContent);
                             }
                         }
@@ -6724,8 +6788,11 @@ export class AgentFramework {
      * affordance to a model that cannot find it (older models especially).
      *
      * Semantics:
-     * - Refused unless the agent is idle: puppeting mid-turn would corrupt
-     *   the turn state machine and the live stream's wire ordering.
+     * - Refused unless the agent is idle with no turn alive: puppeting
+     *   mid-turn would corrupt the turn state machine and the live stream's
+     *   wire ordering. For its own duration the puppet HOLDS the turn-alive
+     *   marker (wakes requeue, cross-turn writers defer), so a wake landing
+     *   during the tool's execution cannot start a turn underneath the pair.
      * - Refused for tools outside the agent's own surface (canUseTool): the
      *   stored pair must be an act the agent could genuinely have taken.
      * - The call executes FOR REAL through the shared dispatch (MCPL,
@@ -6746,8 +6813,12 @@ export class AgentFramework {
         const agent = this.agents.get(agentName);
         if (!agent)
             throw new Error(`Unknown agent: ${agentName}`);
-        if (agent.state.status !== 'idle') {
-            throw new Error(`puppet refused: agent ${agentName} is ${agent.state.status} (requires idle — ` +
+        // Idle AND no turn alive: status reads 'idle' from dequeue until the
+        // stream registers, and again while a turn's teardown is pending
+        // (the scheduler's own busy test, 'idle+turn-alive').
+        if (agent.state.status !== 'idle' || this.activeTurnTokens.has(agentName)) {
+            const shown = agent.state.status === 'idle' ? 'idle+turn-alive' : agent.state.status;
+            throw new Error(`puppet refused: agent ${agentName} is ${shown} (requires idle — ` +
                 `injecting a turn under an active stream corrupts wire ordering)`);
         }
         const onSurface = this.getToolsForAgent(agentName)
@@ -6763,36 +6834,85 @@ export class AgentFramework {
         for (let i = 0; i < 22; i++)
             suffix += alphabet[Math.floor(Math.random() * alphabet.length)];
         const toolUseId = `toolu_01${suffix}`;
-        const started = Date.now();
-        const result = await this.executeToolCall({
-            id: toolUseId,
-            name: toolName,
-            input,
-            callerAgentName: agentName,
-        });
-        const durationMs = Date.now() - started;
-        // Store the pair through the same shapes the ordinary path uses. Build
-        // the result blocks BEFORE storing the tool_use: the spill path awaits,
-        // and a message arriving during that await must land before the pair,
-        // never between tool_use and its tool_result. The two addMessage calls
-        // below are synchronous and adjacent — nothing can interleave.
-        const { blocks } = await this.buildStoredToolResultContent([{ id: toolUseId, name: toolName, input, result, durationMs }], this.resolveToolResultInlineCap(agent).cap);
-        const cm = agent.getContextManager();
-        cm.addMessage(agentName, [
-            { type: 'tool_use', id: toolUseId, name: toolName, input },
-        ]);
-        cm.addMessage('user', blocks);
-        this.emitTrace({
-            type: 'puppet:tool-call',
-            agentName,
-            toolName,
-            toolUseId,
-            isError: !!result.isError,
-            durationMs,
-        });
-        console.log(`[puppet] ${agentName}: ${toolName} → ${result.isError ? 'ERROR' : 'ok'} ` +
-            `in ${durationMs}ms (${toolUseId})`);
-        return { toolUseId, result };
+        // Reserve the agent against turn start for the WHOLE operation, before
+        // the first await (#145). The idle check above is a point in time; the
+        // tool execution and the result build both await, and a wake arriving
+        // in either gap used to start a real turn — then the pair below wrote
+        // straight through the context manager into a turn that never saw it,
+        // the exact wire-order corruption this method exists to avoid. Holding
+        // a turn token is the same invariant the scheduler respects (turn-alive
+        // requeues wakes) and the addMessage guard reads (cross-turn writers
+        // defer), so for the duration this behaves like a turn with no stream.
+        // Token-matched release in finally, same leak-proofing as
+        // startAgentStream: a token nobody clears wedges the agent.
+        const turnToken = this.nextTurnToken++;
+        this.activeTurnTokens.set(agentName, turnToken);
+        let ownedToEnd = false;
+        try {
+            const started = Date.now();
+            const result = await this.executeToolCall({
+                id: toolUseId,
+                name: toolName,
+                input,
+                callerAgentName: agentName,
+            });
+            const durationMs = Date.now() - started;
+            // Store the pair through the same shapes the ordinary path uses. Build
+            // the result blocks BEFORE storing the tool_use: the spill path awaits.
+            // A message arriving during either await is deferred by the turn
+            // token (as during a real tool call) and lands AFTER the pair, never
+            // between tool_use and its tool_result. The two addMessage calls
+            // below are synchronous and adjacent — nothing can interleave.
+            const { blocks } = await this.buildStoredToolResultContent(agentName, [{ id: toolUseId, name: toolName, input, result, durationMs }], this.resolveToolResultInlineCap(agent).cap);
+            const toolUse = [
+                { type: 'tool_use', id: toolUseId, name: toolName, input },
+            ];
+            // Defensive: no path replaces a live token any more (the provider-
+            // admission re-entry re-tests turn-alive and requeues instead), but
+            // if one ever does, the side effect has happened and the pair must
+            // still be stored — not under that turn: queue it as a unit for the
+            // next flush (drainDeferredFor keeps order; the tool_result entry is
+            // never split from its tool_use because both ride the same drain).
+            // The finally below flushes it itself if that turn is already over.
+            ownedToEnd = this.activeTurnTokens.get(agentName) === turnToken;
+            if (ownedToEnd) {
+                const cm = agent.getContextManager();
+                cm.addMessage(agentName, toolUse);
+                cm.addMessage('user', blocks);
+            }
+            else {
+                this.deferredMessages.push({ participant: agentName, content: toolUse, forAgent: agentName }, { participant: 'user', content: blocks, forAgent: agentName });
+            }
+            this.emitTrace({
+                type: 'puppet:tool-call',
+                agentName,
+                toolName,
+                toolUseId,
+                isError: !!result.isError,
+                durationMs,
+                ...(ownedToEnd ? {} : { deferred: true }),
+            });
+            console.log(`[puppet] ${agentName}: ${toolName} → ${result.isError ? 'ERROR' : 'ok'} ` +
+                `in ${durationMs}ms (${toolUseId})${ownedToEnd ? '' : ' — deferred behind a live turn'}`);
+            return { toolUseId, result };
+        }
+        finally {
+            if (this.activeTurnTokens.get(agentName) === turnToken)
+                this.activeTurnTokens.delete(agentName);
+            // Messages deferred while we held the token land now, after the pair
+            // — the same end-of-turn flush driveStream performs, under the same
+            // tool-cycle guard. (No wake is requested: the agent sees the pair,
+            // and anything that arrived meanwhile, on its next turn.) Keyed on
+            // "no turn alive", not on token ownership: if a turn did replace us
+            // and has already ended, its flush ran before our pair was queued —
+            // nobody else will flush it, so we do.
+            if (!this.activeTurnTokens.has(agentName)
+                && this.deferredMessages.length > 0 && this.pendingAssistantBlocks.size === 0) {
+                for (const msg of this.drainDeferredFor(agentName)) {
+                    this.addMessage(msg.participant, msg.content, msg.metadata, msg.forAgent ? { forAgent: msg.forAgent } : undefined);
+                }
+            }
+        }
     }
     async executeToolCallFrom(call, origin) {
         // Client-side programmatic tool calling for promise-based callers
@@ -7224,13 +7344,25 @@ export class AgentFramework {
      * #89). Returns the stored blocks plus the per-call spill outcomes so the
      * live wire copy can reuse the identical strings.
      */
-    async buildStoredToolResultContent(toolResults, maxChars) {
+    async buildStoredToolResultContent(agentName, toolResults, maxChars) {
         const spilled = new Map();
         const dateLabel = new Date().toISOString().slice(0, 10);
+        const ledger = this.toolImageLedgerFor(agentName);
         for (const tc of toolResults) {
+            // Retain every image the result carries BEFORE the placeholder is
+            // written (issue #104): the placeholder embeds the ref, so the image
+            // stays reachable by provenance after the bytes leave the wire.
             const raw = tc.result.isError
                 ? tc.result.error ?? 'Unknown error'
-                : toolResultDataToHistoryString(tc.result.data, undefined);
+                : toolResultDataToHistoryString(tc.result.data, undefined, {
+                    imageRef: (blockIndex, image) => ledger.retain({
+                        toolCallId: tc.id,
+                        toolName: tc.name,
+                        blockIndex,
+                        data: image.data,
+                        mediaType: image.mimeType,
+                    }).ref,
+                });
             spilled.set(tc.id, await this.spillOrTruncate(raw, maxChars, `${dateLabel}-${tc.id}`));
         }
         const blocks = toolResults.map(tc => ({
@@ -7247,6 +7379,13 @@ export class AgentFramework {
     async spillOrTruncate(content, cap, label) {
         if (!cap || content.length <= cap)
             return { text: content, filePath: null };
+        // The stored text is the only place save_recent_image discovers tool
+        // images, and the live wire delivers every image regardless of text
+        // length — so an image slot dropped by the cut is an image the resident
+        // saw that the index would silently slide past (issue #104). Keep the
+        // slots at or past the cut, re-appended after the notice.
+        const { head, tail } = splitPreservingImageSlots(content, cap);
+        const kept = formatPreservedImageSlots(tail);
         const workspace = this.getWorkspaceModule();
         const mountName = workspace ? this.firstWritableMountName(workspace) : null;
         if (workspace && mountName) {
@@ -7256,11 +7395,18 @@ export class AgentFramework {
             try {
                 const result = await workspace.writeBinary(path, Buffer.from(content, 'utf8'), 'text/plain');
                 if (result.success) {
+                    // JSON serialization can expand each read-back code unit to six
+                    // chars (\\u0000). Leave room for the page's metadata and a possible
+                    // extra code unit at a surrogate-pair boundary.
+                    const pageOverhead = JSON.stringify(path).length + 256;
+                    const readLimit = Math.max(1, Math.min(2000, Math.floor((cap - pageOverhead) / 6) - 1));
                     return {
-                        text: safeSlice(content, 0, cap)
-                            + `\n\n[truncated — showing ${cap} of ${content.length} chars; full content: workspace file ${path}. `
-                            + 'Read/grep it with your file tools, or raise the inline cap via '
-                            + 'agent_settings update tool_result_inline_max_chars.]',
+                        text: head
+                            + `\n\n[truncated — showing ${head.length} of ${content.length} chars; full content: workspace file ${path}`
+                            + `. Page with workspace--read ${JSON.stringify({ path, offsetChars: 0, limitChars: readLimit })}; `
+                            + 'use nextOffsetChars as offsetChars until null, keeping limitChars. Or raise the inline cap via '
+                            + 'agent_settings update tool_result_inline_max_chars.]'
+                            + kept,
                         filePath: path,
                     };
                 }
@@ -7282,15 +7428,17 @@ export class AgentFramework {
             });
             console.error(`[spill] workspace write failed for ${path} (${content.length} chars): ${failure}`);
             return {
-                text: safeSlice(content, 0, cap)
-                    + `\n\n[truncated — showing ${cap} of ${content.length} chars; spill to workspace file ${path} FAILED`
-                    + ` (${failure}); content over the cap was not retained]`,
+                text: head
+                    + `\n\n[truncated — showing ${head.length} of ${content.length} chars; spill to workspace file ${path} FAILED`
+                    + ` (${failure}); content over the cap was not retained]`
+                    + kept,
                 filePath: null,
             };
         }
         return {
-            text: safeSlice(content, 0, cap)
-                + '\n\n[truncated — original was ' + content.length + ' chars; no writable workspace, full content not retained]',
+            text: head
+                + '\n\n[truncated — original was ' + content.length + ' chars; no writable workspace, full content not retained]'
+                + kept,
             filePath: null,
         };
     }
@@ -7493,6 +7641,14 @@ export class AgentFramework {
         }
         return hasImage ? blocks : null;
     }
+    toolImageLedgerFor(agentName) {
+        let ledger = this.toolImageLedgers.get(agentName);
+        if (!ledger) {
+            ledger = new ToolImageLedger();
+            this.toolImageLedgers.set(agentName, ledger);
+        }
+        return ledger;
+    }
     /** Strategy-derived per-message bound (maxMessageTokens * 4 chars). */
     strategyDerivedToolResultChars(agent) {
         const strategy = agent.getContextManager().getStrategy();
@@ -7574,12 +7730,20 @@ export class AgentFramework {
         const entryToStore = { ...entry };
         // Blob threshold: 10KB - typical context-heavy requests exceed this
         const BLOB_THRESHOLD = 10000;
+        // Both branches persist the JSON view, never the live object: a compiled
+        // request carries non-JSON members (the kv-unified `onCacheWireReceipt`
+        // hook is a function) and Chronicle's JSON bridge rejects those with
+        // "JS functions cannot be represented as a serde_json::Value" — which,
+        // thrown from the failure path, masked the failure being logged.
         if (entry.request && typeof entry.request === 'object') {
             const requestJson = JSON.stringify(entry.request);
             if (requestJson.length > BLOB_THRESHOLD) {
                 const blobId = this.store.storeBlob(Buffer.from(requestJson), 'application/json');
                 entryToStore.request = { blobId };
             }
+            else {
+                entryToStore.request = JSON.parse(requestJson);
+            }
         }
         if (entry.response && typeof entry.response === 'object') {
             const responseJson = JSON.stringify(entry.response);
@@ -7587,6 +7751,9 @@ export class AgentFramework {
                 const blobId = this.store.storeBlob(Buffer.from(responseJson), 'application/json');
                 entryToStore.response = { blobId };
             }
+            else {
+                entryToStore.response = JSON.parse(responseJson);
+            }
         }
         // Append one record per inference. A read-modify-write via setStateJson
         // would emit a whole-array Set — record size then grows with accumulated
@@ -10095,10 +10262,53 @@ export class AgentFramework {
         })();
     }
     /**
-     * Handle the synthesized `save_recent_image` tool: locate the requested
-     * image blocks in the calling agent's context (blobs re-inlined, counted
-     * back from the most recent) and write their bytes to a workspace mount
-     * via WorkspaceModule.writeBinary.
+     * `save_recent_image` barrier. Module tool calls in a batch are only
+     * ENQUEUED by dispatch, while the save runs at once — so a [snap, save]
+     * round would inventory before the snapshot exists and silently save the
+     * newest OLDER image (issue #104, same-batch representation). Wait for
+     * every sibling in the round to settle; if one never does, fail closed
+     * rather than trust an index the batch may still change. Sibling saves
+     * produce no images and are not waited on (two saves in one batch would
+     * otherwise deadlock into a double timeout). Script-inner calls
+     * (`pytc-…`) run sequentially inside their script host and skip the
+     * barrier — the host call itself is the only pending sibling they'd see.
+     */
+    async awaitSiblingToolCalls(agent, call) {
+        if (call.id.startsWith('pytc-'))
+            return;
+        const BARRIER_MS = 120_000;
+        const POLL_MS = 20;
+        const startedAt = Date.now();
+        for (;;) {
+            const state = agent.state;
+            // Idle (puppet path) or the round was torn down: nothing to wait on.
+            if (state.status !== 'waiting_for_tools')
+                return;
+            const open = [...state.pending.values()].filter((p) => p.id !== call.id && p.name !== 'save_recent_image');
+            if (open.length === 0)
+                return;
+            if (Date.now() - startedAt > BARRIER_MS) {
+                throw new Error(`save_recent_image: ${open.length} sibling tool call(s) in this batch still pending after ` +
+                    `${Math.round(BARRIER_MS / 1000)}s (${open.map((p) => `${p.name} (call ${p.id})`).join(', ')}) — their results ` +
+                    'may carry newer images than anything in your context, so no index can be trusted yet. Nothing written. ' +
+                    'Save again once they have finished.');
+            }
+            await new Promise((r) => setTimeout(r, POLL_MS));
+        }
+    }
+    /**
+     * Handle the synthesized `save_recent_image` tool (issue #104): build ONE
+     * ordered inventory of every image the calling agent has seen — attachment
+     * image blocks (blobs re-inlined) AND tool-result images (their history
+     * placeholders carry a ref, resolved through the agent's ToolImageLedger)
+     * — counted back from the most recent, then write the requested bytes to
+     * a workspace mount via WorkspaceModule.writeBinary.
+     *
+     * Fail-closed: when the image at a requested position cannot be produced
+     * (bytes evicted, minted by an earlier process, or a placeholder written
+     * before retention existed) the call fails AT THAT INDEX and writes
+     * nothing. It never slides to an older image — a filename must not
+     * authenticate bytes from another surface.
      */
     dispatchSaveImageToolCall(agentName, call) {
         this.emitTrace({ type: 'tool:started', module: 'workspace', tool: call.name, callId: call.id, input: call.input });
@@ -10125,16 +10335,166 @@ export class AgentFramework {
                 if (typeof input.path !== 'string' || input.path.length === 0) {
                     throw new Error('save_recent_image: `path` (mount-prefixed) is required');
                 }
-                const index = input.index === undefined ? 0 : Number(input.index);
-                if (!Number.isInteger(index) || index < 0) {
-                    throw new Error('save_recent_image: `index` must be a non-negative integer');
+                const ledger = this.toolImageLedgerFor(agentName);
+                const describeTool = (c) => `${c.toolName} (call ${c.toolCallId})`;
+                const unavailable = (status) => status === 'evicted'
+                    ? 'its bytes were evicted from the bounded retention budget'
+                    : 'this process has no record of that ref (refs are per-process and a restart clears them; ' +
+                        'very old refs age out; a mistyped ref looks the same)';
+                const resolve = (candidate, position) => {
+                    const rangeOffset = 0; // filled by the caller
+                    if (candidate.kind === 'attachment') {
+                        if (candidate.data === null) {
+                            throw new Error(`save_recent_image: image at index ${position} is not stored inline (base64) — cannot save it. Nothing written.`);
+                        }
+                        const bytes = Buffer.from(candidate.data, 'base64');
+                        return {
+                            rangeOffset,
+                            data: candidate.data,
+                            mediaType: candidate.mediaType,
+                            receipt: {
+                                source: 'attachment',
+                                mediaType: candidate.mediaType,
+                                byteSize: bytes.byteLength,
+                                sha256: sha256Hex(bytes),
+                                messagesBack: candidate.messagesBack,
+                            },
+                        };
+                    }
+                    if (candidate.kind === 'reference') {
+                        throw new Error(`save_recent_image: image at index ${position} is a reference (${candidate.refId}, ${candidate.mediaType}, ` +
+                            `from ${describeTool(candidate)}) — its bytes are not held here. Nothing written. ` +
+                            'Fetch it with fetch_reference and save the materialized file instead.');
+                    }
+                    if (candidate.ref === null) {
+                        throw new Error(`save_recent_image: image at index ${position} is a tool-result image from ${describeTool(candidate)} ` +
+                            'recorded without a retention ref (written before tool-image retention existed, or inside a ' +
+                            'script run, where tool images are not retained) — its bytes are not available. Nothing written. ' +
+                            'Re-run the tool for a fresh image rather than saving an older one.');
+                    }
+                    const lookup = ledger.lookup(candidate.ref);
+                    // The placeholder came out of stored TEXT, which a tool result can
+                    // quote from anywhere (a fetch_history of a channel where someone
+                    // pasted their save receipt). A genuine placeholder is written by
+                    // its own call's serialization, so the ref's provenance names that
+                    // call; a quoted or forged one cannot. Refuse the mismatch.
+                    if (lookup.status !== 'unknown' && lookup.image.toolCallId !== candidate.toolCallId) {
+                        throw new Error(`save_recent_image: image at index ${position} cites ${candidate.ref}, but that image belongs to ` +
+                            `${describeTool(lookup.image)}, not to ${describeTool(candidate)} where the placeholder appears — ` +
+                            'the placeholder is quoted or forged text, not this result\'s own image. Nothing written.');
+                    }
+                    if (lookup.status !== 'retained') {
+                        throw new Error(`save_recent_image: image at index ${position} (${candidate.ref}, from ${describeTool(candidate)}) ` +
+                            `is no longer retained — ${unavailable(lookup.status)}. Nothing written. ` +
+                            'Re-run the tool for a fresh image rather than saving an older one.');
+                    }
+                    const image = lookup.image;
+                    return {
+                        rangeOffset,
+                        data: image.data,
+                        mediaType: image.mediaType,
+                        receipt: {
+                            source: 'tool-result',
+                            ref: image.ref,
+                            toolName: image.toolName,
+                            toolCallId: image.toolCallId,
+                            blockIndex: image.blockIndex,
+                            mediaType: image.mediaType,
+                            byteSize: image.byteSize,
+                            sha256: image.sha256,
+                            messagesBack: candidate.messagesBack,
+                        },
+                    };
+                };
+                // Barrier: a save dispatched alongside other calls in one batch must
+                // not inventory before their results exist — those are the newest
+                // images. Waits (bounded) for every sibling to settle, or fails closed.
+                await this.awaitSiblingToolCalls(agent, call);
+                const found = [];
+                let index = 0;
+                let count = 1;
+                /** Direct-ref mode: the one ref to find in the scannable context. */
+                let wantedRef = null;
+                if (input.ref !== undefined) {
+                    if (typeof input.ref !== 'string' || !TOOL_IMAGE_REF_RE.test(input.ref)) {
+                        throw new Error('save_recent_image: `ref` must look like "img_k7x3q2_7" (copy it from the image placeholder in your context)');
+                    }
+                    if (input.index !== undefined || input.count !== undefined) {
+                        throw new Error('save_recent_image: `ref` is mutually exclusive with `index`/`count`');
+                    }
+                    wantedRef = input.ref;
                 }
-                const count = input.count === undefined ? 1 : Number(input.count);
-                const MAX_COUNT = 20;
-                if (!Number.isInteger(count) || count < 1 || count > MAX_COUNT) {
-                    throw new Error(`save_recent_image: \`count\` must be an integer in 1..${MAX_COUNT}`);
+                else {
+                    index = input.index === undefined ? 0 : Number(input.index);
+                    if (!Number.isInteger(index) || index < 0) {
+                        throw new Error('save_recent_image: `index` must be a non-negative integer');
+                    }
+                    count = input.count === undefined ? 1 : Number(input.count);
+                    const MAX_COUNT = 20;
+                    if (!Number.isInteger(count) || count < 1 || count > MAX_COUNT) {
+                        throw new Error(`save_recent_image: \`count\` must be an integer in 1..${MAX_COUNT}`);
+                    }
                 }
                 const lastWanted = index + count - 1;
+                let seen = 0;
+                const collecting = () => (wantedRef !== null ? found.length === 0 : found.length < count);
+                // One walk serves both modes. By index: the requested range of the
+                // ordered inventory. By ref: the slot whose placeholder cites that
+                // ref — the ref is resolved THROUGH its occurrence in context, so
+                // the same provenance cross-check applies (a ref that is not visible
+                // in the scannable window — an undone branch, quoted text naming a
+                // real ref — is not saveable by name either).
+                const consider = (candidate) => {
+                    if (wantedRef !== null) {
+                        if (candidate.kind === 'tool' && candidate.ref === wantedRef && found.length === 0) {
+                            found.push(resolve(candidate, seen));
+                        }
+                    }
+                    else if (seen >= index && seen <= lastWanted) {
+                        const resolved = resolve(candidate, seen);
+                        resolved.rangeOffset = seen - index;
+                        found.push(resolved);
+                    }
+                    seen++;
+                };
+                const considerToolResultImages = (toolCallId, toolName, placeholders, messagesBack) => {
+                    for (let p = placeholders.length - 1; p >= 0 && collecting(); p--) {
+                        const ph = placeholders[p];
+                        if (ph.kind === 'inline') {
+                            consider({ kind: 'tool', ref: ph.ref, toolCallId, toolName, mediaType: ph.mediaType, messagesBack });
+                            continue;
+                        }
+                        // Reference stub: the registry's testimony (when this process
+                        // still has the record) says whether it was an image; the
+                        // sniffed stub text is the fallback. Non-image references
+                        // are not slots.
+                        const testimony = referenceRegistry.get(ph.refId)?.testimony.mimeType?.toLowerCase() ?? ph.mediaType;
+                        if (!testimony || !testimony.startsWith('image/'))
+                            continue;
+                        consider({ kind: 'reference', refId: ph.refId, mediaType: testimony, toolCallId, toolName, messagesBack });
+                    }
+                };
+                // Same-batch results (e.g. a snapshot dispatched alongside the save)
+                // are not in the store yet but ARE the newest images. Classify them
+                // with the very serializer the commit path will run — contradiction
+                // blocks withheld, uri-form blocks as reference stubs, unknown shapes
+                // as no slot at all — so the inventory means the same thing before
+                // and after commit. Retention is idempotent per block, so the
+                // placeholder written at commit time carries the same ref.
+                const state = agent.state;
+                if (state.status === 'waiting_for_tools') {
+                    for (let i = state.completed.length - 1; i >= 0 && collecting(); i--) {
+                        const tc = state.completed[i];
+                        if (tc.result.isError)
+                            continue;
+                        const text = toolResultDataToHistoryString(tc.result.data, undefined, {
+                            imageRef: (blockIndex, image) => ledger.retain({
+                                toolCallId: tc.id, toolName: tc.name, blockIndex, data: image.data, mediaType: image.mimeType,
+                            }).ref,
+                        });
+                        considerToolResultImages(tc.id, tc.name, parseImagePlaceholders(text), 0);
+                    }
+                }
                 // Walk the message store tail-first in bounded windows, re-inlining
                 // blob media, until we've collected the requested range. Scanning is
                 // capped so a pathological index can't drag the whole store through
@@ -10143,37 +10503,45 @@ export class AgentFramework {
                 const WINDOW = 25;
                 const cm = agent.getContextManager();
                 const total = cm.getMessageCount();
-                let seen = 0;
                 let scanned = 0;
-                const found = [];
-                for (let end = total; end > 0 && scanned < MAX_SCAN && found.length < count; end -= WINDOW) {
+                for (let end = total; end > 0 && scanned < MAX_SCAN && collecting(); end -= WINDOW) {
                     const start = Math.max(0, end - WINDOW);
-                    const { messages } = cm.getMessageWindow(start, end - start, { resolveBlobs: true });
+                    // By ref, attachment bytes are never needed — skip blob resolution.
+                    const { messages } = cm.getMessageWindow(start, end - start, { resolveBlobs: wantedRef === null });
                     scanned += end - start;
-                    for (let i = messages.length - 1; i >= 0 && found.length < count; i--) {
+                    for (let i = messages.length - 1; i >= 0 && collecting(); i--) {
                         const content = messages[i]?.content;
                         if (!Array.isArray(content))
                             continue;
-                        for (let b = content.length - 1; b >= 0 && found.length < count; b--) {
+                        const messagesBack = total - (start + i);
+                        for (let b = content.length - 1; b >= 0 && collecting(); b--) {
                             const block = content[b];
-                            if (block?.type !== 'image')
-                                continue;
-                            if (seen >= index && seen <= lastWanted) {
-                                if (block.source?.type !== 'base64' || typeof block.source.data !== 'string') {
-                                    throw new Error(`save_recent_image: image at index ${seen} is not stored inline (base64) — cannot save it`);
-                                }
-                                found.push({
-                                    rangeOffset: seen - index,
-                                    data: block.source.data,
-                                    mediaType: block.source.mediaType ?? 'image/png',
-                                    messagesBack: total - (start + i),
+                            if (block?.type === 'image') {
+                                const inline = block.source?.type === 'base64' && typeof block.source.data === 'string';
+                                consider({
+                                    kind: 'attachment',
+                                    data: inline ? block.source.data : null,
+                                    mediaType: block.source?.mediaType ?? 'image/png',
+                                    messagesBack,
                                 });
                             }
-                            seen++;
+                            else if (block?.type === 'tool_result' && typeof block.content === 'string') {
+                                considerToolResultImages(block.toolUseId ?? 'unknown', block.toolName ?? 'unknown tool', parseImagePlaceholders(block.content), messagesBack);
+                            }
                         }
                     }
                 }
                 if (found.length === 0) {
+                    if (wantedRef !== null) {
+                        const lookup = ledger.lookup(wantedRef);
+                        throw new Error(lookup.status === 'unknown'
+                            ? `save_recent_image: ref ${wantedRef} cannot be saved — ${unavailable('unknown')}. Nothing written.`
+                            : `save_recent_image: ref ${wantedRef} (from ${describeTool(lookup.image)}) does not appear in your recent ` +
+                                `context (scanned ${Math.min(scanned, MAX_SCAN)} messages) — a ref is saved through its placeholder, ` +
+                                'which must be visible to you' +
+                                (lookup.status === 'evicted' ? '; its bytes were also evicted from the bounded retention budget' : '') +
+                                '. Nothing written.');
+                    }
                     throw new Error(seen === 0
                         ? `save_recent_image: no images found in the most recent ${Math.min(scanned, MAX_SCAN)} messages`
                         : `save_recent_image: only ${seen} image(s) found in the most recent ${Math.min(scanned, MAX_SCAN)} messages (asked for index ${index})`);
@@ -10209,7 +10577,7 @@ export class AgentFramework {
                     savedFiles.push({
                         ...result.data,
                         imageIndex: index + image.rangeOffset,
-                        messagesBack: image.messagesBack,
+                        ...image.receipt,
                     });
                 }
                 finish({