@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

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

@@ -18,7 +18,7 @@
  *  - File review under the `cursor` harness id, with the two files the gate
  *    writes into the repo excluded from the mid-run progress diff
  *    ({@link CURSOR_RUNNER_OWNED_PATHS}). The capture itself is the runtime's
- *    (`harness/capture.ts`, S3 M4); this adapter contributes only the hook
+ *    (`harness/capture.ts`, since #1096); this adapter contributes only the hook
  *    sidecar it binds as the runtime's CAS observations (`turn-setup.ts`).
  */
 

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

@@ -1,57 +1,91 @@
 /**
- * Cursor SDK event recorder for capturing raw SDKMessage events.
+ * The raw recording of the Cursor translator's input — both SDK channels, in
+ * arrival order — for checking the translator against what the real SDK sends.
  *
- * 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.
+ * Off unless `CURSOR_EVENT_RECORD_DIR` is set: `turn-settle.ts` reads the env
+ * once per turn and hands the directory in, so this module touches no process
+ * state and its tests need no env. When off, {@link createCursorEventRecorder}
+ * returns undefined and the loop's `recorder?.record(...)` costs nothing.
  *
- * 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.
+ * Two channels, one sequence. The Cursor SDK hands the runner a turn on two
+ * channels: the discrete `run.stream()` `SDKMessage`s (message boundaries, tool
+ * calls, the result) and the fine-grained `onDelta` `InteractionUpdate`s (text
+ * and thinking tokens, live shell output, tool-call completion instants,
+ * usage). The translator (`translator.ts`) reads both, and the questions a
+ * recording exists to answer — what shape `shell-output-delta` carries, whether
+ * `tool-call-completed` arrives before or after the stream's own completed
+ * `tool_call` — are questions about the ORDER across channels. So the recorder
+ * owns one monotonic `seq` and stamps every line with its `channel`; a reader
+ * sorts nothing, it reads the file top to bottom. Until #1097's live-run gate
+ * this module recorded the stream channel alone, under the loop's own
+ * event counter, which could not place a delta relative to a stream event.
  *
- * Mirrors the native harness's v3-event-recorder.ts / V3_EVENT_RECORD_DIR.
+ * Output: `<dir>/<executionId>.cursor-events.jsonl`, one JSON object per line,
+ * flushed once after the stream completes (`turn-settle.ts`). Payloads pass
+ * through {@link safeClone} so a cyclic event cannot fail the flush. The native
+ * harness's `v3-event-recorder.ts` is the same idea for its one channel.
  */
 
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import type { SDKMessage } from "@cursor/sdk";
+import type { InteractionUpdate, SDKMessage } from "@cursor/sdk";
+
+/** Which of the SDK's two channels a recorded line came from. */
+export type CursorRecordedChannel = "stream" | "delta";
 
 export interface CursorEventRecorder {
-  record(event: SDKMessage, seq: number): void;
+  /** A discrete `run.stream()` event, sequenced with the deltas around it. */
+  record(event: SDKMessage): void;
+  /** An `onDelta` update, sequenced with the stream events around it. */
+  recordDelta(update: InteractionUpdate): void;
+  /** Write every recorded line, once. A no-op when nothing was recorded. */
   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.
+ * Create a recorder for `recordDir`, or undefined when there is none (the
+ * env var unset or empty) — the caller does `recorder?.record(event)`.
  */
 export function createCursorEventRecorder(
   executionId: string,
+  recordDir: string | undefined,
 ): 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[] = [];
+  /** The one arrival counter both channels share (the header's reason). */
+  private seq = 0;
 
   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,
+  record(event: SDKMessage): void {
+    this.append("stream", event.type, {
       agent_id: event.agent_id,
       run_id: event.run_id,
       event: safeClone(event),
-    };
-    this.lines.push(JSON.stringify(entry));
+    });
+  }
+
+  recordDelta(update: InteractionUpdate): void {
+    this.append("delta", update.type, { update: safeClone(update) });
+  }
+
+  private append(channel: CursorRecordedChannel, type: string, payload: Record<string, unknown>): void {
+    this.lines.push(
+      JSON.stringify({
+        seq: this.seq++,
+        capturedAt: new Date().toISOString(),
+        channel,
+        type,
+        ...payload,
+      }),
+    );
   }
 
   async flush(): Promise<void> {
@@ -59,15 +93,10 @@ class FileCursorEventRecorder implements CursorEventRecorder {
 
     await mkdir(this.outputDir, { recursive: true });
 
-    const filePath = join(
-      this.outputDir,
-      `${this.executionId}.cursor-events.jsonl`,
-    );
+    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}`,
-    );
+    console.log(`CursorEventRecorder: flushed ${this.lines.length} lines to ${filePath}`);
   }
 }
 

package/src/activities/execute-cursor/fetch-interceptor.ts

@@ -65,7 +65,7 @@ interface ProxyConfig {
    * manager's token coordinator), so a rotation reaches the next request
    * without a call into this module. Which credential it is differs per
    * root — the static root's control-plane token, the manager's minted
-   * runner token (Q-S2-7) — and this module never knows which.
+   * runner token — and this module never knows which.
    */
   proxyTokenRef: { readonly current: string | null };
   executionId?: string;

package/src/activities/execute-cursor/http2-interceptor.ts

@@ -64,7 +64,7 @@ interface Http2InterceptorConfig {
    * installed this interceptor owns the ref and rotates it in place, so a
    * rotation reaches the next `request()` on an already-open session without
    * a call into this module (see fetch-interceptor.ts for the two roots'
-   * bindings, Q-S2-7).
+   * bindings).
    */
   proxyTokenRef: { readonly current: string | null };
 }

package/src/activities/execute-cursor/prompt-builder.ts

@@ -6,7 +6,7 @@
  * user message and persist in the agent's own conversation store; a resumed
  * agent receives only what is per-turn).
  *
- * What is this harness's and what is shared (S3 M5, Q-S3-10 / Q-M5-2):
+ * What is this harness's and what is shared (since #1096):
  *  - Shared through `shared/prompt-sections.ts`: WHICH standing sections
  *    render and in WHAT order (`standingContextSections`) and the input-files
  *    bullet and disclosure lines (`inputFileLines`). Their WORDS come from
@@ -70,7 +70,7 @@ const RUNNER_PATH_MARKERS = [
 ] as const;
 
 // The prompt renders the attachment resolver's own result type — a local
-// structural twin (`AttachmentPromptEntry`) lived here until S3 M5 and the
+// structural twin (`AttachmentPromptEntry`) lived here until #1096 and the
 // projection into it was the one reason `turn-setup.ts` had a
 // `prepareAttachmentPrompt` step; the twin dropped the size, so this
 // harness's input-files line never carried it. One type, one truth: the
@@ -315,7 +315,7 @@ export function buildReinvocationPrompt(
     } else if (action === ApprovalAction.REJECT) {
       // A REJECT denies the tool and the run continues (stigmer#197); the
       // runtime settles its row SKIPPED. Told apart from a SKIP in the prose
-      // so the model reads a refusal, not an omission (S3 M1, Q-S3-2).
+      // so the model reads a refusal, not an omission (since #1096).
       rejected.push(describeApproval(pa));
     }
   }
@@ -566,8 +566,8 @@ export function formatWorkspaceContext(dirs: string[]): string {
 /**
  * The `<input_files>` section: this harness's intro around the shared lines
  * (`prompt-sections.ts` `inputFileLines` says what each bullet and disclosure
- * carries and why). The size on each bullet is new to this harness at S3 M5
- * (Q-M5-3): the twin this builder rendered from had dropped it.
+ * carries and why). The size on each bullet is new to this harness in #1096:
+ * the twin this builder rendered from had dropped it.
  */
 export function formatInputFiles(
   attachments: readonly ResolvedAttachment[],
@@ -755,7 +755,7 @@ export function buildToolApprovalRuleFile(): string {
 // ---------------------------------------------------------------------------
 // Prompt selection — which of the four shapes a turn sends, from how the
 // agent resolved and whether the turn carries adjudicated approvals. Moved
-// from `index.ts` at S2 M3b, body unchanged; `__tests__/build-prompt.test.ts`
+// from `index.ts` in #1070, body unchanged; `__tests__/build-prompt.test.ts`
 // pins every branch.
 // ---------------------------------------------------------------------------
 

package/src/activities/execute-cursor/service-tier.ts

@@ -53,8 +53,7 @@ const AUTO_MODEL_IDS = new Set(["default", "auto"]);
  * the served variant deterministic while leaving effort knobs on their
  * catalog defaults. `fast` changes the per-token price; `thinking` is
  * price-neutral but changes token consumption and must never follow the
- * account default. Sourced from the Cursor catalog survey
- * (stigmer-cloud _projects/2026-08/20260806.04.model-service-tier).
+ * account default. Sourced from a survey of the Cursor catalog (2026-08).
  */
 const FAST_PARAM_ID = "fast";
 const THINKING_PARAM_ID = "thinking";

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;
+}