@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/__test-utils__/hermetic-activity.d.ts

@@ -0,0 +1,450 @@
+/**
+ * Hermetic activity driver — run a REAL runner activity end to end with no
+ * network, no credentials, and no live Temporal worker, and read back every
+ * status it persisted.
+ *
+ * Why this exists: the runner's activities (`ExecuteCursor`, `ExecuteDeepAgent`)
+ * are the wire contract the control plane's workflow keys on — the phases they
+ * persist, the copy they write, whether they RETURN a slim status or THROW
+ * `CancelledFailure`. Refactoring them safely needs goldens recorded through the
+ * activity whole, not through its modules one at a time. The native harness's
+ * earlier activity tests ran their activity hermetically by mocking three
+ * modules at the boundary with a hand-written `Context` stand-in and a scripted
+ * graph object; this module is that convention made reusable, harness-agnostic,
+ * and driven by the framework's own activity environment. Both harnesses now
+ * run on it (`execute-cursor/__test-utils__/hermetic-cursor.ts`,
+ * `execute-deep-agent/__test-utils__/hermetic-deep-agent.ts`), and the earlier
+ * native tests were re-homed onto the native driver (#1096), their assertions
+ * carried into `execute-deep-agent/__tests__/hermetic/`.
+ *
+ * What is generic here and what is not: everything an activity touches that is
+ * NOT the vendor SDK — the Temporal `Context`, the control-plane client, the
+ * runner-owned `~/.stigmer` tree, artifact storage, the model registry, the
+ * clock, the worker-shutdown signal — is set up here. The vendor SDK double
+ * belongs to the harness (`activities/execute-cursor/__test-utils__/scripted-*.ts`),
+ * the same split as `approval-contract/` (runner-wide kit) + each harness's
+ * `gateway-substrate.ts`.
+ *
+ * Three substitutions, and why each is shaped the way it is:
+ *
+ *  1. `Context.current()` — `MockActivityEnvironment` from `@temporalio/testing`,
+ *     ONE PER INVOCATION. It gives the activity a real `Context` (real
+ *     `cancellationSignal`, real `heartbeat()` surfaced as events, real
+ *     `CancelledFailure` on throw). The native tests' stand-in mints a fresh
+ *     `AbortController` on every `Context.current()` call and so cannot drive a
+ *     pause; production hands each attempt one `Context`, and so does this. The
+ *     environment's documented caveat — once cancelled it stays cancelled — is
+ *     why it is per invocation and never shared.
+ *
+ *  2. `StigmerClient` — the test file mocks the module (`vi.mock` is hoisted and
+ *     must live in the test file; see {@link hermeticStigmerClientModule}) and
+ *     the constructor hands back whatever client {@link bindHermeticClient} bound
+ *     for the current run. The client is `mockStigmerClient` over an
+ *     {@link ExecutionRecord}: `updateStatus` writes back into the record the way
+ *     the server would, and `appendSessionEvents` into its modelled log, so a
+ *     REINVOCATION (`threadId` set) reads what the first invocation wrote —
+ *     the resume path runs on real data, not on a hand-built status. The
+ *     runner's rows never cross the wire; the record reads them where the
+ *     emitter does ({@link ExecutionRecord.persistedRows}), so a test asserts
+ *     on the rows each write was made from.
+ *
+ *  3. The environment — a temp `HOME` (the runner-owned `~/.stigmer` tree,
+ *     `platform-dir.ts` reads `process.env.HOME`), a temp workspace root, local
+ *     artifact storage in a temp dir, and the HITL fingerprint secret pinned by
+ *     env var (`fingerprint-secret.ts` falls back to `randomBytes` — the ONE
+ *     source of randomness on the activity path — and memoizes on first call, so
+ *     the pin must precede the first invocation in the process).
+ *
+ * Determinism: the clock is faked for `Date` ONLY (`vi.useFakeTimers({ toFake:
+ * ["Date"] })`) and TICKS — the harness double advances it a fixed quantum per
+ * script step through {@link ScriptedClock}. Frozen time would make
+ * the streaming scheduler's cadence (`Date.now()` against its last send) never
+ * elapse and silently skip the mid-stream persist path production always runs;
+ * a ticking clock runs the same path and lands on the same instants every run.
+ * Timers stay real so the periodic heartbeat and the stall watchdog behave.
+ *
+ * The live posture (#1097's live-run gate): a `CURSOR_API_KEY`-gated live
+ * instrument keeps all three substitutions above — the real `Context`, the
+ * record behind the client, the temp environment — and drops only the
+ * harness's SDK double, so the REAL activity runs against the REAL vendor SDK
+ * with everything the activity persists still readable from the record.
+ * Two things differ from a hermetic run and both are the caller's explicit
+ * choice: no `ScriptedClock` is installed (the real SDK is not ticked, and a
+ * frozen clock would skip the persist cadence production runs), and the
+ * environment may name an `eventRecordingDir` so the run leaves a recording.
+ * The harness's driver names the entry (`beginLiveCursorScenario`).
+ *
+ * Not in scope: this module never edits a production module and never
+ * normalizes output. If a golden is not byte-stable, the volatile source is
+ * controlled at its origin or the surprise is escalated — never redacted here.
+ */
+import { CancelledFailure } from "@temporalio/activity";
+import { type Run, type RunStatus } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import { type TurnRows } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import { RunControlSignal, RunPhase } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import { type Session } from "@stigmer/apis/ai/stigmer/agentic/session/v1/api_pb";
+import { type SessionEvent } from "@stigmer/apis/ai/stigmer/agentic/session/v1/event_pb";
+import { type SessionEventPreview } from "@stigmer/apis/ai/stigmer/agentic/session/v1/io_pb";
+import type { Agent } from "@stigmer/apis/ai/stigmer/agentic/agent/v1/api_pb";
+import type { Skill } from "@stigmer/apis/ai/stigmer/agentic/skill/v1/api_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import { type FileReviewVerdicts } from "./file-review-projection.js";
+import type { ToolCall } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import { ApprovalAction } from "../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+/** A status write as its golden holds it (`<name>.status.json`): the status fields alone. */
+export declare function statusGolden(status: RunStatus): string;
+/** The rows a write was made from, as their golden holds them (`<name>.rows.json`). */
+export declare function rowsGolden(rows: TurnRows): string;
+/** The rows golden beside a status golden: `<name>.status.json` becomes `<name>.rows.json`. */
+export declare function rowsGoldenPath(statusGoldenPath: string): string;
+/**
+ * The three resources the activity's blueprint reads (the execution, the
+ * session its target names, and the agent its status stamps at
+ * `agent_id` / `agent_version_hash`, read as that version) plus the status
+ * the server would hold. A record for the built-in assistant (the stamp
+ * names no agent) has no agent: the blueprint must stop at the session, so
+ * the client REFUSES every agent read instead of answering an empty
+ * message.
+ */
+export interface ExecutionRecordInput {
+    readonly execution: Run;
+    readonly session: Session;
+    readonly agent: Agent | undefined;
+    /**
+     * What `UpdateStatus` answers for each FULL status write — the platform's
+     * STOP lever (`RunControlSignal`), decided by the control plane per
+     * write and read by the harness stream loop on its mid-stream persist.
+     * Evaluated AFTER the write lands, on the snapshot just persisted and the
+     * rows it was made from, so a policy can key on the transcript ("stop once
+     * the first assistant message is in"). Defaults to UNSPECIFIED: keep going.
+     */
+    readonly controlSignal?: (status: RunStatus, rows: TurnRows) => RunControlSignal;
+    /** The skills the control plane holds, answered by slug; any other reference is NotFound. */
+    readonly skills?: readonly Skill[];
+    /**
+     * The saved agents the record's agent lists as subagents, answered by
+     * reference (slug and pinned version: each one's `status.version_hash`);
+     * any other reference is NotFound.
+     */
+    readonly subagents?: readonly Agent[];
+}
+export declare class ExecutionRecord {
+    readonly execution: Run;
+    readonly session: Session;
+    readonly agent: Agent | undefined;
+    private readonly controlSignal;
+    private readonly skills;
+    private readonly subagents;
+    /** Every `updateStatus` payload, in order, snapshotted at write time. */
+    readonly persisted: RunStatus[];
+    /**
+     * The rows each `updateStatus` payload was made from, one per entry of
+     * {@link persisted} (an empty `TurnRows` for a write that read none, a
+     * setup-progress report).
+     */
+    readonly persistedRows: TurnRows[];
+    /** Fired after every full-status `applyStatusUpdate`; {@link whenToolCallsSettled} subscribes here. */
+    private readonly persistListeners;
+    /** Setup-progress labels reported before the stream started, in order. */
+    readonly setupProgress: string[];
+    /** Every `bindHarnessState` call, in order (the `harness_state_id` write-back). */
+    readonly harnessBinds: {
+        readonly runId: string;
+        readonly harnessStateId: string;
+    }[];
+    /** The session's event log as the runner appended it, in order (one entry per distinct id). */
+    readonly sessionEvents: SessionEvent[];
+    /** Every preview the runner sent, in order. */
+    readonly sessionPreviews: SessionEventPreview[];
+    /** Ids the runner sent again although the log held them: a resumed turn that forgot what it wrote. */
+    readonly resentEventIds: string[];
+    /** Every append the log refused, by its reason: a runner defect the emitter would drop silently. */
+    readonly refusedAppends: string[];
+    /** The reconcile turn {@link startReconcileTurn} created, once it has; its status is its own. */
+    reconcileRun: Run | undefined;
+    /** Every status the reconcile turn's runner wrote, in order. */
+    readonly reconcilePersisted: RunStatus[];
+    /** The rows each reconcile turn write was made from, one per entry of {@link reconcilePersisted}. */
+    readonly reconcilePersistedRows: TurnRows[];
+    constructor(input: ExecutionRecordInput);
+    get executionId(): string;
+    /** The status the server would currently hold (what `getExecution` returns). */
+    get status(): RunStatus | undefined;
+    /** The last FULL status written (phase set), or undefined if none yet. */
+    get lastFullStatus(): RunStatus | undefined;
+    /** The rows the last FULL status was made from, or undefined if none yet. */
+    get lastFullRows(): TurnRows | undefined;
+    /** The rows the latest write that read any was made from: the runner's rows as the log last saw them. */
+    get rows(): TurnRows | undefined;
+    /** The rows `status` (an entry of {@link persisted} or {@link reconcilePersisted}) was made from. */
+    rowsOf(status: RunStatus): TurnRows;
+    /**
+     * The ORDERED, DISTINCT phases the activity persisted — the deterministic
+     * shape of the persist cadence. The COUNT of persists depends on the
+     * debounce timer and is deliberately not exposed as an assertion surface.
+     */
+    get persistedPhases(): RunPhase[];
+    /** Every tool call on the latest rows (top-level messages), in order. */
+    toolCalls(): ToolCall[];
+    /**
+     * Resolves once every one of `ids` is a SETTLED row (not RUNNING) in a status
+     * the activity has persisted — root messages and every sub-agent's alike.
+     * Resolves at once for an empty list or when they already are.
+     *
+     * This is the barrier a real model gives the runtime for free and a
+     * scripted one does not: a model that takes 300 ms to answer never starts
+     * its next turn before the loop has folded and persisted the tool results
+     * it is answering, while `ScriptedModel` answers instantly and LangGraph's
+     * producer can run a whole turn ahead of the consumer while the consumer
+     * awaits one mid-stream persist (on a git workspace that persist shells out
+     * for `file_change_progress`). The stamps the consumer writes at apply time
+     * then land on either side of the scripted clock's next tick depending on
+     * I/O timing — a golden that flips between `:01` and `:02` on the day. The
+     * driver awaits this before it ticks (`hermetic-deep-agent.ts`), so every
+     * stamp of turn N precedes turn N+1's instant, run after run.
+     *
+     * Why "settled" and not "seen": the row's `completedAt` is stamped when the
+     * tool's end event is applied, and the producer calls the next model turn
+     * right after emitting that event, so a barrier on the row merely existing
+     * would still race the completion stamp. The persist that carries the
+     * settled row always exists: a tool's finish forces one (the builder's
+     * force flag), and a turn followed by another turn always has a tool call.
+     *
+     * Bounded by real time (timers are real under the scripted clock): a
+     * scenario that breaks the fact above — a persist that never carries the
+     * row — fails naming the ids still open, never hangs.
+     */
+    whenToolCallsSettled(ids: readonly string[], timeoutMs?: number): Promise<void>;
+    /**
+     * Resolves once every one of `ids` is a row, in any state, in a status the
+     * activity has persisted. The barrier {@link whenToolCallsSettled} gives
+     * a turn that answers results, for a turn that runs beside a call still
+     * running (a sub-agent's first turn, inside its parent's call); bounded
+     * the same way.
+     */
+    whenToolCallsSeen(ids: readonly string[], timeoutMs?: number): Promise<void>;
+    /** The ids of every row not RUNNING in the latest rows, across the root and every sub-agent transcript. */
+    private settledToolCallIds;
+    /**
+     * What a turn recorded on an older runner left on the server, restored in
+     * one act: the events its session event emitter wrote for its rows into
+     * the log (`harness/events/emitter.ts`, the terminal write), then the
+     * status it persisted. A resumed turn learns from the log that the run's
+     * engine already worked (`turn-context.ts` `runWroteEngineEvents`) and
+     * which calls it asked and still waits on (`transcript/resume-seed.ts`), so a status
+     * restored without its events would read as a first turn.
+     */
+    restorePausedTurn(rows: TurnRows, status: RunStatus): Promise<void>;
+    /** The tool calls currently paused for a decision. */
+    waitingToolCalls(): ToolCall[];
+    /**
+     * What the server's answer core does when a person answers the calls that
+     * asked (`confirmToolUse`, `grantPermission`): append the answer to the
+     * session's log (`approval-log.ts`). Nothing is stamped on any row: the
+     * resumed turn seeds its asks from the log and copies each answer onto its
+     * row (`harness/transcript/resume-seed.ts`, `harness/approval-answers.ts`), so a kit
+     * that answered on the row would prove nothing. This is the ONE place a
+     * test answers, and the call stays waiting until the resumed turn runs the
+     * tool, exactly as in production. `onlyId` answers one of several calls
+     * paused in the same round and leaves the rest waiting, as a person
+     * answering them one at a time does; a deny may carry `denyMessage`, the
+     * reason the model reads. `_decidedAt` is the instant a person answered,
+     * which no event carries.
+     */
+    decideWaitingToolCalls(action: ApprovalAction, _decidedAt: string, onlyId?: string, denyMessage?: string): number;
+    /**
+     * What the server's decision core does between invocations: every change
+     * of every captured set on the held file record the log holds no decision
+     * for gets a per-file verdict, written into the log as
+     * `stigmer.file_review.decided` (`file-review-projection.ts`). The runner
+     * authors the record; the decisions are the log's — so this is the ONE
+     * place a test writes them. Returns how many decisions were written.
+     */
+    decideCapturedFileChanges(verdicts: FileReviewVerdicts, _decidedAt: string): number;
+    /**
+     * The reconcile turn the decision core starts for an Undo on a finished
+     * run: a second run of this session with `reconcile_file_review` set and no
+     * message, created as the server's create path would (in progress, nothing
+     * on its status). The client answers it by its id from then on. Returns its
+     * id.
+     */
+    startReconcileTurn(runId?: string): string;
+    /** The reconcile turn's last full status (phase set), or undefined if it wrote none. */
+    get reconcileFinalStatus(): RunStatus | undefined;
+    /** The run a request names: the reconcile turn's id answers it, any other this execution. */
+    private runNamed;
+    /** A write to the reconcile turn: kept as written, its phase held when the write carries none. */
+    private applyReconcileStatus;
+    /**
+     * The server's typed read of the log (`listEvents` with `types` and
+     * `order`), newest first when asked: one page holds it all. Only the types
+     * the runner asks for are named; any other event matches no type.
+     */
+    listSessionEventsPage(types: readonly string[], order: "asc" | "desc"): SessionEvent[];
+    /**
+     * Apply one `UpdateStatus` write and answer the control signal the server
+     * would. The rows it was made from are the ones the emitter last read for
+     * this run, or `written` when a test hands them in itself. A write with no phase never carries a signal (the runner ignores
+     * the response there). It is a setup-progress report, or the write an
+     * orchestrator stop settles (the runtime writes no phase for it; the
+     * workflow does, stigmer#980): the server's merge applies it and leaves
+     * the phase to its writers, so the double keeps the held phase.
+     */
+    applyStatusUpdate(status: RunStatus, written?: TurnRows): RunControlSignal;
+    /** The server's append rules over the modelled log (the class header). */
+    appendSessionEvents(runId: string, events: readonly SessionEvent[], previews: readonly SessionEventPreview[]): void;
+    /**
+     * The modelled log as a golden: one protobuf JSON object per event, with
+     * its envelope's thread, in append order. What the runner sent, before
+     * the server stamps a seq or an accepted time. Throws when the runner
+     * resent an id the log held or had an append refused, so every golden
+     * also proves a resumed turn writes only what is new and that nothing
+     * landed after the run finished.
+     */
+    eventsGolden(): string;
+    /** The runner's write with the server-stamped fields of the held status carried over, and its file record upserted. */
+    private keepServerStamp;
+    /**
+     * The control-plane client the activity sees: every read answers from this
+     * record; every write lands in it. Reads the activity makes for optional
+     * facets (the run's values, channels, skills) answer the everyday shape —
+     * no values (a run whose declarations hold none), no channels, no scoped
+     * token (the OSS/local posture) — so a scenario opts INTO a facet by
+     * overriding.
+     */
+    client(overrides?: Partial<StigmerClient>): StigmerClient;
+}
+/**
+ * Bind the client the mocked `StigmerClient` constructor hands out for the
+ * current run. Called by the harness driver immediately before invoking the
+ * activity factory (`createCursorActivities(config)` constructs its client
+ * inside the factory, so the bind must precede the factory call).
+ */
+export declare function bindHermeticClient(client: StigmerClient): void;
+/**
+ * The factory a test passes to `vi.mock(".../client/stigmer-client.js", ...)`.
+ * `vi.mock` is hoisted and must appear in the test file itself; the factory can
+ * `await import()` this module. Usage:
+ *
+ * ```ts
+ * vi.mock("../../../../client/stigmer-client.js", async () =>
+ *   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
+ * );
+ * ```
+ */
+export declare function hermeticStigmerClientModule(): {
+    StigmerClient: new () => StigmerClient;
+};
+export interface HermeticEnvironmentOptions {
+    /**
+     * Where the Cursor event recorder writes this run's raw SDK recording
+     * (`<dir>/<executionId>.cursor-events.jsonl`). Named ONLY by a live
+     * instrument, whose point is a recording of the real SDK; a hermetic
+     * scenario leaves it unset and the variable is cleared for the run.
+     */
+    readonly eventRecordingDir?: string;
+}
+export interface HermeticEnvironment {
+    /** The temp `HOME` (the runner's `~/.stigmer` lands under it). */
+    readonly home: string;
+    /** The temp workspace root (`config.workspaceRootDir`). */
+    readonly workspaceRootDir: string;
+    /** The temp local artifact store (`LOCAL_ARTIFACT_PATH`). */
+    readonly artifactPath: string;
+    /** Restore every env var and remove the temp tree. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Create the temp tree and pin the env vars. Call once per test FILE (in
+ * `beforeAll`) — the fingerprint secret is memoized per process on first use,
+ * and vitest isolates files in forks, so per-file is the natural unit.
+ */
+export declare function createHermeticEnvironment(options?: HermeticEnvironmentOptions): HermeticEnvironment;
+/**
+ * A deterministic, TICKING clock: `Date` AND `performance` are faked and
+ * advance together; timers stay real (the periodic heartbeat, the stall
+ * watchdog, `withTimeout` all need them). The harness double calls
+ * {@link ScriptedClock.tick} once per script step, so every clock-based
+ * decision on the activity path — status timestamps, the builder's row
+ * instants, cache TTLs (`Date`); the streaming scheduler's persist cadence
+ * (`performance.now()`) — sees the same instants run after run and runs the
+ * same branches production runs.
+ *
+ * Why both (since #1096): until then only `Date` was faked, so the
+ * scheduler paced persists on REAL elapsed time and `fileChangeProgress`,
+ * which rides persists, could gain or lose a capture under load — a golden
+ * flake seen twice while the native adapter moved onto the runtime. One clock,
+ * two faces: `tick` advances through
+ * the fake clock's own `tick` (`vi.advanceTimersByTime`), which moves both
+ * `Date` and `performance.now()`; `vi.setSystemTime` would move `Date` alone
+ * (fake-timers keeps `performance` monotonic across a system-time jump), so
+ * only {@link reset} uses it — rewinding `Date` to the epoch for a second
+ * scenario while `performance` stays monotonic, which is harmless because
+ * every turn constructs its scheduler fresh and measures from its own start.
+ *
+ * Faking `performance` replaces the whole global (`now`, a `timeOrigin` at
+ * the epoch, every other method a no-op); nothing on the activity path reads
+ * more than `now`, and a module importing from `node:perf_hooks` would bypass
+ * the fake (none under `src/` does).
+ */
+export declare class ScriptedClock {
+    /** A fixed epoch: 2026-01-01T00:00:00.000Z. Chosen for readability in goldens. */
+    static readonly EPOCH_MS: number;
+    /** One second per step — well under any stall or cache horizon. */
+    static readonly STEP_MS = 1000;
+    private nowMs;
+    install(): void;
+    tick(ms?: number): void;
+    /** Back to the epoch — for a second scenario in the same file. `Date` rewinds; `performance` stays monotonic (see the header). */
+    reset(): void;
+    uninstall(): void;
+}
+/** How an activity invocation ended: the return value or the error it threw. */
+export type ActivityOutcome = {
+    readonly kind: "returned";
+    readonly value: unknown;
+} | {
+    readonly kind: "threw";
+    readonly error: unknown;
+};
+export interface ActivityInvocation {
+    readonly outcome: ActivityOutcome;
+    /** Heartbeat details the activity reported, in order. */
+    readonly heartbeats: unknown[];
+    /** The `taskQueue` the invocation ran on (the shutdown signal is keyed by it). */
+    readonly taskQueue: string;
+}
+/**
+ * Handles a scenario uses to interrupt the invocation FROM A SCRIPT STEP —
+ * never from a timer. `cancel()` aborts the activity's `cancellationSignal`
+ * (a user pause, as the workflow delivers it). `signalWorkerShutdown()` aborts
+ * the queue's shutdown signal first, which the activity reads to tell a worker
+ * drain from a user pause (`classifyTurnInterruption`). `cancelTimedOut()`
+ * aborts it with Temporal's own reason, `TIMED_OUT` (a heartbeat timeout),
+ * the cancellation the turn reads as infrastructure.
+ */
+export interface InvocationControls {
+    cancel(): void;
+    signalWorkerShutdown(): void;
+    cancelTimedOut(): void;
+}
+export interface RunActivityOptions {
+    readonly taskQueue?: string;
+    /**
+     * Receives the invocation's controls before the activity starts, so a
+     * scenario can hand them to the harness double's `effect` steps.
+     */
+    readonly onControls?: (controls: InvocationControls) => void;
+}
+/**
+ * Run one activity function under a fresh `MockActivityEnvironment` and
+ * capture how it ended. `CancelledFailure` is caught like any other throw and
+ * reported as `{ kind: "threw" }` — the throw-vs-return table is the thing
+ * under test, so the driver never interprets it.
+ */
+export declare function runActivityHermetically<A extends unknown[]>(activity: (...args: A) => Promise<unknown>, args: A, options?: RunActivityOptions): Promise<ActivityInvocation>;
+/** True when the outcome is a thrown Temporal `CancelledFailure`. */
+export declare function threwCancelledFailure(outcome: ActivityOutcome): outcome is {
+    kind: "threw";
+    error: CancelledFailure;
+};