@stigmer/runner 3.14.0-dev.20260910084630 → 3.14.1

package/dist/harness/capabilities.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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)                               |
+ *
+ * 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";
+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;
+}

package/dist/harness/capabilities.js

@@ -0,0 +1,36 @@
+/**
+ * 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)                               |
+ *
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG"}

package/dist/harness/registry.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ *
+ * What is NOT here yet: `createHarnessActivities` (its body is the turn
+ * runtime, which does not exist until the extraction entry) and the table of
+ * real adapters (they exist once the Cursor and native harnesses implement
+ * the contract). Both land with the runtime; no empty table sits on `main`
+ * between the two.
+ *
+ * `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.
+ */
+import type { Config } from "../config.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];
+/**
+ * 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,112 @@
+/**
+ * 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.
+ *
+ * What is NOT here yet: `createHarnessActivities` (its body is the turn
+ * runtime, which does not exist until the extraction entry) and the table of
+ * real adapters (they exist once the Cursor and native harnesses implement
+ * the contract). Both land with the runtime; no empty table sits on `main`
+ * between the two.
+ *
+ * `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.
+ */
+/**
+ * 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",
+};
+/**
+ * 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/types.d.ts

@@ -0,0 +1,268 @@
+/**
+ * The harness adapter contract — the line between what the turn runtime owns
+ * and what a harness owns.
+ *
+ * Stigmer runs an agent turn through one of several engines ("harnesses"):
+ * the native LangGraph deep-agent, the Cursor SDK, and in future the Claude
+ * Agent SDK and the Codex SDK. Everything about a turn that does NOT touch a
+ * vendor SDK — fetching the execution, resolving the blueprint and the
+ * environment, provisioning and locking the workspace, mounting skills,
+ * resolving MCP servers and approval policies, seeding the transcript, the
+ * persist cadence, the stall watchdog, the Temporal heartbeat, pause vs
+ * shutdown, the cost cap, the file-review boundary, the terminal mapping —
+ * is the RUNTIME's, written once. What a harness owns is its SDK slice: how
+ * the engine is created or resumed, how the prompt is placed, how MCP servers
+ * are bound, how the engine is made to stop before a gated side effect, and
+ * how its events become transcript rows. This file is the whole of what a
+ * harness author has to implement; `__test-utils__/harness-contract/` is the
+ * kit every implementation has to pass.
+ *
+ * Every member here is a rename of a function the Cursor loop already injects
+ * (`execute-cursor/turn-stream.ts` `CursorTurnStreamDeps`) or a fact the
+ * runtime cannot read anywhere else. Nothing here is speculative: where the
+ * program's original sketch and the code disagreed, the code won, and the
+ * disagreement was ruled at the entry's gate
+ * (stigmer-cloud `_projects/2026-09/20260911.02.sp.harness-contract-and-kit/`).
+ *
+ * What is deliberately NOT on this contract, and why:
+ *
+ *  - No `dispose()`. One adapter object serves many concurrent turns
+ *    (`maxConcurrentActivities`), so a per-turn teardown method on the
+ *    adapter is a race. The adapter owns its per-turn teardown in its own
+ *    `finally` inside `runTurn` (the Cursor harness already parks its agent
+ *    there).
+ *  - No `isCancelled()`, no `heartbeat(details)`, no `ExecutionStatusWriter`
+ *    base. Each would be a second way of saying something `stopSignal`,
+ *    `recordActivity()` or `requestPersist()` already says, and two writers of
+ *    one fact drift (the native builders' `forceNextUpdate` flag is the same
+ *    fact as a `requestPersist()` call).
+ *  - No `reason` on `interrupted`, no payload on `completed`, no `retryable`
+ *    on `failed`. Every cause of stopping is the runtime's own evidence; the
+ *    final text and structured output are already folded onto the status;
+ *    Temporal never retries a returned activity, so a retryable flag would
+ *    have no reader.
+ *  - No token-rotation hook. `Config.stigmerTokenRef` is the canonical
+ *    mutable ref; an adapter's transport reads it per request.
+ *  - No `TurnInput.status`. The runtime seeds `TurnSink.status` from the
+ *    persisted transcript; a second copy on the input is the drift the
+ *    single-source-of-truth mandate forbids.
+ *
+ * Module shape follows `shared/checkpointer/`: `types.ts`, `capabilities.ts`,
+ * `registry.ts`, no barrel. Nothing production-facing imports this module
+ * until the runtime that consumes it lands (S2 of the program).
+ */
+import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { Config } from "../config.js";
+import type { NormalizedActivityInput } from "../shared/activity-input.js";
+import type { HarnessCapabilities } from "./capabilities.js";
+/**
+ * One harness, as the runtime sees it. ONE adapter object exists per worker
+ * process; it serves every concurrent turn of its harness and holds no
+ * per-turn state (per-turn state lives in the `runTurn` frame). Three
+ * lifetimes meet here — worker (`boot`/`shutdown`), session
+ * (`releaseSession`) and turn (`runTurn`) — because the Cursor harness parks
+ * an engine per SESSION between turns, longer than a turn and shorter than
+ * the worker.
+ *
+ * `name` is a diagnostic identity (log lines, kit messages, the registry's
+ * duplicate check). It is NOT the activity the harness is bound to: the wire
+ * binding is the registry row's (`registry.ts` `HARNESS_ACTIVITY_NAMES`),
+ * so an adapter never declares a byte-pinned wire name and a test double can
+ * implement this interface under its own name.
+ */
+export interface HarnessAdapter {
+    readonly name: string;
+    readonly capabilities: HarnessCapabilities;
+    /**
+     * Worker lifetime, once per process, run by the registry in declaration
+     * order in BOTH composition roots (`runner.ts`, `runner-manager.ts`). Runs
+     * BEFORE bootstrap resolution — the Cursor interceptors must patch
+     * `node:http2` before the control plane is dialled — so `config` carries
+     * no Temporal coordinates yet. Vendor SDKs are imported lazily inside, so a
+     * harness that is not selected costs nothing at boot. A rejection here
+     * fails the worker's boot; a worker that cannot boot a harness must not
+     * start.
+     */
+    boot(config: Config): Promise<void>;
+    /**
+     * Worker lifetime, once per process, after the Temporal worker has drained.
+     * Releases everything the adapter still holds (the Cursor harness closes
+     * every parked agent). Must resolve even when nothing is held.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Session lifetime: the session is done on this host, release anything
+     * parked for it (the Cursor harness: the parked agent, its executor and the
+     * MCP subprocesses the lease pins, #215). Called by the registry from the
+     * manager's `removeSession`. A harness that parks nothing per session
+     * resolves as a no-op and says so in its header. Unknown session ids are a
+     * no-op, never an error: the runtime does not track which host parked what.
+     */
+    releaseSession(sessionId: string): Promise<void>;
+    /**
+     * Turn lifetime: run ONE engine turn against the resolved input, folding
+     * the engine's transcript rows into `sink.status` as they arrive, and
+     * settle with a {@link TurnOutcome}.
+     *
+     * The rules every implementation is held to (the kit's invariants):
+     *
+     *  - Resolves, never rejects. A vendor failure becomes
+     *    `{ kind: "failed", message }` with the user-facing sentence the
+     *    adapter's classifier produced. A `CancelledFailure` never escapes: the
+     *    runtime, not the adapter, decides what is a pause and what is a
+     *    shutdown, and it throws exactly where Temporal semantics require.
+     *  - Stops promptly when `sink.stopSignal` aborts, whatever the cause,
+     *    settling `interrupted`. Every call the adapter makes is bounded: the
+     *    runtime's heartbeat is live for the whole activity, and a live
+     *    heartbeat over an unbounded call keeps a dead activity alive forever.
+     *  - Proposes, never adjudicates. A gated side effect surfaces as a
+     *    WAITING_APPROVAL row on `sink.status` and the turn ends
+     *    `awaiting_approval`; the decision arrives on the next invocation in
+     *    `input.approvalDecisions`. APPROVE executes exactly once; REJECT and
+     *    SKIP never execute.
+     *  - Owns its own per-turn teardown in a `finally` inside this method.
+     */
+    runTurn(input: TurnInput, sink: TurnSink): Promise<TurnOutcome>;
+}
+/**
+ * What the runtime resolved for this turn and the adapter cannot read
+ * anywhere else. This is the core; the runtime extraction (S2) grows it one
+ * typed field per phase it takes over from the orchestrators (environment,
+ * workspace, skills, MCP servers with merged policies, attachments, memory,
+ * prompt bundle, model), in the `setup.ts` `SetupResult` mold.
+ *
+ * `threadId` is the engine's state id as the runtime knows it: empty on an
+ * `engine-minted` harness's first turn (nothing minted yet) and the id the
+ * adapter bound through {@link TurnSink.bindHarnessState} on every later
+ * invocation; the runtime-minted id on every turn of a `deterministic`
+ * harness. An adapter derives create-vs-resume from it and its own state; the
+ * contract carries no `isReinvocation` flag because the two harnesses would
+ * derive it differently.
+ */
+export interface TurnInput extends NormalizedActivityInput {
+    /**
+     * The session this turn belongs to. Read by the runtime from the fetched
+     * execution; the adapter needs it to key anything it parks per session and
+     * to recognise a later {@link HarnessAdapter.releaseSession}.
+     */
+    readonly sessionId: string;
+    /**
+     * The approval decisions the user has made on this execution's WAITING
+     * rows, keyed by tool-call id: the one projection both harness readers
+     * agree on (`status.messages[].toolCalls[]` where `approvalAction` is set
+     * and `status` is WAITING_APPROVAL). Derived by the runtime from
+     * `sink.status` on every invocation, never stored, so it cannot drift from
+     * the rows. An adapter reads the ROW for anything else it needs (args,
+     * content digest) and this map for the verdict; it never re-derives the
+     * verdict from the rows itself.
+     */
+    readonly approvalDecisions: ReadonlyMap<string, ApprovalAction>;
+}
+/**
+ * The runtime's face during one turn: the five things an adapter may ask of
+ * it, and the one status it folds into. One sink per turn, owned by the
+ * runtime; the adapter never constructs one.
+ *
+ * Field ownership on `status` before the canonical transcript lands (S4):
+ * the adapter appends the engine's transcript rows (assistant messages,
+ * tool-call rows and their approval status, sub-agent rows, todos); the
+ * runtime writes the phase, the terminal system messages, `streamingUsage`,
+ * artifacts, write-backs and the file-review projection. An adapter never
+ * writes a phase or a terminal copy: those are Temporal semantics the
+ * runtime owns once.
+ */
+export interface TurnSink {
+    /**
+     * The one execution status this turn folds into. On a reinvocation it is
+     * seeded by the runtime from the persisted transcript, so the WAITING rows
+     * the adapter wrote last time, and their decisions, are already on it.
+     */
+    readonly status: AgentExecutionStatus;
+    /**
+     * The ONE way a turn is told to stop, whatever the cause: user pause,
+     * worker shutdown, stall, cost cap, platform STOP. The runtime knows why
+     * and maps the outcome; the adapter's only job is to settle promptly as
+     * `interrupted`. `stopSignal.reason` is the runtime's own evidence — an
+     * adapter never branches on it. Check `aborted` at every step boundary and
+     * listen for `abort` inside anything long-running. May already be aborted
+     * when `runTurn` is entered; then return `interrupted` before doing any
+     * work.
+     */
+    readonly stopSignal: AbortSignal;
+    /**
+     * "Persist the status soon": schedules a write through the runtime's single
+     * persist chokepoint (tool-output offload, size cap, secret withholding,
+     * the streaming scheduler). Fire and forget — never awaited by the adapter,
+     * never a promise. The runtime persists unconditionally when the turn
+     * settles, so no adapter has to flush before returning.
+     */
+    requestPersist(): void;
+    /**
+     * "I made progress": resets the runtime's stall watchdog and is carried
+     * into the next Temporal heartbeat. Call it on every engine event and every
+     * token delta — a long generation emits deltas but few discrete events, and
+     * resetting only on events false-positives a stall. Never throws.
+     */
+    recordActivity(): void;
+    /**
+     * Token counts for one engine turn. The runtime accumulates, prices and
+     * enforces `max_cost_usd`; an adapter reports and never accounts. Every
+     * count is a non-negative delta since the previous report.
+     */
+    reportUsage(delta: UsageDelta): void;
+    /**
+     * The engine-minted state id, the moment it exists and BEFORE the turn
+     * proceeds, so a crash mid-turn still resumes on the next invocation. The
+     * runtime writes it to the session at once (the Cursor harness's
+     * `harness_state_id`). Called only by adapters whose
+     * `capabilities.stateIdSource` is `"engine-minted"`, and before their first
+     * `requestPersist`; a `deterministic` harness never calls it. Rejects when
+     * the session write fails; the adapter then ends the turn `failed` with
+     * that error and executes nothing further.
+     */
+    bindHarnessState(harnessStateId: string): Promise<void>;
+}
+/**
+ * Token counts for one engine turn, as the Cursor loop reads them from the
+ * SDK's `turn-ended` delta (`execute-cursor/usage-accumulator.ts`
+ * `TurnUsage` is this shape; the runtime extraction collapses the two). Every
+ * field is optional because engines report different subsets; a missing
+ * field means zero, never "unknown".
+ */
+export interface UsageDelta {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+}
+/**
+ * How one turn ended, carrying ONLY what the runtime cannot read from
+ * `sink.status` or its own evidence.
+ *
+ *  - `completed`: the engine finished. The final text and any structured
+ *    output are already folded onto the status; nothing rides here.
+ *  - `awaiting_approval`: the engine proposed at least one gated side effect
+ *    and stopped. The WAITING_APPROVAL rows are already on the status; the
+ *    runtime persists them and returns to the workflow, which reinvokes with
+ *    the decisions.
+ *  - `failed`: the engine or its transport failed in a way the adapter can
+ *    name. `message` is the user-facing sentence; `cause` is for the log.
+ *    The runtime persists FAILED and RETURNS (Temporal does not retry a
+ *    returned activity; re-running the same prompt would fail the same way).
+ *  - `interrupted`: `sink.stopSignal` aborted and the adapter stopped. WHY it
+ *    aborted is the runtime's evidence (its watchdog, its accounting, its
+ *    heartbeat, its shutdown signal), so no reason rides here; the runtime
+ *    classifies and applies the throw-vs-return table.
+ */
+export type TurnOutcome = {
+    readonly kind: "completed";
+} | {
+    readonly kind: "awaiting_approval";
+} | {
+    readonly kind: "failed";
+    readonly message: string;
+    readonly cause?: unknown;
+} | {
+    readonly kind: "interrupted";
+};

package/dist/harness/types.js

@@ -0,0 +1,55 @@
+/**
+ * The harness adapter contract — the line between what the turn runtime owns
+ * and what a harness owns.
+ *
+ * Stigmer runs an agent turn through one of several engines ("harnesses"):
+ * the native LangGraph deep-agent, the Cursor SDK, and in future the Claude
+ * Agent SDK and the Codex SDK. Everything about a turn that does NOT touch a
+ * vendor SDK — fetching the execution, resolving the blueprint and the
+ * environment, provisioning and locking the workspace, mounting skills,
+ * resolving MCP servers and approval policies, seeding the transcript, the
+ * persist cadence, the stall watchdog, the Temporal heartbeat, pause vs
+ * shutdown, the cost cap, the file-review boundary, the terminal mapping —
+ * is the RUNTIME's, written once. What a harness owns is its SDK slice: how
+ * the engine is created or resumed, how the prompt is placed, how MCP servers
+ * are bound, how the engine is made to stop before a gated side effect, and
+ * how its events become transcript rows. This file is the whole of what a
+ * harness author has to implement; `__test-utils__/harness-contract/` is the
+ * kit every implementation has to pass.
+ *
+ * Every member here is a rename of a function the Cursor loop already injects
+ * (`execute-cursor/turn-stream.ts` `CursorTurnStreamDeps`) or a fact the
+ * runtime cannot read anywhere else. Nothing here is speculative: where the
+ * program's original sketch and the code disagreed, the code won, and the
+ * disagreement was ruled at the entry's gate
+ * (stigmer-cloud `_projects/2026-09/20260911.02.sp.harness-contract-and-kit/`).
+ *
+ * What is deliberately NOT on this contract, and why:
+ *
+ *  - No `dispose()`. One adapter object serves many concurrent turns
+ *    (`maxConcurrentActivities`), so a per-turn teardown method on the
+ *    adapter is a race. The adapter owns its per-turn teardown in its own
+ *    `finally` inside `runTurn` (the Cursor harness already parks its agent
+ *    there).
+ *  - No `isCancelled()`, no `heartbeat(details)`, no `ExecutionStatusWriter`
+ *    base. Each would be a second way of saying something `stopSignal`,
+ *    `recordActivity()` or `requestPersist()` already says, and two writers of
+ *    one fact drift (the native builders' `forceNextUpdate` flag is the same
+ *    fact as a `requestPersist()` call).
+ *  - No `reason` on `interrupted`, no payload on `completed`, no `retryable`
+ *    on `failed`. Every cause of stopping is the runtime's own evidence; the
+ *    final text and structured output are already folded onto the status;
+ *    Temporal never retries a returned activity, so a retryable flag would
+ *    have no reader.
+ *  - No token-rotation hook. `Config.stigmerTokenRef` is the canonical
+ *    mutable ref; an adapter's transport reads it per request.
+ *  - No `TurnInput.status`. The runtime seeds `TurnSink.status` from the
+ *    persisted transcript; a second copy on the input is the drift the
+ *    single-source-of-truth mandate forbids.
+ *
+ * Module shape follows `shared/checkpointer/`: `types.ts`, `capabilities.ts`,
+ * `registry.ts`, no barrel. Nothing production-facing imports this module
+ * until the runtime that consumes it lands (S2 of the program).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/harness/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.14.0-dev.20260910084630",
+  "version": "3.14.1",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -104,9 +104,9 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.14.0-dev.20260910084630",
-    "@stigmer/temporal-codecs": "3.14.0-dev.20260910084630",
-    "@stigmer/zip-structure": "3.14.0-dev.20260910084630",
+    "@stigmer/protos": "3.14.1",
+    "@stigmer/temporal-codecs": "3.14.1",
+    "@stigmer/zip-structure": "3.14.1",
     "@temporalio/activity": "1.16.2",
     "@temporalio/common": "1.16.2",
     "@temporalio/interceptors-opentelemetry": "1.16.2",