@stigmer/runner 3.14.0 → 3.15.0

package/dist/harness/capabilities.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Harness capability flags — the facts about an engine the runtime branches
+ * on, declared once per adapter and read nowhere else.
+ *
+ * The runtime is written against the flags, not against harness names: a
+ * phase that must differ per engine asks "does this harness accept a system
+ * prompt?" rather than "is this Cursor?". That is what keeps a new harness a
+ * registry row and an SDK slice instead of a new branch in every phase.
+ * Every row of the matrix below is either a flag here or internal to one
+ * adapter; nothing in it needed a third kind of thing.
+ *
+ * The matrix the contract was designed against (2026-09; Claude and Codex are
+ * the surveyed SDKs, not built harnesses):
+ *
+ * | Capability        | Native (LangGraph)          | Cursor (`@cursor/sdk`)                  | Claude (`@anthropic-ai/claude-agent-sdk`)     | Codex (`@openai/codex-sdk`)                    |
+ * |-------------------|-----------------------------|-----------------------------------------|-----------------------------------------------|------------------------------------------------|
+ * | `pausePrimitive`  | `interrupt` (checkpoint)    | `deny-and-retry` (hook, ledger, cancel) | `callback` (`canUseTool`, in-process)         | `none` (approvalPolicy only) → capture-only    |
+ * | `stateIdSource`   | `deterministic` (thread id) | `engine-minted` (agent id)              | either (caller-supplied or minted)            | `engine-minted` (thread id)                    |
+ * | `systemPrompt`    | yes                         | no (rides the first message)            | yes                                           | no (`AGENTS.md` or first message)              |
+ * | `subAgents`       | yes (compiled sub-graphs)   | yes (`agents` option)                   | yes (`AgentDefinition`)                       | no                                             |
+ * | `toolRestriction` | yes (tool list)             | no (the hook enforces)                  | yes (`disallowedTools`, `tools`)              | per-server config                              |
+ * | `visionProfile`   | PNG, JPEG, WebP, GIF        | PNG, JPEG (transport re-sniffs)         | (surveyed later)                              | (surveyed later)                               |
+ * | `fileReview`      | `deep-agent`, no excludes   | `cursor`, `.cursor/hooks.json` excluded | (surveyed later)                              | (surveyed later)                               |
+ *
+ * Adapter-internal, deliberately NOT flags: how MCP servers are bound, how
+ * metering is routed, how the cost cap is applied inside the engine, how a
+ * run is cancelled. Those differ per engine but the runtime never needs to
+ * know.
+ *
+ * Two flags matter to the contract kit directly: `pausePrimitive` (the kit
+ * proves the two real primitives are indistinguishable above the contract
+ * line — both end a turn `awaiting_approval` and both take the decisions on
+ * reinvocation) and `stateIdSource` (an `engine-minted` adapter must bind its
+ * id before its first persist; a `deterministic` one must never bind).
+ */
+import type { VisionProfile } from "../shared/attachment-vision.js";
+/**
+ * How the engine can be made to stop before a gated side effect.
+ *
+ *  - `interrupt`: the engine checkpoints and stops at the gate (LangGraph
+ *    `interrupt`); the adapter resumes it with the decisions.
+ *  - `deny-and-retry`: an out-of-process hook denies the tool, the adapter
+ *    records the denial, cancels the run, and re-runs with grants on the next
+ *    invocation.
+ *  - `callback`: an in-process callback decides per tool; the runtime still
+ *    returns `awaiting_approval` and reinvokes, so the adapter answers the
+ *    callback with "deny, stop" and resumes with the decisions.
+ *  - `none`: the engine offers no gate; the runtime confines it to
+ *    capture-only work (a read-only sandbox) and gated actions never reach
+ *    the engine.
+ */
+export type PausePrimitive = "interrupt" | "deny-and-retry" | "callback" | "none";
+/**
+ * Who mints the engine's state id. `deterministic`: the runtime derives it
+ * from the session before the first turn (`EnsureThread`), so it is known
+ * before any engine exists. `engine-minted`: the engine issues it on first
+ * use and the adapter must hand it to the runtime at once
+ * (`TurnSink.bindHarnessState`) so a crash mid-turn still resumes.
+ */
+export type StateIdSource = "deterministic" | "engine-minted";
+/**
+ * The two facts the runtime's file-review reconcile needs from the harness
+ * and cannot know: the id the projection reads from the BASELINE payload
+ * (`shared/filereview/capture.ts` `applyCaptureDecisions`), and the
+ * workspace-relative paths the harness writes into the repo that a turn's
+ * diff must never show (Cursor's transient `.cursor/hooks.json`). Declared
+ * once per adapter, read by `turn-context.ts` (ruled Q-M2-6 as an argument,
+ * homed here at M3).
+ */
+export interface FileReviewIdentity {
+    readonly harnessId: string;
+    readonly excludePaths: readonly string[];
+}
+export interface HarnessCapabilities {
+    readonly pausePrimitive: PausePrimitive;
+    readonly stateIdSource: StateIdSource;
+    /** The engine accepts a system prompt; otherwise instructions ride the first user message. */
+    readonly systemPrompt: boolean;
+    /** The engine runs delegated sub-agents from a definition map. */
+    readonly subAgents: boolean;
+    /** The engine can hide or deny tools by name; otherwise the gate enforces `enabledTools`. */
+    readonly toolRestriction: boolean;
+    /** Which image types the engine can display inline; the runtime degrades the rest before the turn. */
+    readonly visionProfile: VisionProfile;
+    /** How the harness's captured file changes are identified and what its own repo writes are excluded from a diff. */
+    readonly fileReview: FileReviewIdentity;
+}

package/dist/harness/capabilities.js

@@ -0,0 +1,37 @@
+/**
+ * Harness capability flags — the facts about an engine the runtime branches
+ * on, declared once per adapter and read nowhere else.
+ *
+ * The runtime is written against the flags, not against harness names: a
+ * phase that must differ per engine asks "does this harness accept a system
+ * prompt?" rather than "is this Cursor?". That is what keeps a new harness a
+ * registry row and an SDK slice instead of a new branch in every phase.
+ * Every row of the matrix below is either a flag here or internal to one
+ * adapter; nothing in it needed a third kind of thing.
+ *
+ * The matrix the contract was designed against (2026-09; Claude and Codex are
+ * the surveyed SDKs, not built harnesses):
+ *
+ * | Capability        | Native (LangGraph)          | Cursor (`@cursor/sdk`)                  | Claude (`@anthropic-ai/claude-agent-sdk`)     | Codex (`@openai/codex-sdk`)                    |
+ * |-------------------|-----------------------------|-----------------------------------------|-----------------------------------------------|------------------------------------------------|
+ * | `pausePrimitive`  | `interrupt` (checkpoint)    | `deny-and-retry` (hook, ledger, cancel) | `callback` (`canUseTool`, in-process)         | `none` (approvalPolicy only) → capture-only    |
+ * | `stateIdSource`   | `deterministic` (thread id) | `engine-minted` (agent id)              | either (caller-supplied or minted)            | `engine-minted` (thread id)                    |
+ * | `systemPrompt`    | yes                         | no (rides the first message)            | yes                                           | no (`AGENTS.md` or first message)              |
+ * | `subAgents`       | yes (compiled sub-graphs)   | yes (`agents` option)                   | yes (`AgentDefinition`)                       | no                                             |
+ * | `toolRestriction` | yes (tool list)             | no (the hook enforces)                  | yes (`disallowedTools`, `tools`)              | per-server config                              |
+ * | `visionProfile`   | PNG, JPEG, WebP, GIF        | PNG, JPEG (transport re-sniffs)         | (surveyed later)                              | (surveyed later)                               |
+ * | `fileReview`      | `deep-agent`, no excludes   | `cursor`, `.cursor/hooks.json` excluded | (surveyed later)                              | (surveyed later)                               |
+ *
+ * Adapter-internal, deliberately NOT flags: how MCP servers are bound, how
+ * metering is routed, how the cost cap is applied inside the engine, how a
+ * run is cancelled. Those differ per engine but the runtime never needs to
+ * know.
+ *
+ * Two flags matter to the contract kit directly: `pausePrimitive` (the kit
+ * proves the two real primitives are indistinguishable above the contract
+ * line — both end a turn `awaiting_approval` and both take the decisions on
+ * reinvocation) and `stateIdSource` (an `engine-minted` adapter must bind its
+ * id before its first persist; a `deterministic` one must never bind).
+ */
+export {};
+//# sourceMappingURL=capabilities.js.map

package/dist/harness/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/harness/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}

package/dist/harness/persist-chokepoint.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import type { ToolOutputOffloadContext } from "../shared/status-offload.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 declare class PersistChokepoint {
+    private readonly deps;
+    private inFlight;
+    private followUp;
+    constructor(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>;
+    /**
+     * 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.
+     */
+    write(): Promise<void>;
+}

package/dist/harness/persist-chokepoint.js

@@ -0,0 +1,88 @@
+/**
+ * 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 { ExecutionControlSignal } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+import { persistStatus } from "../shared/status.js";
+import { withholdSecretContentFromMessages } from "../shared/tool-row.js";
+export class PersistChokepoint {
+    deps;
+    inFlight;
+    followUp;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 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() {
+        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() {
+        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();
+        }
+    }
+}
+//# sourceMappingURL=persist-chokepoint.js.map

package/dist/harness/persist-chokepoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-chokepoint.js","sourceRoot":"","sources":["../../src/harness/persist-chokepoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAC;AACtG,OAAO,EAAE,2BAA2B,EAAE,MAAM,+DAA+D,CAAC;AAG5G,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,iCAAiC,EAAE,MAAM,uBAAuB,CAAC;AAqB1E,MAAM,OAAO,iBAAiB;IAIC;IAHrB,QAAQ,CAA4B;IACpC,QAAQ,CAA4B;IAE5C,YAA6B,IAA2B;QAA3B,SAAI,GAAJ,IAAI,CAAuB;IAAG,CAAC;IAE5D;;;;OAIG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;gBACtC,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;YAC5B,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;YACtB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE;gBACtC,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC;gBAC1B,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;YACxB,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC;QACtE,iCAAiC,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAC9E,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,KAAK,EAAE,QAAQ,EAAE,CAAC;YACpB,MAAM,CAAC,cAAc,GAAG,MAAM,CAAC,2BAA2B,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChF,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAC7E,SAAS,EAAE,CAAC;QACZ,IAAI,MAAM,KAAK,sBAAsB,CAAC,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;CACF"}

package/dist/harness/registry.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The harness registry — the lifecycle fan-out over the adapters a worker
+ * runs, and the byte-pinned binding from harness to Temporal activity name.
+ *
+ * Plain functions over an `adapters` argument, no module state and no DI
+ * (the composition roots are staged plain functions; a missing adapter is a
+ * compile error or a loud boot throw, never a silent no-op). ORDER IS
+ * LOAD-BEARING: `bootHarnesses` runs adapters in declaration order because
+ * the Cursor harness's interceptors must patch `node:http2` before anything
+ * dials the control plane, and `shutdownHarnesses` runs them in reverse so
+ * what was set up last is torn down first.
+ *
+ * Error posture, ruled at the entry's gate (Q-S1-10):
+ *  - Boot validates the whole table BEFORE booting anything (a duplicate name
+ *    is a configuration defect, and a half-booted worker is the worst state to
+ *    discover it in), then fails fast at the first adapter that rejects. A
+ *    worker that cannot boot a harness must not start.
+ *  - Shutdown and session release CONTINUE past a failing adapter and throw
+ *    one `AggregateError` at the end naming each failure, so one bad teardown
+ *    never leaks the others' resources.
+ *
+ * `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 ExecuteActivityInput } from "../shared/activity-input.js";
+import type { HarnessAdapter } from "./types.js";
+/** The harnesses the control plane can dispatch to, as the registry knows them. */
+export type HarnessName = "cursor" | "deep-agent";
+/**
+ * Byte-pinned Temporal activity names, one per harness. The server side of
+ * the pin is `stigmer-server/src/temporal/agentexecution/names.ts`
+ * (`EXECUTE_CURSOR_ACTIVITY_NAME`, `EXECUTE_DEEP_AGENT_ACTIVITY_NAME`); the
+ * two must stay byte-identical or the workflow schedules an activity no
+ * worker registers. Never "cleaned up".
+ */
+export declare const HARNESS_ACTIVITY_NAMES: {
+    readonly cursor: "ExecuteCursor";
+    readonly "deep-agent": "ExecuteDeepAgent";
+};
+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 declare function adaptersOf(rows: readonly HarnessRow[]): HarnessAdapter[];
+/**
+ * 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 declare function createHarnessActivities(rows: readonly HarnessRow[], config: Config): Promise<Partial<Record<HarnessActivityName, HarnessActivity>>>;
+/**
+ * Boot every adapter in declaration order, one at a time, awaiting each. The
+ * table is validated first; the first rejection stops the boot and propagates
+ * (adapters after it are never booted; adapters before it stay booted for the
+ * caller's shutdown path to release).
+ */
+export declare function bootHarnesses(adapters: readonly HarnessAdapter[], config: Config): Promise<void>;
+/**
+ * Shut every adapter down in reverse declaration order, continuing past
+ * failures. Rejects with one `AggregateError` carrying every failure once all
+ * adapters have been given their chance.
+ */
+export declare function shutdownHarnesses(adapters: readonly HarnessAdapter[]): Promise<void>;
+/**
+ * Tell every adapter the session is done on this host, in declaration order,
+ * continuing past failures. An adapter that parks nothing per session
+ * resolves as a no-op; the registry does not know which do.
+ */
+export declare function releaseHarnessSession(adapters: readonly HarnessAdapter[], sessionId: string): Promise<void>;

package/dist/harness/registry.js

@@ -0,0 +1,168 @@
+/**
+ * The harness registry — the lifecycle fan-out over the adapters a worker
+ * runs, and the byte-pinned binding from harness to Temporal activity name.
+ *
+ * Plain functions over an `adapters` argument, no module state and no DI
+ * (the composition roots are staged plain functions; a missing adapter is a
+ * compile error or a loud boot throw, never a silent no-op). ORDER IS
+ * LOAD-BEARING: `bootHarnesses` runs adapters in declaration order because
+ * the Cursor harness's interceptors must patch `node:http2` before anything
+ * dials the control plane, and `shutdownHarnesses` runs them in reverse so
+ * what was set up last is torn down first.
+ *
+ * Error posture, ruled at the entry's gate (Q-S1-10):
+ *  - Boot validates the whole table BEFORE booting anything (a duplicate name
+ *    is a configuration defect, and a half-booted worker is the worst state to
+ *    discover it in), then fails fast at the first adapter that rejects. A
+ *    worker that cannot boot a harness must not start.
+ *  - Shutdown and session release CONTINUE past a failing adapter and throw
+ *    one `AggregateError` at the end naming each failure, so one bad teardown
+ *    never leaks the others' resources.
+ *
+ * `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 { activityFinished, activityStarted } from "../idle-watchdog.js";
+import { normalizeActivityInput } from "../shared/activity-input.js";
+import { runTurnActivity } from "./run-turn.js";
+/**
+ * Byte-pinned Temporal activity names, one per harness. The server side of
+ * the pin is `stigmer-server/src/temporal/agentexecution/names.ts`
+ * (`EXECUTE_CURSOR_ACTIVITY_NAME`, `EXECUTE_DEEP_AGENT_ACTIVITY_NAME`); the
+ * two must stay byte-identical or the workflow schedules an activity no
+ * worker registers. Never "cleaned up".
+ */
+export const HARNESS_ACTIVITY_NAMES = {
+    cursor: "ExecuteCursor",
+    "deep-agent": "ExecuteDeepAgent",
+};
+/** The adapters of a row list, for the lifecycle functions below. */
+export function adaptersOf(rows) {
+    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, config) {
+    const { StigmerClient } = await import("../client/stigmer-client.js");
+    const client = new StigmerClient({
+        endpoint: config.stigmerBackendEndpoint,
+        token: config.stigmerToken,
+        tokenRef: config.stigmerTokenRef,
+        runnerTokenRef: config.stigmerRunnerTokenRef,
+    });
+    const activities = {};
+    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
+ * would be indistinguishable in every log line and kit message.
+ */
+function assertUniqueNames(adapters) {
+    const seen = new Set();
+    for (const adapter of adapters) {
+        if (seen.has(adapter.name)) {
+            throw new Error(`harness registry: duplicate adapter name '${adapter.name}'; every adapter must have a unique name`);
+        }
+        seen.add(adapter.name);
+    }
+}
+/**
+ * Boot every adapter in declaration order, one at a time, awaiting each. The
+ * table is validated first; the first rejection stops the boot and propagates
+ * (adapters after it are never booted; adapters before it stay booted for the
+ * caller's shutdown path to release).
+ */
+export async function bootHarnesses(adapters, config) {
+    assertUniqueNames(adapters);
+    for (const adapter of adapters) {
+        await adapter.boot(config);
+    }
+}
+/**
+ * Shut every adapter down in reverse declaration order, continuing past
+ * failures. Rejects with one `AggregateError` carrying every failure once all
+ * adapters have been given their chance.
+ */
+export async function shutdownHarnesses(adapters) {
+    const failures = [];
+    for (const adapter of [...adapters].reverse()) {
+        try {
+            await adapter.shutdown();
+        }
+        catch (err) {
+            failures.push(describeFailure(adapter, "shutdown", err));
+        }
+    }
+    throwIfAny(failures, "harness registry: shutdown failed for one or more adapters");
+}
+/**
+ * Tell every adapter the session is done on this host, in declaration order,
+ * continuing past failures. An adapter that parks nothing per session
+ * resolves as a no-op; the registry does not know which do.
+ */
+export async function releaseHarnessSession(adapters, sessionId) {
+    const failures = [];
+    for (const adapter of adapters) {
+        try {
+            await adapter.releaseSession(sessionId);
+        }
+        catch (err) {
+            failures.push(describeFailure(adapter, `releaseSession('${sessionId}')`, err));
+        }
+    }
+    throwIfAny(failures, `harness registry: releaseSession('${sessionId}') failed for one or more adapters`);
+}
+function describeFailure(adapter, call, err) {
+    const cause = err instanceof Error ? err : new Error(String(err));
+    return new Error(`${adapter.name}: ${call} rejected: ${cause.message}`, { cause });
+}
+function throwIfAny(failures, message) {
+    if (failures.length > 0)
+        throw new AggregateError(failures, `${message}: ${failures.map((f) => f.message).join("; ")}`);
+}
+//# sourceMappingURL=registry.js.map

package/dist/harness/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/harness/registry.ts"],"names":[],"mappings":"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"}

package/dist/harness/run-turn.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The turn runtime — one agent turn as a Temporal activity, written once for
+ * every harness, with the engine behind the adapter contract (`types.ts`).
+ *
+ * What runs here and nowhere else: the activity's identity and its
+ * execution-scoped context; the status and the single persist chokepoint;
+ * the periodic heartbeat; the stop controller and its four producers (the
+ * stall watchdog, the cost cap, the platform STOP, Temporal's cancellation);
+ * the resolution phases (`turn-context.ts`) composed into the `TurnInput`;
+ * the sink the adapter is handed; the terminal table (`terminal-table.ts`)
+ * with its throw-vs-return rule, applied by `settleWith`, the one writer of
+ * a terminal; the completion epilogue (final text,
+ * structured output, plan artifact, write-back); the finally that releases
+ * the workspace lock last. The adapter owns its SDK slice inside `runTurn`
+ * and its own teardown inside its own `finally`, which runs BEFORE this
+ * module's (the gate is torn down before the lock is released, as it always
+ * was).
+ *
+ * Shape: one activity per registry row (`createHarnessActivities`), each a
+ * closure over the adapter, the activity's byte-pinned name and one shared
+ * `StigmerClient`; `runTurnActivity` is the body. Every `console` line here
+ * names the activity (`ExecuteCursor started: …`) so the log reads as it did
+ * before the extraction, and never a harness literal — the harness is a
+ * registry row, not a branch.
+ *
+ * Extracted from `activities/execute-cursor/index.ts` `executeCursorInner`
+ * (S2 M3; the milestone log in stigmer-cloud
+ * `_projects/2026-09/20260911.03.sp.turn-runtime-extraction/` has every
+ * ruling). Its twelve resolution phases came out at M2; what came out here is
+ * everything between them and after the engine: the seventeen hermetic
+ * goldens under `execute-cursor/__tests__/hermetic/` pin the result byte
+ * for byte, and `__tests__/run-turn.test.ts` proves the table against the
+ * scripted fake without any engine at all.
+ */
+import type { Config } from "../config.js";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import type { NormalizedActivityInput } from "../shared/activity-input.js";
+import type { HarnessAdapter } from "./types.js";
+/** What every activity of the registry shares: the adapter it drives, its wire name, and the one client. */
+export interface TurnRuntimeDeps {
+    readonly adapter: HarnessAdapter;
+    readonly activityName: string;
+    readonly client: StigmerClient;
+    readonly config: Config;
+}
+/**
+ * Run one turn: the activity body behind every harness's registry row. Sets
+ * the execution-scoped context for the WHOLE activity (the interceptors stamp
+ * every proxy-bound request from it, and much of that traffic is the
+ * runtime's own: offload, attachments, the epilogue's extraction) and runs
+ * the turn inside it.
+ */
+export declare function runTurnActivity(deps: TurnRuntimeDeps, input: NormalizedActivityInput): Promise<unknown>;