@stigmer/runner 3.0.1

package/src/activities/execute-cursor/cursor-event-recorder.ts

@@ -0,0 +1,83 @@
+/**
+ * Cursor SDK event recorder for capturing raw SDKMessage events.
+ *
+ * Activated by the CURSOR_EVENT_RECORD_DIR environment variable. When set,
+ * the Cursor streaming loop records every SDKMessage and flushes them
+ * atomically to a JSONL file after the stream completes.
+ *
+ * This is development infrastructure for validating the agent_id-based
+ * sub-agent routing hypothesis. The captured events reveal whether
+ * sub-agent events carry distinct agent_id values and whether they
+ * flow through the parent's run.stream() at all.
+ *
+ * Mirrors the native harness's v3-event-recorder.ts / V3_EVENT_RECORD_DIR.
+ */
+
+import { writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { SDKMessage } from "@cursor/sdk";
+
+export interface CursorEventRecorder {
+  record(event: SDKMessage, seq: number): void;
+  flush(): Promise<void>;
+}
+
+/**
+ * Create a recorder if CURSOR_EVENT_RECORD_DIR is set, otherwise undefined.
+ * The caller does `recorder?.record(event, seq)` — zero overhead when off.
+ */
+export function createCursorEventRecorder(
+  executionId: string,
+): CursorEventRecorder | undefined {
+  const recordDir = process.env.CURSOR_EVENT_RECORD_DIR;
+  if (!recordDir) return undefined;
+  return new FileCursorEventRecorder(executionId, recordDir);
+}
+
+class FileCursorEventRecorder implements CursorEventRecorder {
+  private readonly lines: string[] = [];
+
+  constructor(
+    private readonly executionId: string,
+    private readonly outputDir: string,
+  ) {}
+
+  record(event: SDKMessage, seq: number): void {
+    const entry = {
+      seq,
+      capturedAt: new Date().toISOString(),
+      type: event.type,
+      agent_id: event.agent_id,
+      run_id: event.run_id,
+      event: safeClone(event),
+    };
+    this.lines.push(JSON.stringify(entry));
+  }
+
+  async flush(): Promise<void> {
+    if (this.lines.length === 0) return;
+
+    await mkdir(this.outputDir, { recursive: true });
+
+    const filePath = join(
+      this.outputDir,
+      `${this.executionId}.cursor-events.jsonl`,
+    );
+
+    await writeFile(filePath, this.lines.join("\n") + "\n");
+    console.log(
+      `CursorEventRecorder: flushed ${this.lines.length} events to ${filePath}`,
+    );
+  }
+}
+
+function safeClone(obj: unknown): unknown {
+  try {
+    return JSON.parse(JSON.stringify(obj));
+  } catch {
+    if (obj && typeof obj === "object") {
+      return { _serializationError: true, keys: Object.keys(obj) };
+    }
+    return { _serializationError: true };
+  }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Cursor mode determination for sessions using HARNESS_CURSOR.
+ *
+ * Cloud Cursor agents are DISABLED platform-wide right now, so every session
+ * — including git-backed ones — runs as a LOCAL Cursor agent.
+ *
+ * Why cloud is disabled: Cursor cloud agents clone repositories via Cursor's
+ * own GitHub App connection and accept no per-request git credential. Stigmer
+ * collects the user's git credentials but has no way to hand them to Cursor's
+ * cloud clone, so git-backed cloud sessions fail for user repos. Until that
+ * credential story is resolved, Stigmer provisions the workspace itself
+ * (including git clones, using the user's GITHUB_TOKEN) and runs a local
+ * Cursor agent against it.
+ */
+
+import { CursorMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+
+/**
+ * Determine the CursorMode for a session.
+ *
+ * Always returns LOCAL while cloud Cursor agents are disabled (see the
+ * file-level note). The parameters are retained so the previous
+ * workspace/flag-based mode-selection logic (preserved in git history) can be
+ * restored when cloud is re-enabled.
+ */
+export function determineCursorMode(
+  _workspaceEntries: WorkspaceEntry[],
+  _cloudModeEnabled: boolean,
+): CursorMode {
+  return CursorMode.LOCAL;
+}
+
+/**
+ * Type guard that returns true when the mode is CLOUD.
+ *
+ * Treats UNSPECIFIED as LOCAL for backward compatibility with sessions
+ * created before the cursor_mode field existed.
+ */
+export function isCloudMode(mode: CursorMode): boolean {
+  return mode === CursorMode.CLOUD;
+}

package/src/activities/execute-cursor/delta-enricher.ts

@@ -0,0 +1,307 @@
+/**
+ * DeltaEnricher processes Cursor SDK InteractionUpdate events to provide
+ * real-time enrichments that the stream channel alone cannot deliver.
+ *
+ * The Cursor SDK provides two concurrent event channels:
+ *   - run.stream() (SDKMessage) — coarse-grained, post-hoc events
+ *   - onDelta (InteractionUpdate) — fine-grained, real-time deltas
+ *
+ * The stream channel remains the source of truth for message construction.
+ * The delta channel provides supplementary real-time signals:
+ *   - shell-output-delta: live stdout/stderr from running shell commands
+ *   - tool-call-started/completed: precise lifecycle timestamps
+ *   - thinking-completed: accurate thinking duration from the SDK
+ *
+ * Concurrency model: Node.js is single-threaded. The onDelta callback fires
+ * between iterations of the for-await stream loop (during event loop yields).
+ * The enricher buffers data internally; the stream loop calls
+ * applyEnrichments() on each iteration to flush buffered state onto the
+ * message array. No locks needed — access is always sequential.
+ *
+ * Design invariant: The enricher never creates messages or tool calls.
+ * It only mutates existing ones that the MessageAccumulator has created.
+ * If a delta arrives before its corresponding stream event (e.g.,
+ * shell-output-delta before tool_call running), the data is buffered
+ * and applied retroactively on the next applyEnrichments() call that
+ * finds the matching ToolCall.
+ */
+
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ToolCallStatus, ToolCallStreamingSource } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { InteractionUpdate } from "@cursor/sdk";
+import { utcTimestamp } from "./message-translator.js";
+
+interface ShellOutputBuffer {
+  chunks: string[];
+  totalLength: number;
+}
+
+interface ToolCallTiming {
+  startedAt?: string;
+  completedAt?: string;
+}
+
+export class DeltaEnricher {
+  private shellOutputByCallId = new Map<string, ShellOutputBuffer>();
+  private timingByCallId = new Map<string, ToolCallTiming>();
+  private thinkingDurationMs: number | undefined;
+  private _isDirty = false;
+  private lastPersistTime = 0;
+  private lastShellCallId: string | undefined;
+
+  /**
+   * Minimum interval between persist-triggering dirty flags (milliseconds).
+   * Prevents excessive backend writes during rapid shell output bursts.
+   * Matches the Python agent-runner's update_scheduler interval.
+   */
+  static readonly PERSIST_DEBOUNCE_MS = 500;
+
+  /**
+   * Process a single InteractionUpdate from the onDelta callback.
+   * Buffers enrichment data for later application by applyEnrichments().
+   *
+   * Called from the onDelta callback (between stream loop iterations).
+   */
+  processDelta(update: InteractionUpdate): void {
+    switch (update.type) {
+      case "shell-output-delta":
+        this.handleShellOutputDelta(update);
+        break;
+      case "tool-call-started":
+        this.handleToolCallStarted(update);
+        break;
+      case "tool-call-completed":
+        this.handleToolCallCompleted(update);
+        break;
+      case "thinking-completed":
+        this.thinkingDurationMs = update.thinkingDurationMs;
+        break;
+    }
+  }
+
+  /**
+   * Apply all buffered enrichments to the current message array.
+   * Called from the stream loop after each processEvent() iteration.
+   *
+   * Returns true if any enrichments were applied (messages were mutated).
+   */
+  applyEnrichments(messages: AgentMessage[]): boolean {
+    let applied = false;
+
+    if (this.shellOutputByCallId.size > 0) {
+      applied = this.applyShellOutput(messages) || applied;
+    }
+
+    if (this.timingByCallId.size > 0) {
+      applied = this.applyTiming(messages) || applied;
+    }
+
+    if (this.thinkingDurationMs !== undefined) {
+      applied = this.applyThinkingDuration(messages) || applied;
+    }
+
+    return applied;
+  }
+
+  /**
+   * Whether the enricher has pending data that warrants an immediate persist.
+   * Only returns true when meaningful UI-visible data has arrived AND the
+   * debounce interval has elapsed since the last persist.
+   */
+  get isDirty(): boolean {
+    if (!this._isDirty) return false;
+    const now = Date.now();
+    return (now - this.lastPersistTime) >= DeltaEnricher.PERSIST_DEBOUNCE_MS;
+  }
+
+  /**
+   * Acknowledge that a persist has occurred. Resets the dirty flag and
+   * records the persist timestamp for debounce calculations.
+   */
+  markPersisted(): void {
+    this._isDirty = false;
+    this.lastPersistTime = Date.now();
+  }
+
+  /**
+   * Finalize streaming state and reconcile tool call statuses.
+   *
+   * Called after the stream loop ends (alongside accumulator.finalize()).
+   * Two passes:
+   *   1. Clear `isStreaming` on all tool calls (existing behavior).
+   *   2. Reconciliation sweep: any tool call still RUNNING with evidence
+   *      of completion (completedAt set or result non-empty) is promoted
+   *      to COMPLETED. This is the catch-all safety net — when the stream
+   *      ends, no tool call should remain in a non-terminal status.
+   */
+  finalize(messages: AgentMessage[]): void {
+    for (const msg of messages) {
+      for (const tc of msg.toolCalls) {
+        if (tc.isStreaming) {
+          tc.isStreaming = false;
+          tc.streamingSource = ToolCallStreamingSource.UNSPECIFIED;
+        }
+
+        if (tc.status === ToolCallStatus.TOOL_CALL_RUNNING && (tc.completedAt || tc.result)) {
+          tc.status = ToolCallStatus.TOOL_CALL_COMPLETED;
+          if (!tc.completedAt) {
+            tc.completedAt = utcTimestamp();
+          }
+          console.log(
+            `DeltaEnricher finalize reconciliation: promoted tool call ` +
+            `${tc.id} (${tc.name}) from RUNNING to COMPLETED`,
+          );
+        }
+      }
+    }
+  }
+
+  private handleShellOutputDelta(
+    update: Extract<InteractionUpdate, { type: "shell-output-delta" }>,
+  ): void {
+    const event = update.event;
+    const text = extractShellOutputText(event);
+    if (!text) return;
+
+    const callId = extractCallIdFromShellEvent(event) ?? this.lastShellCallId;
+    if (!callId) return;
+
+    let buffer = this.shellOutputByCallId.get(callId);
+    if (!buffer) {
+      buffer = { chunks: [], totalLength: 0 };
+      this.shellOutputByCallId.set(callId, buffer);
+    }
+
+    buffer.chunks.push(text);
+    buffer.totalLength += text.length;
+    this._isDirty = true;
+  }
+
+  private handleToolCallStarted(
+    update: Extract<InteractionUpdate, { type: "tool-call-started" }>,
+  ): void {
+    const timing = this.getOrCreateTiming(update.callId);
+    timing.startedAt = utcTimestamp();
+
+    if (update.toolCall.type === "shell") {
+      this.lastShellCallId = update.callId;
+    }
+  }
+
+  private handleToolCallCompleted(
+    update: Extract<InteractionUpdate, { type: "tool-call-completed" }>,
+  ): void {
+    const timing = this.getOrCreateTiming(update.callId);
+    timing.completedAt = utcTimestamp();
+  }
+
+  private getOrCreateTiming(callId: string): ToolCallTiming {
+    let timing = this.timingByCallId.get(callId);
+    if (!timing) {
+      timing = {};
+      this.timingByCallId.set(callId, timing);
+    }
+    return timing;
+  }
+
+  private applyShellOutput(messages: AgentMessage[]): boolean {
+    let applied = false;
+
+    for (const [callId, buffer] of this.shellOutputByCallId) {
+      const tc = findToolCallById(messages, callId);
+      if (!tc) continue;
+
+      const content = buffer.chunks.join("");
+      tc.result = content;
+      tc.isStreaming = true;
+      tc.streamingSource = ToolCallStreamingSource.OUTPUT;
+
+      buffer.chunks = [content];
+      applied = true;
+    }
+
+    return applied;
+  }
+
+  private applyTiming(messages: AgentMessage[]): boolean {
+    let applied = false;
+
+    for (const [callId, timing] of this.timingByCallId) {
+      const tc = findToolCallById(messages, callId);
+      if (!tc) continue;
+
+      if (timing.startedAt && !tc.startedAt) {
+        tc.startedAt = timing.startedAt;
+        applied = true;
+      }
+      if (timing.completedAt && !tc.completedAt) {
+        tc.completedAt = timing.completedAt;
+        applied = true;
+      }
+      // Promote status when the delta channel reports completion but
+      // the stream channel has not yet delivered the status update.
+      // Only promotes RUNNING -> COMPLETED; never overwrites terminal
+      // states (FAILED, SKIPPED) that carry richer semantics.
+      if (timing.completedAt && tc.status === ToolCallStatus.TOOL_CALL_RUNNING) {
+        tc.status = ToolCallStatus.TOOL_CALL_COMPLETED;
+        applied = true;
+      }
+
+      this.timingByCallId.delete(callId);
+    }
+
+    return applied;
+  }
+
+  private applyThinkingDuration(_messages: AgentMessage[]): boolean {
+    // Log thinking duration for observability. No proto field exists for this;
+    // adding one is a future enhancement (requires proto + UI changes).
+    if (this.thinkingDurationMs !== undefined) {
+      console.log(`DeltaEnricher: thinking completed in ${this.thinkingDurationMs}ms`);
+      this.thinkingDurationMs = undefined;
+      return true;
+    }
+    return false;
+  }
+}
+
+function findToolCallById(messages: AgentMessage[], callId: string) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    for (const tc of messages[i].toolCalls) {
+      if (tc.id === callId) return tc;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Extract displayable text from a shell-output-delta event payload.
+ *
+ * The Cursor SDK's shell-output-delta event carries a generic
+ * Record<string, unknown>. Based on observed payloads, the structure is:
+ *   { type: "stdout" | "stderr", data: string }
+ * or sometimes:
+ *   { output: string }
+ *
+ * This function handles both shapes defensively.
+ */
+function extractShellOutputText(event: Record<string, unknown>): string {
+  if (typeof event.data === "string") return event.data;
+  if (typeof event.output === "string") return event.output;
+  if (typeof event.text === "string") return event.text;
+  return "";
+}
+
+/**
+ * Extract the tool call ID from a shell-output-delta event payload.
+ *
+ * The event may carry callId directly, or we may need to match by
+ * context. Based on observed payloads:
+ *   { callId: string, type: "stdout", data: string }
+ */
+function extractCallIdFromShellEvent(event: Record<string, unknown>): string | undefined {
+  if (typeof event.callId === "string") return event.callId;
+  if (typeof event.call_id === "string") return event.call_id;
+  if (typeof event.id === "string") return event.id;
+  return undefined;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Resolve execution environment variables from the ExecutionContext.
+ *
+ * Mirrors the Python agent-runner's environment.py: fetches the merged,
+ * decrypted env vars from the backend so MCP servers receive credentials
+ * (e.g. API keys for HTTP headers, secrets for stdio subprocesses).
+ */
+
+import type { StigmerClient } from "../../client/stigmer-client.js";
+
+export interface EnvResult {
+  envVars: Record<string, string>;
+  secretKeys: Set<string>;
+}
+
+/**
+ * Fetch and extract env vars from the ExecutionContext for a given execution.
+ *
+ * Returns an empty env if no ExecutionContext exists (e.g. executions
+ * without any configured secrets or env vars).
+ */
+export async function resolveExecutionEnv(
+  client: StigmerClient,
+  executionId: string,
+): Promise<EnvResult> {
+  let execCtx;
+  try {
+    execCtx = await client.getExecutionContextByExecutionId(executionId);
+  } catch (err) {
+    const code = (err as { code?: number })?.code;
+    // NOT_FOUND (5) is expected for executions without env vars
+    if (code === 5) {
+      console.log(
+        `No ExecutionContext found for execution ${executionId} — ` +
+          `proceeding with empty environment.`,
+      );
+      return { envVars: {}, secretKeys: new Set() };
+    }
+    throw err;
+  }
+
+  const envVars: Record<string, string> = {};
+  const secretKeys = new Set<string>();
+  const data = execCtx.spec?.data;
+
+  if (data) {
+    for (const [key, execValue] of Object.entries(data)) {
+      envVars[key] = execValue.value;
+      if (execValue.isSecret) {
+        secretKeys.add(key);
+      }
+    }
+  }
+
+  console.log(
+    `Resolved environment from ExecutionContext: ` +
+      `context_id=${execCtx.metadata?.id}, ` +
+      `env_count=${Object.keys(envVars).length}, ` +
+      `secret_count=${secretKeys.size}, ` +
+      `keys=[${Object.keys(envVars).sort().join(", ")}]`,
+  );
+
+  return { envVars, secretKeys };
+}