@stigmer/runner 3.0.8-dev.20260613085218 → 3.0.9-dev.20260615145121

package/src/activities/execute-deep-agent/__tests__/status-builder.test.ts

@@ -300,7 +300,10 @@ describe("StatusBuilder", () => {
       expect(tc.error).toBe("permission denied");
     });
 
-    it("truncates long results", () => {
+    it("stores the full result faithfully (no builder-level truncation)", () => {
+      // Size-bounding is owned by the persist chokepoint (offload + enforce),
+      // not the builder. The builder must reflect the stream verbatim so binary
+      // content (e.g. a screenshot's base64) survives intact for offload.
       const sb = makeBuilder();
       sb.processEvent(chatStreamEvent("run-1", "text"));
       sb.processEvent(toolStartEvent("tool-run-1", "read"));
@@ -309,8 +312,8 @@ describe("StatusBuilder", () => {
       sb.processEvent(toolEndEvent("tool-run-1", longResult));
 
       const tc = sb.currentStatus.messages[0].toolCalls[0];
-      expect(tc.result.length).toBeLessThan(longResult.length);
-      expect(tc.result).toContain("[truncated:");
+      expect(tc.result).toBe(longResult);
+      expect(tc.result).not.toContain("[truncated:");
     });
 
     it("sets forceNextUpdate", () => {

package/src/activities/execute-deep-agent/__tests__/streaming-v3.test.ts

@@ -524,4 +524,74 @@ describe("streamExecutionV3", () => {
       expect(status.streamingUsage!.inputTokens).toBe(10n);
     });
   });
+
+  describe("image offload through the persist chokepoint", () => {
+    it("offloads an MCP image tool result to a renderable ToolCallOutputRef", async () => {
+      // End-to-end: a tool returns image content blocks; the builder stores them
+      // faithfully (no truncation), and the persist chokepoint offloads the image
+      // to artifact storage so the persisted ToolCall carries outputRef.isImage.
+      const uploads: { key: string; size: number; contentType?: string }[] = [];
+      const artifactStorage = {
+        upload: vi.fn(async (key: string, content: Buffer, contentType?: string) => {
+          uploads.push({ key, size: content.length, contentType });
+          return key;
+        }),
+        getDownloadUrl: vi.fn(async (key: string) => `https://artifacts.local/${key}`),
+        exists: vi.fn(async () => true),
+      } as any;
+
+      const base64 = Buffer.from("PNGBYTES".repeat(64)).toString("base64");
+      const imageEnvelope = {
+        lc: 1,
+        type: "constructor",
+        id: ["langchain_core", "messages", "ToolMessage"],
+        kwargs: {
+          status: "success",
+          content: [{ type: "image", data: base64, mimeType: "image/png" }],
+          tool_call_id: "toolu_1",
+        },
+      };
+
+      const events = [
+        makeEvent(0, "messages", { event: "message-start", run_id: "r1" }),
+        makeToolStartedEvent(1, "screenshot", {}),
+        makeEvent(2, "tools", {
+          event: "tool-finished",
+          tool_call_id: "toolu_1",
+          output: imageEnvelope,
+        }, { namespace: ["tools:toolu_1"] }),
+        makeEvent(3, "messages", { event: "message-finish", run_id: "r1" }),
+      ];
+      const graph = mockV3Graph(events, { messages: [] });
+
+      const persisted: any[] = [];
+      const updateStatus = vi.fn(async (_id: string, status: any) => {
+        persisted.push(status);
+        return { signal: 0 };
+      });
+
+      const promise = streamExecutionV3(baseDeps({
+        agentGraph: graph,
+        client: { updateStatus } as any,
+        offload: { artifactStorage, executionId: "exec-v3-test" },
+      }));
+      await vi.runAllTimersAsync();
+      await promise;
+
+      // Find a persisted snapshot whose tool call carries the image ref.
+      const refTc = persisted
+        .flatMap((s) => s.messages)
+        .flatMap((m: any) => m.toolCalls)
+        .find((tc: any) => tc?.id === "toolu_1" && tc?.outputRef);
+
+      expect(refTc).toBeDefined();
+      expect(refTc.outputRef.isImage).toBe(true);
+      expect(refTc.outputRef.mimeType).toBe("image/png");
+      expect(refTc.outputRef.downloadUrl).toContain("artifacts/exec-v3-test/toolcalls/toolu_1.png");
+      // The base64 must not survive inline on the persisted result.
+      expect(refTc.result).not.toContain(base64);
+      expect(uploads).toHaveLength(1);
+      expect(uploads[0].contentType).toBe("image/png");
+    });
+  });
 });

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

@@ -16,13 +16,14 @@ import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/a
 import { ExecutionPhase, InteractionMode, MessageType, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { activityStarted, activityFinished } from "../../idle-watchdog.js";
 import { persistStatus, slimStatus, utcTimestamp } from "../../shared/status.js";
+import type { ToolOutputOffloadContext } from "../../shared/status-offload.js";
 import { publishPlanArtifact } from "../../shared/plan-artifact.js";
 import { classifyTool } from "../../shared/tool-kind.js";
 import type { Config } from "../../config.js";
 import { StigmerClient } from "../../client/stigmer-client.js";
 import { performSetup, type SetupResult } from "./setup.js";
 import { streamExecution, type StreamResult } from "./streaming.js";
-import { loadStreamingConfig } from "./streaming-scheduler.js";
+import { loadStreamingConfig } from "../../shared/streaming-scheduler.js";
 import { StatusBuilder } from "./status-builder.js";
 import { InlinePublisher } from "./inline-publisher.js";
 import { WriteBackCoordinator } from "./writeback-coordinator.js";
@@ -48,6 +49,16 @@ export function createDeepAgentActivities(config: Config) {
 
         setup = await performSetup({ config, client, executionId, threadId });
 
+        // Single offload context for every persist in this execution: spill
+        // oversized tool outputs (e.g. computer-use screenshots) to artifact
+        // storage so the UI can render them, and keep the status under the
+        // gRPC cap. Threaded into the streaming loop and reused for the
+        // terminal persists below so the guard is never skipped.
+        const statusOffload: ToolOutputOffloadContext = {
+          artifactStorage: setup.artifactStorage,
+          executionId,
+        };
+
         const initialStatus = create(AgentExecutionStatusSchema, {});
         const statusBuilder = new StatusBuilder(executionId, initialStatus);
 
@@ -77,7 +88,7 @@ export function createDeepAgentActivities(config: Config) {
               }),
             ],
           });
-          await persistStatus(client, executionId, failedStatus);
+          await persistStatus(client, executionId, failedStatus, { offload: statusOffload });
           return slimStatus(failedStatus);
         }
 
@@ -113,6 +124,7 @@ export function createDeepAgentActivities(config: Config) {
           client,
           initialStatus,
           streamingConfig,
+          offload: statusOffload,
           gracefulStop: setup.gracefulStop,
           inlinePublisher,
           writebackCoordinator: writebackCoordinator ?? undefined,
@@ -137,7 +149,7 @@ export function createDeepAgentActivities(config: Config) {
 
         if (result.terminalStatus) {
           if (initialStatus.phase === ExecutionPhase.EXECUTION_PAUSED) {
-            await persistStatus(client, executionId, initialStatus);
+            await persistStatus(client, executionId, initialStatus, { offload: statusOffload });
             console.log(`[ExecuteDeepAgent] Paused for execution ${executionId}: events=${result.eventsProcessed}`);
             throw new CancelledFailure("Activity paused by orchestrator");
           }
@@ -189,7 +201,7 @@ export function createDeepAgentActivities(config: Config) {
             }
             initialStatus.messages.push(aiMsg);
 
-            await persistStatus(client, executionId, initialStatus);
+            await persistStatus(client, executionId, initialStatus, { offload: statusOffload });
             return slimStatus(initialStatus);
           }
         }
@@ -257,7 +269,7 @@ export function createDeepAgentActivities(config: Config) {
           });
         }
 
-        await persistStatus(client, executionId, initialStatus);
+        await persistStatus(client, executionId, initialStatus, { offload: statusOffload });
 
         console.log(
           `[ExecuteDeepAgent] Completed for execution ${executionId}: ` +

package/src/activities/execute-deep-agent/status-builder-shared.ts

@@ -69,14 +69,34 @@ export function toBigInt(value: unknown): bigint {
 
 // ── Tool Result Extraction ─────────────────────────────────────────
 
-export const MAX_TOOL_RESULT_CHARS = 50_000;
+/**
+ * Serialize a LangChain message `content` field into the canonical tool-result
+ * string.
+ *
+ * Text-only content is a plain string and passes through unchanged. Multimodal
+ * content (image, or mixed text+image — e.g. a computer-use screenshot) is an
+ * array of content blocks; we serialize the blocks array ITSELF, not the
+ * surrounding message envelope, so the result lands in the exact top-level-array
+ * shape the persist-time offload (`detectImagePayload`/`contentBlocks` in
+ * status-offload.ts) consumes to lift the image out into a renderable
+ * `ToolCallOutputRef`. Serializing the envelope instead would bury the base64
+ * one level deeper and defeat that detection.
+ *
+ * Returns undefined when `content` is neither a string nor an array, letting the
+ * caller fall back to serializing whatever else it holds.
+ */
+function serializeToolContent(content: unknown): string | undefined {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return JSON.stringify(content);
+  return undefined;
+}
 
 export function extractToolResult(data: Record<string, unknown>): string {
   const output = data.output;
   if (typeof output === "string") return output;
   if (typeof output === "object" && output !== null) {
-    const content = (output as Record<string, unknown>).content;
-    if (typeof content === "string") return content;
+    const fromContent = serializeToolContent((output as Record<string, unknown>).content);
+    if (fromContent !== undefined) return fromContent;
   }
   try {
     return JSON.stringify(output ?? data);
@@ -96,9 +116,11 @@ export function extractToolResultV3(output: unknown): string {
     const obj = output as Record<string, unknown>;
     const kwargs = obj.kwargs as Record<string, unknown> | undefined;
     if (kwargs) {
-      if (typeof kwargs.content === "string") return kwargs.content;
+      const fromKwargs = serializeToolContent(kwargs.content);
+      if (fromKwargs !== undefined) return fromKwargs;
     }
-    if (typeof obj.content === "string") return obj.content;
+    const fromContent = serializeToolContent(obj.content);
+    if (fromContent !== undefined) return fromContent;
   }
   try {
     return JSON.stringify(output);

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

@@ -34,7 +34,6 @@ import {
   UsageAccumulator,
   extractToolResult,
   sanitizeArgsPreview,
-  MAX_TOOL_RESULT_CHARS,
 } from "./status-builder-shared.js";
 
 /** Minimal LangGraph streamEvents v2 event shape. */
@@ -290,11 +289,10 @@ export class StatusBuilder {
       tc.status = ToolCallStatus.TOOL_CALL_FAILED;
       tc.error = errorMsg;
     } else {
+      // Faithful result only; payload size is bounded at the persist chokepoint
+      // (see v3 builder note). Truncating here would corrupt image base64.
       tc.status = ToolCallStatus.TOOL_CALL_COMPLETED;
-      const result = extractToolResult(event.data);
-      tc.result = result.length > MAX_TOOL_RESULT_CHARS
-        ? result.slice(0, MAX_TOOL_RESULT_CHARS) + `\n[truncated: ${result.length} chars total]`
-        : result;
+      tc.result = extractToolResult(event.data);
     }
 
     tc.completedAt = utcTimestamp();

package/src/activities/execute-deep-agent/streaming-v3.ts

@@ -16,9 +16,8 @@ import { ExecutionControlSignal, ExecutionPhase } from "@stigmer/protos/ai/stigm
 import { createV3EventRecorder, type V3ProtocolEvent } from "./v3-event-recorder.js";
 import { normalize } from "./v3-protocol-normalizer.js";
 import { V3StatusBuilder } from "./v3-status-builder.js";
-import { StreamingUpdateScheduler } from "./streaming-scheduler.js";
-import { persistWithRetry } from "../../shared/grpc-retry.js";
-import { slimStatus } from "../../shared/status.js";
+import { StreamingUpdateScheduler } from "../../shared/streaming-scheduler.js";
+import { persistStatus, slimStatus } from "../../shared/status.js";
 import { StreamingSideEffects } from "./streaming-side-effects.js";
 import {
   handlePause,
@@ -49,6 +48,7 @@ export async function streamExecutionV3(
     initialStatus,
     streamingConfig,
     retryOptions,
+    offload,
     stallTimeoutMs = DEFAULT_STALL_TIMEOUT_MS,
     heartbeatFn,
     isCancelledFn,
@@ -118,11 +118,11 @@ export async function streamExecutionV3(
         }
 
         statusBuilder.syncSubAgentExecutions();
-        const signal = await persistWithRetry(
+        const signal = await persistStatus(
           client,
           executionId,
           statusBuilder.currentStatus,
-          retryOptions,
+          { offload, retry: retryOptions },
         );
         scheduler.markUpdateSent(eventsProcessed);
 

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

@@ -32,9 +32,10 @@ import {
 import {
   StreamingUpdateScheduler,
   type StreamingConfig,
-} from "./streaming-scheduler.js";
-import { persistWithRetry, type RetryOptions } from "../../shared/grpc-retry.js";
-import { slimStatus, utcTimestamp } from "../../shared/status.js";
+} from "../../shared/streaming-scheduler.js";
+import { type RetryOptions } from "../../shared/grpc-retry.js";
+import { persistStatus, slimStatus, utcTimestamp } from "../../shared/status.js";
+import type { ToolOutputOffloadContext } from "../../shared/status-offload.js";
 import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { GracefulStopMiddleware } from "../../middleware/index.js";
 import type { InlinePublisher } from "./inline-publisher.js";
@@ -59,6 +60,13 @@ export interface StreamDependencies {
   readonly initialStatus: AgentExecutionStatus;
   readonly streamingConfig?: StreamingConfig;
   readonly retryOptions?: RetryOptions;
+  /**
+   * Offload context for the persist chokepoint. When set, oversized tool
+   * outputs (e.g. computer-use screenshots) are spilled to artifact storage so
+   * the UI can render them; when omitted, the aggregate size backstop still
+   * keeps the payload under the gRPC cap.
+   */
+  readonly offload?: ToolOutputOffloadContext;
   readonly stallTimeoutMs?: number;
   /** Temporal heartbeat. Injected so the loop is testable without Temporal. */
   readonly heartbeatFn?: (details: Record<string, unknown>) => void;
@@ -112,6 +120,7 @@ async function streamExecutionV2(
     initialStatus,
     streamingConfig,
     retryOptions,
+    offload,
     stallTimeoutMs = DEFAULT_STALL_TIMEOUT_MS,
     heartbeatFn,
     isCancelledFn,
@@ -179,11 +188,11 @@ async function streamExecutionV2(
           statusBuilder.clearForceFlag();
         }
 
-        const signal = await persistWithRetry(
+        const signal = await persistStatus(
           client,
           executionId,
           statusBuilder.currentStatus,
-          retryOptions,
+          { offload, retry: retryOptions },
         );
         scheduler.markUpdateSent(eventsProcessed);
 

package/src/activities/execute-deep-agent/subagent-tracker.ts

@@ -29,7 +29,7 @@ import {
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { utcTimestamp } from "../../shared/status.js";
 import { classifyTool } from "../../shared/tool-kind.js";
-import { extractToolResultV3, MAX_TOOL_RESULT_CHARS } from "./status-builder-shared.js";
+import { extractToolResultV3 } from "./status-builder-shared.js";
 import type { StigmerRunEvent, V3UsagePayload } from "./v3-events.js";
 
 // ── Per-SubAgent State ───────────────────────────────────────────────────────
@@ -299,11 +299,10 @@ export class SubAgentTracker {
     const tc = state.toolCalls.get(callId);
     if (!tc) return;
 
-    const result = extractToolResultV3(output);
+    // Faithful result only; payload size is bounded at the persist chokepoint
+    // (see v3 builder note). Truncating here would corrupt image base64.
     tc.status = ToolCallStatus.TOOL_CALL_COMPLETED;
-    tc.result = result.length > MAX_TOOL_RESULT_CHARS
-      ? result.slice(0, MAX_TOOL_RESULT_CHARS) + `\n[truncated: ${result.length} chars total]`
-      : result;
+    tc.result = extractToolResultV3(output);
     tc.completedAt = utcTimestamp();
     tc.isStreaming = false;
     state.toolArgBuffers.delete(callId);

package/src/activities/execute-deep-agent/v3-status-builder.ts

@@ -36,7 +36,6 @@ import {
   UsageAccumulator,
   extractToolResultV3,
   sanitizeArgsPreview,
-  MAX_TOOL_RESULT_CHARS,
 } from "./status-builder-shared.js";
 import { SubAgentTracker } from "./subagent-tracker.js";
 
@@ -296,11 +295,12 @@ export class V3StatusBuilder implements ExecutionStatusWriter {
     const tc = this.state.toolCalls.get(callId);
     if (!tc) return;
 
-    const result = extractToolResultV3(output);
+    // Store the faithful result; bounding the gRPC payload is owned solely by
+    // the persist chokepoint (offload + enforce in status.ts/status-offload.ts).
+    // Truncating here would corrupt binary content (e.g. a screenshot's base64)
+    // before offload can lift it into a renderable ToolCallOutputRef.
     tc.status = ToolCallStatus.TOOL_CALL_COMPLETED;
-    tc.result = result.length > MAX_TOOL_RESULT_CHARS
-      ? result.slice(0, MAX_TOOL_RESULT_CHARS) + `\n[truncated: ${result.length} chars total]`
-      : result;
+    tc.result = extractToolResultV3(output);
     tc.completedAt = utcTimestamp();
     tc.isStreaming = false;
     this.state.toolStartTimes.delete(callId);

package/src/config.ts

@@ -28,6 +28,15 @@ import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir, tmpdir } from "node:os";
 
+/**
+ * Default no-progress bound for the Cursor harness stream (ms). Larger than the
+ * shared DEFAULT_STALL_TIMEOUT_MS (120s) because opaque MCP / GUI tool calls
+ * can run for minutes while emitting no stream activity. Single source of truth
+ * for env-loaded ({@link loadConfig}) and options-mapped (runner / manager)
+ * config so the three construction sites never drift.
+ */
+export const DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS = 180_000;
+
 export interface Config {
   readonly taskQueue: string;
   readonly temporalAddress: string;
@@ -61,6 +70,19 @@ export interface Config {
   readonly checkpointerType: "memory" | "http";
   readonly checkpointerProxyEndpoint: string | null;
   readonly primaryModel: string;
+  /**
+   * No-progress bound for the Cursor harness stream (milliseconds). If no
+   * stream event or token delta arrives for this long, the stall watchdog
+   * (see activities/execute-cursor + shared/stall-watchdog.ts) cancels the run
+   * and fails the execution with a StallTimeoutError rather than hanging at
+   * EXECUTION_IN_PROGRESS forever.
+   *
+   * Larger than the shared DEFAULT_STALL_TIMEOUT_MS (120s) because opaque MCP /
+   * GUI tool calls can legitimately run for minutes while emitting no stream
+   * activity. This bounds no-progress time only; it is orthogonal to Temporal's
+   * heartbeatTimeout (process liveness) and the 30s keep-alive heartbeat.
+   */
+  readonly cursorStreamStallTimeoutMs: number;
   /** Shared mutable token reference for dynamic token updates (manager mode). */
   readonly stigmerTokenRef?: { current: string | null };
 }
@@ -119,6 +141,10 @@ export function loadConfig(): Config {
 
   const primaryModel = process.env.STIGMER_PRIMARY_MODEL ?? "gpt-4.1";
 
+  const cursorStreamStallTimeoutMs = process.env.CURSOR_STREAM_STALL_TIMEOUT_MS
+    ? parseInt(process.env.CURSOR_STREAM_STALL_TIMEOUT_MS, 10)
+    : DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS;
+
   return {
     taskQueue,
     temporalAddress,
@@ -135,6 +161,7 @@ export function loadConfig(): Config {
     checkpointerType,
     checkpointerProxyEndpoint,
     primaryModel,
+    cursorStreamStallTimeoutMs,
   };
 }
 

package/src/in-flight.ts

@@ -0,0 +1,71 @@
+/**
+ * Per-task-queue in-flight activity tracking.
+ *
+ * A session/wfexec worker must NOT be torn down while one of its activities
+ * (notably the long-running ExecuteCursor) is still running: doing so abandons
+ * the activity and removes the only poller on its queue, turning a harmless UI
+ * navigation into an "Activity task timed out" dead-end. The activity inbound
+ * interceptor increments on every activity start and decrements on finish;
+ * runner-manager's removeSession/removeWorkflowExecution consult the count and
+ * defer teardown until it drains.
+ *
+ * This lives in its own module (rather than inside the runner-manager closure)
+ * so the interceptor — which has no handle to that closure — and unit tests can
+ * both reach it. Keyed by task queue (`session:{id}` / `wfexec:{id}`), it is
+ * process-global, mirroring the shutdown-signal registry.
+ */
+
+interface InFlightEntry {
+  count: number;
+  /** Invoked once when count returns to 0; used to run a deferred teardown. */
+  onDrained?: () => void;
+}
+
+const registry = new Map<string, InFlightEntry>();
+
+/** Record that an activity started on the given task queue. */
+export function activityStartedOnQueue(taskQueue: string): void {
+  const entry = registry.get(taskQueue) ?? { count: 0 };
+  entry.count++;
+  registry.set(taskQueue, entry);
+}
+
+/**
+ * Record that an activity finished on the given task queue. When the count
+ * returns to zero, any registered drain callback fires exactly once.
+ */
+export function activityFinishedOnQueue(taskQueue: string): void {
+  const entry = registry.get(taskQueue);
+  if (!entry) return;
+  entry.count = Math.max(0, entry.count - 1);
+  if (entry.count === 0 && entry.onDrained) {
+    const onDrained = entry.onDrained;
+    entry.onDrained = undefined;
+    onDrained();
+  }
+}
+
+/** Current number of in-flight activities on the task queue (0 if unknown). */
+export function inFlightCountForQueue(taskQueue: string): number {
+  return registry.get(taskQueue)?.count ?? 0;
+}
+
+/**
+ * Register (or clear) a callback to run when the queue next drains to zero
+ * in-flight activities. No-op if the queue has no entry (count already 0); the
+ * caller handles the already-idle case by tearing down immediately.
+ */
+export function setQueueDrainCallback(taskQueue: string, cb: (() => void) | undefined): void {
+  const entry = registry.get(taskQueue);
+  if (entry) entry.onDrained = cb;
+}
+
+/** Forget all tracking for a queue (called after its worker is torn down). */
+export function forgetQueue(taskQueue: string): void {
+  registry.delete(taskQueue);
+}
+
+/** Test-only: clear the entire registry between cases. */
+export function __resetInFlightRegistryForTests(): void {
+  registry.clear();
+}