@stigmer/runner 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/src/activities/execute-cursor/session-store.ts

@@ -0,0 +1,187 @@
+/**
+ * Session-keyed Cursor SDK store — the on-disk SQLite store a session's
+ * agent records, runs and checkpoints live in, opened once per session and
+ * handed to every `Agent.create` / `Agent.resume` of that session
+ * (stigmer/stigmer#1053).
+ *
+ * Why this exists: `@cursor/sdk` 1.0.31 removed the `platform` option the
+ * runner used to key the SDK's store (`platform.workspaceRef` /
+ * `platform.stateRoot`) and replaced it with a caller-owned
+ * `local.store: LocalAgentStore`. The SDK's own instruction is "open once per
+ * workspace / state root and reuse across `Agent.create` / `resume`". So the
+ * store has a lifetime the runner owns, and this module is where it lives.
+ *
+ * Where the store lives on disk is unchanged from the `platform` era:
+ * `{workspaceRootDir}/.stigmer/cursor-sdk-state/{sessionId}` — the durable
+ * workspace volume rather than `$HOME`, so native `Agent.resume()` survives
+ * pod restart, reschedule and snapshot restore; keyed by sessionId so sessions
+ * sharing one volume (a workflow sandbox's child agent executions) never
+ * collide. The `workspaceRef` is the same synthetic `stigmer-session:<id>`,
+ * deliberately not a filesystem path, so lookups are stable regardless of
+ * `process.cwd()` (in a cloud sandbox that is the runner's app directory, not
+ * the workspace).
+ *
+ * Lifetime — the session's, on the two hooks the adapter already has:
+ * - `sessionStore()` opens on first use and memoizes the OPEN PROMISE per
+ *   session, so two activities racing on one session (the agent cache's
+ *   documented race: the loser resolves its own agent) await the same open
+ *   instead of racing two opens on one file. A failed open is not memoized;
+ *   the next call retries.
+ * - `releaseSessionStore(sessionId)` is called from the adapter's
+ *   `releaseSession` — the runtime saying the session is done on this host.
+ * - `releaseAllSessionStores()` is called from the adapter's `shutdown`.
+ * - A re-acquire under a DIFFERENT state root (the session moved volumes)
+ *   releases the store it held and opens the new one — the same rule the agent
+ *   cache applies to a fingerprint mismatch: a handle for the old binding can
+ *   never serve the new one, and holding it would only pin a file.
+ * Nothing else disposes a store. In particular the store does NOT ride the
+ * agent handle's `close()` — the handle has five close sites and a second
+ * resource on each would be a parallel lifecycle — and it does not enter the
+ * agent cache, whose exclusive-checkout model is about one handle per turn.
+ *
+ * At 1.0.13 the SDK memoized its platform (with open SQLite handles) for the
+ * whole process; a per-session store released when the session is released is
+ * a tighter lifetime, not a looser one.
+ *
+ * `SessionStores` is the mechanism with the opener injected, so its rules are
+ * unit-tested without a SQLite file; the module-level instance binds the SDK's
+ * `SqliteLocalAgentStore.open` (`@cursor/sdk/sqlite`, the subpath entry that
+ * keeps the sqlite driver off the main package's import path). In a hermetic
+ * run that subpath is doubled beside `@cursor/sdk` itself (`scripted-sdk.ts`).
+ *
+ * THIS MODULE'S STATIC GRAPH IS SDK-FREE, like `agent-session-cache.ts`: the
+ * adapter imports both statically, and the adapter's own static graph must
+ * stay SDK-free so the composition roots can import it before `boot` installs
+ * the interceptors (`adapter.ts` header). The SDK's sqlite entry is loaded
+ * with a dynamic import at the first open — the runner's
+ * dynamic-import-for-order convention — and only its TYPE is imported here.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { SqliteLocalAgentStore } from "@cursor/sdk/sqlite";
+
+const CURSOR_SDK_STATE_DIR = ".stigmer/cursor-sdk-state";
+
+/** Where a session's store lives and the ref the SDK scopes it under. */
+export interface SessionStoreLocation {
+  /** Synthetic, stable across activity invocations: `stigmer-session:<sessionId>`. */
+  readonly workspaceRef: string;
+  /** `{workspaceRootDir}/.stigmer/cursor-sdk-state/{sessionId}`, created eagerly. */
+  readonly stateRoot: string;
+}
+
+/** The slice of the SDK store whose lifetime this module owns. */
+export interface ReleasableStore {
+  readonly stateRoot: string;
+  dispose(): Promise<void>;
+}
+
+/**
+ * Compute a session's store location. Both inputs are required and must be
+ * non-empty: the state root is keyed by sessionId, so an empty sessionId would
+ * collapse every session sharing the volume onto one store and corrupt their
+ * conversation state; an empty root would put the store somewhere that does
+ * not survive a restart. The directory is created eagerly to prevent ENOENT on
+ * the SDK's first write.
+ */
+export function resolveSessionStoreLocation(sessionId: string, workspaceRootDir: string): SessionStoreLocation {
+  if (!sessionId) {
+    throw new Error(
+      "resolveSessionStoreLocation: sessionId is required but was empty. The Cursor SDK " +
+        "state store is keyed by sessionId; an empty value would collide across sessions " +
+        "sharing a workspace volume (e.g. a workflow sandbox's child agent executions).",
+    );
+  }
+  if (!workspaceRootDir) {
+    throw new Error(
+      "resolveSessionStoreLocation: workspaceRootDir is required but was empty. The Cursor " +
+        "SDK state store must live on the durable workspace volume to survive restarts.",
+    );
+  }
+  const stateRoot = join(workspaceRootDir, CURSOR_SDK_STATE_DIR, sessionId);
+  mkdirSync(stateRoot, { recursive: true });
+  return { workspaceRef: `stigmer-session:${sessionId}`, stateRoot };
+}
+
+/** One store per session, opened through `open`, held until released. */
+export class SessionStores<S extends ReleasableStore> {
+  private readonly held = new Map<string, { readonly stateRoot: string; readonly store: Promise<S> }>();
+
+  constructor(private readonly open: (location: SessionStoreLocation) => Promise<S>) {}
+
+  /** The session's store, opened on first use; the same instance on every later call. */
+  acquire(sessionId: string, workspaceRootDir: string): Promise<S> {
+    const location = resolveSessionStoreLocation(sessionId, workspaceRootDir);
+    const existing = this.held.get(sessionId);
+    if (existing && existing.stateRoot === location.stateRoot) return existing.store;
+    if (existing) {
+      console.log(
+        `session-store: session=${sessionId} re-acquired under a different state root ` +
+          `(held=${existing.stateRoot}, requested=${location.stateRoot}) — releasing the held store`,
+      );
+      void this.release(sessionId);
+    }
+    const store = this.open(location);
+    this.held.set(sessionId, { stateRoot: location.stateRoot, store });
+    // A failed open must not be memoized: the next acquire retries. Only the
+    // entry THIS open created is removed (a later re-acquire may have replaced it).
+    store.catch(() => {
+      if (this.held.get(sessionId)?.store === store) this.held.delete(sessionId);
+    });
+    return store;
+  }
+
+  /** Disposes and forgets the session's store, if any. A later acquire reopens. */
+  async release(sessionId: string): Promise<void> {
+    const entry = this.held.get(sessionId);
+    if (!entry) return;
+    this.held.delete(sessionId);
+    await disposeQuietly(sessionId, entry.store);
+  }
+
+  /** Worker shutdown: dispose every held store. */
+  async releaseAll(): Promise<void> {
+    const entries = [...this.held.entries()];
+    this.held.clear();
+    await Promise.all(entries.map(([sessionId, entry]) => disposeQuietly(sessionId, entry.store)));
+  }
+
+  /** How many stores are held — for assertions. */
+  get size(): number {
+    return this.held.size;
+  }
+}
+
+async function disposeQuietly<S extends ReleasableStore>(sessionId: string, store: Promise<S>): Promise<void> {
+  try {
+    await (await store).dispose();
+  } catch (err) {
+    // Best effort: a store whose open failed has nothing to dispose, and a
+    // dispose that fails on a dead handle changes nothing the session needs.
+    console.warn(
+      `session-store: dispose failed for session=${sessionId}:`,
+      err instanceof Error ? err.message : err,
+    );
+  }
+}
+
+const sessionStores = new SessionStores<SqliteLocalAgentStore>(async (location) => {
+  const { SqliteLocalAgentStore } = await import("@cursor/sdk/sqlite");
+  return SqliteLocalAgentStore.open(location);
+});
+
+/** The session's SDK store, opened on first use — pass as `local.store` on create AND resume. */
+export function sessionStore(sessionId: string, workspaceRootDir: string): Promise<SqliteLocalAgentStore> {
+  return sessionStores.acquire(sessionId, workspaceRootDir);
+}
+
+/** The session is done on this host (the adapter's `releaseSession`). */
+export function releaseSessionStore(sessionId: string): Promise<void> {
+  return sessionStores.release(sessionId);
+}
+
+/** Worker shutdown (the adapter's `shutdown`). */
+export function releaseAllSessionStores(): Promise<void> {
+  return sessionStores.releaseAll();
+}

package/src/activities/execute-cursor/sub-agent-steps.ts

@@ -0,0 +1,188 @@
+/**
+ * A Cursor sub-agent's transcript, from the `task` tool's completed result to
+ * the canonical events that fold it (`harness/transcript/events.ts`), scoped
+ * to the sub-agent's own `subAgentId`.
+ *
+ * WHY THE TRANSCRIPT ARRIVES AS A BLOB. The Cursor SDK returns sub-agent work
+ * inside the `task` tool's completed event, not as streaming events with a
+ * distinct agent id. Re-verified 2026-08-23 on the pinned SDK (1.0.13) AND the
+ * latest (1.0.28), including the write side (stigmer/stigmer#839): an injected
+ * platform.eventStore/eventNotifier receives parent events only on 1.0.13 and
+ * is bypassed entirely on 1.0.28 (persistence moved into the executor daemon's
+ * own state dir); zero events reach the parent's run.stream() mid-task; the
+ * agentId in the task args is not a platform-store agent id at all, so it can
+ * never be addressable via Agent.listRuns / Agent.getRun (this is WHY the
+ * 2026-07-02 read-side polls all returned not-found). On 1.0.28 the child
+ * transcript lands at a deterministic path knowable at spawn
+ * (~/.cursor/projects/<slug>/agent-transcripts/<parentId>/subagents/<argsAgentId>.jsonl)
+ * but is flushed only at completion — verified with 200ms sampling across a
+ * full sub-agent run. Live nested visibility is therefore still an upstream
+ * SDK limitation — do not try to fake it here; the UI shows an elapsed-time
+ * affordance instead (SubAgentSection). This is Cursor's timing — the
+ * sub-agent's rows exist only at completion — and it stays Cursor's.
+ *
+ * THE SHAPE. The result is `{ status: "success", value: { conversationSteps } }`
+ * (or a bare `{ conversationSteps }`), where each ConversationStep is a
+ * protobuf-oneof object keyed DIRECTLY by its kind — there is NO
+ * `{ type, message }` envelope in production blobs, though the legacy `type`
+ * form is still read:
+ *   - { thinkingMessage: { text, thinkingDurationMs? } }
+ *   - { assistantMessage: { text } }
+ *   - { toolCall: { toolCallId, <kind>ToolCall: { args, result } } }
+ * The tool family is the lone `<kind>ToolCall` sibling of `toolCallId`
+ * (`readToolCall`, `globToolCall`, `grepToolCall`, `shellToolCall`, …); the bare
+ * tool name is the suffix-stripped key, which feeds the shared `classifyTool`
+ * exactly like a top-level call. `result` is itself a oneof
+ * `{ success | error | permissionDenied | rejected }`. This is deliberately
+ * key-driven rather than an enumerated switch, so a new tool family the SDK
+ * adds surfaces automatically instead of being dropped. History: an earlier
+ * revision parsed a `{ type: "toolCall", message: { type, args, result } }`
+ * envelope that never appears in the real blob, so every sub-agent tool call
+ * was silently discarded and the UI showed a sub-agent that "did nothing".
+ *
+ * WHAT THIS MODULE EMITS, AND WHY EVENTS. Until #1097 this parser built
+ * `AgentMessage` protos itself (the conversation-steps extractor in the accumulator)
+ * — a third copy of the folding rule, whose message boundary drifted from the
+ * root's until then. Now each step becomes the events any harness's translator
+ * would emit for the same thing, and the shared `TranscriptBuilder` folds them
+ * with the root's own rules: an `assistantMessage` step is its own message
+ * (`runId` `<subAgentId>:step:<i>`, so two consecutive steps never merge); a
+ * `thinkingMessage` step a THINKING row under the same key; a `toolCall` step
+ * a `tool_started` then a `tool_finished`/`tool_error`, which the builder
+ * attaches to the transcript's current AI message (the assistant step that
+ * proposed it) or an empty one when there is none. Unknown step
+ * kinds and empty texts are skipped for forward compatibility. The rows carry
+ * no attribution or provenance (#1133).
+ *
+ * The `task` row's own `tool_finished` and the sub-agent's `sub_agent_finished`
+ * are the translator's (`translator.ts`); this module answers only "what
+ * happened inside".
+ */
+
+import type { TranscriptEvent } from "../../harness/transcript/events.js";
+import { canonicalizeImageResult } from "./tool-result.js";
+
+/**
+ * The failure branches of a sub-agent tool call's `result` oneof. A completion
+ * is `{ success: ... }`; every other branch is a non-completion the UI must show
+ * as failed — an errored read/glob/grep (`error`), or a shell the approval gate
+ * stopped (`permissionDenied` / `rejected`).
+ */
+const SUBAGENT_TOOL_RESULT_FAILURE_KEYS: ReadonlySet<string> = new Set([
+  "error",
+  "permissionDenied",
+  "rejected",
+]);
+
+/** The canonical events for one sub-agent's completed `conversationSteps`, all scoped to `subAgentId`. */
+export function subAgentStepEvents(result: unknown, subAgentId: string): TranscriptEvent[] {
+  const steps = conversationStepsOf(result);
+  const out: TranscriptEvent[] = [];
+  for (const [index, step] of steps.entries()) {
+    if (step == null || typeof step !== "object") continue;
+    const s = step as Record<string, unknown>;
+    const type = s.type as string | undefined;
+    const runId = `${subAgentId}:step:${index}`;
+
+    if (type === "thinkingMessage" || s.thinkingMessage != null) {
+      const text = stepText(type === "thinkingMessage" ? s.message : s.thinkingMessage);
+      if (text) {
+        out.push({ kind: "message_start", runId, subAgentId });
+        out.push({ kind: "reasoning_delta", runId, text, subAgentId });
+        out.push({ kind: "message_finish", runId, subAgentId });
+      }
+    } else if (type === "assistantMessage" || s.assistantMessage != null) {
+      const text = stepText(type === "assistantMessage" ? s.message : s.assistantMessage);
+      if (text) {
+        out.push({ kind: "message_start", runId, subAgentId });
+        out.push({ kind: "text_delta", runId, text, subAgentId });
+        out.push({ kind: "message_finish", runId, subAgentId });
+      }
+    } else if (s.toolCall != null) {
+      out.push(...subAgentToolCallEvents(s.toolCall, index, subAgentId));
+    }
+  }
+  return out;
+}
+
+/** The `conversationSteps` array from the task result's envelope, or none. */
+function conversationStepsOf(result: unknown): unknown[] {
+  if (result == null || typeof result !== "object") return [];
+  const r = result as Record<string, unknown>;
+  const value = r.value ?? r;
+  if (value == null || typeof value !== "object") return [];
+  const steps = (value as Record<string, unknown>).conversationSteps;
+  return Array.isArray(steps) ? steps : [];
+}
+
+function stepText(message: unknown): string {
+  if (message == null || typeof message !== "object") return "";
+  const text = (message as Record<string, unknown>).text;
+  return typeof text === "string" ? text : "";
+}
+
+/**
+ * One `toolCall` step as a started row and its outcome. The SDK's real call id
+ * keeps the row stable across resumes and distinct from its siblings; a
+ * synthetic `sub-<name>-<stepIndex>` stands in only when the SDK omits one.
+ * A step with no `<kind>ToolCall` key (malformed or forward-incompatible) emits
+ * nothing rather than a blank, nameless row.
+ */
+function subAgentToolCallEvents(toolCall: unknown, stepIndex: number, subAgentId: string): TranscriptEvent[] {
+  if (toolCall == null || typeof toolCall !== "object") return [];
+  const obj = toolCall as Record<string, unknown>;
+
+  const kindKey = Object.keys(obj).find((k) => k !== "toolCallId" && k.endsWith("ToolCall"));
+  if (!kindKey) return [];
+
+  const name = kindKey.slice(0, -"ToolCall".length);
+  const inner = obj[kindKey] != null && typeof obj[kindKey] === "object"
+    ? (obj[kindKey] as Record<string, unknown>)
+    : {};
+  const callId = typeof obj.toolCallId === "string" && obj.toolCallId
+    ? obj.toolCallId
+    : `sub-${name}-${stepIndex}`;
+  const input = inner.args != null && typeof inner.args === "object"
+    ? (inner.args as Record<string, unknown>)
+    : {};
+
+  const outcome = interpretSubAgentToolResult(inner.result);
+  return [
+    { kind: "tool_started", callId, name, input, mcpServerSlug: "", subAgentId },
+    outcome.status === "completed"
+      ? { kind: "tool_finished", callId, result: outcome.result, subAgentId }
+      : { kind: "tool_error", callId, message: outcome.error, subAgentId },
+  ];
+}
+
+/**
+ * A sub-agent tool call's `result` oneof as an outcome: `success` → completed
+ * with the serialized payload (a screenshot is canonicalized the same way as a
+ * top-level result); any failure branch → failed with the serialized detail
+ * (`error` alone — never a duplicate in `result`). An absent result is
+ * a completed call with no output — the SDK omits `result` for a call that
+ * reports nothing; an unknown oneof branch is surfaced as a completed result
+ * rather than dropped.
+ */
+export function interpretSubAgentToolResult(result: unknown):
+  | { status: "completed"; result: string }
+  | { status: "failed"; error: string } {
+  if (result == null || typeof result !== "object") {
+    return { status: "completed", result: "" };
+  }
+  const r = result as Record<string, unknown>;
+
+  if ("success" in r) {
+    const val = r.success;
+    const str = canonicalizeImageResult(val) ?? (typeof val === "string" ? val : JSON.stringify(val));
+    return { status: "completed", result: str };
+  }
+
+  const failKey = Object.keys(r).find((k) => SUBAGENT_TOOL_RESULT_FAILURE_KEYS.has(k));
+  if (failKey) {
+    const val = r[failKey];
+    return { status: "failed", error: typeof val === "string" ? val : JSON.stringify(val) };
+  }
+
+  return { status: "completed", result: JSON.stringify(r) };
+}

package/src/activities/execute-cursor/tool-result.ts

@@ -0,0 +1,128 @@
+/**
+ * The Cursor harness's rendering of a tool result into the one string a
+ * transcript row carries — the translator's half of `tool_finished.result`
+ * (`harness/transcript/events.ts`): the engine's output envelope is the
+ * harness's to unwrap, the builder stores what it is handed, and the persist
+ * chokepoint bounds it. Native's twin is
+ * `extractToolResult` in `execute-deep-agent/translator.ts` (the LangChain
+ * ToolMessage envelope and the LangGraph Command).
+ *
+ * Its own module because two readers need it — the translator for a root
+ * row's result, `sub-agent-steps.ts` for a sub-agent's — and the second would
+ * otherwise import the first, which imports the second. Moved from
+ * `message-translator.ts` verbatim.
+ */
+
+/**
+ * Normalize a tool_call event result into a string for the ToolCall proto.
+ * Returns "" for an absent result so callers can treat "no result yet" and
+ * "empty result" uniformly (e.g. to avoid clobbering a captured result).
+ *
+ * The one non-passthrough case is a multimodal MCP result (e.g. a computer-use
+ * screenshot): see {@link canonicalizeImageResult}. Everything else is the
+ * string as-is, or a whole-value JSON.stringify — byte-identical to before.
+ */
+export function toResultString(result: unknown): string {
+  if (result == null) return "";
+  if (typeof result === "string") return result;
+  const canonical = canonicalizeImageResult(result);
+  if (canonical !== undefined) return canonical;
+  return JSON.stringify(result);
+}
+
+/**
+ * Re-emit a Cursor MCP result that carries an image block as the canonical
+ * top-level content-block array the persist-time offload understands.
+ *
+ * The Cursor SDK wraps an MCP tool result as `{ status, value: { content: [...] } }`
+ * (or a bare `{ content: [...] }`), where an image block is
+ * `{ image: { data, mimeType } }` and `data` is a Node Buffer-JSON
+ * (`{ type:"Buffer", data:number[] }`). Persisting that envelope verbatim buries
+ * the image where `detectImagePayload`/`contentBlocks` (shared/status-offload.ts)
+ * cannot see it, so the screenshot lands as `text/plain` instead of a renderable
+ * `ToolCallOutputRef`.
+ *
+ * This mirrors `serializeToolContent` in the deep-agent path
+ * (harness/transcript/tool-result.ts): the harness adapter normalizes
+ * its own wire shape into the canonical array
+ *   `[{ type:"text", text }, { type:"image", data:<base64>, mimeType }]`
+ * so the shared offload stays harness-agnostic (its envelope handling is
+ * documented there as insurance, not the primary path). Buffer-JSON is decoded
+ * to base64 here so the bloated byte-array never propagates into the status.
+ *
+ * Returns undefined when there is no content array or no image block, so the
+ * caller falls back to its existing serialization (no change for text/error
+ * results).
+ */
+export function canonicalizeImageResult(result: unknown): string | undefined {
+  if (result == null || typeof result !== "object") return undefined;
+  const blocks = resultContentBlocks(result as Record<string, unknown>);
+  if (!blocks) return undefined;
+
+  const canonical: Array<Record<string, unknown>> = [];
+  let sawImage = false;
+  for (const block of blocks) {
+    if (!block || typeof block !== "object") continue;
+    const b = block as Record<string, unknown>;
+
+    if (b.image && typeof b.image === "object") {
+      const img = b.image as Record<string, unknown>;
+      const base64 = imageDataToBase64(img.data);
+      if (base64) {
+        const mimeType = typeof img.mimeType === "string" ? img.mimeType : "image/png";
+        canonical.push({ type: "image", data: base64, mimeType });
+        sawImage = true;
+        continue;
+      }
+    }
+
+    const text = blockText(b);
+    if (text !== undefined) canonical.push({ type: "text", text });
+  }
+
+  return sawImage ? JSON.stringify(canonical) : undefined;
+}
+
+/** Extract the content-block array from a Cursor result envelope or a bare one. */
+function resultContentBlocks(obj: Record<string, unknown>): unknown[] | undefined {
+  const value = obj.value;
+  if (value && typeof value === "object" && Array.isArray((value as Record<string, unknown>).content)) {
+    return (value as Record<string, unknown>).content as unknown[];
+  }
+  if (Array.isArray(obj.content)) return obj.content;
+  return undefined;
+}
+
+/**
+ * Decode an image block's `data` to plain base64. Accepts a Node Buffer-JSON
+ * (`{ type:"Buffer", data:number[] }`, how the Cursor SDK serializes bytes), a
+ * `data:` URL, or an already-base64 string. Returns undefined for anything else.
+ */
+function imageDataToBase64(data: unknown): string | undefined {
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    if (d.type === "Buffer" && Array.isArray(d.data)) {
+      try {
+        return Buffer.from(d.data as number[]).toString("base64");
+      } catch {
+        return undefined;
+      }
+    }
+    return undefined;
+  }
+  if (typeof data === "string" && data) {
+    const dataUrl = data.match(/^data:image\/[a-zA-Z0-9.+-]+;base64,([\s\S]+)$/);
+    return (dataUrl ? dataUrl[1] : data).replace(/\s+/g, "");
+  }
+  return undefined;
+}
+
+/** Extract the text from a Cursor content block: `{ text:{text} }` or `{ text }`. */
+function blockText(b: Record<string, unknown>): string | undefined {
+  const t = b.text;
+  if (typeof t === "string") return t;
+  if (t && typeof t === "object" && typeof (t as Record<string, unknown>).text === "string") {
+    return (t as Record<string, unknown>).text as string;
+  }
+  return undefined;
+}