@stigmer/runner 3.0.1

package/src/activities/execute-cursor/todo-tracker.ts

@@ -0,0 +1,133 @@
+/**
+ * Tracks todo tool call events from the Cursor SDK stream and populates
+ * AgentExecutionStatus.todos with structured TodoItem protos.
+ *
+ * The Cursor SDK emits todo updates as tool_call events. Historically the
+ * tool was named "TodoWrite"; current SDK versions use "updateTodos" with
+ * a slightly different args schema (camelCase statuses, no per-item id).
+ * This tracker accepts both names for resilience across SDK versions.
+ *
+ * The MessageAccumulator captures the same event as a MESSAGE_TOOL
+ * (preserving visibility in the message thread). This tracker is a
+ * parallel extraction into the proto map that downstream consumers
+ * (React TodoList, CLI emitTodoEvents) already know how to render.
+ *
+ * Follows the same single-responsibility pattern as DeltaEnricher:
+ * the orchestrator (execute-cursor.ts) wires it into the event loop.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import { TodoItemSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
+import type { TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/todo_pb";
+import { TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { SDKMessage } from "@cursor/sdk";
+import { utcTimestamp } from "./message-translator.js";
+
+const TODO_TOOL_NAMES = new Set(["TodoWrite", "updateTodos"]);
+
+const STATUS_MAP: Record<string, TodoStatus> = {
+  pending: TodoStatus.TODO_PENDING,
+  in_progress: TodoStatus.TODO_IN_PROGRESS,
+  inprogress: TodoStatus.TODO_IN_PROGRESS,
+  completed: TodoStatus.TODO_COMPLETED,
+  cancelled: TodoStatus.TODO_CANCELLED,
+};
+
+interface RawTodoItem {
+  id?: string;
+  content?: string;
+  status?: string;
+  created_at?: string;
+}
+
+export class TodoTracker {
+  private readonly todos: { [key: string]: TodoItem };
+  private _isDirty = false;
+
+  constructor(todos: { [key: string]: TodoItem }) {
+    this.todos = todos;
+  }
+
+  /**
+   * Process a stream event. Only acts on completed todo tool calls
+   * (both legacy "TodoWrite" and current SDK "updateTodos").
+   */
+  processEvent(event: SDKMessage): void {
+    if (event.type !== "tool_call") return;
+    if (!TODO_TOOL_NAMES.has(event.name)) return;
+    if (event.status !== "completed") return;
+
+    const args = this.parseArgs(event.args);
+    if (!args) return;
+
+    const rawTodos = args.todos as RawTodoItem[] | undefined;
+    if (!Array.isArray(rawTodos) || rawTodos.length === 0) {
+      if (args.merge !== true) {
+        this.clearMap();
+        this._isDirty = true;
+      }
+      return;
+    }
+
+    const merge = args.merge === true;
+    const now = utcTimestamp();
+
+    if (!merge) {
+      this.clearMap();
+    }
+
+    for (let i = 0; i < rawTodos.length; i++) {
+      const raw = rawTodos[i];
+      const id = raw.id || `todo-${i}`;
+      const statusStr = (raw.status ?? "pending").toLowerCase();
+      const status = STATUS_MAP[statusStr] ?? TodoStatus.TODO_PENDING;
+
+      const existing = merge ? this.todos[id] : undefined;
+
+      this.todos[id] = create(TodoItemSchema, {
+        id,
+        content: raw.content ?? "",
+        status,
+        createdAt: existing?.createdAt || raw.created_at || now,
+        updatedAt: now,
+      });
+    }
+
+    this._isDirty = true;
+    console.log(
+      `TodoTracker: processed ${rawTodos.length} todo(s) from ${event.name} (merge=${merge})`,
+    );
+  }
+
+  get isDirty(): boolean {
+    return this._isDirty;
+  }
+
+  markPersisted(): void {
+    this._isDirty = false;
+  }
+
+  private parseArgs(args: unknown): { todos?: unknown[]; merge?: boolean } | null {
+    if (args == null) return null;
+
+    if (typeof args === "string") {
+      try {
+        return JSON.parse(args);
+      } catch {
+        return null;
+      }
+    }
+
+    if (typeof args === "object") {
+      return args as { todos?: unknown[]; merge?: boolean };
+    }
+
+    return null;
+  }
+
+  private clearMap(): void {
+    for (const key of Object.keys(this.todos)) {
+      delete this.todos[key];
+    }
+  }
+}

package/src/activities/execute-cursor/usage-accumulator.ts

@@ -0,0 +1,126 @@
+/**
+ * Accumulates per-turn token usage from Cursor SDK onDelta callbacks.
+ *
+ * Designed for the empty {@code turn-ended} handler in execute-cursor.ts.
+ * Each call to {@link addTurn} sums token counts and computes a running
+ * estimated cost from the cursor-runner's local pricing table.
+ *
+ * The snapshot is written to {@code AgentExecutionStatus.streaming_usage}
+ * on every heartbeat, giving the UI real-time streaming visibility.
+ *
+ * This data is display-only. The authoritative billing source is the
+ * BiDi proxy (CursorBidiStreamHandler) which will record usage from the
+ * wire via ProxyUsageReporter once traffic routing (Task 5B) is complete.
+ */
+
+import { getCursorModelPricing, computeTurnCost } from "./model-pricing.js";
+
+export interface TurnUsage {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly cacheReadTokens?: number;
+  readonly cacheWriteTokens?: number;
+}
+
+export interface UsageSnapshot {
+  readonly inputTokens: bigint;
+  readonly outputTokens: bigint;
+  readonly cacheReadTokens: bigint;
+  readonly cacheWriteTokens: bigint;
+  readonly totalTokens: bigint;
+  readonly turnCount: number;
+  readonly estimatedCostUsd: number;
+  readonly model: string;
+  readonly observedAt: string;
+}
+
+const EMPTY_SNAPSHOT: UsageSnapshot = {
+  inputTokens: 0n,
+  outputTokens: 0n,
+  cacheReadTokens: 0n,
+  cacheWriteTokens: 0n,
+  totalTokens: 0n,
+  turnCount: 0,
+  estimatedCostUsd: 0,
+  model: "",
+  observedAt: "",
+};
+
+export interface TurnRecord {
+  readonly sequence: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly cacheReadTokens: number;
+  readonly cacheWriteTokens: number;
+}
+
+export class UsageAccumulator {
+  private inputTokens = 0;
+  private outputTokens = 0;
+  private cacheReadTokens = 0;
+  private cacheWriteTokens = 0;
+  private turnCount = 0;
+  private estimatedCostUsd = 0;
+  private observedAt = "";
+  private readonly turnRecords: TurnRecord[] = [];
+
+  constructor(private readonly model: string) {}
+
+  addTurn(usage: TurnUsage): void {
+    const input = usage.inputTokens ?? 0;
+    const output = usage.outputTokens ?? 0;
+    const cacheRead = usage.cacheReadTokens ?? 0;
+    const cacheWrite = usage.cacheWriteTokens ?? 0;
+
+    this.inputTokens += input;
+    this.outputTokens += output;
+    this.cacheReadTokens += cacheRead;
+    this.cacheWriteTokens += cacheWrite;
+    this.turnCount++;
+    this.observedAt = new Date().toISOString();
+    this.turnRecords.push({
+      sequence: this.turnCount,
+      inputTokens: input,
+      outputTokens: output,
+      cacheReadTokens: cacheRead,
+      cacheWriteTokens: cacheWrite,
+    });
+
+    const pricing = getCursorModelPricing(this.model);
+    this.estimatedCostUsd += computeTurnCost(
+      pricing, input, output, cacheWrite, cacheRead,
+    );
+  }
+
+  get hasTurns(): boolean {
+    return this.turnCount > 0;
+  }
+
+  get modelName(): string {
+    return this.model;
+  }
+
+  turns(): readonly TurnRecord[] {
+    return this.turnRecords;
+  }
+
+  snapshot(): UsageSnapshot {
+    if (this.turnCount === 0) return EMPTY_SNAPSHOT;
+
+    return {
+      inputTokens: BigInt(this.inputTokens),
+      outputTokens: BigInt(this.outputTokens),
+      cacheReadTokens: BigInt(this.cacheReadTokens),
+      cacheWriteTokens: BigInt(this.cacheWriteTokens),
+      totalTokens: BigInt(
+        this.inputTokens +
+        this.outputTokens +
+        this.cacheReadTokens +
+        this.cacheWriteTokens),
+      turnCount: this.turnCount,
+      estimatedCostUsd: this.estimatedCostUsd,
+      model: this.model,
+      observedAt: this.observedAt,
+    };
+  }
+}

package/src/activities/execute-cursor/workspace-provision.ts

@@ -0,0 +1,55 @@
+/**
+ * Local workspace provisioning for the Cursor harness.
+ *
+ * Cursor agents run LOCAL (cloud is disabled — see cursor-mode.ts), so the
+ * runner must clone git-repo workspace entries itself and mount local-path
+ * entries before the agent runs, mirroring the native harness. Cloud agents
+ * previously cloned git repos server-side; that path is no longer used.
+ */
+
+import type { Config } from "../../config.js";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { WorkspaceProvisioner } from "../../shared/workspace/provisioner.js";
+import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
+import { ensurePlatformDir } from "../../shared/workspace/platform-dir.js";
+
+/**
+ * Provision the session's workspace entries for a LOCAL Cursor agent.
+ *
+ * Clones git-repo entries (using the user's GITHUB_TOKEN from the resolved
+ * execution environment) and mounts local-path entries, then returns the
+ * directories the agent should operate in. Falls back to the configured
+ * workspace root when the session declares no workspace entries.
+ *
+ * provisionGit is idempotent (it reuses an existing clone), so this is safe
+ * to call on every execution, including multi-turn and HITL reinvocations.
+ */
+export async function provisionCursorWorkspace(
+  config: Config,
+  session: Session,
+  envVars: Record<string, string>,
+  sessionId: string,
+): Promise<string[]> {
+  const entries = session.spec?.workspaceEntries ?? [];
+  if (entries.length === 0) {
+    return [config.workspaceRootDir];
+  }
+
+  const platformDir = await ensurePlatformDir(sessionId);
+  const backend = new LocalWorkspaceBackend(config.workspaceRootDir, platformDir);
+
+  const provisioner = new WorkspaceProvisioner();
+  const results = await provisioner.provisionAll(
+    entries.map((entry) => ({ name: entry.name, source: entry.source })),
+    backend,
+    envVars,
+    config.mode === "local",
+    config.mode !== "local",
+  );
+
+  const dirs = results
+    .map((result) => result.rootDir)
+    .filter((dir): dir is string => Boolean(dir));
+
+  return dirs.length > 0 ? dirs : [config.workspaceRootDir];
+}

package/src/activities/execute-cursor/workspace-setup.ts

@@ -0,0 +1,75 @@
+/**
+ * Writes Cursor hooks configuration and scripts to the workspace.
+ *
+ * Before creating or resuming a Cursor Agent, the cursor-runner writes:
+ * 1. .cursor/hooks.json — declares the preToolUse hook
+ * 2. .cursor/hooks/stigmer-approval.sh — the hook script
+ * 3. .cursor/hooks/stigmer-approval-state.json — approval state for the hook
+ * 4. .cursor/hooks/stigmer-denials.jsonl — per-turn denial ledger (reset here,
+ *    appended by the hook on each deny, read back by the activity)
+ *
+ * This setup enables the durable HITL model: the hook denies tools that need
+ * approval and records each denial to the ledger; the activity reads the ledger,
+ * marks the gated tool calls WAITING_APPROVAL (the backend then projects
+ * pending_approvals from that status), and returns to the workflow. On
+ * reinvocation the state file is updated with the approved tools so the hook
+ * allows them.
+ */
+
+import { writeFile, mkdir, chmod } from "node:fs/promises";
+import { join } from "node:path";
+import { generateHookScript } from "./hook-script.js";
+import { writeApprovalStateFile, resetDenialLedger, type ApprovalStateFile } from "./approval-state.js";
+
+const HOOKS_DIR = ".cursor";
+const HOOKS_SCRIPTS_DIR = ".cursor/hooks";
+const HOOKS_CONFIG_FILE = "hooks.json";
+const HOOK_SCRIPT_FILE = "stigmer-approval.sh";
+
+/**
+ * Write the complete hooks setup to the workspace directory.
+ *
+ * Creates or overwrites:
+ * - .cursor/hooks.json (hooks configuration)
+ * - .cursor/hooks/stigmer-approval.sh (hook script, executable)
+ * - .cursor/hooks/stigmer-approval-state.json (approval state)
+ */
+export async function writeHooksToWorkspace(
+  workspaceRoot: string,
+  approvalState: ApprovalStateFile,
+): Promise<void> {
+  const hooksDir = join(workspaceRoot, HOOKS_DIR);
+  const scriptsDir = join(workspaceRoot, HOOKS_SCRIPTS_DIR);
+  await mkdir(hooksDir, { recursive: true });
+  await mkdir(scriptsDir, { recursive: true });
+
+  const stateFilePath = await writeApprovalStateFile(workspaceRoot, approvalState);
+
+  // Reset the denial ledger for this turn (co-located with the state-file write
+  // so the runner only reads denials produced by the current run, even across
+  // HITL reinvocations on the durable workspace and Temporal activity retries).
+  const ledgerFilePath = await resetDenialLedger(workspaceRoot);
+
+  const hookScriptPath = join(scriptsDir, HOOK_SCRIPT_FILE);
+  await writeFile(hookScriptPath, generateHookScript(stateFilePath, ledgerFilePath), "utf-8");
+  await chmod(hookScriptPath, 0o755);
+
+  const hooksConfig = {
+    version: 1,
+    hooks: {
+      preToolUse: [
+        {
+          command: `.cursor/hooks/${HOOK_SCRIPT_FILE}`,
+          timeout: 10,
+          failClosed: true,
+        },
+      ],
+    },
+  };
+
+  await writeFile(
+    join(hooksDir, HOOKS_CONFIG_FILE),
+    JSON.stringify(hooksConfig, null, 2),
+    "utf-8",
+  );
+}

package/src/activities/execute-deep-agent/__test-utils__/v3-event-fixtures.ts

@@ -0,0 +1,281 @@
+/**
+ * V3 protocol event factories for normalizer and status builder tests.
+ *
+ * Shapes are derived from real recordings in /tmp/stigmer-v3-provider/
+ * captured during Phase 1 validation with Claude claude-sonnet-4-6.
+ */
+
+import type { V3ProtocolEvent } from "../v3-event-recorder.js";
+
+let seqCounter = 0;
+export function resetSeq(): void { seqCounter = 0; }
+function nextSeq(): number { return seqCounter++; }
+
+// ── Core Factory ──────────────────────────────────────────────────
+
+export function makeProtocolEvent(
+  method: string,
+  data: unknown,
+  opts?: {
+    seq?: number;
+    namespace?: string[];
+    node?: string;
+    timestamp?: number;
+  },
+): V3ProtocolEvent {
+  return {
+    type: "event",
+    seq: opts?.seq ?? nextSeq(),
+    method,
+    params: {
+      namespace: opts?.namespace ?? [],
+      timestamp: opts?.timestamp ?? Date.now(),
+      node: opts?.node,
+      data,
+    },
+  };
+}
+
+// ── Lifecycle ─────────────────────────────────────────────────────
+
+export function makeLifecycleRunning(graphName = "root"): V3ProtocolEvent {
+  return makeProtocolEvent("lifecycle", { event: "running", graph_name: graphName });
+}
+
+export function makeLifecycleStarted(graphName: string, ns?: string[]): V3ProtocolEvent {
+  return makeProtocolEvent("lifecycle", { event: "started", graph_name: graphName }, { namespace: ns });
+}
+
+export function makeLifecycleCompleted(graphName: string, ns?: string[]): V3ProtocolEvent {
+  return makeProtocolEvent("lifecycle", { event: "completed", graph_name: graphName }, { namespace: ns });
+}
+
+// ── Messages: message-start / message-finish ──────────────────────
+
+export function makeMessageStart(
+  runId: string,
+  opts?: { messageId?: string; namespace?: string[]; node?: string; usage?: Record<string, unknown> },
+): V3ProtocolEvent {
+  return makeProtocolEvent("messages", {
+    event: "message-start",
+    id: opts?.messageId ?? `msg_${runId}`,
+    usage: opts?.usage,
+    run_id: runId,
+  }, { namespace: opts?.namespace, node: opts?.node ?? "model_request" });
+}
+
+export function makeMessageFinish(
+  runId: string,
+  opts?: {
+    reason?: string;
+    usage?: Record<string, unknown>;
+    namespace?: string[];
+    node?: string;
+    metadata?: Record<string, unknown>;
+  },
+): V3ProtocolEvent {
+  return makeProtocolEvent("messages", {
+    event: "message-finish",
+    reason: opts?.reason ?? "end_turn",
+    usage: opts?.usage,
+    metadata: opts?.metadata,
+    responseMetadata: opts?.metadata,
+    run_id: runId,
+  }, { namespace: opts?.namespace, node: opts?.node ?? "model_request" });
+}
+
+// ── Messages: content-block-start/delta/finish ────────────────────
+
+export function makeContentBlockStartText(
+  runId: string,
+  index = 0,
+  opts?: { namespace?: string[] },
+): V3ProtocolEvent {
+  return makeProtocolEvent("messages", {
+    event: "content-block-start",
+    index,
+    content: { type: "text", text: "" },
+    run_id: runId,
+  }, { namespace: opts?.namespace, node: "model_request" });
+}
+
+export function makeTextDelta(
+  runId: string,
+  text: string,
+  opts?: { index?: number; namespace?: string[] },
+): V3ProtocolEvent {
+  return makeProtocolEvent("messages", {
+    event: "content-block-delta",
+    index: opts?.index ?? 0,
+    delta: { type: "text-delta", text },
+    run_id: runId,
+  }, { namespace: opts?.namespace, node: "model_request" });
+}
+
+export function makeReasoningDelta(
+  runId: string,
+  text: string,
+  opts?: { index?: number; namespace?: string[] },
+): V3ProtocolEvent {
+  return makeProtocolEvent("messages", {
+    event: "content-block-delta",
+    index: opts?.index ?? 0,
+    delta: { type: "reasoning-delta", reasoning: text },
+    run_id: runId,
+  }, { namespace: opts?.namespace, node: "model_request" });
+}
+
+export function makeToolCallArgDelta(
+  runId: string,
+  callId: string,
+  args: string,
+  opts?: { index?: number; namespace?: string[] },
+): V3ProtocolEvent {
+  return makeProtocolEvent("messages", {
+    event: "content-block-delta",
+    index: opts?.index ?? 0,
+    delta: {
+      type: "block-delta",
+      fields: { type: "tool_call_chunk", id: callId, args },
+    },
+    run_id: runId,
+  }, { namespace: opts?.namespace, node: "model_request" });
+}
+
+export function makeContentBlockFinish(
+  runId: string,
+  index = 0,
+  opts?: { content?: unknown; namespace?: string[] },
+): V3ProtocolEvent {
+  return makeProtocolEvent("messages", {
+    event: "content-block-finish",
+    index,
+    content: opts?.content ?? { type: "text", text: "" },
+    run_id: runId,
+  }, { namespace: opts?.namespace, node: "model_request" });
+}
+
+// ── Messages: usage / provider ────────────────────────────────────
+
+export function makeUsageEvent(
+  runId: string,
+  usage: Record<string, unknown>,
+  opts?: { namespace?: string[] },
+): V3ProtocolEvent {
+  return makeProtocolEvent("messages", {
+    event: "usage",
+    usage,
+    run_id: runId,
+  }, { namespace: opts?.namespace, node: "model_request" });
+}
+
+export function makeProviderEvent(
+  runId: string,
+  provider: string,
+  model: string,
+  opts?: { namespace?: string[] },
+): V3ProtocolEvent {
+  return makeProtocolEvent("messages", {
+    event: "provider",
+    provider,
+    name: "message_start",
+    payload: { model, id: `msg_${runId}` },
+    run_id: runId,
+  }, { namespace: opts?.namespace, node: "model_request" });
+}
+
+// ── Tools ─────────────────────────────────────────────────────────
+
+export function makeToolStarted(
+  callId: string,
+  toolName: string,
+  input: unknown = "{}",
+  opts?: { namespace?: string[] },
+): V3ProtocolEvent {
+  return makeProtocolEvent("tools", {
+    event: "tool-started",
+    tool_call_id: callId,
+    tool_name: toolName,
+    input,
+  }, { namespace: opts?.namespace ?? [`tools:${callId}`] });
+}
+
+export function makeToolFinished(
+  callId: string,
+  output: unknown = "ok",
+  opts?: { namespace?: string[] },
+): V3ProtocolEvent {
+  const wrappedOutput = typeof output === "string"
+    ? {
+        lc: 1, type: "constructor",
+        id: ["langchain_core", "messages", "ToolMessage"],
+        kwargs: { status: "success", content: output, tool_call_id: callId, name: "tool" },
+      }
+    : output;
+
+  return makeProtocolEvent("tools", {
+    event: "tool-finished",
+    tool_call_id: callId,
+    output: wrappedOutput,
+  }, { namespace: opts?.namespace ?? [`tools:${callId}`] });
+}
+
+export function makeToolError(
+  callId: string,
+  message: string,
+  opts?: { namespace?: string[] },
+): V3ProtocolEvent {
+  return makeProtocolEvent("tools", {
+    event: "tool-error",
+    tool_call_id: callId,
+    message,
+  }, { namespace: opts?.namespace ?? [`tools:${callId}`] });
+}
+
+export function makeToolOutputDelta(
+  callId: string,
+  delta: string,
+  opts?: { namespace?: string[] },
+): V3ProtocolEvent {
+  return makeProtocolEvent("tools", {
+    event: "tool-output-delta",
+    tool_call_id: callId,
+    delta,
+  }, { namespace: opts?.namespace ?? [`tools:${callId}`] });
+}
+
+// ── Ignored channels (for normalizer completeness tests) ──────────
+
+export function makeCheckpointEvent(): V3ProtocolEvent {
+  return makeProtocolEvent("checkpoints", {
+    id: "ckpt_001",
+    parent_id: "ckpt_000",
+    step: 1,
+    source: "loop",
+  });
+}
+
+export function makeTasksEvent(): V3ProtocolEvent {
+  return makeProtocolEvent("tasks", {
+    id: "task_001",
+    name: "model_request",
+    input: {},
+    triggers: [],
+    interrupts: [],
+  });
+}
+
+export function makeValuesEvent(): V3ProtocolEvent {
+  return makeProtocolEvent("values", {
+    messages: [],
+    todos: [],
+    files: {},
+  });
+}
+
+export function makeUpdatesEvent(node = "model_request"): V3ProtocolEvent {
+  return makeProtocolEvent("updates", {
+    node,
+    values: {},
+  }, { node });
+}