@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

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

@@ -0,0 +1,281 @@
+/**
+ * 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, the approval default and the agent's tool
+ * scope are resolved, the skills are mounted, the attachments are resolved.
+ * What remains is Cursor's own reading of that record: the cursor mode; the
+ * tool-list checks this engine can and cannot honour; the row facts beside the
+ * runtime's approval verdicts; the SDK's MCP config and tool restriction; the
+ * prompt-shaped view of the attachments; the agent's hooks (the evaluator,
+ * the workspace hook files a person's own folder may not carry, the tools
+ * a hook would answer for that Cursor never shows one); the HITL gate (hook
+ * script, approval state, grants, the hook server, denial watcher, and the
+ * hook sidecar bound as the runtime's CAS observations); 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 in #1070; the
+ * step bodies are the orchestrator's, verbatim where nothing changed.
+ */
+import type { SDKUserMessage } from "@cursor/sdk";
+import { CursorMode } from "@stigmer/apis/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 { HookEvaluator } from "../../shared/hooks/evaluate.js";
+import { type ApprovalGrant } from "./approval-state.js";
+import { type HookDecisionLog } from "./hook-server.js";
+import { toCursorMcpConfig } from "./cursor-mcp-config.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";
+import type { PendingApproval, TurnRows } from "../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+/**
+ * The runner config this harness reads per turn, as a named slice
+ * (`shared/workspace/session-provision.ts` `SessionProvisionConfig` is the
+ * idiom): taken from a `Config` at boot (`adapter.ts` `resolveCursorConfig`),
+ * a test constructs these fields and nothing else.
+ *
+ * `transport` is where the SDK's traffic goes: in the agent host, always the
+ * local proxy's Cursor lane, `null` only for an SDK that calls Cursor
+ * itself. `proxyEndpoint` is still the runner's own: whether the Cursor key
+ * is the Stigmer platform's, which decides the wording of a billing error.
+ * The two were one setting while the harness ran in the runner's process.
+ */
+export type CursorAdapterConfig = Pick<Config, "proxyEndpoint" | "cursorApiKey" | "stigmerTokenRef" | "workspaceRootDir" | "cloudModeEnabled" | "agentResolveTimeoutMs" | "cursorStreamStallTimeoutMs"> & {
+    readonly transport: string | null;
+};
+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 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 approvals a hook asked for, by tool-call id. */
+    readonly adjudicatedHookAsks: ReadonlySet<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 hooks' decisions on the calls that may run, for the rows' provenance; absent for an agent without hooks. */
+    readonly hookDecisions?: HookDecisionLog;
+    /** Closes the denial-ledger watcher; idempotent. */
+    readonly stopDenialWatcher: () => void;
+    /** Restores the workspace's hook files (issue #173) and stops the hook server; 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;
+};
+/**
+ * A turn this engine refuses because of the agent's tool lists, before
+ * anything runs: the fix is the agent author's, so the turn fails with this
+ * sentence on the `actionable` surface (`turn.ts` `classifyThrown`), as a
+ * `ToolListResolutionError` does on both engines.
+ */
+export declare class CursorToolListRefusal extends Error {
+    constructor(message: string);
+}
+/** The refusal for a saved subagent that brings what this engine cannot keep to it. */
+export declare function subagentBringsOwnMessage(name: string): string;
+/**
+ * The agent's tool lists, checked against what this engine can enforce, before
+ * anything is installed. Refuses the turn (throws {@link CursorToolListRefusal}
+ * or `ToolListResolutionError`, each settling it `failed` with its own
+ * sentence) when:
+ *  - a saved subagent the main agent may start brings its own plugins, hooks,
+ *    MCP servers or tool lists ({@link subagentBringsOwnMessage}): its definition reaches
+ *    the SDK as instructions, model and skills, and the hook cannot tell its
+ *    calls from the main agent's, so they would run unscoped or unhooked;
+ *  - a plugin subagent the main agent may start carries lists of its own: the hook
+ *    cannot tell which sub-agent made a call (`preToolUse` carries no
+ *    sub-agent id), and the SDK's `tools` options restrict only the main
+ *    loop, so a sub-agent's lists would silently not bind. The native engine
+ *    enforces them per sub-agent. A sub-agent `Agent(type, …)` excludes is
+ *    never registered (`subAgentsInScope`) and can never run, so its lists
+ *    cannot matter and it is not checked. No sub-agent's lists reach the
+ *    zero-resolution check below either: one with lists never gets past
+ *    this one;
+ *  - the agent has lists and the session runs a cloud agent, which takes
+ *    neither the SDK's `tools` options nor the workspace hook;
+ *  - the main agent admits `Agent` but limits it to a type list
+ *    (`Agent(type, …)`): Cursor's built-in sub-agent types start through a
+ *    `task` call that fires neither `preToolUse` nor `subagentStart` on the
+ *    1.0.31 local runtime (live probe, 2026-10-05,
+ *    `cursor-hook-protocol.live.test.ts`), so nothing could hold one back.
+ *    The native engine enforces the list; bare `Agent` and an excluded
+ *    `Agent` need no type check and pass;
+ *  - a non-empty `tools`, the agent's or the turn's, names nothing this turn
+ *    has (`checkMainToolListResolution`), as Claude refuses to launch such an
+ *    agent.
+ */
+export declare function checkToolScope(input: TurnInput, mode: {
+    agentMode: CursorAgentMode;
+}): void;
+/** The agent's hooks on this engine: the evaluator, and the SDK tools the turn hides because a hook would answer for them. */
+export interface CursorHooks {
+    readonly evaluator: HookEvaluator;
+    readonly hiddenTools: readonly string[];
+}
+/**
+ * A Cursor turn the workspace's hook files would leave unsafe is refused
+ * before any agent exists (`workspace-hook-files.ts` says why): a person's
+ * own folder whose `.claude` settings carry hooks, such settings reached
+ * through a link, or a gate file that is a link, which the engine would not
+ * load. Throws `CursorWorkspaceHooksRefusal`, which settles the turn
+ * `failed` on the `actionable` surface.
+ */
+export declare function checkWorkspaceHookFiles(input: TurnInput): Promise<void>;
+/**
+ * The agent's hooks, built as the native engine builds them
+ * (`shared/hooks/setup.ts`) over this engine's views of its calls
+ * (`hook-views.ts`); `null` for an agent with none this runner runs. Throws
+ * `HookSetupError` when a hook cannot run as written, or when the session
+ * runs a cloud agent, which loads no hook of the runner's.
+ */
+export declare function prepareHooks(input: TurnInput, sink: Pick<TurnSink, "stopSignal" | "recordActivity">, config: CursorAdapterConfig, mode: {
+    agentMode: CursorAgentMode;
+}): Promise<CursorHooks | null>;
+/**
+ * The real path an excluded `Read` may still reach files inside
+ * (`HookToolScope.readRoot`): the platform dir's, on a turn whose workspace
+ * `.stigmer` is the link to it (`stigmerSymlinkPointsAt`), else "". A turn
+ * that mounted no skill and no attachment made no link and has no platform
+ * content, so a `.stigmer` there is the repository's own and admits nothing.
+ */
+export declare function platformReadRoot(primaryDir: string, platformDir: string): Promise<string>;
+/**
+ * The platform dir's real path whatever the link says, for the hidden-skill
+ * refusal (`HookToolScope.skillRoot`): a skill an earlier turn mounted stays
+ * refused even on a turn that made no link. "" when the dir does not exist,
+ * which leaves nothing to refuse.
+ */
+export declare function platformRealRoot(platformDir: string): Promise<string>;
+/**
+ * What a Cursor agent create or resume that timed out says, by whether the
+ * retry on a fresh transport was the last attempt. In the agent host every
+ * Cursor call crosses the runner's Cursor lane, so the route it names is the
+ * runner's: the platform's proxy, or Cursor directly.
+ */
+export declare function resolveTimeoutMessage(facts: {
+    readonly resuming: boolean;
+    readonly timeoutSeconds: number;
+    readonly platformProxied: boolean;
+}): (finalAttempt: boolean) => string;
+/**
+ * The adapter's own read of the adjudicated rows the runtime already turned
+ * into verdicts, with what each was asked under: both from the log, as the
+ * runtime read it (`input.approvalDecisions`, `input.approvalAsks`); the
+ * rows (the asks the runtime seeded from the log, `sink.rows`) give only the
+ * set and the calls. Create-vs-resume is the adapter's
+ * fact about its ENGINE: a bound agent id (`threadId`, engine-minted) means
+ * the Cursor agent already holds this session's conversation, so this turn
+ * resumes it — the runtime's `isReinvocation` answers its own question and
+ * is not consulted here.
+ */
+export declare function readAdjudicatedRows(input: TurnInput, rows: Pick<TurnRows, "messages">): 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>;
+/**
+ * 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 is the runtime's (`harness/capture.ts`: the baseline is pinned
+ * before this adapter runs, the candidate captured after it returns); what
+ * this gate contributes is the hook's on-disk sidecar of gitignored writes,
+ * bound as the runtime's CAS observations.
+ */
+export declare function installGate(input: TurnInput, sink: TurnSink, rows: AdjudicatedRows, streamState: TurnStreamState, hooks: CursorHooks | null): 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 (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;
+}, hooks?: CursorHooks | null): 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,
+ * the turn's appended system prompt) and the vision payload policy.
+ */
+export declare function buildTurnPrompt(input: TurnInput, sink: TurnSink, engine: CursorEngine, rows: AdjudicatedRows): Promise<CursorPrompt>;