@stigmer/runner 3.14.1 → 3.15.1

package/src/harness/persist-chokepoint.ts

@@ -0,0 +1,112 @@
+/**
+ * The turn runtime's single persist chokepoint: every write of the
+ * execution status during a turn — the adapter's streaming requests, the
+ * runtime's own terminal writes — goes through here and nowhere else, so
+ * the guards that must never be skipped cannot be skipped by a call site
+ * that forgot them.
+ *
+ * What one write does, in order:
+ *  1. The never-persist-secret backstop (DD-26 #2): content is withheld from
+ *     any built-in write row targeting a secret-like path, top-level and
+ *     sub-agent. The single airtight choke point for a deny-gate harness and
+ *     the only guarantee under `auto_approve_all`. Idempotent.
+ *  2. `streaming_usage` is refreshed from the accumulator when it has turns,
+ *     so the summary the UI shows is the one the write carries.
+ *  3. `persistStatus` (`shared/status.ts`): tool-output offload, the
+ *     aggregate size cap, transient retry, oversize recovery. Never rejects.
+ *  4. A Temporal heartbeat, so a long streaming turn's liveness is proven by
+ *     the writes it makes (Q-S2-10).
+ *  5. The control plane's answer: STOP becomes the runtime's platform-stop
+ *     cause on the stop controller, which aborts the adapter's signal.
+ *
+ * Single-flight with coalescing: an adapter's `requestPersist()` while a
+ * write is in flight does not start a second concurrent write (two writes of
+ * one status racing on the wire is the drift the chokepoint exists to
+ * prevent); it schedules ONE follow-up write after the current one lands,
+ * and resolves when that follow-up has. The promise it returns therefore
+ * always means "the state as of my request is on the control plane", which
+ * is what lets the Cursor loop await it and see a STOP before it pulls the
+ * next event, exactly as its own inline persist did (Q-M3-2).
+ *
+ * The runtime's terminal writes use the same path (`write()`), so the
+ * secret backstop and the usage summary ride the final status too, as they
+ * did when the orchestrator's `persist` closure was the one place to write.
+ */
+
+import { create } from "@bufbuild/protobuf";
+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 { StigmerClient } from "../client/stigmer-client.js";
+import { persistStatus } from "../shared/status.js";
+import type { ToolOutputOffloadContext } from "../shared/status-offload.js";
+import { withholdSecretContentFromMessages } from "../shared/tool-row.js";
+import type { UsageAccumulator } from "./usage-accumulator.js";
+
+export interface PersistChokepointDeps {
+  readonly client: StigmerClient;
+  readonly executionId: string;
+  readonly status: AgentExecutionStatus;
+  /** Present when artifact storage resolved; enables tool-output offload on every write. */
+  readonly offload: ToolOutputOffloadContext | undefined;
+  /**
+   * The accumulator, read at WRITE time: it exists only once the runtime has
+   * the turn's model preferences, after resolution, so it arrives as a thunk
+   * and is `undefined` for a write made before then (no usage yet anyway).
+   */
+  readonly usage: () => UsageAccumulator | undefined;
+  /** The Temporal heartbeat, pulsed after each write. */
+  readonly heartbeat: () => void;
+  /** The control plane answered STOP to this write. */
+  readonly onPlatformStop: () => void;
+}
+
+export class PersistChokepoint {
+  private inFlight: Promise<void> | undefined;
+  private followUp: Promise<void> | undefined;
+
+  constructor(private readonly deps: PersistChokepointDeps) {}
+
+  /**
+   * The adapter's `requestPersist()`: a write now, or one follow-up write
+   * after the in-flight one. Resolves when the state as of this call has
+   * been written. Never rejects.
+   */
+  request(): Promise<void> {
+    if (this.inFlight === undefined) {
+      const write = this.write().finally(() => {
+        this.inFlight = undefined;
+      });
+      this.inFlight = write;
+      return write;
+    }
+    if (this.followUp === undefined) {
+      this.followUp = this.inFlight.then(() => {
+        this.followUp = undefined;
+        return this.request();
+      });
+    }
+    return this.followUp;
+  }
+
+  /**
+   * One write, now. The runtime's own writes (a settlement, a terminal
+   * status) call this directly: they run when no adapter write can be in
+   * flight (before `runTurn` or after it settled), so they need no
+   * coalescing, and they must not be deferred behind one.
+   */
+  async write(): Promise<void> {
+    const { client, executionId, status, offload, heartbeat } = this.deps;
+    withholdSecretContentFromMessages(status.messages, status.subAgentExecutions);
+    const usage = this.deps.usage();
+    if (usage?.hasTurns) {
+      status.streamingUsage = create(StreamingUsageSummarySchema, usage.snapshot());
+    }
+    const signal = await persistStatus(client, executionId, status, { offload });
+    heartbeat();
+    if (signal === ExecutionControlSignal.STOP) {
+      this.deps.onPlatformStop();
+    }
+  }
+}

package/src/harness/registry.ts

@@ -19,19 +19,35 @@
  *    one `AggregateError` at the end naming each failure, so one bad teardown
  *    never leaks the others' resources.
  *
- * What is NOT here yet: `createHarnessActivities` (its body is the turn
- * runtime, which does not exist until the extraction entry) and the table of
- * real adapters (they exist once the Cursor and native harnesses implement
- * the contract). Both land with the runtime; no empty table sits on `main`
- * between the two.
+ * `createHarnessActivities` binds each row to its Temporal activity over the
+ * turn runtime (`run-turn.ts`). The table of real rows is NOT here: it lives
+ * at the source root (`src/harness-adapters.ts`), because a row imports its
+ * adapter from `activities/` and nothing under `src/harness/` may
+ * (`__tests__/import-direction.test.ts`; Q-M3-1). The registry knows rows,
+ * never which adapters exist.
  *
  * `HarnessName` lives here and not in `types.ts` on purpose: the wire
  * vocabulary is the registry's concern. An adapter never declares the
  * activity it is bound to (its `name` is a diagnostic identity); the registry
  * row does.
+ *
+ * THIS MODULE'S STATIC GRAPH MUST STAY CONNECT-FREE. Both composition roots
+ * import it BEFORE they boot the harnesses, and the Cursor adapter's boot
+ * patches `node:http2` (its HTTP/2 auth interceptor); a static import of
+ * anything that loads `@connectrpc/connect-node` here would snapshot the
+ * `node:http2` ESM facade to the unpatched `connect` before that boot ran,
+ * and every BiDi stream would silently 401. So `StigmerClient` is loaded
+ * with a dynamic import inside `createHarnessActivities`, the runner's
+ * dynamic-import-for-order convention (`bootstrap.ts` documents the same
+ * omission for the same reason). `__tests__/harness-boot-order.test.ts`
+ * boots a fresh process through this module and fails if the facade froze.
  */
 
 import type { Config } from "../config.js";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import { activityFinished, activityStarted } from "../idle-watchdog.js";
+import { normalizeActivityInput, type ExecuteActivityInput } from "../shared/activity-input.js";
+import { runTurnActivity } from "./run-turn.js";
 import type { HarnessAdapter } from "./types.js";
 
 /** The harnesses the control plane can dispatch to, as the registry knows them. */
@@ -51,6 +67,64 @@ export const HARNESS_ACTIVITY_NAMES = {
 
 export type HarnessActivityName = (typeof HARNESS_ACTIVITY_NAMES)[HarnessName];
 
+/** One harness the worker serves: the wire name it answers to and the adapter that runs its turns. */
+export interface HarnessRow {
+  readonly harness: HarnessName;
+  readonly adapter: HarnessAdapter;
+}
+
+/**
+ * The legacy positional activity signature, kept as the wire shape both
+ * control planes send until they both send the typed object
+ * (`shared/activity-input.ts`). Every harness's activity has it.
+ */
+export type HarnessActivity = (arg0: ExecuteActivityInput | string, arg1?: string) => Promise<unknown>;
+
+/** The adapters of a row list, for the lifecycle functions below. */
+export function adaptersOf(rows: readonly HarnessRow[]): HarnessAdapter[] {
+  return rows.map((row) => row.adapter);
+}
+
+/**
+ * One Temporal activity per row, under the row's byte-pinned name, over ONE
+ * `StigmerClient` for all of them (each harness used to build its own). The
+ * activity normalizes the wire input, brackets the turn with the idle
+ * watchdog, and hands the turn runtime the adapter. The roots spread the
+ * result into the worker's activity map beside the activities the runtime
+ * does not own.
+ *
+ * Async because the client is loaded here, not at the top of the module (see
+ * the header): the roots call this after the harnesses have booted, when
+ * connect-node may load.
+ */
+export async function createHarnessActivities(
+  rows: readonly HarnessRow[],
+  config: Config,
+): Promise<Partial<Record<HarnessActivityName, HarnessActivity>>> {
+  const { StigmerClient } = await import("../client/stigmer-client.js");
+  const client: StigmerClient = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: config.stigmerToken,
+    tokenRef: config.stigmerTokenRef,
+    runnerTokenRef: config.stigmerRunnerTokenRef,
+  });
+  const activities: Partial<Record<HarnessActivityName, HarnessActivity>> = {};
+  for (const row of rows) {
+    const activityName = HARNESS_ACTIVITY_NAMES[row.harness];
+    const deps = { adapter: row.adapter, activityName, client, config };
+    activities[activityName] = async (arg0, arg1) => {
+      const input = normalizeActivityInput(arg0, arg1);
+      activityStarted();
+      try {
+        return await runTurnActivity(deps, input);
+      } finally {
+        activityFinished();
+      }
+    };
+  }
+  return activities;
+}
+
 /**
  * Refuse a table two of whose adapters share a name. Names are the registry's
  * identity for diagnostics and for this check; a duplicate means two adapters