@stigmer/runner 3.14.0 → 3.15.0

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

@@ -0,0 +1,240 @@
+/**
+ * One Cursor engine turn — the SDK slice of the Cursor harness, behind the
+ * turn runtime's contract (`harness/types.ts`).
+ *
+ * `runCursorTurn` is what `adapter.ts`'s `runTurn` delegates to: the HITL
+ * gate, the agent (parked, created or resumed), the prompt, the stream, the
+ * turn boundary, `run.wait()` and its recovery spines, and its own teardown
+ * (the denial watcher, the gate, the OTel span, and what becomes of the agent
+ * handle). Everything else about a turn is the runtime's
+ * (`harness/run-turn.ts`): the resolution phases, the persist chokepoint, the
+ * watchdog, the cost cap, the interruption table, the completion epilogue,
+ * the lock.
+ *
+ * This module is where `@cursor/sdk` enters the adapter's graph (through
+ * `turn-setup.ts` and its siblings), which is WHY it is a separate module
+ * from `adapter.ts` and is loaded there with a dynamic import inside `boot`:
+ * the adapter's HTTP/2 interceptor must patch `node:http2` before the SDK
+ * (and, through it, `@connectrpc/connect-node`) is first imported, and the
+ * composition roots import `adapter.ts` before they boot it. Nothing outside
+ * `adapter.ts` imports this module.
+ *
+ * Never throws out of `runCursorTurn` (an SDK failure is `failed` with the
+ * classifier's sentence; an unexpected exception is `failed` on the
+ * `internal` surface; a `CancelledFailure` never exists here), never branches
+ * on why `stopSignal` aborted, never writes a phase or a terminal copy, never
+ * imports `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`).
+ *
+ * Engine disposition, one rule per outcome (Q-S2-6): the agent is PARKED
+ * for the session's next turn on every exit but a failure — `completed`,
+ * `cancelled`, `awaiting_approval` and `interrupted` alike (a wedged handle
+ * after a stall is caught by the poisoned-handle recovery on the next turn;
+ * before S2 a pause, a shutdown and a stall dropped the handle, leaking the
+ * executor lease). A `failed` turn keeps the orchestrator's three
+ * dispositions: an engine-reported failure parks (a bad key is not a bad
+ * handle), a user-actionable failure closes, an internal failure drops.
+ *
+ * Extracted from `index.ts` `executeCursorInner` at S2 M3b and moved out of
+ * `adapter.ts` at S2 M5; the seventeen hermetic goldens under `__tests__/hermetic/`
+ * pin the result byte for byte.
+ */
+
+import type { TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
+import { describeExecutionError } from "../../shared/model-error.js";
+import { cacheSessionAgent } from "./agent-session-cache.js";
+import { formatClassifiedError, synthesizeError } from "./error-classifier.js";
+import { setInterceptorExecutionId } from "./fetch-interceptor.js";
+import { closeProxySessions } from "./http2-interceptor.js";
+import { clearCapturedRejection, getCapturedRejection } from "./rejection-capture.js";
+import { newTurnStreamState } from "./turn-stream.js";
+import { streamAndSettle, usageSnapshotFor } from "./turn-settle.js";
+import {
+  buildTurnPrompt,
+  installGate,
+  readAdjudicatedRows,
+  resolveCursorMode,
+  resolveEngine,
+  type CursorAdapterConfig,
+  type CursorEngine,
+  type CursorGate,
+} from "./turn-setup.js";
+
+export async function runCursorTurn(input: TurnInput, sink: TurnSink, config: CursorAdapterConfig): Promise<TurnOutcome> {
+  const { executionId, sessionId } = input;
+
+  // Ensure fresh HTTP/2 transport — prevents a degraded session from a
+  // prior workflow task from poisoning this execution's agent stream.
+  closeProxySessions();
+  // The module-level fallback the interceptors read when no execution
+  // context is entered (the runtime enters one around the whole activity;
+  // the SDK warm-up in main.ts has none). Deprecated; an S5 footprint item.
+  setInterceptorExecutionId(executionId);
+
+  if (sink.stopSignal.aborted) return { kind: "interrupted" };
+
+  let engine: CursorEngine | undefined;
+  let gate: CursorGate | undefined;
+  let finishTurnTelemetry: (() => Promise<void>) | undefined;
+  let outcome: TurnOutcome | undefined;
+
+  try {
+    // The flags the stream produces that outlive the loop: created before the
+    // gate so the denial watcher can write into them.
+    const streamState = newTurnStreamState();
+    const mode = resolveCursorMode(input, config);
+    const rows = readAdjudicatedRows(input);
+    gate = await installGate(input, sink, rows, streamState);
+    if (sink.stopSignal.aborted) return (outcome = { kind: "interrupted" });
+
+    engine = await resolveEngine(input, sink, config, mode);
+    sink.recordActivity();
+    if (sink.stopSignal.aborted) return (outcome = { kind: "interrupted" });
+
+    const prompt = await buildTurnPrompt(input, sink, engine, rows);
+
+    // The OTel turn span. Coarse-grained — spans the whole turn (agent.send +
+    // stream + any recovery retry + the turn boundary), ended once from the
+    // finally so it never leaks on a non-happy path and includes any recovery
+    // retry's tokens (read from the runtime's usage summary at end time).
+    const { startCursorTurnSpan } = await import("../../otel.js");
+    const turnSpan = await startCursorTurnSpan({ model: engine.validatedModel, mode: engine.agentMode, sessionId });
+    let turnTelemetryFinished = false;
+    const resolvedEngine = engine;
+    finishTurnTelemetry = async () => {
+      if (turnTelemetryFinished) return;
+      turnTelemetryFinished = true;
+      const usage = usageSnapshotFor(sink);
+      turnSpan.setTokens(Number(usage.inputTokens), Number(usage.outputTokens));
+      turnSpan.end();
+      try {
+        const { recordTurnMetrics } = await import("../../otel.js");
+        const startedAt = sink.status.startedAt ? new Date(sink.status.startedAt).getTime() : Date.now();
+        await recordTurnMetrics({
+          durationMs: Date.now() - startedAt,
+          inputTokens: Number(usage.inputTokens),
+          outputTokens: Number(usage.outputTokens),
+          model: resolvedEngine.validatedModel,
+          mode: resolvedEngine.agentMode,
+        });
+      } catch {
+        // Metrics not initialized — silently skip.
+      }
+    };
+
+    outcome = await streamAndSettle({ input, sink, config, engine, gate, prompt, rows, streamState });
+    return outcome;
+  } catch (err) {
+    outcome = await classifyThrown(err, input, config, engine);
+    return outcome;
+  } finally {
+    // End the OTel turn span + record metrics on EVERY exit path (idempotent).
+    await finishTurnTelemetry?.();
+
+    // Close the denial-ledger watcher on EVERY exit path (idempotent) so no
+    // orphaned fs.watch handle survives the turn.
+    gate?.stopDenialWatcher();
+
+    // Tear down the HITL gate on EVERY exit path (success, error, approval
+    // pause, stop) so attaching a real repo leaves the user's .cursor/hooks.json
+    // untouched between turns (issue #173). Best-effort: a leftover hooks.json
+    // is inert because the scope guard allows all invocations once this
+    // runner PID is gone. The `.stigmer` link is the runtime's to remove,
+    // after this.
+    if (gate) {
+      try {
+        await gate.removeGate();
+      } catch (cleanupErr) {
+        console.warn(
+          `ExecuteCursor HITL gate teardown failed (non-fatal): ` +
+            `execution=${executionId}, error=${cleanupErr instanceof Error ? cleanupErr.message : cleanupErr}`,
+        );
+      }
+    }
+
+    if (engine) disposeEngine(engine, sessionId, outcome);
+  }
+}
+
+/**
+ * What becomes of the agent handle (see the header). Parking keeps the
+ * executor lease (and its MCP subprocesses) warm for the session's next
+ * turn; the idle TTL / shutdown hooks in agent-session-cache own the
+ * eventual release, so cache buildup across sessions stays bounded (#215).
+ */
+function disposeEngine(engine: CursorEngine, sessionId: string, outcome: TurnOutcome | undefined): void {
+  const park = (): void => cacheSessionAgent(sessionId, engine.resolution.agent, engine.agentFingerprint);
+  const close = (): void => {
+    try {
+      engine.resolution.agent.close();
+    } catch {
+      /* best effort */
+    }
+  };
+  if (outcome === undefined) {
+    // No outcome means the catch itself threw; nothing sane to do with the handle.
+    return;
+  }
+  switch (outcome.kind) {
+    case "completed":
+    case "cancelled":
+    case "awaiting_approval":
+    case "interrupted":
+      park();
+      return;
+    case "failed":
+      switch (outcome.surface) {
+        case "engine":
+          park();
+          return;
+        case "actionable":
+          close();
+          return;
+        case "internal":
+          return;
+        default: {
+          const exhaustive: never = outcome.surface;
+          throw new Error(`cursor adapter: unknown failure surface ${String(exhaustive)}`);
+        }
+      }
+    default: {
+      const exhaustive: never = outcome;
+      throw new Error(`cursor adapter: unknown outcome ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+
+/**
+ * An exception that escaped the turn, classified: a thrown `CursorSdkError`
+ * carries structured fields (code/status/endpoint/requestId) the generic
+ * description would flatten, so it goes through the same classifier as the
+ * `run.wait()` error path; anything else is described by
+ * `describeExecutionError` (a model error arrives MiddlewareError-wrapped
+ * with raw provider prose; non-model errors keep the root error's identity).
+ * Both are the `internal` surface: the runner or its transport broke.
+ */
+async function classifyThrown(err: unknown, input: TurnInput, config: CursorAdapterConfig, engine: CursorEngine | undefined): Promise<TurnOutcome> {
+  const { executionId } = input;
+  const fallbackContext = engine
+    ? { model: engine.validatedModel, mode: engine.agentMode, agentId: engine.resolution.agentId }
+    : { model: input.model.requested, mode: "local", agentId: "" };
+
+  const { CursorSdkError } = await import("@cursor/sdk");
+  if (err instanceof CursorSdkError) {
+    console.error(`ExecuteCursor SDK error: execution=${executionId}, sdkError=${JSON.stringify(err.toJSON())}`);
+    const classified = synthesizeError({
+      sdkError: { code: err.code, status: err.status, message: err.message },
+      sdkResultFields: undefined,
+      streamErrorMessage: undefined,
+      capturedRejection: getCapturedRejection(executionId),
+      isResumedHandle: false,
+      fallbackContext,
+      proxyMode: !!config.proxyEndpoint,
+    });
+    clearCapturedRejection(executionId);
+    return { kind: "failed", surface: "internal", message: formatClassifiedError(classified), cause: err };
+  }
+
+  const { errorType, errorMessage } = describeExecutionError(err, { proxyMode: !!config.proxyEndpoint });
+  console.error(`ExecuteCursor failed: execution=${executionId}, [${errorType}] ${errorMessage}`);
+  return { kind: "failed", surface: "internal", message: `[${errorType}] ${errorMessage}`, cause: err };
+}

package/src/activities/execute-cursor/usage-pricing.ts

@@ -0,0 +1,67 @@
+/**
+ * The Cursor harness's half of usage accounting: pricing one `turn-ended`
+ * delta at the rates of the variant this turn requested, and naming that
+ * basis on the priced delta the runtime accumulates.
+ *
+ * The runtime cannot price without the vendor's table and variant semantics,
+ * and it must not import them (Q-S2-12), so the adapter hands
+ * `TurnSink.reportUsage` a delta that already carries `estimatedCostUsd`
+ * and the basis (`model`, the catalog-validated id; `requestedModelParams`,
+ * the JSON of the params sent with every create/resume) the runtime writes
+ * into `streaming_usage`. Split out of the accumulator at S2 M3
+ * (`harness/usage-accumulator.ts` keeps the sums); the arithmetic and the
+ * rounding are unchanged, so the estimate is byte-for-byte the old one.
+ *
+ * Estimate at the rates of the variant we explicitly requested: a FAST run
+ * priced at base rates would understate the display estimate ~4x relative
+ * to the authoritative bill (#357). Thinking is price-neutral (#772) and
+ * never enters the estimate.
+ */
+
+import type { ModelParameterValue } from "@cursor/sdk";
+import { ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import type { UsageDelta } from "../../harness/types.js";
+import { getCursorModelPricingForVariant, computeTurnCost } from "./model-pricing.js";
+
+/** The token counts of one `turn-ended` delta as the Cursor SDK reports them. */
+export interface TurnUsage {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly cacheReadTokens?: number;
+  readonly cacheWriteTokens?: number;
+}
+
+export class CursorUsagePricer {
+  /** JSON-encoded params the runner sent with the model selection (#357); "" when none. */
+  private readonly requestedModelParams: string;
+
+  constructor(
+    private readonly model: string,
+    private readonly requestedServiceTier: ServiceTier,
+    requestedModelParams: readonly ModelParameterValue[] = [],
+  ) {
+    this.requestedModelParams = requestedModelParams.length > 0 ? JSON.stringify(requestedModelParams) : "";
+  }
+
+  /** One SDK usage delta, priced and attributed, ready for `TurnSink.reportUsage`. */
+  price(usage: TurnUsage): UsageDelta {
+    const inputTokens = usage.inputTokens ?? 0;
+    const outputTokens = usage.outputTokens ?? 0;
+    const cacheReadTokens = usage.cacheReadTokens ?? 0;
+    const cacheWriteTokens = usage.cacheWriteTokens ?? 0;
+    const pricing = getCursorModelPricingForVariant(
+      this.model,
+      this.requestedServiceTier === ServiceTier.FAST ? "fast" : null,
+    );
+    return {
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+      cacheWriteTokens,
+      estimatedCostUsd: computeTurnCost(pricing, inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens),
+      model: this.model,
+      requestedModelParams: this.requestedModelParams,
+    };
+  }
+}

package/src/activities/execute-deep-agent/approval-file-change.ts

@@ -9,7 +9,7 @@
  * few fields). The approval card renders the proposed write/edit content from
  * these args; there is no separate captured `file_changes` (removed in Phase 5
  * Slice 4 — the args are the single source, and the Cursor deny-gate's
- * exact-apply reads the same args on resume; see execute-cursor/exact-apply.ts).
+ * exact-apply reads the same args on resume; see shared/exact-apply.ts).
  *
  * @since First-Class Diff Review (#186), approval-gate phase
  */

package/src/activities/execute-deep-agent/environment.ts

@@ -42,7 +42,7 @@ export async function resolveEnvironment(
     execCtx = await client.getExecutionContextByExecutionId(executionId, scopedToken);
   } catch (err: unknown) {
     // ConnectError uses numeric Code.NotFound (5); match the pattern
-    // from execute-cursor/env-resolver.ts.
+    // from shared/env-resolver.ts.
     const code = (err as { code?: number | string })?.code;
     if (code === 5 || code === "not_found" || code === "NOT_FOUND") {
       console.log(

package/src/activities/execute-deep-agent/setup.ts

@@ -1006,8 +1006,9 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
  *
  * A session with no entries gets its own empty per-session directory (see
  * shared/workspace/session-root.ts) — never the shared root, which would
- * leak other sessions' files into it. Mirrors the Cursor harness's
- * provisionCursorWorkspace exactly.
+ * leak other sessions' files into it. Mirrors shared/workspace/
+ * session-provision.ts `provisionSessionWorkspace` exactly; S3 of the
+ * harness runtime program retires this twin in favor of that one.
  */
 async function provisionWorkspace(
   config: Config,

package/src/activities/hydrate-workflow-execution.ts

@@ -282,7 +282,7 @@ async function fetchAndFlattenEnv(
     execCtx = await client.getExecutionContextByExecutionId(executionId, scopedToken);
   } catch (err: unknown) {
     // ConnectError uses numeric Code.NotFound (5); match the pattern
-    // from execute-cursor/env-resolver.ts.
+    // from shared/env-resolver.ts.
     const code = (err as { code?: number | string })?.code;
     if (code === 5 || code === "not_found" || code === "NOT_FOUND") {
       console.log(

package/src/config.ts

@@ -143,6 +143,19 @@ export interface Config {
    * desktop runner (see stigmer-client.ts).
    */
   readonly stigmerRunnerTokenRef?: { current: string | null };
+  /**
+   * Shared mutable reference to the credential the Cursor proxy transport
+   * sends as `x-stigmer-auth` (the fetch and HTTP/2 interceptors read it per
+   * request). Each composition root binds its own credential here, because
+   * the two differ: the static root binds the control-plane token (its host
+   * provides the proxy credential and mints no other, so
+   * `proxyTokenRef === stigmerTokenRef`), the manager binds the minted runner
+   * token (`proxyTokenRef === stigmerRunnerTokenRef`). Reading either sibling
+   * directly would send the wrong credential from one of the two roots
+   * (Q-S2-7). Required whenever `proxyEndpoint` is set; the Cursor adapter's
+   * boot refuses a proxy without it.
+   */
+  readonly proxyTokenRef?: { current: string | null };
 }
 
 export function loadConfig(): Config {

package/src/harness/__tests__/import-direction.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Pins the import direction the turn runtime stands on: nothing under
+ * `src/harness/` imports from `src/activities/`, and no production module
+ * under `src/shared/` does either.
+ *
+ * Why it matters (the extraction plan, section 3): the runtime is meant to
+ * be written once and call harness-specific code only through the adapter
+ * contract. If `harness/` could reach into `activities/execute-cursor/`, the
+ * runtime would be Cursor's orchestrator in a new directory and the "SDK
+ * slice plus a registry row" promise for the next harness would be false.
+ * The `shared/` half is what makes the `harness/` half hold: `harness/`
+ * imports `shared/` freely, so a `shared/` module that imported
+ * `activities/` would open the same door one hop away.
+ *
+ * The rule is read off the TypeScript syntax tree, not a regex
+ * (`__test-utils__/module-specifiers.ts`, shared with the adapter's
+ * Temporal-free fence), so a path quoted in a header comment (several
+ * `shared/` modules cite `activities/...` in prose) cannot trip it, and no
+ * import form can slip past it: static, type-only, side-effect, re-export
+ * and dynamic `import()` are all module specifiers to the parser. Ruled at
+ * the S2 gate (Q-S2-9); the `shared/` half ruled at the M1 gate (Q-M1-5).
+ */
+
+import { describe, it, expect } from "vitest";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { forbiddenImports, readSource, typeScriptFilesUnder } from "../../__test-utils__/module-specifiers.js";
+
+const SRC_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+const FORBIDDEN_ROOT = join(SRC_ROOT, "activities");
+
+interface Offence {
+  readonly file: string;
+  readonly specifier: string;
+}
+
+interface Sweep {
+  /** Files inspected, relative to `src/`; the liveness guards read this. */
+  readonly visited: string[];
+  readonly offences: Offence[];
+}
+
+function sweep(root: string, skipDirectories: ReadonlySet<string>): Sweep {
+  const visited: string[] = [];
+  const offences: Offence[] = [];
+  for (const file of typeScriptFilesUnder(root, skipDirectories)) {
+    const relativeFile = relative(SRC_ROOT, file);
+    visited.push(relativeFile);
+    for (const specifier of forbiddenImports(file, readSource(file), FORBIDDEN_ROOT)) {
+      offences.push({ file: relativeFile, specifier });
+    }
+  }
+  return { visited, offences };
+}
+
+function describeOffences(offences: readonly Offence[]): string {
+  return offences.map((o) => `  ${o.file} imports "${o.specifier}"`).join("\n");
+}
+
+describe("forbiddenImports (the checker itself)", () => {
+  const file = join(SRC_ROOT, "harness", "run-turn.ts");
+
+  it.each([
+    [
+      "a static import",
+      'import { a } from "../activities/execute-cursor/x.js";',
+    ],
+    [
+      "a type-only import",
+      'import type { A } from "../activities/execute-cursor/x.js";',
+    ],
+    ["a side-effect import", 'import "../activities/execute-cursor/x.js";'],
+    ["a re-export", 'export { a } from "../activities/execute-cursor/x.js";'],
+    ["a star re-export", 'export * from "../activities/x.js";'],
+    [
+      "a dynamic import",
+      'const m = await import("../activities/execute-cursor/x.js");',
+    ],
+    [
+      "a path that leaves and re-enters",
+      'import { a } from "../shared/../activities/x.js";',
+    ],
+  ])("flags %s", (_label, source) => {
+    expect(forbiddenImports(file, source, FORBIDDEN_ROOT)).toHaveLength(1);
+  });
+
+  it.each([
+    ["a shared import", 'import { a } from "../shared/status.js";'],
+    ["a sibling import", 'import { a } from "./types.js";'],
+    ["a package import", 'import { create } from "@bufbuild/protobuf";'],
+    ["a node builtin", 'import { join } from "node:path";'],
+    [
+      "a forbidden path quoted in a comment",
+      '// see: import { a } from "../activities/execute-cursor/x.js"\nimport { b } from "./types.js";',
+    ],
+    [
+      "a forbidden path in a plain string",
+      'const hint = "../activities/execute-cursor/x.js";',
+    ],
+    [
+      "a dynamic import whose specifier is not a literal",
+      "const m = await import(pathFromConfig);",
+    ],
+  ])("does not flag %s", (_label, source) => {
+    expect(forbiddenImports(file, source, FORBIDDEN_ROOT)).toEqual([]);
+  });
+
+  it("names every offending specifier when a file has several", () => {
+    const source = [
+      'import { a } from "../activities/a.js";',
+      'import { b } from "../shared/b.js";',
+      'export { c } from "../activities/c.js";',
+    ].join("\n");
+    expect(forbiddenImports(file, source, FORBIDDEN_ROOT)).toEqual([
+      "../activities/a.js",
+      "../activities/c.js",
+    ]);
+  });
+});
+
+describe("src/harness never imports src/activities", () => {
+  const result = sweep(join(SRC_ROOT, "harness"), new Set());
+
+  it("inspected the runtime's own files (the walk is rooted where it claims)", () => {
+    expect(result.visited).toEqual(
+      expect.arrayContaining([
+        join("harness", "registry.ts"),
+        join("harness", "types.ts"),
+        join("harness", "capabilities.ts"),
+      ]),
+    );
+  });
+
+  it("finds no import into src/activities, tests included", () => {
+    expect(
+      result.offences,
+      `src/harness/ must not import from src/activities/:\n${describeOffences(result.offences)}`,
+    ).toEqual([]);
+  });
+});
+
+describe("src/shared production modules never import src/activities", () => {
+  // Tests under shared/__tests__ may legitimately import both harnesses'
+  // implementations to compare them (attachment-naming.test.ts does); the
+  // rule is about what production code can reach.
+  const result = sweep(join(SRC_ROOT, "shared"), new Set(["__tests__"]));
+
+  it("inspected the shared modules (the walk is rooted where it claims)", () => {
+    expect(result.visited).toEqual(
+      expect.arrayContaining([
+        join("shared", "status.ts"),
+        join("shared", "workspace", "session-provision.ts"),
+      ]),
+    );
+    expect(
+      result.visited.some((f) => f.includes(`${sep}__tests__${sep}`)),
+      "the production sweep must skip __tests__ directories",
+    ).toBe(false);
+  });
+
+  it("finds no import into src/activities", () => {
+    expect(
+      result.offences,
+      `src/shared/ production code must not import from src/activities/:\n${describeOffences(result.offences)}`,
+    ).toEqual([]);
+  });
+});