@stigmer/runner 3.7.0 → 3.9.0

package/src/activities/execute-deep-agent/hitl.ts

@@ -37,10 +37,15 @@ const ACTION_MAP: ReadonlyMap<ApprovalAction, string> = new Map([
   [ApprovalAction.REJECT, "reject"],
 ]);
 
-export interface ResumeResult {
-  readonly graphInput: Command | Record<string, unknown>;
-  readonly isResumeFromApproval: boolean;
-}
+/**
+ * Either a genuine approval resume carrying the `Command(resume)` payload, or
+ * not one — in which case the caller uses `setup.langgraphInput` (the single
+ * construction site of the turn's user message; this module deliberately does
+ * NOT build a second copy that could drift from it).
+ */
+export type ResumeResult =
+  | { readonly isResumeFromApproval: true; readonly graphInput: Command }
+  | { readonly isResumeFromApproval: false };
 
 export interface GraphStateSnapshot {
   readonly values: Record<string, unknown>;
@@ -71,8 +76,8 @@ export interface InterruptValue {
  * Resolve the resume input for a reinvocation after approval.
  *
  * Returns a `Command(resume=...)` if there are pending interrupts with
- * matching approval decisions, or a fresh user message input if this is
- * not a resume scenario.
+ * matching approval decisions; otherwise reports "not a resume" and the
+ * caller falls back to `setup.langgraphInput`.
  *
  * The graph checkpoint snapshot is read once by the caller and passed in: the
  * same snapshot also decides whether status must be seeded from the persisted
@@ -82,22 +87,15 @@ export interface InterruptValue {
 export function resolveResumeInput(
   execution: AgentExecution,
   graphState: GraphStateSnapshot,
-  userMessage: string,
 ): ResumeResult {
   const pendingInterrupts = extractPendingInterrupts(graphState);
   if (pendingInterrupts.length === 0) {
-    return {
-      graphInput: { messages: [{ role: "user", content: userMessage }] },
-      isResumeFromApproval: false,
-    };
+    return { isResumeFromApproval: false };
   }
 
   const decisions = extractApprovalDecisions(execution);
   if (decisions.size === 0) {
-    return {
-      graphInput: { messages: [{ role: "user", content: userMessage }] },
-      isResumeFromApproval: false,
-    };
+    return { isResumeFromApproval: false };
   }
 
   const resumeDict: Record<string, { action: string; comment?: string }> = {};
@@ -117,10 +115,7 @@ export function resolveResumeInput(
   }
 
   if (Object.keys(resumeDict).length === 0) {
-    return {
-      graphInput: { messages: [{ role: "user", content: userMessage }] },
-      isResumeFromApproval: false,
-    };
+    return { isResumeFromApproval: false };
   }
 
   console.log(

package/src/activities/execute-deep-agent/index.ts

@@ -161,12 +161,11 @@ export function createDeepAgentActivities(config: Config) {
           unattended: setup.unattended,
         });
 
-        const resume = resolveResumeInput(
-          setup.execution,
-          graphState,
-          setup.execution.spec!.message,
-        );
+        const resume = resolveResumeInput(setup.execution, graphState);
 
+        // Not an approval resume -> setup.langgraphInput, the single
+        // construction site of the turn's user message (string or multimodal
+        // content blocks when the turn carries inline images).
         const effectiveInput = resume.isResumeFromApproval
           ? resume.graphInput
           : setup.langgraphInput;

package/src/activities/execute-deep-agent/mcp-gate.ts

@@ -0,0 +1,37 @@
+/**
+ * The deep-agent harness's MCP gate: whether this execution enters MCP
+ * resolution at all (resolve, backfill, synthesized-attachment
+ * injection, connect). Unlike the Cursor harness — which resolves MCP
+ * unconditionally — deep-agent skips the whole block when no tool
+ * source exists, so EVERY tool source must appear here or its tools are
+ * silently dropped for exactly the agents whose only source it is
+ * (proactive-messaging DD-006 D7 learned this for channel messaging).
+ *
+ * Extracted from setup.ts as a pure function because setup.ts is
+ * untestable at file load (its import graph is why no setup.test.ts
+ * exists); the gate is the one piece whose regression is silent, so it
+ * gets its own module and an arm-by-arm test.
+ */
+
+/** One flag per tool source. Adding a source? It gates here or it is dropped. */
+export interface McpToolSources {
+  /** Declared MCP server usages (agent spec + session spec). */
+  readonly mcpServerUsageCount: number;
+  /** Declared datastore usages (the records attachment, T05). */
+  readonly datastoreUsageCount: number;
+  /** Serving proactive-messaging channels (the channels attachment, DD-006). */
+  readonly channelMessagingCount: number;
+  /** The serving channel id when this session IS a live channel
+   *  conversation (the conversation attachment, DD-008). */
+  readonly conversationChannelId: string | undefined;
+}
+
+/** True when any tool source demands MCP resolution and connect. */
+export function shouldConnectMcp(sources: McpToolSources): boolean {
+  return (
+    sources.mcpServerUsageCount > 0 ||
+    sources.datastoreUsageCount > 0 ||
+    sources.channelMessagingCount > 0 ||
+    sources.conversationChannelId !== undefined
+  );
+}

package/src/activities/execute-deep-agent/prompt-builder.ts

@@ -11,11 +11,16 @@ import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecuti
 import type { ProvisionResult, GitMetadata } from "../../shared/workspace/types.js";
 import { SourceType } from "../../shared/workspace/types.js";
 import { formatContextBridgeText } from "../../shared/context-bridge.js";
+import { formatConversationCatchupText } from "../../shared/conversation-catchup.js";
 import {
   formatSenderIdentityText,
   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,
@@ -107,6 +112,12 @@ export interface PromptBuilderInput {
   workspaceFileRefs: string[];
   workspaceRoot: string;
   injectedFiles: InjectedFile[];
+  /**
+   * Vision facts about this turn's attachments (T04): which images the model
+   * sees inline in the user message and which degraded to path-only.
+   * Rendered inside the Input Files section.
+   */
+  vision?: VisionPromptInfo;
   /**
    * The execution's interaction mode. PLAN appends the shared plan-mode
    * directive so the model knows the turn's deliverable is a plan document.
@@ -157,6 +168,17 @@ export interface InjectedFile {
   size?: number | null;
 }
 
+/**
+ * Which images ride the user message inline (in send order) and which
+ * degraded to the file-pointer story — the shared vision wording
+ * (attachment-vision.ts) keeps this prompt and the Cursor harness's
+ * input-files section telling the agent the same thing.
+ */
+export interface VisionPromptInfo {
+  inlineFilenames: string[];
+  notViewable: NotViewableEntry[];
+}
+
 /**
  * Assemble the full system prompt from base instructions and contextual
  * sections. Pure function with no I/O.
@@ -195,7 +217,7 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
   }
 
   if (input.injectedFiles.length > 0) {
-    prompt += buildInjectedFilesSection(input.injectedFiles);
+    prompt += buildInjectedFilesSection(input.injectedFiles, input.vision);
   }
 
   if (input.senderIdentity) {
@@ -241,9 +263,28 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
   return prompt;
 }
 
+/**
+ * Compose the turn's USER MESSAGE for the graph invocation: the framed
+ * conversation catchup (cloud DD-006), when present, prepended to the
+ * customer's message. In the user message and never the system prompt (A27):
+ * the system prompt is rebuilt per invocation and would forget the digest one
+ * turn later, while a message enters the checkpointer with the turn and
+ * persists in history — the same durability the cursor harness gets from its
+ * prompt prefix. The caller's `spec.message` is never mutated; the prepend
+ * exists only in the graph input.
+ */
+export function composeUserMessage(
+  message: string,
+  conversationCatchup: string | undefined,
+): string {
+  return conversationCatchup
+    ? `${formatConversationCatchupText(conversationCatchup)}\n\n---\n\n${message}`
+    : message;
+}
+
 function buildWorkspacePromptSection(
-  provisionResults: ProvisionResult[],
-  containerRoot: string,
+    provisionResults: ProvisionResult[],
+    containerRoot: string,
 ): string {
   if (provisionResults.length === 0) return "";
 
@@ -354,7 +395,10 @@ function buildReferencedFilesSection(
   return section;
 }
 
-function buildInjectedFilesSection(files: InjectedFile[]): string {
+function buildInjectedFilesSection(
+  files: InjectedFile[],
+  vision?: VisionPromptInfo,
+): string {
   let section = "\n\n## Input Files\n\n";
   section +=
     "The following files have been provided as read-only reference " +
@@ -370,5 +414,16 @@ function buildInjectedFilesSection(files: InjectedFile[]): string {
     section += `- \`${f.path}\`${sizeInfo}\n`;
   }
 
+  // The vision lines (shared wording, attachment-vision.ts) tell the model
+  // which of these files it can already SEE inline in the user message versus
+  // which degraded to path-only — without them an agent silently ignores a
+  // photo the user believes it can see.
+  if (vision) {
+    const lines = visionDisclosureLines(vision.inlineFilenames, vision.notViewable);
+    if (lines.length > 0) {
+      section += "\n" + lines.join("\n") + "\n";
+    }
+  }
+
   return section;
 }

package/src/activities/execute-deep-agent/setup.ts

@@ -25,6 +25,7 @@ import type { StigmerClient } from "../../client/stigmer-client.js";
 import { TimingRecorder, emitTimingLog } from "../../shared/cold-start-timing.js";
 import { createCheckpointer } from "../../shared/checkpointer/factory.js";
 import { readContextBridge } from "../../shared/context-bridge.js";
+import { readConversationCatchup } from "../../shared/conversation-catchup.js";
 import { readSenderIdentity } from "../../shared/sender-identity.js";
 import {
   injectCallerIdentityEnv,
@@ -44,7 +45,12 @@ import {
   formatChannelTemplatesSection,
   synthesizeChannelAttachment,
 } from "../../shared/channel-attachment.js";
+import {
+  readChannelConversationId,
+  synthesizeConversationAttachment,
+} from "../../shared/conversation-attachment.js";
 import { injectSynthesizedAttachment } from "../../shared/synthesized-attachment.js";
+import { shouldConnectMcp } from "./mcp-gate.js";
 import { WorkspaceProvisioner } from "../../shared/workspace/provisioner.js";
 import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
 import type { WorkspaceBackend, ProvisionResult } from "../../shared/workspace/types.js";
@@ -59,7 +65,7 @@ import { resolveSessionWorkspaceRoot } from "../../shared/workspace/session-root
 import { buildWorkspaceFileTree } from "../../shared/workspace/file-tree.js";
 import { reportSetupProgress } from "../../shared/status.js";
 import { resolveEnvironment, type EnvironmentResult } from "./environment.js";
-import { buildEnhancedSystemPrompt } from "./prompt-builder.js";
+import { buildEnhancedSystemPrompt, composeUserMessage } from "./prompt-builder.js";
 import { buildMiddlewareStack } from "../../middleware/index.js";
 import type { GracefulStopMiddleware } from "../../middleware/index.js";
 import { createThinkTool, createWebFetchTool, resolveGuardPosture } from "../../tools/index.js";
@@ -93,6 +99,12 @@ import {
 } from "../../shared/skill-writer.js";
 import { filterSkills, SKILL_COUNT_THRESHOLD } from "../../shared/skill-relevance.js";
 import { injectAttachments } from "./attachment-injector.js";
+import {
+  DEEP_AGENT_VISION_PROFILE,
+  VisionBudget,
+  toLangChainImageBlocks,
+  type NotViewableEntry,
+} from "../../shared/attachment-vision.js";
 import { transformAndCompileSubagents } from "./subagent-transformer.js";
 import {
   resolveRecursionLimit,
@@ -361,8 +373,18 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // answer — no tool, no section, execution unharmed.
     const channelMessaging = await discoverChannelMessaging(client, exchangedRunnerToken);
 
+    // The conversation-attachment decision (DD-008 D-c): the channel-id
+    // session label, stamped server-side on every channel session — a
+    // free, synchronous read, so no hoisted discovery needed.
+    const conversationChannelId = readChannelConversationId(session.metadata?.labels);
+
     let resolvedMcpServers: Awaited<ReturnType<typeof resolveMcpServers>> | null = null;
-    if (mcpServerUsages.length > 0 || datastoreUsages.length > 0 || channelMessaging.length > 0) {
+    if (shouldConnectMcp({
+      mcpServerUsageCount: mcpServerUsages.length,
+      datastoreUsageCount: datastoreUsages.length,
+      channelMessagingCount: channelMessaging.length,
+      conversationChannelId,
+    })) {
       await reportSetupProgress(client, executionId, "Connecting tools…");
       const transportPosture = resolveMcpTransportPosture(config.mode);
       // The MCP-bound env map (and ONLY it) carries the reserved
@@ -424,6 +446,21 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
           );
         }
       }
+
+      // The conversation participation attachment (DD-008 D-c) — the
+      // third sibling, same after-backfill rule. HTTP-only: synthesize
+      // answers undefined with no bridge endpoint by design (see
+      // shared/conversation-attachment.ts).
+      const conversationAttachment = synthesizeConversationAttachment(conversationChannelId, {
+        bridgeEndpoint: config.mcpBridgeEndpoint,
+        credential: attachmentCredential,
+        backendEndpoint: config.stigmerBackendEndpoint,
+      });
+      if (conversationAttachment) {
+        backfilledServers = injectSynthesizedAttachment(
+          backfilledServers, conversationAttachment, "conversation participation",
+        );
+      }
       resolvedMcpServers = { resolvedServers: backfilledServers };
       timing.mark("backfill_mcp");
 
@@ -477,14 +514,39 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       timing.mark("resolve_skills");
     }
 
-    // Step 7c: Inject attachments
+    // Step 7c: Inject attachments. 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 attachments = execution.spec!.attachments || [];
+    const visionBudget = new VisionBudget(DEEP_AGENT_VISION_PROFILE);
     const injectedFiles = await injectAttachments({
       backend: workspaceBackend,
       attachments,
       storage: artifactStorage,
       isLocalMode: config.mode === "local",
+      visionBudget,
     });
+    // Vision facts, derived once from the single injection result: the images
+    // the model will see inline (in attachment order) and the ones that
+    // degraded to path-only, disclosed in the system prompt's Input Files
+    // section.
+    const visionImages = injectedFiles.flatMap((f) => (f.vision ? [f.vision] : []));
+    const visionNotViewable: NotViewableEntry[] = injectedFiles.flatMap((f) =>
+      f.visionDegraded ? [{ path: f.path, reason: f.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}`))}`,
+      );
+    }
     timing.mark("inject_attachments");
 
     // Step 8: Build enhanced system prompt
@@ -504,6 +566,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       workspaceFileRefs: execution.spec!.workspaceFileRefs || [],
       workspaceRoot: workspaceBackend.rootDir,
       injectedFiles,
+      vision: visionPromptInfo,
       interactionMode: execution.spec!.executionConfig?.interactionMode,
       buildFromPlan: execution.spec!.executionConfig?.buildFromPlan,
       contextBridge: readContextBridge(session.spec!.metadata),
@@ -743,13 +806,34 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       ...(isPlanMode ? { permissions: planModePermissions } : {}),
     } as Parameters<typeof createDeepAgent>[0]);
 
-    // Step 11: Prepare invocation input and config
-    let userMessage = execution.spec!.message;
+    // Step 11: Prepare invocation input and config. The conversation catchup
+    // (cloud DD-006) rides the USER MESSAGE, not the system prompt — see
+    // composeUserMessage for the durability rationale (A27).
+    let userMessage = composeUserMessage(
+      execution.spec!.message,
+      readConversationCatchup(execution.spec!.conversationCatchup),
+    );
     if (outputSchema) {
       userMessage += `\n\n---\nIMPORTANT: When your analysis is complete, provide your findings as structured output matching the required schema. The system will capture your structured response automatically.`;
     }
+    // With inline images the user message becomes a multimodal content-block
+    // array — image blocks (with filename labels) FIRST, the composed text
+    // last, per Anthropic's images-before-text guidance. Without images the
+    // content stays a plain string, byte-identical to the pre-vision shape.
+    // The LangGraph messages reducer coerces either form into a HumanMessage
+    // untouched (verified against the installed @langchain/langgraph).
     const langgraphInput = {
-      messages: [{ role: "user", content: userMessage }],
+      messages: [
+        {
+          role: "user",
+          content: visionImages.length > 0
+            ? [
+                ...toLangChainImageBlocks(visionImages),
+                { type: "text", text: userMessage },
+              ]
+            : userMessage,
+        },
+      ],
     };
 
     const langgraphConfig: Record<string, unknown> = {

package/src/runner-manager.ts

@@ -332,6 +332,25 @@ export async function createStigmerRunnerManager(
 
   const activities = await createAllActivities(config);
   markBoot("activities_imported");
+  // Surface the resolved artifact store at boot (see runner.ts for rationale):
+  // a path/type misconfiguration is the #285 failure class, and it should be
+  // visible here rather than only when a read fails mid-execution.
+  try {
+    const { loadArtifactStorageConfig } = await import(
+      "./shared/artifact-storage.js"
+    );
+    const artifactCfg = loadArtifactStorageConfig(config);
+    console.log(
+      `[runner-manager] Artifact store: type=${artifactCfg.type}` +
+        (artifactCfg.type === "local"
+          ? ` | root=${artifactCfg.localPath}`
+          : ` | proxy=${artifactCfg.proxyEndpoint ?? "(unset)"}`),
+    );
+  } catch (err) {
+    console.warn(
+      `[runner-manager] Artifact store: could not resolve config for boot log: ${err}`,
+    );
+  }
   const payloadCodec = await createPayloadCodec(config);
 
   const connection = await NativeConnection.connect({

package/src/runner.ts

@@ -282,6 +282,25 @@ export async function createStigmerRunner(
       `Mode: ${config.mode} | ` +
       `Max concurrency: ${config.maxConcurrentActivities}`,
   );
+  // Surface the resolved artifact store at boot so a path/type misconfiguration
+  // (the #285 class of failure) is visible immediately instead of only when an
+  // attachment or offload read fails minutes into an execution.
+  try {
+    const { loadArtifactStorageConfig } = await import(
+      "./shared/artifact-storage.js"
+    );
+    const artifactCfg = loadArtifactStorageConfig(config);
+    console.log(
+      `[runner] Artifact store: type=${artifactCfg.type}` +
+        (artifactCfg.type === "local"
+          ? ` | root=${artifactCfg.localPath}`
+          : ` | proxy=${artifactCfg.proxyEndpoint ?? "(unset)"}`),
+    );
+  } catch (err) {
+    console.warn(
+      `[runner] Artifact store: could not resolve config for boot log: ${err}`,
+    );
+  }
 
   const payloadCodec = await createPayloadCodec(config);
 

package/src/shared/__tests__/artifact-storage.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdtemp, rm, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { tmpdir } from "node:os";
+import { tmpdir, homedir } from "node:os";
 import {
   LocalArtifactStorage,
   ProxyArtifactStorage,
@@ -101,6 +101,63 @@ describe("LocalArtifactStorage", () => {
   });
 });
 
+// ── LocalArtifactStorage path containment ────────────────────────────
+
+describe("LocalArtifactStorage path containment", () => {
+  let tempDir: string;
+  let storage: LocalArtifactStorage;
+
+  // Keys that clean to a location outside the storage root. `join(base, key)`
+  // silently resolves `..` segments, so without a containment check these would
+  // read or write outside the store — the runner-side mirror of the Go finding.
+  const escapingKeys = [
+    "../escape.txt",
+    "../../escape.txt",
+    "attachments/x/../../../../escape.txt",
+    "a/b/../../../escape.txt",
+  ];
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "artifact-contain-"));
+    storage = new LocalArtifactStorage(tempDir, "http://localhost:7235");
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("refuses to upload a key that escapes the storage root", async () => {
+    for (const key of escapingKeys) {
+      await expect(storage.upload(key, Buffer.from("owned"))).rejects.toThrow(
+        /outside the artifact storage root/,
+      );
+    }
+  });
+
+  it("refuses to download a key that escapes the storage root", async () => {
+    for (const key of escapingKeys) {
+      await expect(storage.download(key)).rejects.toThrow(
+        /outside the artifact storage root/,
+      );
+    }
+  });
+
+  it("refuses exists() for a key that escapes the storage root", async () => {
+    for (const key of escapingKeys) {
+      await expect(storage.exists(key)).rejects.toThrow(
+        /outside the artifact storage root/,
+      );
+    }
+  });
+
+  it("still allows keys with `..` segments that stay inside the root", async () => {
+    // Containment rejects escapes, not the mere presence of a `..` segment.
+    const key = "attachments/x/../y/plan.md";
+    await storage.upload(key, Buffer.from("ok"));
+    expect((await storage.download(key)).toString()).toBe("ok");
+  });
+});
+
 // ── ProxyArtifactStorage ─────────────────────────────────────────────
 
 describe("ProxyArtifactStorage", () => {
@@ -480,6 +537,24 @@ describe("loadArtifactStorageConfig", () => {
     });
     expect(cfg.type).toBe("proxy");
   });
+
+  // #285: the local default must be the SAME directory the stigmer-server
+  // writes to (~/.stigmer/data/artifacts), not the container-era
+  // /var/stigmer/artifacts. Asserting the resolved path — not just the type —
+  // is the guard that would have caught the original drift.
+  it("defaults localPath to the shared ~/.stigmer/data/artifacts root and serveUrl to :7235", () => {
+    const cfg = loadArtifactStorageConfig(baseConfig);
+    expect(cfg.localPath).toBe(join(homedir(), ".stigmer", "data", "artifacts"));
+    expect(cfg.localServeUrl).toBe("http://localhost:7235");
+  });
+
+  it("respects explicit LOCAL_ARTIFACT_PATH and LOCAL_ARTIFACT_SERVE_URL", () => {
+    process.env.LOCAL_ARTIFACT_PATH = "/custom/artifacts";
+    process.env.LOCAL_ARTIFACT_SERVE_URL = "http://localhost:9999";
+    const cfg = loadArtifactStorageConfig(baseConfig);
+    expect(cfg.localPath).toBe("/custom/artifacts");
+    expect(cfg.localServeUrl).toBe("http://localhost:9999");
+  });
 });
 
 // ── resolveUsableArtifactStorage (DD-26 follow-up #1) ─────────────────