@stigmer/runner 3.14.0 → 3.15.0

package/src/__test-utils__/harness-contract/scripted-adapter.ts

@@ -0,0 +1,349 @@
+/**
+ * The scripted harness adapter — the reference implementation of
+ * `HarnessAdapter`, driven by a `TurnScenario` per turn instead of a vendor
+ * SDK.
+ *
+ * Two jobs. It is the fake the contract kit runs against under every
+ * capability combination, so the kit is proven before any real adapter
+ * implements the contract. And it is the TEMPLATE a future harness author
+ * reads first: every rule of the contract appears here as the smallest code
+ * that honours it, with the reason beside it. Its measured line count is the
+ * program's "lines a new harness must write" data point.
+ *
+ * The insight this fake makes visible: above the contract line, the two real
+ * pause primitives are indistinguishable. Whether the engine checkpoints at
+ * the gate (`interrupt`) or a hook denies the tool and the run is cancelled
+ * (`deny-and-retry`), the turn ends `awaiting_approval` with a WAITING row on
+ * the status, and the next invocation carries the decision. How the engine
+ * RESUMES is the adapter's business, below the line, and the runtime never
+ * sees it. So this fake takes `pausePrimitive` as an option and does not
+ * branch on it — and the kit runs it under both to prove the kit does not
+ * branch on it either.
+ *
+ * What is deliberately simple here and would be real work in an adapter:
+ * "executing" a side effect is incrementing a counter; the engine state id is
+ * a counter too; the transcript rows are built with the shared proto
+ * factories. What is NOT simplified is the contract behaviour itself —
+ * settling with an outcome and never rejecting, stopping at every step
+ * boundary and inside a hang, binding before the first persist, executing an
+ * approval exactly once, refusing to resume a state it never minted — because
+ * those are what the kit measures.
+ *
+ * What this fake deliberately does NOT do, because it is not an adapter's
+ * job: carry a REJECTed or SKIPped row to its terminal status. The decision
+ * is on the row (the server's field) and the transition follows from it with
+ * no engine knowledge, so it belongs to the runtime — one writer per field,
+ * as `approvalDecisionsOf` is the runtime's one reader (S2 M4, Q-M4-1; the
+ * runtime's arm lands in S3). An adapter's whole duty for a non-executing
+ * decision is to not execute.
+ *
+ * Scenarios are arranged PER SESSION (the engine is per session in every real
+ * harness; a subject arranges that session's engine), and arranging replaces
+ * what that session had not yet played. A `runTurn` with no scenario arranged
+ * for its session is a test bug and throws (the same rule as the scripted
+ * `@cursor/sdk` agent's `send()` with no script left); every other exit is a
+ * `TurnOutcome`.
+ */
+
+import { ApprovalAction, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+
+import type { Config } from "../../config.js";
+import type { HarnessCapabilities, PausePrimitive, StateIdSource } from "../../harness/capabilities.js";
+import type { HarnessAdapter, TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
+import { DEEP_AGENT_VISION_PROFILE } from "../../shared/attachment-vision.js";
+import type { ProposedAction } from "../approval-contract/types.js";
+import { testConfig } from "../config-fixture.js";
+import { aiMessage, findToolCallRow, toolCall, waitingToolCall } from "../proto-helpers.js";
+import type { EngineView, HarnessContractSubject, ScenarioStep, TurnScenario } from "./types.js";
+
+export interface ScriptedHarnessOptions {
+  /** Diagnostic name; defaults to a name that says which primitives this instance runs under. */
+  readonly name?: string;
+  readonly pausePrimitive: PausePrimitive;
+  readonly stateIdSource: StateIdSource;
+  /**
+   * The subject's `Config` over `testConfig()`'s inert defaults. The fake reads
+   * none of it; the RUNTIME does when the subject runs through the real
+   * activity (the workspace root it provisions under, the task queue the
+   * drain signal is keyed by).
+   */
+  readonly config?: Partial<Config>;
+}
+
+/**
+ * Resolves when the signal aborts; resolves at once if it already has. Parks
+ * on the abort EVENT, never on a timer, so a hanging turn holds nothing that
+ * could keep a process alive — the property the runtime's heartbeat relies
+ * on when it declares a stalled turn dead.
+ */
+function whenAborted(signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+}
+
+/** A proposal already carried to a terminal row has been settled by an earlier invocation. */
+function isSettled(row: ToolCall | undefined): boolean {
+  return row !== undefined
+    && (row.status === ToolCallStatus.TOOL_CALL_COMPLETED || row.status === ToolCallStatus.TOOL_CALL_SKIPPED);
+}
+
+export class ScriptedHarnessAdapter implements HarnessAdapter {
+  readonly name: string;
+  readonly capabilities: HarnessCapabilities;
+
+  /** The next turn each session plays; arranging a session replaces its entry. */
+  private readonly arranged = new Map<string, TurnScenario>();
+  private readonly mintedStateIds = new Set<string>();
+  private readonly executions = new Map<string, number>();
+  private readonly hangWaiters: Array<() => void> = [];
+  private mintCounter = 0;
+
+  constructor(options: ScriptedHarnessOptions) {
+    this.name = options.name ?? `scripted(${options.pausePrimitive}, ${options.stateIdSource})`;
+    this.capabilities = {
+      pausePrimitive: options.pausePrimitive,
+      stateIdSource: options.stateIdSource,
+      systemPrompt: true,
+      subAgents: false,
+      toolRestriction: true,
+      visionProfile: DEEP_AGENT_VISION_PROFILE,
+      fileReview: { harnessId: "scripted", excludePaths: [] },
+    };
+  }
+
+  /**
+   * Resolves the next time a turn parks on a `hang` step — for a test that
+   * stands where the runtime's watchdog stands and needs to know the engine
+   * is silent before it advances the clock. Never on a timer.
+   */
+  whenHanging(): Promise<void> {
+    return new Promise((resolve) => this.hangWaiters.push(resolve));
+  }
+
+  // ── Engine controls (the subject's side of the kit seam) ──────────────────
+
+  /**
+   * What the session's next `runTurn` plays. The rest of the view is not
+   * needed here: this fake reads its decisions from `input.approvalDecisions`
+   * and settles a repeated proposal from the row itself, so it has nothing to
+   * decide before the turn.
+   */
+  arrange(turn: TurnScenario, view: Pick<EngineView, "sessionId">): void {
+    this.arranged.set(view.sessionId, turn);
+  }
+
+  executionCount(toolCallId: string): number {
+    return this.executions.get(toolCallId) ?? 0;
+  }
+
+  // ── HarnessAdapter ────────────────────────────────────────────────────────
+
+  /** Nothing to install: a real adapter imports its SDK lazily and installs its transport here. */
+  async boot(_config: Config): Promise<void> {}
+
+  /** Nothing held: a real adapter closes every engine it still has parked. */
+  async shutdown(): Promise<void> {}
+
+  /** Nothing is parked per session here; a real adapter releases the engine it parked for `sessionId`. */
+  async releaseSession(_sessionId: string): Promise<void> {}
+
+  async runTurn(input: TurnInput, sink: TurnSink): Promise<TurnOutcome> {
+    const turn = this.arranged.get(input.sessionId);
+    if (!turn) throw new Error(`${this.name}: runTurn called with no scenario arranged for session '${input.sessionId}' (test bug)`);
+    this.arranged.delete(input.sessionId);
+
+    // The signal may be aborted before the turn is entered; do no work then.
+    if (sink.stopSignal.aborted) return { kind: "interrupted" };
+
+    const resumed = await this.resolveEngineState(input, sink);
+    if (resumed.kind !== "ok") return resumed.outcome;
+
+    for (const step of turn) {
+      // Stop at every step boundary — the Cursor loop's per-event isCancelled().
+      if (sink.stopSignal.aborted) return { kind: "interrupted" };
+      const ended = await this.play(step, input, sink);
+      if (ended) return ended;
+    }
+    return { kind: "completed" };
+  }
+
+  /**
+   * Create or resume the engine, per `stateIdSource`. An engine-minted id is
+   * bound BEFORE the turn proceeds so a crash mid-turn still resumes; a
+   * resume of an id this engine never minted fails the way `Agent.resume` of
+   * an unknown id fails, so a runtime that threads the wrong id is caught. A
+   * deterministic engine's id is the runtime's; nothing to bind.
+   */
+  private async resolveEngineState(
+    input: TurnInput,
+    sink: TurnSink,
+  ): Promise<{ kind: "ok" } | { kind: "ended"; outcome: TurnOutcome }> {
+    if (this.capabilities.stateIdSource === "deterministic") return { kind: "ok" };
+
+    if (input.threadId === "") {
+      const minted = `${this.name}#state-${++this.mintCounter}`;
+      this.mintedStateIds.add(minted);
+      try {
+        await sink.bindHarnessState(minted);
+      } catch (err) {
+        return {
+          kind: "ended",
+          outcome: { kind: "failed", surface: "internal", message: `${this.name}: could not bind engine state`, cause: err },
+        };
+      }
+      return { kind: "ok" };
+    }
+
+    if (!this.mintedStateIds.has(input.threadId)) {
+      return {
+        kind: "ended",
+        outcome: { kind: "failed", surface: "internal", message: `${this.name}: no engine state '${input.threadId}' to resume` },
+      };
+    }
+    return { kind: "ok" };
+  }
+
+  /** Play one step; returns the outcome that ends the turn, or undefined to continue. */
+  private async play(step: ScenarioStep, input: TurnInput, sink: TurnSink): Promise<TurnOutcome | undefined> {
+    switch (step.kind) {
+      case "say": {
+        sink.status.messages.push(aiMessage(step.text));
+        sink.recordActivity();
+        // Awaited, as the Cursor loop awaits its own: a platform STOP the
+        // runtime reads from this write aborts the signal before the next
+        // step boundary sees it (the contract's "MAY await for ordering").
+        await sink.requestPersist();
+        return undefined;
+      }
+      case "propose":
+        return this.propose(step.toolCallId, step.action, input, sink);
+      case "read": {
+        // Ungated: the row lands COMPLETED at once, the effect counts as run,
+        // and the persist is awaited like `say`'s — a real engine's tool call
+        // is the discrete event its loop flushes on.
+        const message = aiMessage("");
+        const row = toolCall(step.toolCallId, "read", ToolCallStatus.TOOL_CALL_COMPLETED);
+        row.result = `contents of ${step.path}`;
+        message.toolCalls.push(row);
+        sink.status.messages.push(message);
+        this.executions.set(step.toolCallId, this.executionCount(step.toolCallId) + 1);
+        sink.recordActivity("read");
+        await sink.requestPersist();
+        return undefined;
+      }
+      case "usage": {
+        sink.reportUsage(step.delta);
+        sink.recordActivity();
+        return undefined;
+      }
+      case "hang": {
+        for (const waiter of this.hangWaiters.splice(0)) waiter();
+        await whenAborted(sink.stopSignal);
+        return { kind: "interrupted" };
+      }
+      case "fail":
+        return { kind: "failed", surface: step.surface, message: step.message };
+      case "cancelled":
+        return { kind: "cancelled" };
+      default: {
+        const exhaustive: never = step;
+        throw new Error(`${this.name}: unknown scenario step ${JSON.stringify(exhaustive)}`);
+      }
+    }
+  }
+
+  /**
+   * The gate, above the contract line. The status is the single source of
+   * truth for whether the effect ran: a row already carried to COMPLETED or
+   * SKIPPED by an earlier invocation is settled and the step is a no-op, which
+   * is what makes "reinvoked twice with the same decision, still once" hold
+   * without a second ledger.
+   */
+  private propose(
+    toolCallId: string,
+    action: ProposedAction,
+    input: TurnInput,
+    sink: TurnSink,
+  ): TurnOutcome | undefined {
+    const existing = findToolCallRow(sink.status, toolCallId);
+    if (isSettled(existing)) return undefined;
+
+    const decision = input.approvalDecisions.get(toolCallId) ?? ApprovalAction.UNSPECIFIED;
+    switch (decision) {
+      case ApprovalAction.UNSPECIFIED: {
+        // Propose: surface the gated call as a WAITING row and stop the turn.
+        // Never write a second row for the same id on a resumed turn.
+        if (!existing) {
+          const message = aiMessage("");
+          message.toolCalls.push(waitingToolCall(toolCallId, action.kind, `Approve ${action.kind} ${action.resource}?`));
+          sink.status.messages.push(message);
+        }
+        sink.recordActivity();
+        sink.requestPersist();
+        return { kind: "awaiting_approval" };
+      }
+      case ApprovalAction.APPROVE:
+      case ApprovalAction.APPROVE_ALL: {
+        this.executions.set(toolCallId, this.executionCount(toolCallId) + 1);
+        this.completeRow(existing, toolCallId, action, sink);
+        return undefined;
+      }
+      case ApprovalAction.SKIP:
+      case ApprovalAction.REJECT: {
+        // Not executed, and the row is left as the runtime handed it (see
+        // the header): the engine simply moves on.
+        sink.recordActivity();
+        return undefined;
+      }
+      default: {
+        const exhaustive: never = decision;
+        throw new Error(`${this.name}: unknown approval action ${String(exhaustive)}`);
+      }
+    }
+  }
+
+  /**
+   * Report the executed action on its row, as a real engine's completion
+   * event does. The row normally exists (the runtime seeded the status with
+   * last turn's WAITING row); a decision with no row is a runtime that decided
+   * out of band, and the adapter still records what happened rather than
+   * losing the fact.
+   */
+  private completeRow(existing: ToolCall | undefined, toolCallId: string, action: ProposedAction, sink: TurnSink): void {
+    if (existing) {
+      existing.status = ToolCallStatus.TOOL_CALL_COMPLETED;
+    } else {
+      const message = aiMessage("");
+      const row = waitingToolCall(toolCallId, action.kind, "");
+      row.status = ToolCallStatus.TOOL_CALL_COMPLETED;
+      message.toolCalls.push(row);
+      sink.status.messages.push(message);
+    }
+    sink.recordActivity();
+    sink.requestPersist();
+  }
+}
+
+/** The scripted adapter as a kit subject: the adapter IS its own engine, so the seam is a thin view over it. */
+export interface ScriptedSubject extends HarnessContractSubject {
+  readonly adapter: ScriptedHarnessAdapter;
+}
+
+/**
+ * The fake fills the `deep-agent` row in S2 — the one row the runtime does
+ * not yet serve for real (the native adapter lands in S3, and takes the row
+ * over from the fake in the runtime half then).
+ */
+export function scriptedSubject(options: ScriptedHarnessOptions): ScriptedSubject {
+  const adapter = new ScriptedHarnessAdapter(options);
+  return {
+    name: adapter.name,
+    harness: "deep-agent",
+    adapter,
+    config: testConfig(options.config),
+    arrange: (turn, view) => adapter.arrange(turn, view),
+    whenHanging: () => adapter.whenHanging(),
+    executionCount: (toolCallId) => adapter.executionCount(toolCallId),
+  };
+}

package/src/__test-utils__/harness-contract/types.ts

@@ -0,0 +1,176 @@
+/**
+ * The test-facing seam of the harness contract kit.
+ *
+ * `HarnessAdapter.runTurn(input, sink)` gives a test no way to make the
+ * engine DO anything: propose a gated action, emit usage, hang, fail. The
+ * approval-contract kit met the same problem with `GatewaySubstrate` — a
+ * small interface each real substrate adapts so one invariant catalog can
+ * drive all of them. This is that seam for harnesses: a
+ * {@link HarnessContractSubject} owns the ENGINE (what the next turn will
+ * do), and the kit owns everything the runtime would own (the sink, the
+ * `TurnInput`, the state id threading, the reinvocation).
+ *
+ * The scenario vocabulary is deliberately small and engine-neutral: it says
+ * what the kit needs to PROVOKE, never how an engine behaves. The scripted
+ * fake consumes it directly; a real harness's subject translates it onto that
+ * harness's own double (the Cursor subject onto the scripted `@cursor/sdk`
+ * agent of `execute-cursor/__test-utils__/`). One vocabulary, not one per
+ * engine, so the kit cannot drift from what the fake can do.
+ *
+ * Gated actions reuse `ProposedAction` from `approval-contract/types.ts`, the
+ * taxonomy-free action every enforcement substrate already translates, so the
+ * two kits speak of the same logical side effect and neither restates the
+ * HITL taxonomy.
+ */
+
+import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import type { Config } from "../../config.js";
+import type { HarnessName } from "../../harness/registry.js";
+import type { FailureSurface, HarnessAdapter, UsageDelta } from "../../harness/types.js";
+import type { ProposedAction } from "../approval-contract/types.js";
+import type { TurnInputFixtureOverrides } from "../turn-input-fixture.js";
+
+/**
+ * One thing the engine does during a turn. A turn plays its steps in order
+ * and ends `completed` when none is left, unless a step ends it first.
+ *
+ *  - `say`: the engine emits assistant text (a transcript row).
+ *  - `propose`: the engine reaches a gated side effect identified by
+ *    `toolCallId`. Undecided → the turn ends `awaiting_approval` and later
+ *    steps do not run; APPROVE → the effect runs once and the turn continues;
+ *    REJECT / SKIP → the effect never runs and the turn continues. WHICH
+ *    kinds a harness gates is the harness's policy and the workspace's
+ *    posture: a `shell` is gated by every harness in every posture; a `write`
+ *    is gated only outside apply-then-review capture (a git tree, or artifact
+ *    storage), so an arm that must gate on every subject proposes a `shell`.
+ *  - `read`: the engine performs an UNGATED read of `path` — a tool-call row
+ *    that runs at once, never pauses, and is the discrete event every harness
+ *    flushes a persist on (the lever an arm pulls when it needs the control
+ *    plane to answer a mid-turn persist).
+ *  - `usage`: the engine reports one turn's token counts.
+ *  - `hang`: the engine makes no further progress until told to stop. The
+ *    step that the stop-signal invariants and the runtime's stall watchdog
+ *    are built around; it must be parked on the signal, never on a timer.
+ *  - `fail`: the engine fails with a message the adapter can name; the turn
+ *    ends `failed` on the given surface (`engine` unless the scenario says
+ *    otherwise — the runtime's three failure copies are its own invariant).
+ *  - `cancelled`: the engine ends its own run cancelled with nothing to
+ *    wait for (an SDK-side cancel); the turn ends `cancelled`.
+ */
+export type ScenarioStep =
+  | { readonly kind: "say"; readonly text: string }
+  | { readonly kind: "propose"; readonly toolCallId: string; readonly action: ProposedAction }
+  | { readonly kind: "read"; readonly toolCallId: string; readonly path: string }
+  | { readonly kind: "usage"; readonly delta: UsageDelta }
+  | { readonly kind: "hang" }
+  | { readonly kind: "fail"; readonly message: string; readonly surface: FailureSurface }
+  | { readonly kind: "cancelled" };
+
+/** One turn's worth of engine behaviour. */
+export type TurnScenario = readonly ScenarioStep[];
+
+/** Step builders — the vocabulary a kit invariant reads as. */
+export const scenario = {
+  say(text: string): ScenarioStep {
+    return { kind: "say", text };
+  },
+  propose(toolCallId: string, action: ProposedAction): ScenarioStep {
+    return { kind: "propose", toolCallId, action };
+  },
+  read(toolCallId: string, path: string): ScenarioStep {
+    return { kind: "read", toolCallId, path };
+  },
+  usage(delta: UsageDelta): ScenarioStep {
+    return { kind: "usage", delta };
+  },
+  hang(): ScenarioStep {
+    return { kind: "hang" };
+  },
+  fail(message: string, surface: FailureSurface = "engine"): ScenarioStep {
+    return { kind: "fail", message, surface };
+  },
+  cancelled(): ScenarioStep {
+    return { kind: "cancelled" };
+  },
+} as const;
+
+/**
+ * What the engine can know about the turn it is about to play, handed to the
+ * subject with every {@link HarnessContractSubject.arrange}: which execution
+ * and session it serves (a real engine is per session — its handle is parked
+ * under the session, its workspace and hook state live under the session —
+ * so a subject arranges THAT session's engine, never "the next turn"), and
+ * the approval decisions the prompt will carry (the runtime's
+ * `approvalDecisionsOf` over the persisted status — the one reader both
+ * drivers call). A subject whose engine cannot re-run a settled action, or
+ * whose model is told not to perform a skipped one, reads its decision here
+ * instead of parsing the prompt for it.
+ */
+export interface EngineView {
+  readonly executionId: string;
+  readonly sessionId: string;
+  readonly approvalDecisions: ReadonlyMap<string, ApprovalAction>;
+}
+
+/**
+ * What a subject may say about the record its engine is handed, laid UNDER
+ * the driver's own facts: the five it threads (`executionId`, `threadId`,
+ * `turnSeq`, `sessionId`, `approvalDecisions`) and the persisted status it
+ * seeds are the kit's bookkeeping and never a subject's to state.
+ */
+export type SubjectInputOverrides = Omit<
+  TurnInputFixtureOverrides,
+  "executionId" | "threadId" | "turnSeq" | "sessionId" | "approvalDecisions" | "persistedStatus"
+>;
+
+/**
+ * One adapter under test, with the engine controls the kit needs. Adapters
+ * translate scenarios into their own double's drives and report what the
+ * double observed; they never reimplement contract behaviour.
+ *
+ * The kit owns the adapter's lifetime: it boots the adapter before the first
+ * turn and shuts it down after the last (the registry boots every adapter
+ * before the worker polls, and a real adapter refuses a turn before boot).
+ * The exported assertion functions therefore REQUIRE a booted adapter.
+ */
+export interface HarnessContractSubject {
+  /** Stable name, used in suite titles and every assertion message. */
+  readonly name: string;
+  /** The registry row this adapter fills; the runtime half selects the activity by it. */
+  readonly harness: HarnessName;
+  /** The adapter under test — the real implementation of the contract. */
+  readonly adapter: HarnessAdapter;
+  /** What `adapter.boot` needs. The subject knows its adapter's fields; the kit does not. */
+  readonly config: Config;
+  /**
+   * Arrange the engine so that the NEXT `runTurn` for `view.sessionId` plays
+   * `turn` — REPLACING whatever was arranged for that session and not yet
+   * played (a turn interrupted before its engine ran leaves no stale script
+   * behind). Called by the kit before every `runTurn`, including a
+   * reinvocation (the engine re-reaches the same gated call on resume, so the
+   * same proposal is arranged again).
+   */
+  arrange(turn: TurnScenario, view: EngineView): void;
+  /**
+   * What this engine needs the record to say beyond the driver's facts (the
+   * model the adapter validates, the workspace its gate installs into). A
+   * subject whose engine reads nothing of the record omits it.
+   */
+  inputOverrides?(view: EngineView): SubjectInputOverrides;
+  /**
+   * Resolves the next time a turn parks on a `hang` step — the moment the
+   * kit stops a turn from the outside, and the moment the runtime half
+   * delivers a cancellation, a drain or the clock tick that trips the stall
+   * watchdog. A real engine reaches its hang only after real setup (file
+   * writes, catalog fetches); a stop delivered any earlier would land in that
+   * setup and prove nothing about the hang. Never a timer.
+   */
+  whenHanging(): Promise<void>;
+  /**
+   * How many times the side effect behind `toolCallId` actually ran, as the
+   * subject's double observed it. The safety-critical observable; zero for an
+   * id the engine never reached.
+   */
+  executionCount(toolCallId: string): number;
+}