@moxxy/sdk 0.43.0 → 0.45.0

package/src/mode/checkpoint-gate.ts

@@ -0,0 +1,198 @@
+import { asPluginId } from '../ids.js';
+import type { MoxxyEvent } from '../events.js';
+import type { ModeContext } from '../mode.js';
+import type { StopReason } from '../provider-utils.js';
+import type { CheckpointResult, TurnCheckpoint } from './checkpoint.js';
+
+/**
+ * The turn-end checkpoint gate and the loop's own lifecycle events, shared by
+ * the ReAct loop and the agent-connection loop.
+ */
+
+const DEFAULT_CHECKPOINT_TIMEOUT_MS = 120_000;
+const CHECKPOINT_EVENT_PLUGIN_ID = asPluginId('react-loop');
+
+/** Gate outcome: end the turn, or loop again (optionally with a volatile nudge). */
+export type GateVerdict = { readonly kind: 'end' } | { readonly kind: 'loop'; readonly volatileText?: string };
+
+export interface GateRound {
+  readonly candidateText: string;
+  readonly stopReason: StopReason;
+  readonly iteration: number;
+  readonly consecutiveIdle: number;
+  readonly injectionsUsed: number;
+  readonly injectionBudget: number;
+  readonly maxInjectChars: number;
+}
+
+export async function* runCheckpointGate(
+  ctx: ModeContext,
+  checkpoints: ReadonlyArray<TurnCheckpoint>,
+  round: GateRound,
+): AsyncGenerator<MoxxyEvent, GateVerdict> {
+  // Natural completions face every checkpoint; truncated/errored candidates
+  // only face the idle-tolerant ones — reviewing a half-sentence as if it
+  // were a completion claim wastes a checker run and confuses the model.
+  const eligible = checkpoints.filter(
+    (cp) =>
+      (round.stopReason === 'end_turn' || (cp.gateOn ?? 'end_turn') === 'idle') && (cp.applies?.(ctx) ?? true),
+  );
+  if (eligible.length === 0) return { kind: 'end' };
+
+  // Budget exhausted → the answer ships as-is, but LOUDLY: silent
+  // degradation would let the user believe a gated answer passed its gates.
+  if (round.injectionsUsed >= round.injectionBudget) {
+    yield await emitError(
+      ctx,
+      'retryable',
+      `checkpoint budget exhausted (${round.injectionBudget} rounds) — ` +
+        `ending the turn with unresolved checkpoint feedback; verify the result manually.`,
+    );
+    return { kind: 'end' };
+  }
+
+  for (const cp of eligible) {
+    // User cancelled mid-gate: end the turn WITHOUT retracting the
+    // already-logged answer — an abort must never un-say what was said.
+    if (ctx.signal.aborted) return { kind: 'end' };
+
+    yield await emitCheckpointEvent(ctx, 'checkpoint_started', {
+      name: cp.name,
+      iteration: round.iteration,
+    });
+
+    const timeoutMs = Math.max(1_000, cp.timeoutMs ?? DEFAULT_CHECKPOINT_TIMEOUT_MS);
+    const timeoutCtl = new AbortController();
+    const timer = setTimeout(() => timeoutCtl.abort(), timeoutMs);
+    timer.unref?.();
+    let result: CheckpointResult;
+    try {
+      result = await cp.run(
+        {
+          candidateText: round.candidateText,
+          stopReason: round.stopReason,
+          iteration: round.iteration,
+          consecutiveIdle: round.consecutiveIdle,
+          injectionsUsed: round.injectionsUsed,
+          injectionBudget: round.injectionBudget,
+          signal: AbortSignal.any([ctx.signal, timeoutCtl.signal]),
+        },
+        ctx,
+      );
+    } catch (err) {
+      if (ctx.signal.aborted) return { kind: 'end' };
+      // Fail OPEN, visibly. A crashed or timed-out checker downgrades the
+      // gate to a warning — it must never wedge the turn (fail-closed is a
+      // turn that can never end) and never crash it (the answer is already
+      // logged).
+      const why = timeoutCtl.signal.aborted
+        ? `timed out after ${timeoutMs}ms`
+        : `failed: ${err instanceof Error ? err.message : String(err)}`;
+      yield await emitError(ctx, 'retryable', `checkpoint "${cp.name}" ${why} — proceeding unchecked`);
+      continue;
+    } finally {
+      clearTimeout(timer);
+    }
+
+    switch (result.action) {
+      case 'pass': {
+        yield await emitCheckpointEvent(ctx, 'checkpoint_passed', { name: cp.name });
+        continue;
+      }
+      case 'stop': {
+        // The checkpoint already emitted its own wrap-up events.
+        yield await emitCheckpointEvent(ctx, 'checkpoint_stopped', { name: cp.name });
+        return { kind: 'end' };
+      }
+      case 'retry': {
+        yield await emitCheckpointEvent(ctx, 'checkpoint_retry', { name: cp.name });
+        return { kind: 'loop' };
+      }
+      case 'inject': {
+        // Guard the guard: an inject with blank text would loop the turn
+        // with no new signal for the model — a checker bug; fail open.
+        const feedback = result.text?.trim();
+        if (!feedback) {
+          yield await emitError(
+            ctx,
+            'retryable',
+            `checkpoint "${cp.name}" injected empty feedback — ignored`,
+          );
+          continue;
+        }
+        const clamped = clampChars(feedback, round.maxInjectChars);
+        if (result.volatile) {
+          yield await emitCheckpointEvent(ctx, 'checkpoint_injected', {
+            name: cp.name,
+            volatile: true,
+          });
+          return { kind: 'loop', volatileText: clamped };
+        }
+        // Persistent: a checkpoint-origin user prompt. Projected as a
+        // user-role message by the existing projection case, marked via the
+        // same `origin` machinery trigger prompts use, cache-safe because it
+        // is an ordinary append at the log tail.
+        yield await ctx.emit({
+          type: 'user_prompt',
+          sessionId: ctx.sessionId,
+          turnId: ctx.turnId,
+          source: 'system',
+          text: clamped,
+          origin: { kind: 'checkpoint', name: cp.name },
+        });
+        yield await emitCheckpointEvent(ctx, 'checkpoint_injected', {
+          name: cp.name,
+          volatile: false,
+        });
+        return { kind: 'loop' };
+      }
+    }
+  }
+  return { kind: 'end' };
+}
+
+function clampChars(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n…[checkpoint feedback truncated: ${text.length - max} chars dropped]`;
+}
+
+export async function emitAbort(ctx: ModeContext, reason: string): Promise<MoxxyEvent> {
+  return ctx.emit({
+    type: 'abort',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    reason,
+  });
+}
+
+export async function emitError(
+  ctx: ModeContext,
+  kind: 'retryable' | 'fatal',
+  message: string,
+): Promise<MoxxyEvent> {
+  return ctx.emit({
+    type: 'error',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    kind,
+    message,
+  });
+}
+
+export async function emitCheckpointEvent(
+  ctx: ModeContext,
+  subtype: string,
+  payload: unknown,
+): Promise<MoxxyEvent> {
+  return ctx.emit({
+    type: 'plugin_event',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    pluginId: CHECKPOINT_EVENT_PLUGIN_ID,
+    subtype,
+    payload,
+  });
+}

package/src/mode/checkpoint.ts

@@ -101,6 +101,12 @@ export interface TurnCheckpoint {
    * (goal/collab-style stall handling wants these too).
    */
   readonly gateOn?: 'end_turn' | 'idle';
+  /**
+   * Also gate turns done by a vendor's agent (an agent connection). Off by
+   * default: the agent decides when its turn is done, as in its own tool, so
+   * Moxxy's end-of-turn reminders stay out of it.
+   */
+  readonly agentConnections?: boolean;
   /**
    * A cheap test of whether this turn needs the checkpoint at all. When it
    * says no, the checkpoint is skipped without a trace — no lifecycle events —

package/src/mode/collect-stream.ts

@@ -22,7 +22,7 @@ export interface CollectedToolUse {
 }
 
 /** Sum two usage frames so multi-`message_end` responses don't undercount. */
-function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+export function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
   const cacheRead =
     a.cacheReadTokens !== undefined || b.cacheReadTokens !== undefined
       ? (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0)

package/src/mode/project-messages.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from 'vitest';
-import { projectMessagesFromLog, projectUserPrompt, resolvedCallIdSet, skillsWithinReach } from './project-messages.js';
+import { MODEL_ATTACHMENT_BUDGET_CHARS } from '../attachment-payload.js';
+import {
+  projectMessagesFromLog,
+  projectUserPrompt,
+  resolvedCallIdSet,
+  skillsWithinReach,
+} from './project-messages.js';
 import type { Skill } from '../skill.js';
 import { computeElisionState } from '../elision-state.js';
 import { asEventId, asSessionId, asTurnId } from '../ids.js';
@@ -181,6 +187,17 @@ describe('projectMessagesFromLog tool_result stringify hardening', () => {
   it('passes a string output through verbatim', () => {
     expect(toolResultText(logWith('plain text'))).toBe('plain text');
   });
+
+  it('shows the model every image a result carries, after its text', () => {
+    const output = { forModel: 'Two windows', mediaType: 'image/png', base64: 'AAA', moreImages: [{ mediaType: 'image/jpeg', base64: 'BBB' }] };
+    const msgs = projectMessagesFromLog({ log: reader(logWith(output)) });
+
+    expect(msgs.find((m) => m.role === 'tool_result')?.content).toEqual([
+      { type: 'tool_result', toolUseId: 'c1', content: 'Two windows', isError: false },
+      { type: 'image', mediaType: 'image/png', data: 'AAA' },
+      { type: 'image', mediaType: 'image/jpeg', data: 'BBB' },
+    ]);
+  });
 });
 
 describe('skillsWithinReach', () => {
@@ -252,3 +269,103 @@ describe('projectMessagesFromLog tool pairing across a compaction boundary', ()
     });
   });
 });
+
+describe('projectMessagesFromLog attachment budget', () => {
+  const pdf = (name: string, chars: number) => ({
+    kind: 'document' as const,
+    content: 'A'.repeat(chars),
+    mediaType: 'application/pdf',
+    name,
+  });
+  const blocksOf = (events: ReadonlyArray<MoxxyEvent>) =>
+    projectMessagesFromLog({ log: reader(events) }).flatMap((m) => m.content);
+
+  it('sends the newest attachments in full and names the older ones that no longer fit', () => {
+    const half = Math.floor(MODEL_ATTACHMENT_BUDGET_CHARS * 0.6);
+    const blocks = blocksOf([
+      userPrompt(0, { text: 'first scan', attachments: [pdf('old-scan.pdf', half)] }),
+      userPrompt(1, { text: 'second scan', attachments: [pdf('new-scan.pdf', half)] }),
+    ]);
+    const documents = blocks.filter((b) => b.type === 'document');
+    expect(documents).toHaveLength(1);
+    expect(documents[0]).toMatchObject({ name: 'new-scan.pdf' });
+    const note = blocks.find((b) => b.type === 'text' && b.text.includes('old-scan.pdf'));
+    expect(note).toBeDefined();
+    const sent = blocks.reduce((n, b) => n + (b.type === 'document' ? b.data.length : 0), 0);
+    expect(sent).toBeLessThanOrEqual(MODEL_ATTACHMENT_BUDGET_CHARS);
+  });
+
+  it('tells the model how to bring a left-out attachment back', () => {
+    const half = Math.floor(MODEL_ATTACHMENT_BUDGET_CHARS * 0.6);
+    const blocks = blocksOf([
+      userPrompt(0, { text: 'first scan', attachments: [pdf('old-scan.pdf', half)] }),
+      userPrompt(1, { text: 'second scan', attachments: [pdf('new-scan.pdf', half)] }),
+    ]);
+    const note = blocks.find((b) => b.type === 'text' && b.text.includes('old-scan.pdf'));
+    expect(note).toMatchObject({ text: expect.stringContaining('recall({ attachment: "0:0" })') });
+  });
+
+  const restore = (seq: number, callId: string, ref: { seq: number; index: number }): MoxxyEvent[] => [
+    event(seq, { type: 'tool_call_requested', turnId: t1, source: 'model', callId, name: 'recall', input: { attachment: `${ref.seq}:${ref.index}` } }),
+    event(seq + 1, {
+      type: 'tool_result',
+      turnId: t1,
+      source: 'tool',
+      callId,
+      ok: true,
+      output: { forModel: 'restored old-scan.pdf', restoredAttachment: ref },
+    }),
+  ];
+
+  it('shows a restored attachment again beside the recall result, within the same budget', () => {
+    const half = Math.floor(MODEL_ATTACHMENT_BUDGET_CHARS * 0.6);
+    const messages = projectMessagesFromLog({
+      log: reader([
+        userPrompt(0, { text: 'first scan', attachments: [pdf('old-scan.pdf', half)] }),
+        userPrompt(1, { text: 'second scan', attachments: [pdf('new-scan.pdf', half)] }),
+        userPrompt(2, { text: 'back to the first one' }),
+        ...restore(3, 'r1', { seq: 0, index: 0 }),
+      ]),
+    });
+    const result = messages.find((m) => m.role === 'tool_result');
+    expect(result?.content).toEqual([
+      { type: 'tool_result', toolUseId: 'r1', content: 'restored old-scan.pdf', isError: false },
+      { type: 'document', mediaType: 'application/pdf', data: 'A'.repeat(half), name: 'old-scan.pdf' },
+    ]);
+    const blocks = messages.flatMap((m) => m.content);
+    expect(blocks.filter((b) => b.type === 'document')).toHaveLength(1);
+    expect(blocks.some((b) => b.type === 'text' && b.text.includes('new-scan.pdf'))).toBe(true);
+  });
+
+  it('restores an attachment whose turn a compaction summarized away', () => {
+    const messages = projectMessagesFromLog({
+      log: reader([
+        userPrompt(0, { text: 'the contract', attachments: [pdf('umowa.pdf', 100)] }),
+        event(1, {
+          type: 'compaction',
+          turnId: t1,
+          source: 'compactor',
+          compactor: 'segments',
+          replacedRange: [0, 0],
+          summary: 'the person shared umowa.pdf',
+          tokensSaved: 10,
+        }),
+        userPrompt(2, { text: 'what was in point 7?' }),
+        ...restore(3, 'r1', { seq: 0, index: 0 }),
+      ]),
+    });
+    const documents = messages.flatMap((m) => m.content).filter((b) => b.type === 'document');
+    expect(documents).toEqual([{ type: 'document', mediaType: 'application/pdf', data: 'A'.repeat(100), name: 'umowa.pdf' }]);
+  });
+
+  it('never sends an empty payload for an attachment whose bytes were left out', () => {
+    const blocks = projectUserPrompt(
+      userPrompt(0, {
+        attachments: [{ kind: 'image', content: '', mediaType: 'image/png', name: 'shot.png', omittedBytes: 2048 }],
+      }),
+      noElision,
+    );
+    expect(blocks.some((b) => b.type === 'image')).toBe(false);
+    expect(blocks.some((b) => b.type === 'text' && b.text.includes('shot.png'))).toBe(true);
+  });
+});

package/src/mode/project-messages.ts

@@ -2,7 +2,13 @@ import type { ContentBlock, ProviderMessage } from '../provider.js';
 import type { ModeContext } from '../mode.js';
 import type { Skill } from '../skill.js';
 import { toolPatternMatches } from '../skill-mentions.js';
-import type { MoxxyEvent, UserPromptEvent } from '../events.js';
+import type { MoxxyEvent, UserPromptAttachment, UserPromptEvent } from '../events.js';
+import {
+  MODEL_ATTACHMENT_BUDGET_CHARS,
+  attachmentBytes,
+  attachmentKey,
+  restoredAttachmentRef,
+} from '../attachment-payload.js';
 import {
   activeCompactionRanges,
   makeCompactionLookup,
@@ -16,51 +22,7 @@ import {
   toolResultStubbed,
   type ElisionState,
 } from '../elision-state.js';
-import { isToolDisplayResult } from '../tool-display.js';
-
-/**
- * Stringify an arbitrary tool output for the model-facing tool_result text.
- * `tool_result.output` is `unknown` and comes straight from whatever a tool
- * returned, so it can be circular or contain a BigInt — either of which makes
- * `JSON.stringify` THROW. Because projection runs on every request over the
- * append-only log, an unguarded throw here permanently wedges the session
- * (every subsequent re-projection re-throws). Mirrors the try/catch guard the
- * sibling sizing paths (`safeJsonLen`, `toolResultBytes`) already use.
- */
-function safeStringifyOutput(output: unknown): string {
-  if (typeof output === 'string') return output;
-  try {
-    return JSON.stringify(output ?? '');
-  } catch {
-    try {
-      return String(output ?? '');
-    } catch {
-      return '[unserializable tool output]';
-    }
-  }
-}
-
-/**
- * An image ContentBlock extracted from an image-shaped tool output. A tool can
- * return either `{ mediaType, base64 }` (the desktop screenshot/clipboard shape)
- * or the provider-native `{ type:'image', mediaType, data }` — both normalize to
- * the same provider `image` block so the model SEES the pixels instead of a
- * stringified blob of base64.
- */
-function imageBlockFromOutput(output: unknown): Extract<ContentBlock, { type: 'image' }> | null {
-  if (typeof output !== 'object' || output === null) return null;
-  const o = output as { type?: unknown; mediaType?: unknown; base64?: unknown; data?: unknown };
-  if (typeof o.mediaType !== 'string') return null;
-  // `{ mediaType, base64 }` (raw shape) or `{ type:'image', mediaType, data }`.
-  const data =
-    typeof o.base64 === 'string'
-      ? o.base64
-      : o.type === 'image' && typeof o.data === 'string'
-        ? o.data
-        : null;
-  if (data === null) return null;
-  return { type: 'image', mediaType: o.mediaType, data };
-}
+import { toolOutputForModel, type ToolImageBlock } from '../tool-output.js';
 
 /** Appended to the system prompt while elision is active (see projection). */
 export const ELISION_SYSTEM_NOTE =
@@ -135,6 +97,96 @@ export interface ProjectMessagesOptions {
   readonly precomputedElisionState?: ElisionState;
 }
 
+function hasModelPayload(att: UserPromptAttachment): boolean {
+  return att.kind === 'image' || att.kind === 'document';
+}
+
+function attachmentLeftOutNote(att: UserPromptAttachment, seq: number, index: number): string {
+  const label = `${att.kind}${att.name ? ` "${att.name}"` : ''}`;
+  const mb = (attachmentBytes(att) / (1024 * 1024)).toFixed(1);
+  return (
+    `[${label} (${mb} MB) was attached earlier in this conversation and is no longer sent ` +
+    `with each request, to keep the request within the model's size limit. ` +
+    `To see it again, call recall({ attachment: "${attachmentKey(seq, index)}" }).]`
+  );
+}
+
+/** The image or document block an attachment the model reads as bytes becomes. */
+function attachmentBlock(att: UserPromptAttachment): ContentBlock {
+  if (att.kind === 'image') {
+    return { type: 'image', mediaType: att.mediaType ?? 'image/png', data: att.content };
+  }
+  return {
+    type: 'document',
+    mediaType: att.mediaType ?? 'application/pdf',
+    data: att.content,
+    ...(att.name ? { name: att.name } : {}),
+  };
+}
+
+/** The prompts that carry attachments, by seq, so a restoring recall finds its original. */
+function attachmentPromptsBySeq(events: ReadonlyArray<MoxxyEvent>): ReadonlyMap<number, UserPromptEvent> {
+  const prompts = new Map<number, UserPromptEvent>();
+  for (const e of events) {
+    if (e.type === 'user_prompt' && e.attachments && e.attachments.length > 0) prompts.set(e.seq, e);
+  }
+  return prompts;
+}
+
+/** The image/document a `recall({ attachment })` result brings back, or null. */
+function restoredAttachment(
+  e: Extract<MoxxyEvent, { type: 'tool_result' }>,
+  prompts: ReadonlyMap<number, UserPromptEvent>,
+): UserPromptAttachment | null {
+  if (!e.ok || e.error) return null;
+  const ref = restoredAttachmentRef(e.output);
+  if (!ref) return null;
+  const prompt = prompts.get(ref.seq);
+  const att = prompt ? prompt.attachments?.[ref.index] : undefined;
+  return att && hasModelPayload(att) && att.omittedBytes === undefined ? att : null;
+}
+
+/** The budget key of what a restoring recall result shows. */
+const restoreKey = (seq: number): string => `r:${seq}`;
+
+/**
+ * Keys of the image/document payloads that go to the model in full: an
+ * attachment's `seq:index`, or `r:seq` for one a recall result restores.
+ * Newest first, while they fit {@link MODEL_ATTACHMENT_BUDGET_CHARS}, so a
+ * restored attachment takes its place among the newest. Deterministic for a
+ * given log, so the prompt cache sees a stable prefix.
+ */
+function attachmentsSentInFull(
+  events: ReadonlyArray<MoxxyEvent>,
+  el: ElisionState,
+  isCompacted: (seq: number) => boolean,
+  prompts: ReadonlyMap<number, UserPromptEvent>,
+): ReadonlySet<string> {
+  const keys = new Set<string>();
+  let room = MODEL_ATTACHMENT_BUDGET_CHARS;
+  const take = (key: string, att: UserPromptAttachment): void => {
+    if (att.content.length > room) return;
+    room -= att.content.length;
+    keys.add(key);
+  };
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const e = events[i];
+    if (!e || isCompacted(e.seq)) continue;
+    if (e.type === 'tool_result') {
+      if (toolResultStubbed(e, el)) continue;
+      const att = restoredAttachment(e, prompts);
+      if (att) take(restoreKey(e.seq), att);
+      continue;
+    }
+    if (e.type !== 'user_prompt' || !e.attachments || conversationalStubbed(e, el)) continue;
+    for (const [index, att] of e.attachments.entries()) {
+      if (!hasModelPayload(att) || att.omittedBytes !== undefined) continue;
+      take(attachmentKey(e.seq, index), att);
+    }
+  }
+  return keys;
+}
+
 /**
  * Pure projection of a single `user_prompt` event to its content blocks.
  *
@@ -144,27 +196,23 @@ export interface ProjectMessagesOptions {
  * what the inline switch arm produced. Caller decides how to wrap it as a
  * message / record the stable prefix.
  */
-export function projectUserPrompt(event: UserPromptEvent, el: ElisionState): ContentBlock[] {
+export function projectUserPrompt(
+  event: UserPromptEvent,
+  el: ElisionState,
+  /** Which attachments go to the model in full; the rest become a short note. Default: all. */
+  sendsInFull: (index: number) => boolean = () => true,
+): ContentBlock[] {
   // Elided + conversational: collapse to a stub (anchor/tiny kept full).
   if (conversationalStubbed(event, el)) {
     return [{ type: 'text', text: conversationalStub('user', event.seq) }];
   }
   const blocks: ContentBlock[] = [{ type: 'text', text: event.text }];
   if (event.attachments) {
-    for (const att of event.attachments) {
-      if (att.kind === 'image') {
-        blocks.push({
-          type: 'image',
-          mediaType: att.mediaType ?? 'image/png',
-          data: att.content,
-        });
-      } else if (att.kind === 'document') {
-        blocks.push({
-          type: 'document',
-          mediaType: att.mediaType ?? 'application/pdf',
-          data: att.content,
-          ...(att.name ? { name: att.name } : {}),
-        });
+    for (const [index, att] of event.attachments.entries()) {
+      if (att.omittedBytes !== undefined || (hasModelPayload(att) && !sendsInFull(index))) {
+        blocks.push({ type: 'text', text: attachmentLeftOutNote(att, event.seq, index) });
+      } else if (hasModelPayload(att)) {
+        blocks.push(attachmentBlock(att));
       } else {
         blocks.push({
           type: 'text',
@@ -277,6 +325,8 @@ export function projectMessages(
   // Only VISIBLE results count: one swallowed by a compaction is never sent, so
   // its still-visible tool_use needs the fallback just like a missing one.
   const resolvedCallIds = resolvedCallIdSet(allEvents.filter((e) => !compactionFor(e.seq)));
+  const attachmentPrompts = attachmentPromptsBySeq(allEvents);
+  const sentInFull = attachmentsSentInFull(allEvents, el, (seq) => compactionFor(seq) !== null, attachmentPrompts);
   // callIds whose tool_use block is projected. A tool_result outside this set
   // answers a call a compaction summarized away (the result landed after later
   // turns began); providers reject a result with no matching call.
@@ -347,7 +397,10 @@ export function projectMessages(
       case 'user_prompt': {
         flush();
         pendingReasoning = null;
-        messages.push({ role: 'user', content: projectUserPrompt(e, el) });
+        messages.push({
+          role: 'user',
+          content: projectUserPrompt(e, el, (index) => sentInFull.has(`${e.seq}:${index}`)),
+        });
         recordStable(e.seq);
         break;
       }
@@ -427,32 +480,38 @@ export function projectMessages(
         // Stub bulky old tool output to a recall-able marker (decision shared
         // with estimateContextTokens via toolResultStubbed).
         let text: string;
-        // An image-shaped output (a screenshot/clipboard grab) is carried as a
-        // provider `image` block so the model SEES the pixels — only when the
+        // An image-shaped output (a screenshot/clipboard grab) is carried as
+        // provider `image` blocks so the model SEES the pixels — only when the
         // result isn't stubbed (elided) or an error and the call succeeded.
-        let image: Extract<ContentBlock, { type: 'image' }> | null = null;
+        let images: ReadonlyArray<ToolImageBlock> = [];
+        // A `recall({ attachment })` result: the original image/document goes
+        // beside it, from the prompt that carried it, while the budget allows.
+        let restored: ContentBlock | null = null;
+        const restoredAtt = toolResultStubbed(e, el) ? null : restoredAttachment(e, attachmentPrompts);
         if (toolResultStubbed(e, el)) {
           text = toolResultStubText(e, el);
         } else if (e.error) {
           text = `[error:${e.error.kind}] ${e.error.message}`;
-        } else if (isToolDisplayResult(e.output)) {
-          // Rich result (e.g. a file diff): the model only needs the short
-          // `forModel` summary — the structured `display` is for channels.
-          text = e.output.forModel;
-        } else if (e.ok && (image = imageBlockFromOutput(e.output))) {
-          // Short marker satisfies the tool_use→tool_result pairing; the image
-          // block (appended below) carries the actual pixels.
+        } else if (restoredAtt) {
           const description = (e.output as { forModel?: unknown }).forModel;
-          text = typeof description === 'string'
-            ? description
-            : '[image returned by tool — see attached image]';
+          text = typeof description === 'string' ? description : '[attachment restored — see below]';
+          if (sentInFull.has(restoreKey(e.seq))) {
+            restored = attachmentBlock(restoredAtt);
+          } else {
+            text +=
+              ' [It could not be shown again: newer attachments already fill what one request may carry.' +
+              ' Ask the person to attach it again if you need it now.]';
+          }
         } else {
-          text = safeStringifyOutput(e.output);
+          const forModel = toolOutputForModel(e.output);
+          text = forModel.text;
+          if (e.ok) images = forModel.images;
         }
         const content: ContentBlock[] = [
           { type: 'tool_result', toolUseId: e.callId, content: text, isError: !e.ok },
+          ...images,
         ];
-        if (image) content.push(image);
+        if (restored) content.push(restored);
         messages.push({ role: 'tool_result', content });
         recordStable(e.seq);
         break;