@stigmer/runner 3.14.1 → 3.15.1

package/src/harness/types.ts

@@ -8,9 +8,9 @@
  * vendor SDK — fetching the execution, resolving the blueprint and the
  * environment, provisioning and locking the workspace, mounting skills,
  * resolving MCP servers and approval policies, seeding the transcript, the
- * persist cadence, the stall watchdog, the Temporal heartbeat, pause vs
- * shutdown, the cost cap, the file-review boundary, the terminal mapping —
- * is the RUNTIME's, written once. What a harness owns is its SDK slice: how
+ * persist chokepoint, the stall watchdog, the Temporal heartbeat, pause vs
+ * shutdown, the cost cap, the terminal mapping — is the RUNTIME's
+ * (`run-turn.ts`), written once. What a harness owns is its SDK slice: how
  * the engine is created or resumed, how the prompt is placed, how MCP servers
  * are bound, how the engine is made to stop before a gated side effect, and
  * how its events become transcript rows. This file is the whole of what a
@@ -22,15 +22,15 @@
  * runtime cannot read anywhere else. Nothing here is speculative: where the
  * program's original sketch and the code disagreed, the code won, and the
  * disagreement was ruled at the entry's gate
- * (stigmer-cloud `_projects/2026-09/20260911.02.sp.harness-contract-and-kit/`).
+ * (stigmer-cloud `_projects/2026-09/20260911.02.sp.harness-contract-and-kit/`
+ * for S1; `20260911.03.sp.turn-runtime-extraction/` M3 for the growth below).
  *
  * What is deliberately NOT on this contract, and why:
  *
  *  - No `dispose()`. One adapter object serves many concurrent turns
  *    (`maxConcurrentActivities`), so a per-turn teardown method on the
  *    adapter is a race. The adapter owns its per-turn teardown in its own
- *    `finally` inside `runTurn` (the Cursor harness already parks its agent
- *    there).
+ *    `finally` inside `runTurn` (the Cursor harness parks its agent there).
  *  - No `isCancelled()`, no `heartbeat(details)`, no `ExecutionStatusWriter`
  *    base. Each would be a second way of saying something `stopSignal`,
  *    `recordActivity()` or `requestPersist()` already says, and two writers of
@@ -46,17 +46,42 @@
  *  - No `TurnInput.status`. The runtime seeds `TurnSink.status` from the
  *    persisted transcript; a second copy on the input is the drift the
  *    single-source-of-truth mandate forbids.
+ *  - No execution context. "This activity is execution X" is the runtime's
+ *    ambient fact for the WHOLE activity (`shared/execution-context.ts`, an
+ *    `AsyncLocalStorage` the runtime enters before anything runs); the
+ *    interceptors read it per request, so no adapter establishes or
+ *    propagates it.
+ *  - No persist cadence. The runtime's chokepoint is single-flight and
+ *    unconditional at settle; WHEN a streaming turn asks for a write is the
+ *    adapter's (`shared/persist-decision.ts` over its own dirty flags, since
+ *    what counts as a discrete change is engine knowledge), until S3 lifts
+ *    the file-review capture and can revisit with both loops in view.
  *
  * Module shape follows `shared/checkpointer/`: `types.ts`, `capabilities.ts`,
- * `registry.ts`, no barrel. Nothing production-facing imports this module
- * until the runtime that consumes it lands (S2 of the program).
+ * `registry.ts`, no barrel.
  */
 
 import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentExecution, AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 
 import type { Config } from "../config.js";
 import type { NormalizedActivityInput } from "../shared/activity-input.js";
+import type { ArtifactStorage } from "../shared/artifact-storage.js";
+import type { TimingRecorder } from "../shared/cold-start-timing.js";
+import type { ResolvedBlueprint } from "../shared/blueprint-resolver.js";
+import type { SessionWorkspaceProvision } from "../shared/workspace/session-provision.js";
+import type { ResolvedMcpServer } from "../shared/mcp-resolver.js";
+import type { ChannelMessagingInfo } from "../shared/channel-attachment.js";
+import type { ActiveLeases, MergedToolPolicy } from "../shared/approval-policy.js";
+import type { SkillMetadata } from "../shared/skill-resolver.js";
+import type { ResolvedAttachment } from "../shared/attachment-resolver.js";
+import type { NotViewableEntry, VisionImage } from "../shared/attachment-vision.js";
+import type { EffectiveServiceTier } from "../shared/service-tier.js";
+import type { EffectiveThinkingMode } from "../shared/thinking-mode.js";
+import type { SenderIdentity } from "../shared/sender-identity.js";
+import type { DeclaredPreferencesContent } from "../shared/declared-preferences.js";
+import type { RecalledMemoriesContent } from "../shared/recalled-memories.js";
 import type { HarnessCapabilities } from "./capabilities.js";
 
 /**
@@ -115,9 +140,9 @@ export interface HarnessAdapter {
    * The rules every implementation is held to (the kit's invariants):
    *
    *  - Resolves, never rejects. A vendor failure becomes
-   *    `{ kind: "failed", message }` with the user-facing sentence the
-   *    adapter's classifier produced. A `CancelledFailure` never escapes: the
-   *    runtime, not the adapter, decides what is a pause and what is a
+   *    `{ kind: "failed", message, surface }` with the user-facing sentence
+   *    the adapter's classifier produced. A `CancelledFailure` never escapes:
+   *    the runtime, not the adapter, decides what is a pause and what is a
    *    shutdown, and it throws exactly where Temporal semantics require.
    *  - Stops promptly when `sink.stopSignal` aborts, whatever the cause,
    *    settling `interrupted`. Every call the adapter makes is bounded: the
@@ -129,24 +154,104 @@ export interface HarnessAdapter {
    *    `input.approvalDecisions`. APPROVE executes exactly once; REJECT and
    *    SKIP never execute.
    *  - Owns its own per-turn teardown in a `finally` inside this method.
+   *  - Imports nothing from `@temporalio/*`: the kit runs an adapter outside
+   *    any activity context, and every Temporal fact it needs arrives through
+   *    the sink (`execute-cursor/__tests__/adapter-is-temporal-free.test.ts`).
    */
   runTurn(input: TurnInput, sink: TurnSink): Promise<TurnOutcome>;
 }
 
+// ---------------------------------------------------------------------------
+// The resolved record
+// ---------------------------------------------------------------------------
+
+/** The resolved environment (phase 2b): the MCP-bound env map and the keys that are secrets. */
+export interface TurnEnvironment {
+  readonly envVars: Record<string, string>;
+  readonly secretKeys: ReadonlySet<string>;
+}
+
+/** The provisioned workspace (phase 2c) and the capture posture derived from it. */
+export interface TurnWorkspace {
+  /** The directories the agent operates in; never empty (`provisionSessionWorkspace` guarantees it). */
+  readonly dirs: readonly string[];
+  /** `dirs[0]`, the tree the turn's lock, gate, capture and skill mount all key on. */
+  readonly primaryDir: string;
+  /** True when `primaryDir` is a git work tree: selects the git-diff capture substrate over CAS. */
+  readonly gitWorkspace: boolean;
+  /** Apply-then-review capture (true) or the classic deny-gate (false); see `shared/filereview/capture.ts` `deriveCaptureMode`. */
+  readonly captureMode: boolean;
+  /** `${executionId}:${turnSeq}`: the deterministic id of the change set this turn may produce. */
+  readonly changeSetId: string;
+  readonly provision: SessionWorkspaceProvision;
+}
+
+/** The tool surface (phases 4 to 4b): the resolved servers with the attachments folded in, and the merged approval policies. */
+export interface TurnMcp {
+  /** Every resolved server, synthesized attachments included; the harness projects its SDK config from this list. */
+  readonly servers: readonly ResolvedMcpServer[];
+  /** Serving proactive channels and their templates (the DD-006 D2 discovery read). */
+  readonly channelMessaging: readonly ChannelMessagingInfo[];
+  readonly leases: ActiveLeases;
+  readonly policies: ReadonlyMap<string, MergedToolPolicy>;
+}
+
+/** The turn's explicit inputs (phase 5b), resolved into the workspace with the vision facts derived once. */
+export interface TurnAttachments {
+  readonly results: readonly ResolvedAttachment[];
+  /** The images the model sees inline, in attachment order. */
+  readonly visionImages: readonly VisionImage[];
+  /** The image-shaped attachments that degraded to path-only, disclosed in the prompt. */
+  readonly visionNotViewable: readonly NotViewableEntry[];
+}
+
+/** What the execution asked for (phase 6, the harness-agnostic half): the raw model name and the effective tier and thinking mode. */
+export interface TurnModelPreferences {
+  /** `spec.executionConfig.modelName`, or `"default"`; the harness validates it against its own catalog. */
+  readonly requested: string;
+  /** Never UNSPECIFIED: `resolveEffectiveServiceTier` is where the platform default is applied. */
+  readonly serviceTier: EffectiveServiceTier;
+  /** Never UNSPECIFIED: `resolveEffectiveThinkingMode` is where the platform default is applied. */
+  readonly thinkingMode: EffectiveThinkingMode;
+}
+
 /**
- * What the runtime resolved for this turn and the adapter cannot read
- * anywhere else. This is the core; the runtime extraction (S2) grows it one
- * typed field per phase it takes over from the orchestrators (environment,
- * workspace, skills, MCP servers with merged policies, attachments, memory,
- * prompt bundle, model), in the `setup.ts` `SetupResult` mold.
+ * The standing context a first prompt carries (phase 9c) and the per-turn
+ * catchup, read once from the session metadata and the execution spec.
+ */
+export interface TurnStandingContext {
+  readonly contextBridge: string | undefined;
+  readonly senderIdentity: SenderIdentity | undefined;
+  readonly sessionContext: string | undefined;
+  readonly declaredPreferences: DeclaredPreferencesContent | undefined;
+  readonly conversationCatchup: string | undefined;
+  /**
+   * The semantic memory selection, memoized to at most one run per
+   * invocation and stamping `status.recalledMemoriesReport` once. A thunk
+   * because only the harness knows whether its prompt carries standing
+   * context (a successfully resumed engine already holds it).
+   */
+  readonly selectRecalledMemories: () => Promise<RecalledMemoriesContent | undefined>;
+}
+
+/**
+ * Everything the runtime resolved for this turn, as small named groups
+ * (`turn-context.ts` produces one per phase; `run-turn.ts` composes them).
+ * This is the whole record: the runtime keeps nothing "private" beside it —
+ * the lock release and the write-back coordinator are the finally's
+ * resources (`run-turn.ts` `TurnFrame`), not facts about the turn.
  *
  * `threadId` is the engine's state id as the runtime knows it: empty on an
  * `engine-minted` harness's first turn (nothing minted yet) and the id the
  * adapter bound through {@link TurnSink.bindHarnessState} on every later
  * invocation; the runtime-minted id on every turn of a `deterministic`
- * harness. An adapter derives create-vs-resume from it and its own state; the
- * contract carries no `isReinvocation` flag because the two harnesses would
- * derive it differently.
+ * harness. An adapter derives create-vs-resume from it and its own state
+ * through `turn-context.ts`'s `isReinvocation`; the contract carries no flag
+ * because the two harnesses would derive it differently.
+ *
+ * Adapter-only facts (the Cursor mode, the service-tier params, the seeded
+ * sub-agent rows) are read by the adapter from these records, never resolved
+ * by the runtime.
  */
 export interface TurnInput extends NormalizedActivityInput {
   /**
@@ -166,12 +271,34 @@ export interface TurnInput extends NormalizedActivityInput {
    * verdict from the rows itself.
    */
   readonly approvalDecisions: ReadonlyMap<string, ApprovalAction>;
+  readonly execution: AgentExecution;
+  /** The same object as `blueprint.session`; `bindHarnessState` writes it. */
+  readonly session: Session;
+  readonly blueprint: ResolvedBlueprint;
+  readonly environment: TurnEnvironment;
+  readonly workspace: TurnWorkspace;
+  readonly mcp: TurnMcp;
+  /** The mounted skills (phase 5): each under the session's platform dir, reachable from the workspace through its `.stigmer` link; the harness renders them into its prompt. */
+  readonly skills: readonly SkillMetadata[];
+  readonly attachments: TurnAttachments;
+  /** Approved whole-file writes the runtime applied itself this turn (exact-apply); the harness issues no grant for them. */
+  readonly appliedToolCallIds: ReadonlySet<string>;
+  readonly model: TurnModelPreferences;
+  /** `spec.executionConfig.structuredOutputSchema`, when the execution asks for structured output. */
+  readonly structuredOutputSchema: Record<string, unknown> | undefined;
+  readonly standing: TurnStandingContext;
+  /** Resolved once by the runtime before any phase; absent when no substrate works. */
+  readonly artifactStorage: ArtifactStorage | undefined;
 }
 
+// ---------------------------------------------------------------------------
+// The sink
+// ---------------------------------------------------------------------------
+
 /**
- * The runtime's face during one turn: the five things an adapter may ask of
- * it, and the one status it folds into. One sink per turn, owned by the
- * runtime; the adapter never constructs one.
+ * The runtime's face during one turn: what an adapter may ask of it, and the
+ * one status it folds into. One sink per turn, owned by the runtime; the
+ * adapter never constructs one.
  *
  * Field ownership on `status` before the canonical transcript lands (S4):
  * the adapter appends the engine's transcript rows (assistant messages,
@@ -179,7 +306,9 @@ export interface TurnInput extends NormalizedActivityInput {
  * runtime writes the phase, the terminal system messages, `streamingUsage`,
  * artifacts, write-backs and the file-review projection. An adapter never
  * writes a phase or a terminal copy: those are Temporal semantics the
- * runtime owns once.
+ * runtime owns once. (The file-review boundary itself is the adapter's until
+ * S3 lifts both harnesses' captures together; `execute-cursor/adapter.ts`
+ * says so.)
  */
 export interface TurnSink {
   /**
@@ -195,41 +324,74 @@ export interface TurnSink {
    * and maps the outcome; the adapter's only job is to settle promptly as
    * `interrupted`. `stopSignal.reason` is the runtime's own evidence — an
    * adapter never branches on it. Check `aborted` at every step boundary and
-   * listen for `abort` inside anything long-running. May already be aborted
-   * when `runTurn` is entered; then return `interrupted` before doing any
-   * work.
+   * listen for `abort` inside anything long-running (the Cursor adapter
+   * cancels its SDK run from that listener). May already be aborted when
+   * `runTurn` is entered; then return `interrupted` before doing any work.
    */
   readonly stopSignal: AbortSignal;
 
   /**
-   * "Persist the status soon": schedules a write through the runtime's single
-   * persist chokepoint (tool-output offload, size cap, secret withholding,
-   * the streaming scheduler). Fire and forget — never awaited by the adapter,
-   * never a promise. The runtime persists unconditionally when the turn
-   * settles, so no adapter has to flush before returning.
+   * The runtime's cold-start timeline for this turn, a live handle like
+   * `status`. The runtime marked its own resolution segments on it before
+   * `runTurn`; the adapter marks its setup segments (skills, gate, engine
+   * resolve) and emits the `execution_setup` line once its engine is ready,
+   * so the one timeline reads end to end (`shared/cold-start-timing.ts`).
+   * Diagnostics only; nothing branches on it.
+   */
+  readonly setupTiming: TimingRecorder;
+
+  /**
+   * "Persist the status": a write through the runtime's single persist
+   * chokepoint (tool-output offload, size cap, secret withholding,
+   * `streamingUsage`). Single-flight: a request while a write is in flight
+   * coalesces into the next write. Resolves when the state as of the request
+   * has been written, so an adapter that needs ordering MAY await it (the
+   * Cursor loop awaits before pulling the next event, so a platform STOP
+   * answered by that write stops the turn before the next event, as it
+   * always has); an adapter never MUST await it, because the runtime
+   * persists unconditionally when the turn settles. Never rejects.
    */
-  requestPersist(): void;
+  requestPersist(): Promise<void>;
 
   /**
    * "I made progress": resets the runtime's stall watchdog and is carried
-   * into the next Temporal heartbeat. Call it on every engine event and every
-   * token delta — a long generation emits deltas but few discrete events, and
-   * resetting only on events false-positives a stall. Never throws.
+   * into the next Temporal heartbeat. Call it on every engine event, every
+   * token delta, and every step boundary of the adapter's own setup (engine
+   * resolved, send returned, boundary done) — a long generation emits deltas
+   * but few discrete events, and resetting only on events false-positives a
+   * stall. `detail` names what progressed (the Cursor loop passes the tool
+   * name of a `tool_call` event); the runtime quotes the last detail in the
+   * stall diagnostic (`last tool: shell`). Never throws.
    */
-  recordActivity(): void;
+  recordActivity(detail?: string): void;
 
   /**
-   * Token counts for one engine turn. The runtime accumulates, prices and
-   * enforces `max_cost_usd`; an adapter reports and never accounts. Every
-   * count is a non-negative delta since the previous report.
+   * Token counts for one engine turn, priced by the adapter against its own
+   * vendor's table. The runtime accumulates and enforces `max_cost_usd`; an
+   * adapter reports and never accounts. Every count is a non-negative delta
+   * since the previous report.
    */
   reportUsage(delta: UsageDelta): void;
 
+  /**
+   * The user-visible setup label (`status.setupProgress.currentPhase`) for a
+   * step only the adapter knows ("Initializing Cursor agent"). The runtime
+   * reports its own resolution labels itself; the adapter reports the labels
+   * of its setup steps exactly as the orchestrator did, so the UI's spinner
+   * copy is unchanged by the extraction (Q-S2-5). Resolves once the label is
+   * written; the write carries no phase, so it never advances the execution.
+   */
+  reportProgress(label: string): Promise<void>;
+
   /**
    * The engine-minted state id, the moment it exists and BEFORE the turn
    * proceeds, so a crash mid-turn still resumes on the next invocation. The
-   * runtime writes it to the session at once (the Cursor harness's
-   * `harness_state_id`). Called only by adapters whose
+   * runtime writes it to the session record the adapter was handed
+   * (`input.session`, with `harness_state_id` set and the metadata slug
+   * cleared, the agnostic quirk of `BuildUpdateStateStep`); the adapter may
+   * set its own harness-specific `SessionSpec` fields on that record before
+   * binding, one writer per field (`harnessStateId` the runtime's,
+   * `cursorMode` the adapter's; Q-S2-11). Called only by adapters whose
    * `capabilities.stateIdSource` is `"engine-minted"`, and before their first
    * `requestPersist`; a `deterministic` harness never calls it. Rejects when
    * the session write fails; the adapter then ends the turn `failed` with
@@ -239,40 +401,73 @@ export interface TurnSink {
 }
 
 /**
- * Token counts for one engine turn, as the Cursor loop reads them from the
- * SDK's `turn-ended` delta (`execute-cursor/usage-accumulator.ts`
- * `TurnUsage` is this shape; the runtime extraction collapses the two). Every
- * field is optional because engines report different subsets; a missing
- * field means zero, never "unknown".
+ * Token counts for one engine turn, priced. The four counts are what the
+ * Cursor loop reads from the SDK's `turn-ended` delta; `estimatedCostUsd` is
+ * the adapter's price for them at its vendor's rates (the runtime cannot
+ * price without the vendor's table and must not import it; Q-S2-12), and
+ * `model` / `requestedModelParams` name the basis it priced against, which
+ * the runtime records into `streamingUsage` (`model` is the catalog-validated
+ * id, `requestedModelParams` the JSON of the params sent — a string on the
+ * proto, so the SDK type stays inside the adapter). Every field is optional
+ * because engines report different subsets; a missing count means zero,
+ * never "unknown"; a missing basis inherits the previous delta's.
  */
 export interface UsageDelta {
   readonly inputTokens?: number;
   readonly outputTokens?: number;
   readonly cacheReadTokens?: number;
   readonly cacheWriteTokens?: number;
+  readonly estimatedCostUsd?: number;
+  readonly model?: string;
+  readonly requestedModelParams?: string;
 }
 
+/**
+ * Which of the runtime's three failure copies a `failed` outcome takes. A
+ * classification, never copy: the runtime owns the words
+ * (`terminal-table.ts`), the adapter says what kind of thing failed.
+ *
+ *  - `engine`: the engine reported its run as failed. The transcript already
+ *    tells the story, so the runtime writes `status.error` and no system row
+ *    (the Cursor `run.wait()` error arm).
+ *  - `actionable`: the user can fix it (a foreign hook blocked a tool). One
+ *    `Execution failed: …` row, the same shape the runtime's own settlements
+ *    use.
+ *  - `internal`: the runner or its transport broke unexpectedly (a thrown
+ *    SDK error, an exception in the adapter). The boilerplate row and an
+ *    `Error details:` row.
+ */
+export type FailureSurface = "engine" | "actionable" | "internal";
+
 /**
  * How one turn ended, carrying ONLY what the runtime cannot read from
  * `sink.status` or its own evidence.
  *
  *  - `completed`: the engine finished. The final text and any structured
  *    output are already folded onto the status; nothing rides here.
+ *  - `cancelled`: the engine ended its own run cancelled and there is nothing
+ *    to wait for — an SDK-side cancel, or a deny-and-retry adapter that
+ *    stopped its run to gate a call and then found nothing to pause for
+ *    (an unattended denial settled as skipped). Not `interrupted`: the
+ *    runtime's `stopSignal` never fired. The runtime writes
+ *    `EXECUTION_CANCELLED` with no copy and completes the turn.
  *  - `awaiting_approval`: the engine proposed at least one gated side effect
  *    and stopped. The WAITING_APPROVAL rows are already on the status; the
  *    runtime persists them and returns to the workflow, which reinvokes with
  *    the decisions.
  *  - `failed`: the engine or its transport failed in a way the adapter can
- *    name. `message` is the user-facing sentence; `cause` is for the log.
- *    The runtime persists FAILED and RETURNS (Temporal does not retry a
- *    returned activity; re-running the same prompt would fail the same way).
+ *    name. `message` is the user-facing sentence, `surface` which copy it
+ *    takes, `cause` is for the log. The runtime persists FAILED and RETURNS
+ *    (Temporal does not retry a returned activity; re-running the same
+ *    prompt would fail the same way).
  *  - `interrupted`: `sink.stopSignal` aborted and the adapter stopped. WHY it
  *    aborted is the runtime's evidence (its watchdog, its accounting, its
- *    heartbeat, its shutdown signal), so no reason rides here; the runtime
- *    classifies and applies the throw-vs-return table.
+ *    chokepoint, the cancellation it was delivered), so no reason rides here;
+ *    the runtime classifies and applies the throw-vs-return table.
  */
 export type TurnOutcome =
   | { readonly kind: "completed" }
+  | { readonly kind: "cancelled" }
   | { readonly kind: "awaiting_approval" }
-  | { readonly kind: "failed"; readonly message: string; readonly cause?: unknown }
+  | { readonly kind: "failed"; readonly message: string; readonly surface: FailureSurface; readonly cause?: unknown }
   | { readonly kind: "interrupted" };

package/src/harness/usage-accumulator.ts

@@ -0,0 +1,122 @@
+/**
+ * The turn runtime's usage accounting: the priced deltas an adapter reports
+ * through `TurnSink.reportUsage`, summed into the `streaming_usage` summary
+ * the persist chokepoint writes before every status write, and the running
+ * cost the `max_cost_usd` cap is enforced against.
+ *
+ * Who owns what (Q-S2-12): the ADAPTER prices, because only it has its
+ * vendor's rate table and variant semantics (`execute-cursor/usage-pricing.ts`
+ * for Cursor); the RUNTIME accounts and enforces, because the cap and the
+ * summary are the platform's, the same for every engine. A delta therefore
+ * arrives already priced, naming the basis it was priced against (`model`,
+ * `requestedModelParams`), and this class adds — it never multiplies. The
+ * tier and thinking mode it records are the runtime's own effective
+ * preferences (`TurnInput.model`), the audit trail that the account default
+ * was never left in control (#357, #772).
+ *
+ * Moved from `activities/execute-cursor/usage-accumulator.ts` at S2 M3, the
+ * pricing call split out; the sums, the snapshot shape and the empty
+ * snapshot are unchanged, so `streamingUsage` is byte-for-byte what the
+ * Cursor orchestrator wrote.
+ *
+ * This data is display-only. The authoritative billing source is the BiDi
+ * proxy, which records usage from the wire.
+ */
+
+import { ServiceTier, ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import type { UsageDelta } from "./types.js";
+
+export interface UsageSnapshot {
+  readonly inputTokens: bigint;
+  readonly outputTokens: bigint;
+  readonly cacheReadTokens: bigint;
+  readonly cacheWriteTokens: bigint;
+  readonly totalTokens: bigint;
+  readonly turnCount: number;
+  readonly estimatedCostUsd: number;
+  /** The basis the adapter last priced against (its catalog-validated model id); `""` until a delta names one. */
+  readonly model: string;
+  readonly observedAt: string;
+  /** Tier the runner requested — always explicit post-translation (#357). */
+  readonly requestedServiceTier: ServiceTier;
+  /** JSON-encoded params the adapter sent with its model selection; "" when none. */
+  readonly requestedModelParams: string;
+  /** Thinking mode the runner requested — always explicit post-translation (#772). */
+  readonly requestedThinkingMode: ThinkingMode;
+}
+
+const EMPTY_SNAPSHOT: UsageSnapshot = {
+  inputTokens: 0n,
+  outputTokens: 0n,
+  cacheReadTokens: 0n,
+  cacheWriteTokens: 0n,
+  totalTokens: 0n,
+  turnCount: 0,
+  estimatedCostUsd: 0,
+  model: "",
+  observedAt: "",
+  requestedServiceTier: ServiceTier.UNSPECIFIED,
+  requestedModelParams: "",
+  requestedThinkingMode: ThinkingMode.UNSPECIFIED,
+};
+
+export class UsageAccumulator {
+  private inputTokens = 0;
+  private outputTokens = 0;
+  private cacheReadTokens = 0;
+  private cacheWriteTokens = 0;
+  private turnCount = 0;
+  private estimatedCostUsd = 0;
+  private observedAt = "";
+  private model = "";
+  private requestedModelParams = "";
+
+  constructor(
+    /** The effective tier the runtime resolved (never UNSPECIFIED on a real turn; the default keeps the empty snapshot honest). */
+    private readonly requestedServiceTier: ServiceTier = ServiceTier.UNSPECIFIED,
+    /** The effective thinking mode the runtime resolved. Price-neutral (#772); recorded purely as the audit trail twin of the tier. */
+    private readonly requestedThinkingMode: ThinkingMode = ThinkingMode.UNSPECIFIED,
+  ) {}
+
+  /** Add one priced delta. A delta without a basis inherits the previous one; a missing count is zero. */
+  addTurn(delta: UsageDelta): void {
+    this.inputTokens += delta.inputTokens ?? 0;
+    this.outputTokens += delta.outputTokens ?? 0;
+    this.cacheReadTokens += delta.cacheReadTokens ?? 0;
+    this.cacheWriteTokens += delta.cacheWriteTokens ?? 0;
+    this.estimatedCostUsd += delta.estimatedCostUsd ?? 0;
+    if (delta.model !== undefined) this.model = delta.model;
+    if (delta.requestedModelParams !== undefined) this.requestedModelParams = delta.requestedModelParams;
+    this.turnCount++;
+    this.observedAt = new Date().toISOString();
+  }
+
+  get hasTurns(): boolean {
+    return this.turnCount > 0;
+  }
+
+  snapshot(): UsageSnapshot {
+    if (this.turnCount === 0) return EMPTY_SNAPSHOT;
+
+    return {
+      inputTokens: BigInt(this.inputTokens),
+      outputTokens: BigInt(this.outputTokens),
+      cacheReadTokens: BigInt(this.cacheReadTokens),
+      cacheWriteTokens: BigInt(this.cacheWriteTokens),
+      // The Cursor SDK follows Anthropic's convention: inputTokens already
+      // INCLUDES the cached portions (cacheReadTokens/cacheWriteTokens are
+      // subsets of it, not additive). The true total throughput is therefore
+      // inputTokens + outputTokens. Adding the cache buckets again would
+      // double-count them and inflate the figure the Usage widget shows.
+      totalTokens: BigInt(this.inputTokens + this.outputTokens),
+      turnCount: this.turnCount,
+      estimatedCostUsd: this.estimatedCostUsd,
+      model: this.model,
+      observedAt: this.observedAt,
+      requestedServiceTier: this.requestedServiceTier,
+      requestedModelParams: this.requestedModelParams,
+      requestedThinkingMode: this.requestedThinkingMode,
+    };
+  }
+}

package/src/harness-adapters.ts

@@ -0,0 +1,30 @@
+/**
+ * The harnesses this worker serves: one registry row per adapter, in boot
+ * order. The ONE place an adapter's factory is named outside its own
+ * directory.
+ *
+ * Lives at the source root, beside the composition roots that read it, and
+ * not in `harness/registry.ts`: a row imports its adapter from
+ * `activities/`, and nothing under `src/harness/` may
+ * (`harness/__tests__/import-direction.test.ts`; the rule the turn runtime
+ * is written under). The registry knows rows, never which adapters exist.
+ *
+ * ORDER IS LOAD-BEARING (`registry.ts` `bootHarnesses`): the Cursor
+ * adapter's interceptors must patch `node:http2` before anything dials the
+ * control plane, so it boots first. The native deep-agent harness joins this
+ * table at S3 of the harness runtime program; until then both roots import
+ * its activities directly beside this table's.
+ *
+ * THIS MODULE'S STATIC GRAPH MUST STAY CONNECT- AND SDK-FREE. The roots
+ * import it BEFORE they boot the harnesses, and the Cursor adapter's boot is
+ * where `node:http2` is patched and `@cursor/sdk` first loaded; an adapter
+ * factory that imported its SDK statically would defeat both. An adapter
+ * named here loads its vendor SDK inside `boot` (`adapter.ts` shows the
+ * shape). `__tests__/harness-boot-order.test.ts` boots a fresh process
+ * through this module and fails if the graph regresses.
+ */
+
+import { createCursorAdapter } from "./activities/execute-cursor/adapter.js";
+import type { HarnessRow } from "./harness/registry.js";
+
+export const HARNESS_ADAPTERS: readonly HarnessRow[] = [{ harness: "cursor", adapter: createCursorAdapter() }];

package/src/main.ts

@@ -44,7 +44,7 @@ import { decidePoolBoot, registerPoolMemberContext } from "./pool-member.js";
 import { buildReadyMessage } from "./ipc-protocol.js";
 import type { IpcCommand, IpcResponse } from "./ipc-protocol.js";
 
-import { handleUnhandledRejection, setExecutionContextRef } from "./activities/execute-cursor/rejection-capture.js";
+import { handleUnhandledRejection } from "./activities/execute-cursor/rejection-capture.js";
 import { installProcessPipeGuards, reportFatal } from "./pipe-safety.js";
 
 // Guard the host pipes before anything writes to them. A dropped stderr/stdout