@stigmer/runner 3.8.0 → 3.10.0

package/README.md

@@ -170,8 +170,8 @@ All configuration is environment-driven. Names and defaults below are verified a
 | Variable | Applies to | Required | Default | Purpose |
 |----------|-----------|----------|---------|---------|
 | `ARTIFACT_STORAGE_TYPE` | All | No | `proxy` if `STIGMER_PROXY_ENDPOINT` is set, else `local` | Selects the artifact backend: `local` (filesystem, served by the Stigmer backend) or `proxy` (presigned URLs via the proxy). An explicit value always wins. Storage follows transport, not execution location. |
-| `LOCAL_ARTIFACT_PATH` | Local storage | No | `/var/stigmer/artifacts` | Filesystem path for the local artifact backend. |
-| `LOCAL_ARTIFACT_SERVE_URL` | Local storage | No | `http://localhost:7235` | Base URL the local backend uses to construct artifact download URLs. |
+| `LOCAL_ARTIFACT_PATH` | Local storage | No | `~/.stigmer/data/artifacts` | Filesystem root of the local artifact store. **Must equal the stigmer-server's `ARTIFACT_LOCAL_BASE_PATH`** — in local mode the server writes an artifact to `<ARTIFACT_LOCAL_BASE_PATH>/<key>` and the runner reads it from `<LOCAL_ARTIFACT_PATH>/<key>`, so a mismatch makes every storage-key attachment and offload fail to resolve. The defaults align out of the box; the CLI local daemon sets both explicitly. |
+| `LOCAL_ARTIFACT_SERVE_URL` | Local storage | No | `http://localhost:7235` | Base URL of the server's artifact HTTP file server (its `ARTIFACT_HTTP_PORT`, default `GRPC_PORT + 1`). Used for blob downloads; the runner's own read-back goes straight to disk. |
 
 ### Claim-check (large Temporal payloads)
 

package/dist/.build-fingerprint

@@ -1 +1 @@
-{"hash":"6786feeec9bc110d","builtAt":"2026-08-08T15:50:14.283Z","fileCount":274}
+{"hash":"a2b4e31e40541bd8","builtAt":"2026-08-10T13:04:56.756Z","fileCount":275}

package/dist/activities/execute-cursor/attachment-resolver.d.ts

@@ -30,10 +30,20 @@
  */
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import { type VisionBudget, type VisionDegradedReason, type VisionImage } from "../../shared/attachment-vision.js";
 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 {
     sessionId: string;
@@ -45,6 +55,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 declare class AttachmentResolutionError extends Error {
     readonly attachmentFilename: string;

package/dist/activities/execute-cursor/attachment-resolver.js

@@ -28,8 +28,9 @@
  * found" class of failure). Any attachment that cannot be materialized aborts
  * 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 { isVisionCandidate, } 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";
 const INPUTS_SUBDIR = "inputs";
@@ -70,9 +71,10 @@ export async function resolveAttachments(attachments, options) {
 async function resolveAttachment(attachment, inputsDir, options) {
     // 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;
         try {
-            await copyFile(attachment.localPath, join(inputsDir, filename));
+            vision = await materializeLocalFile(attachment, filename, inputsDir, options.visionBudget);
         }
         catch (err) {
             throw new AttachmentResolutionError(attachment.filename, `failed to copy local file '${attachment.localPath}': ` +
@@ -81,6 +83,7 @@ async function resolveAttachment(attachment, inputsDir, options) {
         return {
             filename,
             relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+            ...visionOutcomeFields(vision),
         };
     }
     // Universal path: download the uploaded content by storage key.
@@ -91,7 +94,7 @@ async function resolveAttachment(attachment, inputsDir, options) {
         throw new AttachmentResolutionError(attachment.filename, `artifact storage is unavailable, so this attachment ` +
             `(key: ${attachment.storageKey}) cannot be downloaded`);
     }
-    const filename = attachment.filename || basename(attachment.storageKey);
+    const filename = safeInputName(attachment.filename || attachment.storageKey);
     let content;
     try {
         content = await options.storage.download(attachment.storageKey);
@@ -101,9 +104,65 @@ async function resolveAttachment(attachment, inputsDir, options) {
             `${err instanceof Error ? err.message : String(err)}`);
     }
     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, filename, inputsDir, visionBudget) {
+    const dest = join(inputsDir, filename);
+    if (!visionBudget || !isVisionCandidate(attachment.contentType, filename)) {
+        await copyFile(attachment.localPath, dest);
+        return undefined;
+    }
+    // Blind-model check BEFORE the size check: a blind model's oversized image
+    // must report the honest model_no_vision reason, never too_large's "resend
+    // smaller" advice — and an in-cap image needn't be read at all.
+    if (visionBudget.modelCannotSee()) {
+        await copyFile(attachment.localPath, dest);
+        return visionBudget.offerBlind();
+    }
+    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) {
+    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) {
+    const name = basename(raw);
+    if (name === "" || name === "." || name === "..") {
+        throw new AttachmentResolutionError(raw, `'${raw}' does not yield a usable filename for materialization`);
+    }
+    return name;
+}
 //# sourceMappingURL=attachment-resolver.js.map

package/dist/activities/execute-cursor/attachment-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"attachment-resolver.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/attachment-resolver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"attachment-resolver.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/attachment-resolver.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-cursor/index.d.ts

@@ -53,6 +53,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).
@@ -114,4 +120,13 @@ 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 declare function isHitlReinvocation(approvalDecisions: Map<string, ApprovalAction> | undefined): approvalDecisions is Map<string, ApprovalAction>;
 export declare function buildPrompt(input: BuildPromptInput): string;

package/dist/activities/execute-cursor/index.js

@@ -47,6 +47,8 @@ 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 } from "../../shared/artifact-storage.js";
+import { CURSOR_VISION_PROFILE, VisionBudget, toCursorImages, } from "../../shared/attachment-vision.js";
+import { getModelVisionCapability } from "../../shared/model-registry.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
 import { DeltaEnricher } from "./delta-enricher.js";
 import { TodoTracker } from "./todo-tracker.js";
@@ -67,7 +69,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 { acquireWorkspaceLock, WorkspaceLockCancelledError, WorkspaceLockTimeoutError, } from "../../shared/workspace/workspace-lock.js";
@@ -631,14 +633,40 @@ turnSeq) {
         setupTiming.mark("resolve_skills");
         // 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).
+        // The budget also carries the requested model's registry vision
+        // capability, looked up from the raw executionConfig name — full model
+        // validation (Phase 6) isn't needed for this, and ""/"default" (the Auto
+        // pool) resolves to unknown, which the policy treats as sighted.
+        const visionBudget = new VisionBudget(CURSOR_VISION_PROFILE, {
+            modelVision: await getModelVisionCapability(spec.executionConfig?.modelName ?? ""),
+        });
         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 = 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
         // is what gets applied"). The Cursor deny-only harness reinvokes the model,
@@ -917,6 +945,7 @@ turnSeq) {
             workspaceDirs: blueprint.workspaceDirs,
             workspaceFileRefs: spec.workspaceFileRefs ?? [],
             attachmentPaths,
+            vision: visionPromptInfo,
             pendingApprovals: adjudicatedApprovals,
             appliedToolCallIds,
             interactionMode,
@@ -932,6 +961,18 @@ turnSeq) {
             const schemaStr = JSON.stringify(structuredOutputSchema, null, 2);
             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) => 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);
@@ -1032,7 +1073,7 @@ turnSeq) {
         // 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;
@@ -1349,7 +1390,10 @@ turnSeq) {
             // 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);
@@ -1465,6 +1509,7 @@ turnSeq) {
                         workspaceDirs: blueprint.workspaceDirs,
                         workspaceFileRefs: spec.workspaceFileRefs ?? [],
                         attachmentPaths,
+                        vision: visionPromptInfo,
                         pendingApprovals: adjudicatedApprovals,
                         interactionMode,
                         // buildFromPlan was silently dropped here until T03 Sitting 3 —
@@ -1954,13 +1999,23 @@ import { jsonSchemaToZod } from "../../shared/json-schema-to-zod.js";
  * 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) {
+    return approvalDecisions !== undefined && approvalDecisions.size > 0;
+}
 export function buildPrompt(input) {
     const { resolution, approvalDecisions, instructions, userMessage, skills, subAgents, workspaceDirs, workspaceFileRefs, attachmentPaths, interactionMode, buildFromPlan, 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, input.appliedToolCallIds);
     }
     // A successfully resumed agent carries its own conversation context via the
@@ -1969,15 +2024,21 @@ export function buildPrompt(input) {
     // 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,
@@ -1999,6 +2060,7 @@ export function buildPrompt(input) {
         workspaceDirs,
         workspaceFileRefs,
         attachmentPaths,
+        vision: input.vision,
         interactionMode,
         buildFromPlan,
         contextBridge: input.contextBridge,