@stigmer/runner 3.0.1

package/dist/activities/execute-cursor/prompt-builder.js

@@ -0,0 +1,280 @@
+/**
+ * Builds the enhanced prompt for the Cursor agent.
+ *
+ * Replicates prompt_builder.py::enhance_system_prompt() but delivers
+ * the content via the first user message (Cursor SDK has no systemPrompt
+ * parameter). On reinvocation, only the approval decisions are sent.
+ *
+ * Sections (in order, conditionally included):
+ * 1. Agent instructions (persona/character)
+ * 2. Available skills metadata
+ * 3. Sub-agent delegation guidance
+ * 4. Workspace context (multi-root only; single-dir is redundant with SDK cwd)
+ * 5. Input files / referenced files
+ * 6. Response rules (only when agent has no custom instructions)
+ * 7. User's actual message
+ */
+import { resolve } from "node:path";
+import { ApprovalAction, InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+/**
+ * Marker path segments that identify runner-internal directories. A workspace
+ * dir containing any of these segments is almost certainly the runner's own
+ * app directory, not a user workspace.
+ */
+const RUNNER_PATH_MARKERS = [
+    "/runtimes/cursor-runner/",
+    "/runtimes/agent-runner/",
+    "/node_modules/",
+    "/dist/main.js",
+];
+/**
+ * Build the enhanced prompt for the first execution in a session.
+ *
+ * Prepends agent blueprint information before the user's message so the
+ * Cursor agent has full context. This avoids writing files to the workspace.
+ */
+export function buildEnhancedPrompt(options) {
+    const sections = [];
+    const modePrefix = formatInteractionModePrefix(options.interactionMode);
+    if (modePrefix) {
+        sections.push(modePrefix);
+    }
+    if (options.instructions) {
+        sections.push(formatInstructions(options.instructions));
+    }
+    if (options.skills.length > 0) {
+        sections.push(formatSkillsSection(options.skills));
+    }
+    if (options.subAgents.length > 0) {
+        sections.push(formatSubAgentsSection(options.subAgents));
+    }
+    const safeDirs = sanitizeWorkspaceDirs(options.workspaceDirs);
+    // Encourage Cursor's built-in `explore` sub-agent for codebase work whenever
+    // there is a workspace to explore — the headless agent otherwise rarely
+    // delegates exploration the way the Cursor IDE does.
+    if (safeDirs.length > 0) {
+        sections.push(formatExplorationGuidance());
+    }
+    if (safeDirs.length > 1) {
+        sections.push(formatWorkspaceContext(safeDirs));
+    }
+    if (options.attachmentPaths.length > 0) {
+        sections.push(formatInputFiles(options.attachmentPaths));
+    }
+    if (options.workspaceFileRefs.length > 0) {
+        sections.push(formatReferencedFiles(options.workspaceFileRefs));
+    }
+    if (!options.instructions) {
+        sections.push(formatResponseRules());
+    }
+    sections.push(`<user_request>\n${options.userMessage}\n</user_request>`);
+    return sections.join("\n\n---\n\n");
+}
+/**
+ * Build the reinvocation prompt after approval decisions.
+ *
+ * Only contains approval instructions, no blueprint (it persists in the resumed
+ * agent's native context). The actions are described in human-meaningful terms
+ * (the resolved approval message, e.g. "Write file: foo.txt") — NOT the opaque
+ * tool-call ids, which mean nothing to the model. A resumed agent re-issues the
+ * approved tool with a fresh id; the approval gate (see approval-state.ts grants)
+ * is what actually lets the re-attempt through.
+ */
+export function buildReinvocationPrompt(pendingApprovals, approvalDecisions) {
+    const approved = [];
+    const skipped = [];
+    for (const pa of pendingApprovals) {
+        const action = approvalDecisions.get(pa.toolCallId);
+        if (action === ApprovalAction.APPROVE) {
+            approved.push(describeApproval(pa));
+        }
+        else if (action === ApprovalAction.SKIP) {
+            skipped.push(describeApproval(pa));
+        }
+    }
+    const parts = [];
+    if (approved.length) {
+        parts.push("The user reviewed the following action(s) you proposed and APPROVED them. " +
+            "Carry them out now:\n" +
+            approved.map((a) => `- ${a}`).join("\n"));
+    }
+    if (skipped.length) {
+        parts.push("The user SKIPPED the following action(s). Do not perform them; continue " +
+            "with the rest of the task without them:\n" +
+            skipped.map((a) => `- ${a}`).join("\n"));
+    }
+    return parts.join("\n\n");
+}
+/**
+ * Render a pending approval as a short human-readable action description for the
+ * reinvocation prompt. Prefers the already-resolved approval message; falls back
+ * to the tool name plus a bounded args preview.
+ */
+function describeApproval(pa) {
+    if (pa.message)
+        return pa.message;
+    const name = pa.mcpServerSlug ? `${pa.mcpServerSlug}/${pa.toolName}` : pa.toolName;
+    if (!pa.argsPreview)
+        return name;
+    const preview = pa.argsPreview.length > 200
+        ? `${pa.argsPreview.slice(0, 200)}…`
+        : pa.argsPreview;
+    return `${name} (${preview})`;
+}
+/**
+ * Filters out workspace directories that appear to be runner-internal paths.
+ * This prevents the prompt from exposing implementation details like
+ * ~/.stigmer/runtimes/cursor-runner/... to the AI model.
+ */
+export function sanitizeWorkspaceDirs(dirs) {
+    const safe = [];
+    for (const dir of dirs) {
+        const resolved = resolve(dir);
+        if (isRunnerInternalPath(resolved)) {
+            console.warn(`Workspace dir "${dir}" appears to be a runner-internal path — ` +
+                "omitting from prompt to prevent implementation detail leakage.");
+            continue;
+        }
+        safe.push(dir);
+    }
+    return safe;
+}
+function isRunnerInternalPath(absolutePath) {
+    return RUNNER_PATH_MARKERS.some((marker) => absolutePath.includes(marker));
+}
+export function formatInstructions(instructions) {
+    return `<agent_instructions>\n${instructions}\n</agent_instructions>`;
+}
+export function formatSkillsSection(skills) {
+    const entries = skills.map((s) => `- **${s.name}**: ${s.description}\n  Path: \`${s.path}\``);
+    return [
+        "<available_skills>",
+        "You have access to the following skills. When a skill is relevant, read its SKILL.md file using the Read tool and follow the instructions within.",
+        "",
+        ...entries,
+        "</available_skills>",
+    ].join("\n");
+}
+export function formatSubAgentsSection(subAgents) {
+    let anyAdvisoryMcp = false;
+    const entries = subAgents.map((sa) => {
+        const parts = [`- **${sa.name}**: ${sa.description}`];
+        if (sa.mcpAccess.length > 0) {
+            anyAdvisoryMcp = true;
+            const servers = sa.mcpAccess.map((a) => a.mcpServer).join(", ");
+            parts.push(`  MCP access (advisory): ${servers}`);
+        }
+        if (sa.modelOverride) {
+            parts.push(`  Model: ${sa.modelOverride}`);
+        }
+        return parts.join("\n");
+    });
+    const lines = [
+        "<sub_agent_delegation>",
+        "You can delegate tasks to these specialized sub-agents using the Task tool",
+        "(pass the sub-agent's name as the subagent type). They are registered and",
+        "run independently, each with its own fresh context.",
+        "",
+        "Available sub-agents:",
+        "",
+        ...entries,
+        "",
+        "Delegation rules:",
+        "- Delegate a task to the sub-agent whose specialization matches it.",
+        "- Give a clear, self-contained task description — sub-agents do not share your conversation context.",
+        "- Sub-agents run independently and return their results when done.",
+    ];
+    if (anyAdvisoryMcp) {
+        lines.push("- \"MCP access (advisory)\" lists the tools a sub-agent is intended to use; " +
+            "sub-agents inherit this agent's tool access, so treat it as guidance, not a hard limit.");
+    }
+    lines.push("</sub_agent_delegation>");
+    return lines.join("\n");
+}
+/**
+ * Guidance encouraging the agent to use Cursor's built-in `explore` sub-agent
+ * (via the Task tool) for codebase investigation, rather than reading many
+ * files inline. Included only when the agent has a workspace to explore.
+ *
+ * This mirrors how the Cursor IDE aggressively delegates exploration, which the
+ * headless agent otherwise rarely does. Kept concise to limit token overhead
+ * and paired with a "do not over-delegate" guard to avoid trivial spawns.
+ */
+export function formatExplorationGuidance() {
+    return [
+        "<codebase_exploration>",
+        "For non-trivial investigation of this codebase, prefer delegating to the",
+        "built-in `explore` sub-agent via the Task tool instead of reading many",
+        "files yourself. Launch one explore task per distinct area you need to",
+        "understand — they run in parallel, return focused findings, and keep your",
+        "main context clean.",
+        "",
+        "Use explore for: locating where functionality lives, tracing how a feature",
+        "works across files, or surveying unfamiliar areas. Do NOT delegate trivial",
+        "single-file reads or small edits you can do directly.",
+        "</codebase_exploration>",
+    ].join("\n");
+}
+export function formatWorkspaceContext(dirs) {
+    if (dirs.length === 1) {
+        return `<workspace>\nWorking directory: ${dirs[0]}\n</workspace>`;
+    }
+    const entries = dirs.map((d, i) => `${i + 1}. ${d}`);
+    return [
+        "<workspace>",
+        "Multi-root workspace with the following directories:",
+        ...entries,
+        "</workspace>",
+    ].join("\n");
+}
+export function formatInputFiles(paths) {
+    const entries = paths.map((p) => `- \`${p}\``);
+    return [
+        "<input_files>",
+        "The following files have been provided as inputs. Read them when relevant to the task:",
+        ...entries,
+        "</input_files>",
+    ].join("\n");
+}
+export function formatReferencedFiles(refs) {
+    const entries = refs.map((r) => `- \`${r}\``);
+    return [
+        "<referenced_files>",
+        "The user has referenced the following workspace files. Read them when relevant:",
+        ...entries,
+        "</referenced_files>",
+    ].join("\n");
+}
+/**
+ * Returns a system-level directive when the execution is in Plan mode.
+ * Returns `undefined` for Agent mode (default) since no prefix is needed.
+ */
+export function formatInteractionModePrefix(mode) {
+    if (mode == null ||
+        mode === InteractionMode.UNSPECIFIED ||
+        mode === InteractionMode.AGENT) {
+        return undefined;
+    }
+    if (mode === InteractionMode.PLAN) {
+        return [
+            "<interaction_mode>",
+            "IMPORTANT: You are in Plan mode. Analyze the codebase and produce a detailed plan.",
+            "Do NOT create, edit, or delete any files. Do NOT run commands that modify the filesystem.",
+            "Only read, search, and analyze. Your output should be analysis, recommendations, and",
+            "implementation plans — not code changes.",
+            "</interaction_mode>",
+        ].join("\n");
+    }
+    return undefined;
+}
+export function formatResponseRules() {
+    return [
+        "<response_rules>",
+        "- Be concise and direct in your responses",
+        "- When making code changes, explain what you changed and why",
+        "- If a task is unclear, ask for clarification before proceeding",
+        "- Prefer editing existing files over creating new ones",
+        "</response_rules>",
+    ].join("\n");
+}
+//# sourceMappingURL=prompt-builder.js.map

package/dist/activities/execute-cursor/prompt-builder.js.map

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

package/dist/activities/execute-cursor/rejection-capture.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Captures ConnectError details from process-level unhandledRejection events
+ * and correlates them to the active Cursor execution via AsyncLocalStorage.
+ *
+ * Background: The Cursor SDK has a confirmed bug where ConnectRPC stream
+ * errors escape as process-level unhandledRejection instead of surfacing
+ * through run.stream() or run.wait(). The actual error (e.g.,
+ * [unauthenticated], [unavailable]) carries diagnostic detail that
+ * run.wait() strips to a bare { status: "error" }.
+ *
+ * This module installs a process-level handler that extracts ConnectError
+ * fields and stores them in a Map keyed by executionId. The execute-cursor
+ * activity reads from this Map after run.wait() resolves to enrich the
+ * error message.
+ *
+ * Forum reference:
+ * https://forum.cursor.com/t/agent-send-wait-returns-bare-status-error-while-connectrpc-unauthenticated-leaks-as-unhandledrejection/161203
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+export interface CapturedRejection {
+    code: string;
+    message: string;
+    timestamp: number;
+}
+export declare function setExecutionContextRef(ctx: AsyncLocalStorage<{
+    executionId: string;
+}>): void;
+export declare function getCapturedRejection(executionId: string): CapturedRejection | undefined;
+export declare function clearCapturedRejection(executionId: string): void;
+export declare function handleUnhandledRejection(reason: unknown): void;

package/dist/activities/execute-cursor/rejection-capture.js

@@ -0,0 +1,80 @@
+/**
+ * Captures ConnectError details from process-level unhandledRejection events
+ * and correlates them to the active Cursor execution via AsyncLocalStorage.
+ *
+ * Background: The Cursor SDK has a confirmed bug where ConnectRPC stream
+ * errors escape as process-level unhandledRejection instead of surfacing
+ * through run.stream() or run.wait(). The actual error (e.g.,
+ * [unauthenticated], [unavailable]) carries diagnostic detail that
+ * run.wait() strips to a bare { status: "error" }.
+ *
+ * This module installs a process-level handler that extracts ConnectError
+ * fields and stores them in a Map keyed by executionId. The execute-cursor
+ * activity reads from this Map after run.wait() resolves to enrich the
+ * error message.
+ *
+ * Forum reference:
+ * https://forum.cursor.com/t/agent-send-wait-returns-bare-status-error-while-connectrpc-unauthenticated-leaks-as-unhandledrejection/161203
+ */
+const capturedRejections = new Map();
+const REJECTION_TTL_MS = 5 * 60 * 1000;
+let executionContextRef = null;
+export function setExecutionContextRef(ctx) {
+    executionContextRef = ctx;
+}
+export function getCapturedRejection(executionId) {
+    return capturedRejections.get(executionId);
+}
+export function clearCapturedRejection(executionId) {
+    capturedRejections.delete(executionId);
+}
+function isConnectError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const name = err.constructor?.name ?? "";
+    return name === "ConnectError"
+        || err.name === "ConnectError"
+        || (typeof err.code === "string"
+            && err.message?.includes("[")
+            && (err.stack?.includes("connectrpc") ?? false));
+}
+function extractConnectCode(err) {
+    if (typeof err.code === "string")
+        return err.code;
+    const bracketMatch = err.message.match(/\[([a-z_]+)\]/);
+    if (bracketMatch)
+        return bracketMatch[1];
+    return "unknown";
+}
+export function handleUnhandledRejection(reason) {
+    if (isConnectError(reason)) {
+        const code = extractConnectCode(reason);
+        const executionId = executionContextRef?.getStore()?.executionId;
+        if (executionId) {
+            capturedRejections.set(executionId, {
+                code,
+                message: reason.message,
+                timestamp: Date.now(),
+            });
+            console.error(`[rejection-capture] ConnectError correlated to execution=${executionId}, ` +
+                `code=${code}, message=${reason.message}`);
+        }
+        else {
+            console.error(`[rejection-capture] ConnectError without execution context: ` +
+                `code=${code}, message=${reason.message}`);
+        }
+    }
+    else {
+        console.error("Unhandled rejection in runner:", reason);
+    }
+    evictStaleEntries();
+}
+function evictStaleEntries() {
+    const now = Date.now();
+    for (const [id, entry] of capturedRejections) {
+        if (now - entry.timestamp > REJECTION_TTL_MS) {
+            capturedRejections.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=rejection-capture.js.map

package/dist/activities/execute-cursor/rejection-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rejection-capture.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/rejection-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAA6B,CAAC;AAEhE,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAEvC,IAAI,mBAAmB,GAAsD,IAAI,CAAC;AAElF,MAAM,UAAU,sBAAsB,CACpC,GAA+C;IAE/C,mBAAmB,GAAG,GAAG,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,OAAO,kBAAkB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,kBAAkB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,cAAc,CAAC,GAAY;IAClC,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC;IACzC,OAAO,IAAI,KAAK,cAAc;WACzB,GAAG,CAAC,IAAI,KAAK,cAAc;WAC3B,CAAC,OAAQ,GAA0C,CAAC,IAAI,KAAK,QAAQ;eACnE,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC;eAC1B,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,kBAAkB,CAAC,GAA8B;IACxD,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,IAAI,CAAC;IAClD,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IACxD,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;IACzC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,MAAe;IACtD,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,WAAW,GAAG,mBAAmB,EAAE,QAAQ,EAAE,EAAE,WAAW,CAAC;QAEjE,IAAI,WAAW,EAAE,CAAC;YAChB,kBAAkB,CAAC,GAAG,CAAC,WAAW,EAAE;gBAClC,IAAI;gBACJ,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;aACtB,CAAC,CAAC;YACH,OAAO,CAAC,KAAK,CACX,4DAA4D,WAAW,IAAI;gBAC3E,QAAQ,IAAI,aAAa,MAAM,CAAC,OAAO,EAAE,CAC1C,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CACX,8DAA8D;gBAC9D,QAAQ,IAAI,aAAa,MAAM,CAAC,OAAO,EAAE,CAC1C,CAAC;QACJ,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;IAED,iBAAiB,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,iBAAiB;IACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,kBAAkB,EAAE,CAAC;QAC7C,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,gBAAgB,EAAE,CAAC;YAC7C,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/activities/execute-cursor/session-lifecycle.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Maps Stigmer Session lifecycle to Cursor Agent lifecycle.
+ *
+ * SessionSpec.harness_state_id stores the Cursor agentId. This module handles
+ * creating new agents (first execution), resuming existing agents
+ * (subsequent executions), graceful fallback on resume failure, and
+ * cleaning up agents (session deletion).
+ *
+ * Two execution modes:
+ *
+ * - Local mode: Agent.create({ local: { cwd } }) with explicit
+ *   platform.workspaceRef/stateRoot for deterministic store keying.
+ *   Produces agent- prefixed IDs.
+ *
+ * - Cloud mode (feature-flagged): Agent.create({ cloud: { repos } })
+ *   for git-backed workspaces. Produces bc- prefixed IDs. No platform
+ *   options — cloud state lives on Cursor's servers, not local SQLite.
+ *
+ * Key SDK limitation: mcpServers are NOT persisted across Agent.resume().
+ * They must be passed again on every resume call.
+ *
+ * Platform store keying (local only): The Cursor SDK defaults to
+ * process.cwd() for its internal state root lookup. In cloud sandboxes,
+ * process.cwd() is the runner's app directory, not the workspace — causing
+ * Agent.resume() to fail with "Agent not found". We pass explicit
+ * platform.workspaceRef and platform.stateRoot derived from the Stigmer
+ * sessionId to ensure deterministic store lookup regardless of process.cwd().
+ *
+ * Durability model: the SDK's local SQLite store (agent records, runs,
+ * checkpoints) is the source of truth for conversation continuation. It is
+ * persisted under the durable workspace volume (see resolvePlatformOptions)
+ * so Agent.resume() survives pod restart, reschedule, and snapshot restore.
+ * When resume nonetheless fails (store lost, corrupted, or agent unknown),
+ * this module creates a fresh agent and the caller starts a new turn from
+ * the user message plus re-injected instructions — there is no separate
+ * continuation store.
+ */
+import type { SDKAgent, CursorAgentPlatformOptions, AgentDefinition } from "@cursor/sdk";
+import type { CursorMcpServerConfig } from "./mcp-resolver.js";
+export interface CreateAgentOptions {
+    apiKey: string;
+    model: string;
+    workspaceDirs: string[];
+    sessionId: string;
+    /** Durable workspace volume root; the SDK state store lives under it. */
+    workspaceRootDir: string;
+    mcpServers?: Record<string, CursorMcpServerConfig>;
+    /**
+     * Custom sub-agents registered with the Cursor SDK so the parent can delegate
+     * to them by name via the Task tool. Not persisted across resume, so it must
+     * be re-supplied on every create/resume (mirrors mcpServers).
+     */
+    agents?: Record<string, AgentDefinition>;
+}
+export interface ResumeAgentOptions {
+    apiKey: string;
+    agentId: string;
+    sessionId: string;
+    /** Durable workspace volume root; the SDK state store lives under it. */
+    workspaceRootDir: string;
+    model?: string;
+    mcpServers?: Record<string, CursorMcpServerConfig>;
+    /** Custom sub-agents — see {@link CreateAgentOptions.agents}. */
+    agents?: Record<string, AgentDefinition>;
+}
+export interface CloudRepo {
+    url: string;
+    startingRef?: string;
+}
+export interface CreateCloudAgentOptions {
+    apiKey: string;
+    model?: string;
+    repos: CloudRepo[];
+    sessionId: string;
+    mcpServers?: Record<string, CursorMcpServerConfig>;
+    /** Custom sub-agents — see {@link CreateAgentOptions.agents}. */
+    agents?: Record<string, AgentDefinition>;
+}
+export interface ResumeCloudAgentOptions {
+    apiKey: string;
+    agentId: string;
+    model?: string;
+    mcpServers?: Record<string, CursorMcpServerConfig>;
+    /** Custom sub-agents — see {@link CreateAgentOptions.agents}. */
+    agents?: Record<string, AgentDefinition>;
+}
+/**
+ * Discriminated reason explaining how the agent was resolved.
+ *
+ * Drives prompt selection in execute-cursor.ts:
+ * - created_first_execution: first turn, fresh agent
+ * - resumed_successfully: subsequent turn, agent alive (native context)
+ * - created_after_resume_failure: agent unknown/lost, fresh agent (no prior context)
+ */
+export type AgentResolutionReason = "created_first_execution" | "resumed_successfully" | "created_after_resume_failure";
+/**
+ * Result of resolveAgent() — carries the agent handle plus metadata that
+ * downstream phases use for prompt selection, harness_state_id persistence, and
+ * diagnostic logging.
+ */
+export interface AgentResolution {
+    agent: SDKAgent;
+    agentId: string;
+    isNew: boolean;
+    resumed: boolean;
+    mode: "local" | "cloud";
+    reason: AgentResolutionReason;
+    /** Non-empty only when reason is "created_after_resume_failure". */
+    resumeFailureDetail?: string;
+}
+/**
+ * Compute deterministic platform options for a Stigmer session.
+ *
+ * workspaceRef is a synthetic identifier (not a filesystem path) that
+ * ensures the SDK's platform cache key is stable across activity
+ * invocations regardless of process.cwd().
+ *
+ * stateRoot is a session-isolated directory under the durable workspace
+ * volume ({workspaceRootDir}/.stigmer/cursor-sdk-state/{sessionId}) where
+ * the SDK persists its SQLite stores (agent records, runs, checkpoints).
+ * Placing it on the workspace volume (rather than $HOME) makes native
+ * Agent.resume() survive pod restart/reschedule and snapshot restore, and
+ * keys it by sessionId so sessions sharing one volume (e.g. the child agent
+ * executions of a workflow sandbox) never collide. Created eagerly to
+ * prevent ENOENT on first SDK write.
+ *
+ * Both inputs are required and must be non-empty: the stateRoot is keyed by
+ * sessionId, so an empty sessionId would collapse every session sharing the
+ * volume onto the same store and corrupt their conversation state.
+ */
+export declare function resolvePlatformOptions(sessionId: string, workspaceRootDir: string): CursorAgentPlatformOptions;
+/**
+ * Create a new local Cursor Agent for the first execution in a session.
+ *
+ * Supports multi-workspace: passes string[] when multiple dirs, string when single.
+ */
+export declare function createAgent(options: CreateAgentOptions): Promise<SDKAgent>;
+/**
+ * Resume an existing local Cursor Agent for subsequent executions.
+ *
+ * Throws on failure — the caller (resolveAgent) decides whether to
+ * propagate or fall back to a fresh agent with continuation context.
+ */
+export declare function resumeAgent(options: ResumeAgentOptions): Promise<SDKAgent>;
+/**
+ * Create a new cloud Cursor Agent for git-backed sessions.
+ *
+ * Cloud agents (bc- prefix) run on Cursor's servers with cloned repos.
+ * No platform options — cloud state lives server-side, not in local SQLite.
+ * Model is optional — Cursor resolves the caller's configured default
+ * when omitted.
+ */
+export declare function createCloudAgent(options: CreateCloudAgentOptions): Promise<SDKAgent>;
+/**
+ * Resume an existing cloud Cursor Agent for subsequent executions.
+ *
+ * Throws on failure — the caller (resolveAgent) decides whether to
+ * propagate or fall back to a fresh cloud agent with continuation context.
+ * No platform options — cloud state lives server-side.
+ */
+export declare function resumeCloudAgent(options: ResumeCloudAgentOptions): Promise<SDKAgent>;
+/**
+ * Resolve a Cursor Agent for execution: resume if possible, create with
+ * graceful fallback if resume fails.
+ *
+ * The mode parameter determines which create/resume functions are used:
+ * - "local": createAgent / resumeAgent (with platform options)
+ * - "cloud": createCloudAgent / resumeCloudAgent (no platform options)
+ *
+ * When harnessStateId is non-empty (subsequent execution):
+ *   1. Attempt Agent.resume with mode-appropriate options.
+ *   2. On success: return { resumed: true, reason: "resumed_successfully" }.
+ *   3. On failure: log warning, create a fresh agent, return
+ *      { resumed: false, reason: "created_after_resume_failure" }.
+ *      The fresh agent has no prior conversation context; the caller
+ *      starts a new turn from the user message and re-injected instructions.
+ *
+ * When harnessStateId is empty (first execution):
+ *   Create a new agent; return { reason: "created_first_execution" }.
+ *
+ * Agent creation failures always propagate — if we cannot create an agent
+ * at all, that is an unrecoverable infrastructure error.
+ */
+export declare function resolveAgent(harnessStateId: string, options: CreateAgentOptions | CreateCloudAgentOptions, mode?: "local" | "cloud"): Promise<AgentResolution>;
+/**
+ * Dispose a Cursor Agent when a session is deleted.
+ * Best-effort: logs and swallows errors.
+ */
+export declare function disposeAgent(agentId: string, apiKey: string): Promise<void>;