@stigmer/runner 3.14.0-dev.20260910084630 → 3.14.1

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

@@ -0,0 +1,289 @@
+/**
+ * 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.
+ *
+ * A `runTurn` with no scenario arranged 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, waitingToolCall } from "../proto-helpers.js";
+import type { 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;
+}
+
+/**
+ * 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;
+
+  private readonly queue: TurnScenario[] = [];
+  private readonly mintedStateIds = new Set<string>();
+  private readonly executions = new Map<string, number>();
+  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,
+    };
+  }
+
+  // ── Engine controls (the subject's side of the kit seam) ──────────────────
+
+  /** Queue what the next `runTurn` plays. */
+  arrange(turn: TurnScenario): void {
+    this.queue.push(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.queue.shift();
+    if (!turn) throw new Error(`${this.name}: runTurn called with no scenario arranged (test bug)`);
+
+    // 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", 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", 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();
+        sink.requestPersist();
+        return undefined;
+      }
+      case "propose":
+        return this.propose(step.toolCallId, step.action, input, sink);
+      case "usage": {
+        sink.reportUsage(step.delta);
+        sink.recordActivity();
+        return undefined;
+      }
+      case "hang": {
+        await whenAborted(sink.stopSignal);
+        return { kind: "interrupted" };
+      }
+      case "fail":
+        return { kind: "failed", message: step.message };
+      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.settleRow(existing, toolCallId, action, ToolCallStatus.TOOL_CALL_COMPLETED, sink);
+        return undefined;
+      }
+      case ApprovalAction.SKIP:
+      case ApprovalAction.REJECT: {
+        this.settleRow(existing, toolCallId, action, ToolCallStatus.TOOL_CALL_SKIPPED, sink);
+        return undefined;
+      }
+      default: {
+        const exhaustive: never = decision;
+        throw new Error(`${this.name}: unknown approval action ${String(exhaustive)}`);
+      }
+    }
+  }
+
+  /**
+   * Carry the proposal's row to its terminal status. 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 settleRow(
+    existing: ToolCall | undefined,
+    toolCallId: string,
+    action: ProposedAction,
+    status: ToolCallStatus,
+    sink: TurnSink,
+  ): void {
+    if (existing) {
+      existing.status = status;
+    } else {
+      const message = aiMessage("");
+      const row = waitingToolCall(toolCallId, action.kind, "");
+      row.status = status;
+      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;
+}
+
+export function scriptedSubject(options: ScriptedHarnessOptions): ScriptedSubject {
+  const adapter = new ScriptedHarnessAdapter(options);
+  return {
+    name: adapter.name,
+    adapter,
+    config: testConfig(),
+    arrange: (turn) => adapter.arrange(turn),
+    executionCount: (toolCallId) => adapter.executionCount(toolCallId),
+  };
+}

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

@@ -0,0 +1,100 @@
+/**
+ * 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 { Config } from "../../config.js";
+import type { HarnessAdapter, UsageDelta } from "../../harness/types.js";
+import type { ProposedAction } from "../approval-contract/types.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.
+ *  - `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`.
+ */
+export type ScenarioStep =
+  | { readonly kind: "say"; readonly text: string }
+  | { readonly kind: "propose"; readonly toolCallId: string; readonly action: ProposedAction }
+  | { readonly kind: "usage"; readonly delta: UsageDelta }
+  | { readonly kind: "hang" }
+  | { readonly kind: "fail"; readonly message: string };
+
+/** 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 };
+  },
+  usage(delta: UsageDelta): ScenarioStep {
+    return { kind: "usage", delta };
+  },
+  hang(): ScenarioStep {
+    return { kind: "hang" };
+  },
+  fail(message: string): ScenarioStep {
+    return { kind: "fail", message };
+  },
+} as const;
+
+/**
+ * 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.
+ */
+export interface HarnessContractSubject {
+  /** Stable name, used in suite titles and every assertion message. */
+  readonly name: string;
+  /** 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` on this adapter plays
+   * `turn`. 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): 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;
+}