@stigmer/runner 3.14.1 → 3.15.0

package/dist/activities/execute-cursor/turn-setup.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The Cursor harness's setup — what this engine needs before it can be sent
+ * a turn, as small named steps over the runtime's resolved `TurnInput`, each
+ * returning a typed slice (the `SetupResult` mold, never one long function).
+ *
+ * Everything harness-agnostic has already happened when these run: the
+ * execution, session and blueprint are fetched, the workspace is provisioned
+ * and locked, the MCP servers and policies are merged, the skills are mounted,
+ * the attachments are resolved. What remains is Cursor's own reading of that
+ * record: the cursor mode; the row facts beside the runtime's approval
+ * verdicts; the SDK's MCP config; the prompt-shaped view of the attachments;
+ * the HITL gate (hook script, approval state, grants, denial watcher,
+ * capture baseline, progress substrate); the catalog validation of the
+ * requested model; the credential, the sub-agents, the variant params and
+ * the agent itself (parked or resolved); the bind of a new agent's id through
+ * the sink; the prompt in one of its four shapes; the vision payload; the
+ * pricer; the OTel span.
+ *
+ * Every step reads `TurnInput` and the sink and nothing else of the runtime's.
+ * The `execution_setup` cold-start line is emitted here, once the agent is
+ * resolved, over the runtime's timeline (`sink.setupTiming`), so the one
+ * timeline reads end to end.
+ *
+ * Moved from `index.ts` `executeCursorInner` phases 4c to 10c at S2 M3b; the
+ * step bodies are the orchestrator's, verbatim where nothing changed.
+ */
+import type { SDKUserMessage } from "@cursor/sdk";
+import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { CursorMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+import type { Config } from "../../config.js";
+import type { TurnInput, TurnSink } from "../../harness/types.js";
+import { toCursorImages } from "../../shared/attachment-vision.js";
+import { type ProgressCaptureState, type ProgressSubstrate } from "../../shared/filereview/progress.js";
+import { type ApprovalGrant } from "./approval-state.js";
+import { toCursorMcpConfig } from "./cursor-mcp-config.js";
+import { type AttachmentPromptEntry, type VisionPromptInfo } from "./prompt-builder.js";
+import { resolveServiceTierParams } from "./service-tier.js";
+import { type AgentResolution, type CreateAgentOptions, type CreateCloudAgentOptions } from "./session-lifecycle.js";
+import type { TurnStreamState } from "./turn-stream.js";
+import { CursorUsagePricer } from "./usage-pricing.js";
+import { type HitlGateHandle } from "./workspace-setup.js";
+/**
+ * The runner config this harness reads per turn, as a named slice
+ * (`shared/workspace/session-provision.ts` `SessionProvisionConfig` is the
+ * idiom): a whole `Config` satisfies it, a test constructs these fields and
+ * nothing else.
+ */
+export type CursorAdapterConfig = Pick<Config, "proxyEndpoint" | "cursorApiKey" | "stigmerToken" | "stigmerTokenRef" | "workspaceRootDir" | "cloudModeEnabled" | "agentResolveTimeoutMs">;
+export type CursorAgentMode = "cloud" | "local";
+/** The row facts the runtime's approval verdicts sit beside (the contract's rule: the adapter reads the ROW for anything else it needs). */
+export interface AdjudicatedRows {
+    /** Create-vs-resume, derived from the state id exactly as the runtime derives it. */
+    readonly isReinvocation: boolean;
+    /** The sub-agent rows the accumulator re-registers on a resume. */
+    readonly seededSubAgents: readonly SubAgentExecution[];
+    /** The pending-approval protos the grant builder and the reinvocation prompt render. */
+    readonly adjudicatedApprovals: PendingApproval[];
+    /** The content digest that authorizes an approved edit by its exact bytes (a sibling edit to the same file re-gates). */
+    readonly adjudicatedContentDigests: Map<string, string>;
+}
+/** The HITL gate as installed for this turn, and what the stream and the boundary read from it. */
+export interface CursorGate {
+    /** Session HITL directory (runner-owned, outside the workspace): hook script, approval-state file, denial ledger. */
+    readonly hitlDir: string;
+    readonly hitlGate: HitlGateHandle;
+    readonly approvalGrants: ApprovalGrant[] | undefined;
+    /** The pre-turn tree in capture mode, pinned before the agent runs; the boundary diffs against it. */
+    readonly baselineTree: string | undefined;
+    readonly progressSubstrate: ProgressSubstrate | undefined;
+    readonly progressState: ProgressCaptureState;
+    /** Closes the denial-ledger watcher; idempotent. */
+    readonly stopDenialWatcher: () => void;
+    /** Restores the workspace's `.cursor/hooks.json` (issue #173); the runtime removes the `.stigmer` link after it. */
+    readonly removeGate: () => Promise<void>;
+}
+/** The engine this turn runs on: how it was resolved and everything a recovery needs to resolve it again. */
+export interface CursorEngine {
+    readonly agentMode: CursorAgentMode;
+    readonly cursorMode: CursorMode;
+    readonly requestedModel: string;
+    readonly validatedModel: string;
+    readonly effectiveApiKey: string;
+    readonly createOptions: CreateAgentOptions | CreateCloudAgentOptions;
+    readonly agentFingerprint: string;
+    /** Replaced by a recovery spine when a fresh agent takes over the turn. */
+    resolution: AgentResolution;
+    readonly modelParams: Awaited<ReturnType<typeof resolveServiceTierParams>>;
+    readonly usagePricer: CursorUsagePricer;
+}
+/** The prompt this turn sends, and the facts every send site (primary and both recoveries) needs. */
+export interface CursorPrompt {
+    readonly effectivePrompt: string;
+    /** The turn's full vision payload; a recovery send always carries it (issue #366's vision corollary). */
+    readonly turnImages: ReturnType<typeof toCursorImages>;
+    /** What the PRIMARY send carries: nothing on a HITL re-invocation of a resumed agent, whose conversation holds the images already. */
+    readonly primarySendImages: ReturnType<typeof toCursorImages>;
+    readonly toSendMessage: (prompt: string, images: {
+        data: string;
+        mimeType: string;
+    }[]) => string | SDKUserMessage;
+    readonly promptEstimatedTokens: number;
+    /** The fresh-agent recovery prompt, composed at recovery time from the transcript as it then stands. */
+    readonly buildRecoveryPrompt: (fresh: AgentResolution) => Promise<string>;
+}
+/**
+ * Cloud Cursor agents are disabled platform-wide (see determineCursorMode),
+ * so every session runs LOCAL. Any persisted cursor_mode is deliberately
+ * ignored so a session can never route to the cloud path while it is
+ * disabled — even one that was created when cloud was enabled.
+ */
+export declare function resolveCursorMode(input: TurnInput, config: CursorAdapterConfig): {
+    cursorMode: CursorMode;
+    agentMode: CursorAgentMode;
+};
+/** The adapter's own read of the adjudicated rows the runtime already turned into verdicts. */
+export declare function readAdjudicatedRows(input: TurnInput): AdjudicatedRows;
+/**
+ * The Cursor SDK config, projected from the runtime's final server list
+ * exactly once, plus the MCP env pre-flight (diagnostic, non-blocking).
+ */
+export declare function projectMcpConfig(input: TurnInput): ReturnType<typeof toCursorMcpConfig>;
+/** The prompt-shaped projections of the runtime's attachments: the `<input_files>` entries and the vision disclosure. */
+export declare function prepareAttachmentPrompt(input: TurnInput): {
+    attachmentEntries: AttachmentPromptEntry[];
+    visionPromptInfo: VisionPromptInfo | undefined;
+};
+/**
+ * Install the HITL approval gate BEFORE resolving the agent.
+ *
+ * The gate's runtime artifacts (hook script, approval-state file, denial
+ * ledger) live in the session HITL directory OUTSIDE the workspace; only a
+ * minimal, merged, transient .cursor/hooks.json is written into the repo,
+ * pointing at the hook script by absolute path. The hook is scoped to this
+ * runner's own process so the user's interactive IDE — sharing the same repo
+ * hooks.json — is never gated (issue #173). Installing here (rather than
+ * after agent create/resume) guarantees the hook is present no matter when
+ * the SDK reads hook config, and the adapter's finally restores the repo.
+ *
+ * On reinvocation, turn the user's approvals into tool-identity grants so
+ * the resumed agent's re-attempt (which carries a fresh tool-call id) is
+ * allowed through. Exact-applied writes are EXCLUDED from the grants: with no
+ * grant, a further write to that file is re-gated (the user sees every change).
+ * Capture mode: pin the pre-turn baseline tree before the agent runs (and
+ * before the gate is installed, though the gate files are excluded from the
+ * capture anyway). The turn-end capture diffs the post-turn tree against this
+ * to build the per-file cards; the baseline ref is also what a reject reverts
+ * to on resume. Covers a fresh turn and the approved-irreversible resume
+ * fall-through (the agent will run and may make further edits).
+ */
+export declare function installGate(input: TurnInput, sink: TurnSink, rows: AdjudicatedRows, streamState: TurnStreamState): Promise<CursorGate>;
+/**
+ * Resolve the Cursor agent (parked, created, resumed, or created after a
+ * resume failure), emit the cold-start line, and bind a NEW agent's id
+ * through the sink before anything else runs (Q-S2-11: a rejected bind ends
+ * the turn `failed`; the sink rejects and the caller's catch names it).
+ *
+ * The requested name and the effective tier and thinking mode are the
+ * runtime's; validating the NAME against Cursor's catalog is this harness's.
+ */
+export declare function resolveEngine(input: TurnInput, sink: TurnSink, config: CursorAdapterConfig, mode: {
+    cursorMode: CursorMode;
+    agentMode: CursorAgentMode;
+}): Promise<CursorEngine>;
+/** Create a fresh agent for a recovery spine (the same options as the primary resolve). */
+export declare function createFreshAgent(engine: CursorEngine): Promise<AgentResolution["agent"]>;
+/**
+ * Build the prompt in the shape the resolution calls for (`prompt-builder.ts`
+ * `buildPrompt`), with the per-turn directives that ride every send this
+ * turn makes (the structured-output contract, the implement-plan directive)
+ * and the vision payload policy.
+ */
+export declare function buildTurnPrompt(input: TurnInput, sink: TurnSink, engine: CursorEngine, rows: AdjudicatedRows): Promise<CursorPrompt>;