@stigmer/runner 3.8.0 → 3.9.0

package/src/activities/execute-cursor/attachment-resolver.ts

@@ -29,10 +29,17 @@
  * the execution with an actionable error.
  */
 
-import { mkdir, copyFile, writeFile } from "node:fs/promises";
+import { mkdir, copyFile, readFile, stat, writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import {
+  isVisionCandidate,
+  type VisionBudget,
+  type VisionDegradedReason,
+  type VisionImage,
+  type VisionOutcome,
+} from "../../shared/attachment-vision.js";
 import { getPlatformDir } from "../../shared/workspace/platform-dir.js";
 import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/workspace/stigmer-link.js";
 
@@ -42,6 +49,15 @@ export interface ResolvedAttachment {
   filename: string;
   /** Workspace-relative path the agent reads (`.stigmer/inputs/{filename}`). */
   relativePath: string;
+  /** Present when the attachment was accepted into the turn's vision payload. */
+  vision?: VisionImage;
+  /**
+   * Present when the attachment was plausibly an image but could not ride
+   * inline (see {@link VisionDegradedReason}) — disclosed in the prompt so the
+   * agent never silently ignores a photo the user believes it can see.
+   * Attachments that were never image-shaped carry neither field.
+   */
+  visionDegraded?: VisionDegradedReason;
 }
 
 export interface AttachmentResolverOptions {
@@ -54,6 +70,12 @@ export interface AttachmentResolverOptions {
    * then fails with an actionable error rather than a silent skip.
    */
   storage: ArtifactStorage | undefined;
+  /**
+   * The turn's vision selector (attachment-vision.ts owns all policy).
+   * `undefined` disables inline image delivery; file materialization is
+   * identical either way — vision is strictly additive.
+   */
+  visionBudget?: VisionBudget;
 }
 
 export class AttachmentResolutionError extends Error {
@@ -109,9 +131,10 @@ async function resolveAttachment(
 ): Promise<ResolvedAttachment> {
   // Local-mode fast path: the file is already on this machine's disk.
   if (options.mode === "local" && attachment.localPath) {
-    const filename = attachment.filename || basename(attachment.localPath);
+    const filename = safeInputName(attachment.filename || attachment.localPath);
+    let vision: VisionOutcome | undefined;
     try {
-      await copyFile(attachment.localPath, join(inputsDir, filename));
+      vision = await materializeLocalFile(attachment, filename, inputsDir, options.visionBudget);
     } catch (err) {
       throw new AttachmentResolutionError(
         attachment.filename,
@@ -122,6 +145,7 @@ async function resolveAttachment(
     return {
       filename,
       relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+      ...visionOutcomeFields(vision),
     };
   }
 
@@ -140,7 +164,7 @@ async function resolveAttachment(
     );
   }
 
-  const filename = attachment.filename || basename(attachment.storageKey);
+  const filename = safeInputName(attachment.filename || attachment.storageKey);
   let content: Buffer;
   try {
     content = await options.storage.download(attachment.storageKey);
@@ -153,8 +177,70 @@ async function resolveAttachment(
   }
   await writeFile(join(inputsDir, filename), content);
 
+  // The bytes are already in hand for the file write — offer them to the
+  // vision budget before they go out of scope (the sniff decides eligibility;
+  // no pre-filter needed on this branch).
+  const vision = options.visionBudget?.offer(filename, attachment.contentType, content);
+
   return {
     filename,
     relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+    ...visionOutcomeFields(vision),
   };
 }
+
+/**
+ * Materialize a local-path attachment, reading the bytes only when they are
+ * plausibly a vision candidate within the per-image cap — a 25 MB PDF (or an
+ * oversized image, detected by stat) keeps the plain `copyFile` and never
+ * enters memory. Returns the vision outcome, or `undefined` when vision is
+ * disabled or the file is not a candidate.
+ */
+async function materializeLocalFile(
+  attachment: Attachment,
+  filename: string,
+  inputsDir: string,
+  visionBudget: VisionBudget | undefined,
+): Promise<VisionOutcome | undefined> {
+  const dest = join(inputsDir, filename);
+  if (!visionBudget || !isVisionCandidate(attachment.contentType, filename)) {
+    await copyFile(attachment.localPath, dest);
+    return undefined;
+  }
+  const info = await stat(attachment.localPath);
+  if (visionBudget.exceedsImageCap(info.size)) {
+    await copyFile(attachment.localPath, dest);
+    return visionBudget.offerOversized();
+  }
+  const content = await readFile(attachment.localPath);
+  await writeFile(dest, content);
+  return visionBudget.offer(filename, attachment.contentType, content);
+}
+
+function visionOutcomeFields(
+  outcome: VisionOutcome | undefined,
+): Pick<ResolvedAttachment, "vision" | "visionDegraded"> {
+  if (outcome === undefined || outcome.kind === "skipped") return {};
+  return outcome.kind === "accepted"
+    ? { vision: outcome.image }
+    : { visionDegraded: outcome.reason };
+}
+
+/**
+ * Reduce a caller-influenced name to a single, safe path component for writing
+ * under the inputs dir. The name (an attachment's original filename, or a
+ * storage key's tail) is untrusted — a value like `../../evil.md` would steer
+ * the write outside `.stigmer/inputs/`. Taking the basename strips any path
+ * structure; the residual `.`/`..`/empty cases (which basename does not strip)
+ * are rejected loudly so the write target is always a real file inside inputs.
+ */
+function safeInputName(raw: string): string {
+  const name = basename(raw);
+  if (name === "" || name === "." || name === "..") {
+    throw new AttachmentResolutionError(
+      raw,
+      `'${raw}' does not yield a usable filename for materialization`,
+    );
+  }
+  return name;
+}

package/src/activities/execute-cursor/index.ts

@@ -35,7 +35,7 @@ import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agent
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import type { AgentExecution, AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionControlSignal, ExecutionPhase, FileChangeSetStatus, InteractionMode, MessageType, ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import type { Run, ConversationTurn } from "@cursor/sdk";
+import type { Run, ConversationTurn, SDKUserMessage } from "@cursor/sdk";
 
 import type { Config } from "../../config.js";
 import { StigmerClient } from "../../client/stigmer-client.js";
@@ -58,6 +58,12 @@ import { readSessionContext } from "../../shared/session-context.js";
 import { withholdSecretContentFromMessages } from "../../shared/tool-row.js";
 import { StallTimeoutError, formatStallFailure } from "../../shared/stall-watchdog.js";
 import { resolveUsableArtifactStorage, loadArtifactStorageConfig, type ArtifactStorage } from "../../shared/artifact-storage.js";
+import {
+  CURSOR_VISION_PROFILE,
+  VisionBudget,
+  toCursorImages,
+  type NotViewableEntry,
+} from "../../shared/attachment-vision.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
 import { DeltaEnricher } from "./delta-enricher.js";
 import { TodoTracker } from "./todo-tracker.js";
@@ -84,7 +90,7 @@ import { buildCursorSubAgentDefinitions } from "./subagent-config.js";
 import { resolveSkills } from "./skill-resolver.js";
 import { removeStigmerSymlink } from "../../shared/workspace/stigmer-link.js";
 import { resolveAttachments } from "./attachment-resolver.js";
-import { buildEnhancedPrompt, buildReinvocationPrompt, formatConversationCatchupSection, formatInteractionModePrefix, formatImplementPlanSection } from "./prompt-builder.js";
+import { buildEnhancedPrompt, buildReinvocationPrompt, formatConversationCatchupSection, formatInputFiles, formatInteractionModePrefix, formatImplementPlanSection } from "./prompt-builder.js";
 import { installHitlGate, removeHitlGate } from "./workspace-setup.js";
 import { ensureHitlDir } from "../../shared/workspace/platform-dir.js";
 import {
@@ -761,14 +767,38 @@ async function executeCursorInner(
 
     // Phase 5b: Resolve attachments (fail-hard — explicit user inputs; see
     // attachment-resolver.ts). Downloads by storage key through the same
-    // artifactStorage resolved for status offload above.
+    // artifactStorage resolved for status offload above. The vision budget
+    // rides along so image attachments are selected for inline delivery while
+    // their bytes are already in hand (attachment-vision.ts owns all policy).
+    const visionBudget = new VisionBudget(CURSOR_VISION_PROFILE);
     const attachmentResults = await resolveAttachments(spec.attachments, {
       sessionId,
       primaryWorkspaceDir,
       mode: config.mode,
       storage: artifactStorage,
+      visionBudget,
     });
     const attachmentPaths = attachmentResults.map((a) => a.relativePath);
+    // Vision facts, derived once from the single resolution result: the
+    // images the model will see inline (in attachment order) and the ones
+    // that degraded to path-only, disclosed in the prompt.
+    const visionImages = attachmentResults.flatMap((a) => (a.vision ? [a.vision] : []));
+    const visionNotViewable: NotViewableEntry[] = attachmentResults.flatMap((a) =>
+      a.visionDegraded ? [{ path: a.relativePath, reason: a.visionDegraded }] : [],
+    );
+    const visionPromptInfo = visionImages.length > 0 || visionNotViewable.length > 0
+      ? {
+          inlineFilenames: visionImages.map((v) => v.filename),
+          notViewable: visionNotViewable,
+        }
+      : undefined;
+    if (visionPromptInfo) {
+      console.log(
+        `[attachment-vision] execution=${executionId} inline=${visionImages.length} ` +
+        `(${visionImages.reduce((n, v) => n + v.byteSize, 0)} bytes) ` +
+        `degraded=${JSON.stringify(visionNotViewable.map((d) => `${d.path}:${d.reason}`))}`,
+      );
+    }
     setupTiming.mark("resolve_attachments");
 
     // Phase 5b3: Exact-apply approved whole-file writes (HITL "what you approve
@@ -1094,6 +1124,7 @@ async function executeCursorInner(
       workspaceDirs: blueprint.workspaceDirs,
       workspaceFileRefs: spec.workspaceFileRefs ?? [],
       attachmentPaths,
+      vision: visionPromptInfo,
       pendingApprovals: adjudicatedApprovals,
       appliedToolCallIds,
       interactionMode,
@@ -1111,6 +1142,20 @@ async function executeCursorInner(
       effectivePrompt += `\n\n---\nCRITICAL OUTPUT REQUIREMENT:\nYour final response MUST be a single valid JSON object (no markdown, no commentary, no code fences) that matches this schema:\n${schemaStr}\n\nRespond with ONLY the JSON object. Nothing else.`;
     }
 
+    // Phase 10a1: The turn's vision payload. The invariant is "images
+    // accompany the user's turn message — where the message goes, they go":
+    // every send that delivers this turn's message carries them (the primary
+    // send and both fresh-agent recovery retries, whose empty conversations
+    // genuinely need the re-send), while a HITL re-invocation — whose prompt
+    // carries no user message and whose resumed agent already holds the
+    // images in its native conversation — carries none. Computed ONCE here so
+    // all send sites agree by construction.
+    const turnImages = isHitlReinvocation(approvalDecisions)
+      ? []
+      : toCursorImages(visionImages);
+    const toSendMessage = (sendPrompt: string): string | SDKUserMessage =>
+      turnImages.length > 0 ? { text: sendPrompt, images: turnImages } : sendPrompt;
+
     // Phase 10a2: Log Stigmer preamble size for context trimming diagnostics
     const promptChars = effectivePrompt.length;
     const promptEstimatedTokens = Math.ceil(promptChars / 4);
@@ -1225,7 +1270,7 @@ async function executeCursorInner(
     // The stall watchdog is armed inside consumeCursorTurnStream (it needs the
     // run to cancel), stored on turnState.stallWatchdog so this shared onDelta can
     // reset it and the activity's finally can stop it as a backstop.
-    const run = await resolution.agent.send(effectivePrompt, {
+    const run = await resolution.agent.send(toSendMessage(effectivePrompt), {
       onDelta: (event) => {
         if (!turnFirstEventEmitted) {
           turnFirstEventEmitted = true;
@@ -1596,7 +1641,10 @@ async function executeCursorInner(
       // poisoned-handle path leaked the fresh agent — it closed the stale one.)
       resolution = { ...resolution, agent: freshAgent, agentId: freshAgent.agentId, isNew: true };
       turnState.streamErrorMessage = undefined;
-      const retryRun = await freshAgent.send(retryPrompt, {
+      // The retry carries the turn's images too (same toSendMessage): the
+      // fresh agent's conversation is empty, so skipping them here would
+      // silently lose the user's photo on a recovered turn.
+      const retryRun = await freshAgent.send(toSendMessage(retryPrompt), {
         onDelta: makeCursorTurnOnDelta(onDeltaDeps),
       });
       await consumeCursorTurnStream(retryRun, streamDeps);
@@ -1735,6 +1783,7 @@ async function executeCursorInner(
             workspaceDirs: blueprint.workspaceDirs,
             workspaceFileRefs: spec.workspaceFileRefs ?? [],
             attachmentPaths,
+            vision: visionPromptInfo,
             pendingApprovals: adjudicatedApprovals,
             interactionMode,
             // buildFromPlan was silently dropped here until T03 Sitting 3 —
@@ -2310,6 +2359,12 @@ export interface BuildPromptInput {
   workspaceDirs: string[];
   workspaceFileRefs: string[];
   attachmentPaths: string[];
+  /**
+   * Vision facts for the input-files section (T04): which attachments the
+   * model sees inline and which degraded to path-only. PER-TURN like the
+   * catchup — it rides both the enhanced prompt and a resumed turn's prefix.
+   */
+  vision?: import("./prompt-builder.js").VisionPromptInfo;
   pendingApprovals: import("@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb").PendingApproval[];
   /**
    * Approved whole-file writes the runner already applied itself (exact-apply).
@@ -2372,6 +2427,20 @@ export interface BuildPromptInput {
  * 3. first execution / fresh   -> buildEnhancedPrompt (full instructions +
  *    agent after resume failure   skills; no prior conversation to inherit)
  */
+/**
+ * Whether this activity invocation is a HITL re-invocation — the turn resumes
+ * an agent purely to convey approval decisions, carrying NO user message.
+ * The single discriminator for everything that must ride with the user's
+ * message and nothing else: the reinvocation prompt shape (below) and the
+ * vision payload (images accompany the message; a resumed agent already holds
+ * them in its native conversation).
+ */
+export function isHitlReinvocation(
+  approvalDecisions: Map<string, ApprovalAction> | undefined,
+): approvalDecisions is Map<string, ApprovalAction> {
+  return approvalDecisions !== undefined && approvalDecisions.size > 0;
+}
+
 export function buildPrompt(input: BuildPromptInput): string {
   const {
     resolution,
@@ -2388,12 +2457,10 @@ export function buildPrompt(input: BuildPromptInput): string {
     conversationCatchup,
   } = input;
 
-  const isHitlReinvocation = approvalDecisions !== undefined && approvalDecisions.size > 0;
-
   // HITL reinvocation: the agent is resumed, so its native context carries the
   // prior conversation; the reinvocation prompt conveys the approval decisions
   // (and which approved writes the runner already exact-applied).
-  if (isHitlReinvocation) {
+  if (isHitlReinvocation(approvalDecisions)) {
     return buildReinvocationPrompt(
       input.pendingApprovals,
       approvalDecisions,
@@ -2407,15 +2474,21 @@ export function buildPrompt(input: BuildPromptInput): string {
   // session's first turn: the interaction-mode prefix (a follow-up can switch
   // Agent→Plan mid-session, and for Cursor the prompt is the only plan-mode
   // enforcement), the implement-plan directive (the build turn is usually a
-  // follow-up on a resumed agent), and the conversation catchup (handback
-  // ALWAYS lands mid-session on a resumed agent — this prefix is the property
-  // the metadata lane structurally cannot deliver, cloud DD-006). Catchup
-  // last: it is context, and context sits closest to the task (the enhanced
-  // prompt's own ordering doctrine).
+  // follow-up on a resumed agent), THIS turn's attachments (spec.attachments
+  // is per-execution — a file sent on a follow-up turn materializes for this
+  // turn and would otherwise never be announced at all), and the conversation
+  // catchup (handback ALWAYS lands mid-session on a resumed agent — this
+  // prefix is the property the metadata lane structurally cannot deliver,
+  // cloud DD-006). Catchup last: it is context, and context sits closest to
+  // the task (the enhanced prompt's own ordering doctrine); the input files
+  // precede it because they are this turn's payload, not background.
   if (resolution.reason === "resumed_successfully") {
     const prefixes = [
       formatInteractionModePrefix(interactionMode),
       formatImplementPlanSection(buildFromPlan, attachmentPaths),
+      attachmentPaths.length > 0
+        ? formatInputFiles(attachmentPaths, input.vision)
+        : undefined,
       conversationCatchup !== undefined
         ? formatConversationCatchupSection(conversationCatchup)
         : undefined,
@@ -2438,6 +2511,7 @@ export function buildPrompt(input: BuildPromptInput): string {
     workspaceDirs,
     workspaceFileRefs,
     attachmentPaths,
+    vision: input.vision,
     interactionMode,
     buildFromPlan,
     contextBridge: input.contextBridge,

package/src/activities/execute-cursor/prompt-builder.ts

@@ -32,6 +32,10 @@ import {
   type SenderIdentity,
 } from "../../shared/sender-identity.js";
 import { formatSessionContextText } from "../../shared/session-context.js";
+import {
+  visionDisclosureLines,
+  type NotViewableEntry,
+} from "../../shared/attachment-vision.js";
 import { PLAN_MODE_DIRECTIVE } from "../../shared/plan-mode-prompt.js";
 import {
   buildImplementPlanDirective,
@@ -56,6 +60,17 @@ export interface SkillMetadata {
   path: string;
 }
 
+/**
+ * Vision facts about this turn's attachments, rendered inside the
+ * input-files section: which images the model can see inline (in send
+ * order) and which degraded to the file-pointer story. Derived per turn
+ * from the resolved attachments — never carried across turns.
+ */
+export interface VisionPromptInfo {
+  inlineFilenames: string[];
+  notViewable: NotViewableEntry[];
+}
+
 export interface EnhancedPromptOptions {
   instructions: string;
   userMessage: string;
@@ -76,6 +91,8 @@ export interface EnhancedPromptOptions {
   workspaceDirs: string[];
   workspaceFileRefs: string[];
   attachmentPaths: string[];
+  /** Inline/degraded image facts for the input-files section (T04 vision). */
+  vision?: VisionPromptInfo;
   interactionMode?: InteractionMode;
   /**
    * The execution is a Build-from-plan turn (spec.execution_config
@@ -179,7 +196,7 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
   }
 
   if (options.attachmentPaths.length > 0) {
-    sections.push(formatInputFiles(options.attachmentPaths));
+    sections.push(formatInputFiles(options.attachmentPaths, options.vision));
   }
 
   if (options.workspaceFileRefs.length > 0) {
@@ -462,12 +479,20 @@ export function formatWorkspaceContext(dirs: string[]): string {
   ].join("\n");
 }
 
-export function formatInputFiles(paths: string[]): string {
+export function formatInputFiles(paths: string[], vision?: VisionPromptInfo): string {
   const entries = paths.map((p) => `- \`${p}\``);
+  // The vision lines (shared wording, attachment-vision.ts) tell the model
+  // which of these files it can already SEE inline versus which degraded to
+  // path-only — without them an agent silently ignores a photo the user
+  // believes it can see.
+  const disclosure = vision
+    ? visionDisclosureLines(vision.inlineFilenames, vision.notViewable)
+    : [];
   return [
     "<input_files>",
     "The following files have been provided as inputs. Read them when relevant to the task:",
     ...entries,
+    ...disclosure,
     "</input_files>",
   ].join("\n");
 }

package/src/activities/execute-deep-agent/__tests__/attachment-injector.test.ts

@@ -15,6 +15,10 @@ import {
 } from "../attachment-injector.js";
 import { mockWorkspaceBackend } from "../../../__test-utils__/mock-workspace.js";
 import { makeInMemoryArtifactStorage } from "../../../__test-utils__/fake-artifact-storage.js";
+import {
+  DEEP_AGENT_VISION_PROFILE,
+  VisionBudget,
+} from "../../../shared/attachment-vision.js";
 
 // ── ZIP Construction Helpers ─────────────────────────────────────────
 
@@ -552,6 +556,28 @@ describe("injectAttachments", () => {
     })).rejects.toThrow(/missing storageKey/);
   });
 
+  it("rejects a caller-supplied mountPath that escapes the workspace root", async () => {
+    // `resolveMountPath` only stripped leading slashes, so `..` segments on a
+    // non-`.stigmer/` mount path reached the unchecked join(rootDir, path).
+    const storage = makeMockStorage();
+    storage.download.mockResolvedValue(Buffer.from("owned"));
+    const backend = mockWorkspaceBackend();
+
+    const escapes = ["../../escape.txt", "../etc/evil", "foo/../../bar"];
+    for (const mountPath of escapes) {
+      await expect(injectAttachments({
+        backend,
+        attachments: [makeAttachment({
+          filename: "data.txt",
+          storageKey: "attachments/xyz/data.txt",
+          mountPath,
+        })],
+        storage,
+        isLocalMode: false,
+      })).rejects.toThrow(/mount path .* escapes the workspace root|traversal/i);
+    }
+  });
+
   it("preserves binary content via writeFileBuffer", async () => {
     const binaryContent = Buffer.from([0x00, 0x01, 0xFF, 0xFE, 0x89, 0x50, 0x4E, 0x47]);
     const localFile = join(tempDir, "image.png");
@@ -705,3 +731,162 @@ describe("injectAttachments", () => {
     })).rejects.toThrow(AttachmentValidationError);
   });
 });
+
+// ═══════════════════════════════════════════════════════════════════════
+// Vision selection during injection (T04)
+// ═══════════════════════════════════════════════════════════════════════
+// Vision is strictly additive: every case also asserts the file was written
+// exactly as it would be without a budget.
+
+describe("injectAttachments — vision selection", () => {
+  const PNG_BYTES = Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    Buffer.alloc(56, 0xab),
+  ]);
+  const WEBP_BYTES = Buffer.concat([
+    Buffer.from("RIFF", "ascii"),
+    Buffer.from([0x24, 0x00, 0x00, 0x00]),
+    Buffer.from("WEBP", "ascii"),
+    Buffer.alloc(52, 0xcd),
+  ]);
+
+  it("accepts a PNG into the vision payload (deep-agent profile) and still writes the file", async () => {
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/abc/photo.png", PNG_BYTES);
+
+    const [injected] = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "photo.png",
+        storageKey: "attachments/abc/photo.png",
+        contentType: "image/png",
+      })],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected.vision).toMatchObject({
+      filename: "photo.png",
+      mimeType: "image/png",
+      byteSize: PNG_BYTES.length,
+    });
+    expect(Buffer.from(injected.vision!.base64, "base64").equals(PNG_BYTES)).toBe(true);
+    expect(backend.writeFileBuffer).toHaveBeenCalledWith(".stigmer/inputs/photo.png", PNG_BYTES);
+  });
+
+  it("accepts WebP on the deep-agent profile (unlike the Cursor harness)", async () => {
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/abc/pic.webp", WEBP_BYTES);
+
+    const [injected] = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "pic.webp",
+        storageKey: "attachments/abc/pic.webp",
+        contentType: "image/webp",
+      })],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected.vision?.mimeType).toBe("image/webp");
+  });
+
+  it("carries no vision fields for a non-image attachment", async () => {
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/abc/doc.pdf", Buffer.from("%PDF-1.7"));
+
+    const [injected] = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "doc.pdf",
+        storageKey: "attachments/abc/doc.pdf",
+        contentType: "application/pdf",
+      })],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected.vision).toBeUndefined();
+    expect(injected.visionDegraded).toBeUndefined();
+  });
+
+  it("degrades a declared image whose bytes are not one (type_mismatch)", async () => {
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/abc/photo.jpg", Buffer.from("actually HEIC"));
+
+    const [injected] = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "photo.jpg",
+        storageKey: "attachments/abc/photo.jpg",
+        contentType: "image/jpeg",
+      })],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected.vision).toBeUndefined();
+    expect(injected.visionDegraded).toBe("type_mismatch");
+  });
+
+  it("never offers an extract archive to the budget — extracted files carry no vision fields", async () => {
+    // A PNG inside a ZIP has no attachment-level bytes; the archive rides the
+    // normal extraction story with no vision involvement or disclosure.
+    const zip = makeZip({ "inner.png": PNG_BYTES });
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/abc/bundle.zip", zip);
+
+    const injected = await injectAttachments({
+      backend,
+      attachments: [makeAttachment({
+        filename: "bundle.zip",
+        storageKey: "attachments/abc/bundle.zip",
+        extract: true,
+      })],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE),
+    });
+
+    expect(injected.length).toBeGreaterThan(0);
+    for (const file of injected) {
+      expect(file.vision).toBeUndefined();
+      expect(file.visionDegraded).toBeUndefined();
+    }
+  });
+
+  it("degrades over the total budget in attachment order (budget_exhausted)", async () => {
+    const backend = mockWorkspaceBackend();
+    const storage = makeMockStorage();
+    await storage.upload("attachments/a/a.png", PNG_BYTES);
+    await storage.upload("attachments/b/b.png", PNG_BYTES);
+
+    const injected = await injectAttachments({
+      backend,
+      attachments: [
+        makeAttachment({ filename: "a.png", storageKey: "attachments/a/a.png", contentType: "image/png" }),
+        makeAttachment({ filename: "b.png", storageKey: "attachments/b/b.png", contentType: "image/png" }),
+      ],
+      storage,
+      isLocalMode: false,
+      visionBudget: new VisionBudget(DEEP_AGENT_VISION_PROFILE, {
+        maxImageBytes: PNG_BYTES.length,
+        maxTotalBytes: PNG_BYTES.length,
+      }),
+    });
+
+    expect(injected[0].vision).toBeDefined();
+    expect(injected[1].vision).toBeUndefined();
+    expect(injected[1].visionDegraded).toBe("budget_exhausted");
+  });
+});