@stigmer/runner 3.14.1 → 3.15.1

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

@@ -1,38 +1,38 @@
 /**
  * The Cursor harness's stream phase — the single per-event consumption loop that
  * turns a live Cursor SDK run into the streamed transcript, mid-run progress, and
- * the flags that decide how the turn ends.
+ * the one flag that decides how the turn goes on (the first-denial stop).
  *
- * Extracted from the activity entry point (index.ts) so that BOTH the primary
- * turn and the two recovery retries (poisoned-handle / transport-timeout) drive
- * the exact same code. The retries previously re-implemented a stripped "bare"
+ * Extracted from the activity entry point so that BOTH the primary turn and
+ * the two recovery retries (poisoned-handle / transport-timeout) drive the
+ * exact same code. The retries previously re-implemented a stripped "bare"
  * loop that dropped live persist, DD-32/DD-33 mid-run progress, sub-agent
- * tracking, the first-denial early stop, and correct pause/stall handling — so a
+ * tracking, the first-denial early stop, and correct pause handling — so a
  * retry froze the UI and mis-handled a mid-retry pause. One loop removes that
  * drift by construction.
  *
- * This mirrors the deep-agent harness's `streamExecution` seam
- * (execute-deep-agent/streaming.ts): injected `heartbeat`/`isCancelled` so it
- * runs without Temporal, a structural `StreamableRun` so it runs without the live
- * SDK, and a result (the terminal reason) instead of internal terminal mapping.
- * The one deliberate difference: this consumer REPORTS why the stream ended and
- * leaves the terminal MAPPING to the activity, because Cursor's mapping is
- * entangled with worker-shutdown-vs-pause disambiguation, the turn boundary,
- * structured output, and recovery retries — all of which must stay in index.ts.
+ * What the loop asks of the runtime, through the sink (`harness/types.ts`):
+ * `recordActivity()` per event (with the tool name) and per delta, so the
+ * runtime's stall watchdog measures the engine; `reportUsage()` per
+ * `turn-ended` delta, priced here at the requested variant's rates
+ * (`usage-pricing.ts`), so the runtime accounts and enforces the cost cap;
+ * `requestPersist()` where a discrete change or the streaming cadence says
+ * so (`shared/persist-decision.ts` over this loop's own dirty flags), AWAITED,
+ * so a platform STOP the runtime reads from that write aborts the signal
+ * before the next event is pulled; and `stopSignal`, checked at every event
+ * boundary and listened to inside the pull, where an abort cancels the SDK
+ * run — the one way a wedged stream is unblocked, and the same act for every
+ * cause of stopping (the runtime knows why; this loop never does).
+ *
+ * Until S2 M3 this loop armed its own stall watchdog, enforced the cost cap,
+ * read STOP from its own persist, and told a pause from the activity's
+ * cancellation signal; every one of those is the runtime's now, and the loop
+ * reports only `completed`, `first-denial` or `interrupted`.
  */
 
-import { create } from "@bufbuild/protobuf";
-import { CancelledFailure } from "@temporalio/activity";
-import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import { ExecutionControlSignal } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
 import type { SDKMessage, InteractionUpdate } from "@cursor/sdk";
-import {
-  startStallWatchdog,
-  StallTimeoutError,
-  type StallWatchdog,
-} from "../../shared/stall-watchdog.js";
-import { shouldPersistStreamingStatus } from "./persist-decision.js";
+import type { TurnSink } from "../../harness/types.js";
+import { shouldPersistStreamingStatus } from "../../shared/persist-decision.js";
 import { approvalDenials, readDenialLedger } from "./approval-state.js";
 import {
   captureFileChangeProgress,
@@ -43,9 +43,8 @@ import type { MessageAccumulator } from "./message-translator.js";
 import type { DeltaEnricher } from "./delta-enricher.js";
 import type { TodoTracker } from "./todo-tracker.js";
 import type { StreamingUpdateScheduler } from "../../shared/streaming-scheduler.js";
-import type { UsageAccumulator } from "./usage-accumulator.js";
+import type { CursorUsagePricer } from "./usage-pricing.js";
 import type { createCursorEventRecorder } from "./cursor-event-recorder.js";
-import { costCapExceeded } from "./cost-guard.js";
 
 /**
  * The subset of the Cursor SDK `Run` the stream phase consumes. Kept structural
@@ -60,101 +59,60 @@ export interface StreamableRun {
 export type CursorTurnEventRecorder = ReturnType<typeof createCursorEventRecorder>;
 
 /**
- * Why the turn's stream ended. The activity maps each reason to a terminal
- * outcome (see resolvePreBoundaryTerminal in index.ts): `completed` and
- * `first-denial` proceed to the turn boundary; the rest are pre-boundary
- * terminals that return or throw.
+ * Why the turn's stream ended. `completed` and `first-denial` proceed to the
+ * turn boundary; `interrupted` is the runtime's stop, and the adapter settles
+ * `interrupted` (the runtime classifies the cause from its own evidence).
  */
-export type TurnStreamReason =
-  | "completed"
-  | "paused"
-  | "stalled"
-  | "first-denial"
-  | "platform-stop"
-  | "cost-cap";
+export type TurnStreamReason = "completed" | "first-denial" | "interrupted";
 
 /**
- * Single owner for every flag the turn's stream produces. Before this, these
- * eleven fields lived as scattered `let`s co-written by FOUR concurrent
- * producers — the SDK `onDelta`, the fs denial-watcher, the stall-watchdog, and
- * the loop — the classic "who writes this field?" hazard. Consolidating them into
- * one object (created once per turn, shared by every producer, the epilogue, and
- * the outer catch/finally) makes ownership explicit and lets the primary turn and
- * both recovery retries drive the identical stream code.
- *
- * Field ownership is annotated per field: exactly one primary writer, plus any
- * documented producer/consumer handshakes.
+ * The flags the turn's stream produces that outlive the loop: created once per
+ * turn and shared by the primary stream, both recovery retries, the boundary
+ * and the settle, so every reader sees ONE source of truth. Field ownership
+ * is annotated per field: exactly one primary writer.
  */
 export interface TurnStreamState {
-  /** Written by: onDelta (heartbeat cancel) + the loop's cancellation check. Read by: the loop, epilogue, outer catch. */
-  pauseDetected: boolean;
-  /** Written by: the stall-watchdog callback. Read by: the loop + epilogue. */
-  stallDetected: boolean;
-  stallError: StallTimeoutError | undefined;
-  /** Written by: the loop (on the first ledger entry). Read by: the loop, epilogue, settleRetryTurn. */
+  /** Written by: the loop (on the first ledger entry). Read by: the loop, the boundary, settleRetryTurn. */
   firstDenialDetected: boolean;
   /** Written by: the fs denial-watcher (→ true) + the loop (→ false after a read). Read by: the loop. */
   denialLedgerDirty: boolean;
   /** Written by: the loop (the first-denial run.cancel()). Read by: the turn boundary. */
   denialCancelSettled: Promise<void> | undefined;
-  /** Written by: the loop (a platform STOP signal from persist). Read by: the loop + epilogue. */
-  platformStopSignaled: boolean;
-  /** Written by: onDelta (a turn-ended usage delta pushed the estimate past max_cost_usd). Read by: the loop (cancel + break) + epilogue. */
-  costCapExceeded: boolean;
   /** Written by: the loop (a stream ERROR status event) + the retry setup (reset). Read by: error classification. */
   streamErrorMessage: string | undefined;
-  /** Written by: the loop (each tool_call). Read by: the stall-watchdog (message enrichment). */
-  lastToolName: string | undefined;
   /** Written by: the loop. Read by: the event recorder, the persist cadence, and logs. */
   eventCount: number;
   /** Written + read by: onDelta (log the first turn's context attribution exactly once). */
   firstTurnAttributionLogged: boolean;
-  /** The stall watchdog for the CURRENT stream, armed by consumeCursorTurnStream; held so onDelta can reset it and the activity's finally can stop it. */
-  stallWatchdog: StallWatchdog | undefined;
 }
 
 export function newTurnStreamState(): TurnStreamState {
   return {
-    pauseDetected: false,
-    stallDetected: false,
-    stallError: undefined,
     firstDenialDetected: false,
     denialLedgerDirty: false,
     denialCancelSettled: undefined,
-    platformStopSignaled: false,
-    costCapExceeded: false,
     streamErrorMessage: undefined,
-    lastToolName: undefined,
     eventCount: 0,
     firstTurnAttributionLogged: false,
-    stallWatchdog: undefined,
   };
 }
 
 /**
  * The subset of collaborators the shared onDelta needs. Broken out from
  * CursorTurnStreamDeps because the primary send happens BEFORE the accumulator
- * exists — onDelta only touches usage, the enricher, the heartbeat, and state.
+ * exists — onDelta only touches the sink, the pricer, the enricher, and state.
  */
 export interface TurnOnDeltaDeps {
-  readonly usageAccumulator: UsageAccumulator;
+  readonly sink: TurnSink;
+  /** This harness's pricing of a `turn-ended` delta at the requested variant's rates. */
+  readonly usagePricer: CursorUsagePricer;
   readonly deltaEnricher: DeltaEnricher;
-  /** Temporal heartbeat. Injected so the callback is testable without Temporal. */
-  readonly heartbeat: () => void;
   readonly promptEstimatedTokens: number;
   readonly executionId: string;
   readonly state: TurnStreamState;
-  /**
-   * ExecutionConfig.max_cost_usd — 0/unset disables the cap. Checked by
-   * onDelta after each turn-ended usage delta lands (the only point the
-   * running estimate advances); the loop performs the actual run.cancel().
-   * See cost-guard.ts for the semantics.
-   */
-  readonly maxCostUsd: number;
 }
 
 export interface CursorTurnStreamDeps extends TurnOnDeltaDeps {
-  readonly status: AgentExecutionStatus;
   readonly accumulator: MessageAccumulator;
   readonly todoTracker: TodoTracker;
   readonly eventRecorder: CursorTurnEventRecorder | undefined;
@@ -164,46 +122,27 @@ export interface CursorTurnStreamDeps extends TurnOnDeltaDeps {
   readonly changeSetId: string;
   /** Session HITL dir holding the denial ledger; undefined → no gate installed → no first-denial stop. */
   readonly hitlDir: string | undefined;
-  readonly stallTimeoutMs: number;
-  /** The single size-bounded persist chokepoint. Returns the platform control signal. */
-  readonly persist: (status: AgentExecutionStatus) => Promise<ExecutionControlSignal>;
-  /** Temporal cancellation check. Injected so the loop is testable without Temporal. */
-  readonly isCancelled: () => boolean;
 }
 
 /**
  * Build the shared onDelta callback. The Cursor SDK's fine-grained delta channel
  * carries token usage, live shell output, and precise tool-call timings; it also
- * fires far more often than discrete stream events, so it is where the stall
- * timer is reset during a long model generation. A heartbeat CancelledFailure
- * here flags the pause so the loop and epilogue treat it as a user pause (the
- * bare retry loops swallowed this — the cause of the mid-retry mislabel).
+ * fires far more often than discrete stream events, so it is where the runtime's
+ * stall timer is reset during a long model generation.
  */
 export function makeCursorTurnOnDelta(
   deps: TurnOnDeltaDeps,
 ): (event: { update: InteractionUpdate }) => void {
-  const { usageAccumulator, deltaEnricher, heartbeat, promptEstimatedTokens, executionId, state, maxCostUsd } =
-    deps;
+  const { sink, usagePricer, deltaEnricher, promptEstimatedTokens, executionId, state } = deps;
   return ({ update }) => {
-    // Reset the stall timer on the delta channel too: a long model generation
-    // emits token deltas but few discrete stream events, so resetting only in the
-    // stream loop would false-positive a stall.
-    state.stallWatchdog?.recordActivity();
+    // Progress on the delta channel too: a long model generation emits token
+    // deltas but few discrete stream events, and resetting only in the stream
+    // loop would false-positive a stall.
+    sink.recordActivity();
     if (update.type === "turn-ended" && update.usage) {
-      usageAccumulator.addTurn(update.usage);
-
-      // max_cost_usd enforcement (cost-guard.ts): the running estimate only
-      // advances here, so this is the single check point. onDelta cannot reach
-      // the run — the loop reads the flag and performs the clean cancel.
-      if (!state.costCapExceeded
-          && costCapExceeded(maxCostUsd, usageAccumulator.snapshot().estimatedCostUsd)) {
-        state.costCapExceeded = true;
-        console.warn(
-          `ExecuteCursor cost cap exceeded: execution=${executionId}, ` +
-            `estimatedCostUsd=${usageAccumulator.snapshot().estimatedCostUsd.toFixed(4)}, ` +
-            `maxCostUsd=${maxCostUsd.toFixed(2)}`,
-        );
-      }
+      // The running estimate advances only here; the runtime enforces the cap
+      // and aborts the signal, which the loop reads at the next boundary.
+      sink.reportUsage(usagePricer.price(update.usage));
 
       if (!state.firstTurnAttributionLogged) {
         state.firstTurnAttributionLogged = true;
@@ -217,15 +156,6 @@ export function makeCursorTurnOnDelta(
       }
     }
     deltaEnricher.processDelta(update);
-    try {
-      heartbeat();
-    } catch (hbErr) {
-      if (hbErr instanceof CancelledFailure) {
-        state.pauseDetected = true;
-        return;
-      }
-      throw hbErr;
-    }
   };
 }
 
@@ -234,94 +164,58 @@ export function makeCursorTurnOnDelta(
  * transcript, todos, sub-agent tracking, live persist, and DD-32/DD-33 mid-run
  * progress, and reporting WHY the stream ended.
  *
- * Arms + stops its own stall watchdog (stored on `state.stallWatchdog` so the
- * shared onDelta can reset it and the activity's finally can stop it as a
- * backstop). Mutates `deps.status` + `deps.state` in place. The caller owns the
- * post-stream finalize and the terminal mapping.
+ * Mutates `deps.sink.status` + `deps.state` in place. The caller owns the
+ * post-stream finalize and the settle.
  */
 export async function consumeCursorTurnStream(
   run: StreamableRun,
   deps: CursorTurnStreamDeps,
 ): Promise<TurnStreamReason> {
   const {
-    status,
+    sink,
     accumulator,
     todoTracker,
     deltaEnricher,
     eventRecorder,
     scheduler,
-    usageAccumulator,
     progressSubstrate,
     progressState,
     changeSetId,
     hitlDir,
     executionId,
-    stallTimeoutMs,
-    persist,
-    heartbeat,
-    isCancelled,
     state,
   } = deps;
+  const { status, stopSignal } = sink;
 
-  // Arm the stall watchdog now that the run exists. The activity's periodic
-  // heartbeat proves the process is alive, not that the agent is progressing: if
-  // the stream wedges (a tool call or model connection that never returns), no
-  // event/delta arrives and the turn would hang forever. On stall we end the run
-  // cleanly via the SDK's run.cancel() (guarded by supports("cancel")), which
-  // unblocks the for-await; the caller then reports EXECUTION_FAILED with a
-  // recognizable, actionable message.
-  state.stallWatchdog = startStallWatchdog(stallTimeoutMs, (idleMs) => {
-    state.stallDetected = true;
-    state.stallError = new StallTimeoutError(
-      idleMs,
-      state.lastToolName ? `last tool: ${state.lastToolName}` : undefined,
-    );
-    console.warn(
-      `ExecuteCursor stall detected: execution=${executionId}, idleMs=${idleMs}, lastTool=${state.lastToolName ?? "none"}`,
-    );
+  // The runtime's stop, whatever its cause, ends the run through the SDK's
+  // own cancel: that is what unblocks a wedged `for await` (a stall), and it
+  // stops the engine's tools and deltas from outliving the turn on every
+  // other cause too. Guarded by supports("cancel") as the loop's own cancels
+  // are; the teardown rejection it can cause is swallowed below.
+  const cancelOnStop = (): void => {
+    console.log(`ExecuteCursor stopping stream on the runtime's stop signal: execution=${executionId}`);
     if (run.supports?.("cancel")) {
       void run.cancel().catch((cancelErr) => {
         console.warn(
-          `ExecuteCursor run.cancel() after stall failed (non-fatal): execution=${executionId}, ` +
+          `ExecuteCursor run.cancel() after stop failed (non-fatal): execution=${executionId}, ` +
             `error=${cancelErr instanceof Error ? cancelErr.message : cancelErr}`,
         );
       });
     }
-  });
+  };
+  if (stopSignal.aborted) {
+    cancelOnStop();
+    return "interrupted";
+  }
+  stopSignal.addEventListener("abort", cancelOnStop, { once: true });
 
   try {
     for await (const event of run.stream()) {
-      if (state.pauseDetected || isCancelled()) {
-        state.pauseDetected = true;
-        break;
-      }
-      if (state.stallDetected) break;
+      if (stopSignal.aborted) break;
 
-      // Cost cap (cost-guard.ts): onDelta flagged the overrun on a turn-ended
-      // usage delta; end the run through the same clean-cancel pattern as the
-      // stall watchdog and the first-denial stop. Fire-and-forget is correct
-      // here — nothing downstream waits on this turn's agent (unlike the
-      // first-denial stop, whose ledger read needs a stopped agent).
-      if (state.costCapExceeded) {
-        console.log(
-          `ExecuteCursor stopping stream at cost cap: execution=${executionId}`,
-        );
-        if (run.supports?.("cancel")) {
-          void run.cancel().catch((cancelErr) => {
-            console.warn(
-              `ExecuteCursor run.cancel() after cost cap failed (non-fatal): execution=${executionId}, ` +
-                `error=${cancelErr instanceof Error ? cancelErr.message : cancelErr}`,
-            );
-          });
-        }
-        break;
-      }
-
-      // Progress: reset the stall timer on every stream event.
-      state.stallWatchdog.recordActivity();
-      if (event.type === "tool_call" && typeof event.name === "string") {
-        state.lastToolName = event.name;
-      }
+      // Progress: reset the runtime's stall timer on every stream event,
+      // naming the tool so a stall's copy can say `last tool: shell`.
+      sink.recordActivity(event.type === "tool_call" && typeof event.name === "string" ? event.name : undefined);
 
       eventRecorder?.record(event, state.eventCount);
 
@@ -405,9 +299,6 @@ export async function consumeCursorTurnStream(
         scheduler,
         state.eventCount,
       );
-      if (usageAccumulator.hasTurns) {
-        status.streamingUsage = create(StreamingUsageSummarySchema, usageAccumulator.snapshot());
-      }
       if (shouldPersist) {
         // Sync sub-agent executions into status before every persist so the live
         // UI reflects delegation (including the IN_PROGRESS state) while the
@@ -425,52 +316,35 @@ export async function consumeCursorTurnStream(
             state: progressState,
           });
         }
-        const signal = await persist(status);
+        // Awaited: the runtime reads the control plane's answer to this write,
+        // and a STOP must be seen at the next event boundary, not one event late.
+        await sink.requestPersist();
         deltaEnricher.markPersisted();
         todoTracker.markPersisted();
         accumulator.markPersisted();
         scheduler.markUpdateSent(state.eventCount);
-        heartbeat();
-        if (signal === ExecutionControlSignal.STOP) {
-          state.platformStopSignaled = true;
-          console.warn(`ExecuteCursor platform stop signal received: execution=${executionId}`);
-        }
-      }
-
-      if (state.platformStopSignaled) {
-        console.log(
-          `ExecuteCursor stopping stream due to platform stop signal: execution=${executionId}`,
-        );
-        break;
       }
     }
   } catch (streamErr) {
-    // run.cancel() — from the stall watchdog, the first-denial stop, or the
-    // cost-cap stop — can make the stream iterator reject as it tears down;
-    // that is the expected teardown for all three, so swallow it and fall
-    // through. Anything else is a genuine stream failure — rethrow it to the
-    // activity's error handler.
-    if (!state.stallDetected && !state.firstDenialDetected && !state.costCapExceeded) {
+    // run.cancel() — from the runtime's stop or the first-denial stop — can
+    // make the stream iterator reject as it tears down; that is the expected
+    // teardown for both, so swallow it and fall through. Anything else is a
+    // genuine stream failure — rethrow it to the adapter's error handler.
+    if (!stopSignal.aborted && !state.firstDenialDetected) {
       throw streamErr;
     }
     console.warn(
       `ExecuteCursor stream ended via cancel: execution=${executionId}, ` +
-        `stall=${state.stallDetected}, firstDenial=${state.firstDenialDetected}, ` +
-        `costCap=${state.costCapExceeded}`,
+        `stopped=${stopSignal.aborted}, firstDenial=${state.firstDenialDetected}`,
     );
   } finally {
-    state.stallWatchdog.stop();
+    stopSignal.removeEventListener("abort", cancelOnStop);
   }
 
-  // Report why the stream ended, in the same precedence the activity's epilogue
-  // applies: a stall (an EXECUTION_FAILED terminal) outranks everything; a
-  // platform stop, a cost-cap stop, and a first denial are distinct
-  // return/proceed outcomes; a pause is the fallback for a cancellation with
-  // no other cause.
-  if (state.stallDetected) return "stalled";
-  if (state.platformStopSignaled) return "platform-stop";
-  if (state.costCapExceeded) return "cost-cap";
+  // Report why the stream ended: the runtime's stop outranks a first denial
+  // (there is no review to open on a stopped turn), a first denial outranks a
+  // natural end.
+  if (stopSignal.aborted) return "interrupted";
   if (state.firstDenialDetected) return "first-denial";
-  if (state.pauseDetected || isCancelled()) return "paused";
   return "completed";
 }