@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

package/dist/activities/execute-cursor/sub-agent-steps.js

@@ -0,0 +1,180 @@
+/**
+ * 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 { 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 = new Set([
+    "error",
+    "permissionDenied",
+    "rejected",
+]);
+/** The canonical events for one sub-agent's completed `conversationSteps`, all scoped to `subAgentId`. */
+export function subAgentStepEvents(result, subAgentId) {
+    const steps = conversationStepsOf(result);
+    const out = [];
+    for (const [index, step] of steps.entries()) {
+        if (step == null || typeof step !== "object")
+            continue;
+        const s = step;
+        const type = s.type;
+        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) {
+    if (result == null || typeof result !== "object")
+        return [];
+    const r = result;
+    const value = r.value ?? r;
+    if (value == null || typeof value !== "object")
+        return [];
+    const steps = value.conversationSteps;
+    return Array.isArray(steps) ? steps : [];
+}
+function stepText(message) {
+    if (message == null || typeof message !== "object")
+        return "";
+    const text = message.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, stepIndex, subAgentId) {
+    if (toolCall == null || typeof toolCall !== "object")
+        return [];
+    const obj = toolCall;
+    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]
+        : {};
+    const callId = typeof obj.toolCallId === "string" && obj.toolCallId
+        ? obj.toolCallId
+        : `sub-${name}-${stepIndex}`;
+    const input = inner.args != null && typeof inner.args === "object"
+        ? inner.args
+        : {};
+    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) {
+    if (result == null || typeof result !== "object") {
+        return { status: "completed", result: "" };
+    }
+    const r = result;
+    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) };
+}
+//# sourceMappingURL=sub-agent-steps.js.map

package/dist/activities/execute-cursor/sub-agent-steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-agent-steps.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/sub-agent-steps.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-cursor/tool-result.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 declare function toResultString(result: unknown): string;
+/**
+ * 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 declare function canonicalizeImageResult(result: unknown): string | undefined;

package/dist/activities/execute-cursor/tool-result.js

@@ -0,0 +1,130 @@
+/**
+ * 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) {
+    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) {
+    if (result == null || typeof result !== "object")
+        return undefined;
+    const blocks = resultContentBlocks(result);
+    if (!blocks)
+        return undefined;
+    const canonical = [];
+    let sawImage = false;
+    for (const block of blocks) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        if (b.image && typeof b.image === "object") {
+            const img = b.image;
+            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) {
+    const value = obj.value;
+    if (value && typeof value === "object" && Array.isArray(value.content)) {
+        return value.content;
+    }
+    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) {
+    if (data && typeof data === "object") {
+        const d = data;
+        if (d.type === "Buffer" && Array.isArray(d.data)) {
+            try {
+                return Buffer.from(d.data).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) {
+    const t = b.text;
+    if (typeof t === "string")
+        return t;
+    if (t && typeof t === "object" && typeof t.text === "string") {
+        return t.text;
+    }
+    return undefined;
+}
+//# sourceMappingURL=tool-result.js.map

package/dist/activities/execute-cursor/tool-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/tool-result.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-cursor/translator.d.ts

@@ -0,0 +1,178 @@
+/**
+ * CursorTranslator — the Cursor harness's translator: the `@cursor/sdk`'s two
+ * event channels in, the canonical `TranscriptEvent` union out
+ * (`harness/transcript/events.ts`).
+ *
+ * The one module that knows the SDK's wire shape:
+ * the shared `TranscriptBuilder` folds what comes out of here and nothing of
+ * the engine reaches it otherwise. Until #1097 the Cursor harness folded its
+ * own transcript — the message accumulator (the second copy of the folding
+ * rule the memo counted), the delta enricher (row writes from the delta
+ * channel) and the todo tracker (a third writer of `status.todos`) — and
+ * every rule they held
+ * is either the builder's now or answered here. The same word, the same
+ * `translate(raw)` signature and the same seat in its adapter as
+ * `execute-deep-agent/translator.ts`, so a third harness's author finds one
+ * shape in both.
+ *
+ * TWO CHANNELS, ONE DISCIPLINE. The SDK streams `SDKMessage`s from
+ * `run.stream()` (the source of truth for messages and rows) and fires
+ * `InteractionUpdate`s through `onDelta` between them (tool-call timings, live
+ * shell output, a completion's status — facts the stream delivers later or
+ * never). A delta lands while the loop may be awaiting a persist, and a row
+ * write mid-persist would land on a row the offload is replacing, so this
+ * translator never hands a delta's events to anyone
+ * directly: {@link observeDelta} QUEUES them and the loop applies
+ * {@link drainDeltas} after each stream event, and once more before
+ * `finalize()`. A delta for a call the stream has not announced yet (the
+ * output that beats the `running` event) is HELD and replayed right after the
+ * `tool_started` that announces it. Because the fold is later than
+ * the observation, a completion learned from a delta carries `observedAt` —
+ * the instant the tool actually finished — and the builder stamps that, not
+ * the fold's moment. Rows are CREATED by the stream alone: the
+ * delta channel amends (output, completion), never announces.
+ *
+ * WHAT THIS TRANSLATOR ANSWERS, per event:
+ *
+ *   - The MESSAGE BOUNDARY. Cursor has one `run_id` per `send()`,
+ *     and its message boundary is a tool call: text after a tool call is a new
+ *     message. So `runId` here is a minted SEGMENT id, `<run_id>:<n>`, advanced
+ *     on the first text or thinking after a tool call; a tool call emits
+ *     `message_finish` for the open segment (closing its text and thinking).
+ *   - The row's IDENTITY. An MCP call arrives as `name: "mcp"` with the real
+ *     tool packed in `args` (`{ providerIdentifier, toolName, args }`); the row
+ *     is the inner tool. A resumed agent re-runs an approved tool under a
+ *     BRAND-NEW call id; the seeded WAITING row it belongs to is found by the
+ *     identity token the hook and the grants already share, the
+ *     `tool_started` is emitted with the SEEDED id so the builder's by-id flip
+ *     does the rest, and every later event for the new id is aliased onto it.
+ *     The seeded rows that can match exist only in the seed (nothing created
+ *     mid-stream is WAITING until the boundary runs), so they are indexed once
+ *     at construction and consumed on match (a declined row is a
+ *     closed gate and never matched).
+ *   - The GATE and the PROVENANCE. `gate` is the POLICY's word —
+ *     this MCP tool's merged policy, or this built-in's category, requires
+ *     approval — resolved exactly as the accumulator did, lease- and
+ *     bypass-blind; it is NOT the hook's verdict (the hook has arms this side
+ *     cannot evaluate: capture mode, grants, bypass, secret blocks — the
+ *     lesson behind dropping a parked-at-creation arm that had no producer).
+ *     A gated call that STARTED runs until the boundary parks
+ *     it through `approval_proposed`. Provenance is the shared read-side
+ *     `resolveApprovalProvenance` over the same policies and the run's leases.
+ *   - The RESULT string (`tool-result.ts`): a failure's text is its `error`
+ *     alone.
+ *   - The SUB-AGENT: a `task` tool call opens a sub-agent keyed by
+ *     the call id (`sub_agent_started` before the row's own `tool_started`);
+ *     its completion emits the row's `tool_finished`, the child's transcript
+ *     as scoped events (`sub-agent-steps.ts` — Cursor delivers it whole, at
+ *     completion), then `sub_agent_finished` with the same output string; an
+ *     error, `tool_error` then `sub_agent_failed`.
+ *   - The `task` SDK event → `system_note`; a todo write is an
+ *     ordinary tool call the builder keys on `ToolKind.TODO` and projects;
+ *     `system`, `status`, `user`, `request` and `usage` carry no
+ *     transcript fact (usage is the loop's, priced from the `turn-ended`
+ *     delta in `turn-stream.ts` — the same division as native's `usageOf`).
+ *
+ * Stateful, one per turn, shared by the primary stream and the recovery
+ * retries exactly as the accumulator was (the segment map is keyed by
+ * `run_id`, and a retry's send has its own).
+ */
+import type { InteractionUpdate, SDKMessage } from "@cursor/sdk";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { TranscriptEvent } from "../../harness/transcript/events.js";
+import { type MergedToolPolicy } from "../../shared/approval-policy.js";
+import type { ToolApprovalCategory } from "../../shared/tool-kind.js";
+type ToolCallEvent = Extract<SDKMessage, {
+    type: "tool_call";
+}>;
+/** The run's approval posture the translator answers `gate` and `provenance` from. */
+export interface CursorTranslatorOptions {
+    /** The merged four-level MCP policy map (`mergeApprovalPolicies`). */
+    readonly policies: ReadonlyMap<string, MergedToolPolicy>;
+    /** The run-lifetime leases: the pre-armed global bypass and the built-in categories approved for the run. */
+    readonly leases: {
+        readonly global: boolean;
+        readonly categories: ReadonlySet<ToolApprovalCategory>;
+    };
+    /** The transcript as seeded at turn start (`status.messages`): the WAITING rows a resumed agent's re-issued call may belong to. */
+    readonly seeded: readonly AgentMessage[];
+}
+export declare class CursorTranslator {
+    private readonly options;
+    private readonly segments;
+    /** Row ids the stream has announced (a `tool_started` was emitted for them). */
+    private readonly announced;
+    /** A resumed agent's fresh call id → the seeded row it re-runs. */
+    private readonly aliases;
+    /** Identity token → the seeded WAITING rows with it, in transcript order; consumed on match. */
+    private readonly resumable;
+    /** The `task` rows whose completion closes a sub-agent. */
+    private readonly taskCalls;
+    /** Delta-derived events for announced rows, awaiting the loop's drain. */
+    private queue;
+    /**
+     * Delta-derived events for calls the stream has not announced yet, keyed by
+     * the delta's own call id and kept as makers: the row they belong to is
+     * known only when the stream announces the call (a resumed agent's re-run
+     * is aliased onto a seeded row then), so each is materialized at replay.
+     */
+    private readonly held;
+    /** The most recent shell call the delta channel started — the home of an output delta that names no call. */
+    private lastShellCallId;
+    constructor(options: CursorTranslatorOptions);
+    /** One stream event to its canonical events — `translate(raw)` is the one signature every harness's translator shares. */
+    translate(event: SDKMessage): TranscriptEvent[];
+    /**
+     * One delta, queued — never applied here (see the header). The loop drains
+     * the queue after the stream event it is processing.
+     */
+    observeDelta(update: InteractionUpdate): void;
+    /** The delta-derived events ready to apply, in arrival order; empties the queue. */
+    drainDeltas(): TranscriptEvent[];
+    /** The segment id text or thinking streams into now, and the `message_start` that opens it if none is open. */
+    private openSegment;
+    /** A tool call ends the open segment: its text and thinking are finished, and the next text starts a new message. */
+    private closeSegment;
+    private segmentOf;
+    private translateToolCall;
+    /**
+     * The row a call's events fold into: the id the stream gave it, unless the
+     * call is a resumed agent's re-run of a seeded WAITING row (the same
+     * identity token), in which case the seeded id — aliased for every
+     * later event of this call.
+     */
+    private resolveRowId;
+    private toolStarted;
+    /**
+     * The policy's word that this call requires approval, and the card's
+     * message — or nothing for an ungated call. An MCP call (the `mcp` envelope,
+     * whatever its provider field says) is governed by the merged policy map
+     * alone; a built-in by its category.
+     */
+    private gateOf;
+    private rowIdOf;
+    private enqueue;
+}
+/**
+ * Details extracted from an MCP tool call event's args.
+ *
+ * When Cursor invokes an MCP tool, the SDK stream reports event.name as
+ * "mcp" and packs the real tool identity into event.args:
+ * { providerIdentifier: "planton", toolName: "search_services", args: {...} }
+ */
+export interface McpToolDetails {
+    providerIdentifier: string;
+    toolName: string;
+    innerArgs: Record<string, unknown>;
+}
+/** The MCP tool a `tool_call` event names, or undefined for a built-in. */
+export declare function extractMcpToolDetails(event: ToolCallEvent): McpToolDetails | undefined;
+/**
+ * The sub-agent's name from the task tool's args, in both the legacy string
+ * form (`"generalPurpose"`) and the SDK's object form
+ * (`{ kind: "generalPurpose", name?: "..." }`); `description` (always set by
+ * the SDK) before the generic `"task"`. The `kind` value `"unspecified"` is
+ * treated as absent — the SDK's default when the blueprint names no type.
+ */
+export declare function extractSubagentName(args: unknown): string;
+export {};