@stigmer/runner 3.14.0 → 3.15.0

package/dist/__test-utils__/turn-input-fixture.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A whole `TurnInput` for tests that stand in for the runtime.
+ *
+ * The contract's input is the runtime's entire resolved record (`harness/
+ * types.ts`): the execution and session protos, the blueprint, the
+ * environment, the workspace, the tool surface, the attachments, the model
+ * preferences, the standing context. A test that drives an adapter WITHOUT
+ * the runtime — the harness contract kit's `ExecutionDriver`, a unit test of
+ * one adapter step — needs a record that type-checks and is inert: empty
+ * protos, an empty tool surface, a workspace under the OS temp dir, a memory
+ * selection that answers nothing. Everything here is the neutral value;
+ * `overrides` deep-merges one level (a test states the fields it is about
+ * and nothing else), the way `testConfig()` does for `Config`.
+ *
+ * Nothing here is Cursor's or native's: the vision profile, the file-review
+ * identity and the state id source are the ADAPTER's capabilities, not
+ * input facts, so they do not appear.
+ */
+import { type AgentExecution, type AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { type Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import type { TurnInput } from "../harness/types.js";
+import type { ResolvedBlueprint } from "../shared/blueprint-resolver.js";
+/** The ids a fixture record carries when a test does not name its own. */
+export declare const TURN_INPUT_FIXTURE_IDS: {
+    readonly executionId: "aex_fixture_0001";
+    readonly sessionId: "ses_fixture_0001";
+    readonly agentId: "agt_fixture_0001";
+    readonly org: "fixture-org";
+};
+export interface TurnInputFixtureOverrides extends Partial<Omit<TurnInput, "execution" | "session" | "blueprint">> {
+    readonly execution?: AgentExecution;
+    readonly session?: Session;
+    readonly blueprint?: Partial<ResolvedBlueprint>;
+    /**
+     * The user's message on the default execution's spec (ignored when a whole
+     * `execution` is given). Empty by default: the neutral record asks nothing.
+     */
+    readonly message?: string;
+    /**
+     * The status the default execution carries — what the control plane
+     * persisted at the end of the previous invocation, on a reinvocation. The
+     * runtime seeds the turn's in-progress status from a clone of it
+     * (`seedTranscriptFromExecution`) and an adapter may read the record's own
+     * copy for its facts, so a test standing in for the runtime hands both.
+     */
+    readonly persistedStatus?: AgentExecutionStatus;
+    /**
+     * Where the default workspace lives (ignored when a whole `workspace` is
+     * given). A test that only needs "my workspace is here" — because its
+     * engine writes into it — states the directory and nothing else of the
+     * provision record.
+     */
+    readonly workspaceDir?: string;
+}
+/**
+ * The neutral record, with `overrides` laid over it one level deep. The
+ * `session` and `blueprint.session` are the SAME object, as the runtime
+ * guarantees (`bindHarnessState` writes it).
+ */
+export declare function turnInputFixture(overrides?: TurnInputFixtureOverrides): TurnInput;

package/dist/__test-utils__/turn-input-fixture.js

@@ -0,0 +1,118 @@
+/**
+ * A whole `TurnInput` for tests that stand in for the runtime.
+ *
+ * The contract's input is the runtime's entire resolved record (`harness/
+ * types.ts`): the execution and session protos, the blueprint, the
+ * environment, the workspace, the tool surface, the attachments, the model
+ * preferences, the standing context. A test that drives an adapter WITHOUT
+ * the runtime — the harness contract kit's `ExecutionDriver`, a unit test of
+ * one adapter step — needs a record that type-checks and is inert: empty
+ * protos, an empty tool surface, a workspace under the OS temp dir, a memory
+ * selection that answers nothing. Everything here is the neutral value;
+ * `overrides` deep-merges one level (a test states the fields it is about
+ * and nothing else), the way `testConfig()` does for `Config`.
+ *
+ * Nothing here is Cursor's or native's: the vision profile, the file-review
+ * identity and the state id source are the ADAPTER's capabilities, not
+ * input facts, so they do not appear.
+ */
+import { create } from "@bufbuild/protobuf";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AgentExecutionSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ServiceTier, ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { mockWorkspaceBackend } from "./mock-workspace.js";
+/** The ids a fixture record carries when a test does not name its own. */
+export const TURN_INPUT_FIXTURE_IDS = {
+    executionId: "aex_fixture_0001",
+    sessionId: "ses_fixture_0001",
+    agentId: "agt_fixture_0001",
+    org: "fixture-org",
+};
+/**
+ * The neutral record, with `overrides` laid over it one level deep. The
+ * `session` and `blueprint.session` are the SAME object, as the runtime
+ * guarantees (`bindHarnessState` writes it).
+ */
+export function turnInputFixture(overrides = {}) {
+    const executionId = overrides.executionId ?? TURN_INPUT_FIXTURE_IDS.executionId;
+    const sessionId = overrides.sessionId ?? TURN_INPUT_FIXTURE_IDS.sessionId;
+    const session = overrides.session ??
+        create(SessionSchema, {
+            metadata: create(ApiResourceMetadataSchema, { id: sessionId, org: TURN_INPUT_FIXTURE_IDS.org, name: sessionId }),
+            spec: create(SessionSpecSchema, {}),
+        });
+    const execution = overrides.execution ??
+        create(AgentExecutionSchema, {
+            metadata: create(ApiResourceMetadataSchema, { id: executionId, org: TURN_INPUT_FIXTURE_IDS.org, name: executionId }),
+            spec: create(AgentExecutionSpecSchema, { sessionId, message: overrides.message ?? "" }),
+            status: overrides.persistedStatus,
+        });
+    const agent = create(AgentSchema, {
+        metadata: create(ApiResourceMetadataSchema, {
+            id: TURN_INPUT_FIXTURE_IDS.agentId,
+            org: TURN_INPUT_FIXTURE_IDS.org,
+            name: "fixture-agent",
+        }),
+        spec: create(AgentSpecSchema, { instructions: "You are the fixture agent." }),
+    });
+    const workspaceDir = overrides.workspaceDir ?? join(tmpdir(), "stigmer-runner-turn-input-fixture");
+    const blueprint = {
+        agent,
+        agentSpec: agent.spec,
+        session,
+        sessionSpec: session.spec,
+        instructions: agent.spec.instructions,
+        subAgents: [],
+        mergedMcpServerUsages: [],
+        mergedSkillRefs: [],
+        cloudRepos: [],
+        ...overrides.blueprint,
+    };
+    return {
+        executionId,
+        threadId: overrides.threadId ?? "",
+        turnSeq: overrides.turnSeq ?? 0,
+        sessionId,
+        approvalDecisions: overrides.approvalDecisions ?? new Map(),
+        execution,
+        session,
+        blueprint,
+        environment: overrides.environment ?? { envVars: {}, secretKeys: new Set() },
+        workspace: overrides.workspace ?? {
+            dirs: [workspaceDir],
+            primaryDir: workspaceDir,
+            gitWorkspace: false,
+            captureMode: false,
+            changeSetId: `${executionId}:${overrides.turnSeq ?? 0}`,
+            provision: { workspaceDirs: [workspaceDir], provisionResults: [], workspaceBackend: mockWorkspaceBackend() },
+        },
+        mcp: overrides.mcp ?? {
+            servers: [],
+            channelMessaging: [],
+            leases: { global: false, categories: new Set(), servers: new Set() },
+            policies: new Map(),
+        },
+        skills: overrides.skills ?? [],
+        attachments: overrides.attachments ?? { results: [], visionImages: [], visionNotViewable: [] },
+        appliedToolCallIds: overrides.appliedToolCallIds ?? new Set(),
+        model: overrides.model ?? { requested: "default", serviceTier: ServiceTier.STANDARD, thinkingMode: ThinkingMode.DISABLED },
+        structuredOutputSchema: overrides.structuredOutputSchema,
+        standing: overrides.standing ?? {
+            contextBridge: undefined,
+            senderIdentity: undefined,
+            sessionContext: undefined,
+            declaredPreferences: undefined,
+            conversationCatchup: undefined,
+            selectRecalledMemories: async () => undefined,
+        },
+        artifactStorage: overrides.artifactStorage,
+    };
+}
+//# sourceMappingURL=turn-input-fixture.js.map

package/dist/__test-utils__/turn-input-fixture.js.map

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

package/dist/activities/execute-cursor/__test-utils__/contract-subject.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The Cursor harness as a `HarnessContractSubject` — the REAL `createCursorAdapter()`
+ * driven through the harness contract kit, with the kit's engine-neutral
+ * scenario vocabulary translated onto S0's scripted `@cursor/sdk` double.
+ *
+ * The sibling of `gateway-substrate.ts` (the Cursor side of the approval
+ * contract kit): the kit owns the invariants and the runtime stand-in, this
+ * module owns the ENGINE — what the next turn of a session's agent will do —
+ * and reports what the double observed. The adapter under test is the
+ * production one, untouched; it imports no `@temporalio/*` (the fence test
+ * pins that), which is what lets the kit run it outside any activity
+ * context.
+ *
+ * ── The engine is per session ───────────────────────────────────────────────
+ * One scripted agent per session, minted when the kit first arranges a turn
+ * for it and handed out by the double's `Agent.create` for THAT session (keyed
+ * by the SDK's `platform.workspaceRef`, computed the way the adapter computes
+ * it), then parked by the real session cache across turns exactly as in a live
+ * worker. Arranging a turn REPLACES the agent's next script, so a turn the
+ * adapter interrupts before its `send()` leaves no stale script for the
+ * session's next turn. Every session also gets the workspace directory the
+ * runtime's provisioner would give it (`<workspaceRootDir>/sessions/<id>`), so
+ * both halves of the kit gate in the same directory shape; the hook's
+ * active-turn pointer is per workspace, so concurrent sessions cannot repoint
+ * each other's hook.
+ *
+ * ── The translation, one rule per word ──────────────────────────────────────
+ *  - `say(text)`      → an `assistant` event. A first send opens with the
+ *                       `system/init` event; a resumed send does not (the
+ *                       `deny-and-retry` turn-2 script is the precedent).
+ *  - `propose(id, a)` → the STREAM tool call (`edit` / `shell` / `delete`, the
+ *                       kits' shared translation in `cursor-hook-harness.ts`),
+ *                       an `effect` that runs the REAL preToolUse hook the
+ *                       adapter installed against the session's workspace,
+ *                       and the call's completion event. `executionCount(id)`
+ *                       is the hook's `allow` answers for `id` — the SDK
+ *                       executes a tool iff the hook allows it, so this is the
+ *                       safety-critical observable. WHETHER the call is
+ *                       emitted is decided from the kit's view and this
+ *                       subject's own memory, as the model and the SDK would
+ *                       decide it (see {@link CursorContractSubject.proposeSteps}).
+ *  - `read(id, path)` → the `read` tool call, the REAL hook (which allows it —
+ *                       a read is never gated) and the completion; counted as
+ *                       run. The discrete event the adapter's loop flushes a
+ *                       persist on.
+ *  - `usage(delta)`   → a `turn-ended` delta; the adapter prices it.
+ *  - `hang`           → an `effect` parked on the run's own `cancelled`
+ *                       status, which the adapter's stop-signal listener
+ *                       (`turn-stream.ts` `cancelOnStop`) produces. Never a
+ *                       timer. Resolves `whenHanging`.
+ *  - `fail(msg, s)`   → `engine`: the run ends `{ status: "error" }` and
+ *                       `run.wait()` carries the message; `internal`: an
+ *                       `effect` throws mid-stream (the adapter's catch
+ *                       classifies it). `actionable` is refused as a test bug:
+ *                       only the unattributed-hook-block path produces that
+ *                       surface, and the kit's invariants do not ask for it.
+ *  - `cancelled`      → an `effect` calling `run.cancel()` from the SDK side
+ *                       (the `run-cancelled` golden's shape).
+ * Every script that does not end in `fail`, `cancelled` or `hang` closes with
+ * `finished({ result: <last say> })` so `run.wait()` has an answer.
+ *
+ * ── Two modelling decisions (S2 M4, Q-M4-4) ─────────────────────────────────
+ * A `propose` for an id this subject has already seen the hook ALLOW emits
+ * nothing: the real SDK does not re-run a completed tool on resume — the parked
+ * agent's conversation already holds the tool's result. A `propose` whose id
+ * carries a SKIP or REJECT decision emits nothing either: the resume prompt
+ * tells the model the user declined the action and an obedient model moves
+ * on. Both are what "the engine re-reaches the same call" and "the turn
+ * continues" MEAN for a deny-and-retry harness; neither hides anything from
+ * the safety observable, because a fresh identical command from a
+ * disobedient model IS a new gated act and Cursor re-gates it — the subject
+ * file proves that with {@link CursorContractSubject.forceReissue}.
+ *
+ * The completion event a `propose` emits is scripted from the answer the hook
+ * is EXPECTED to give (deny for an undecided proposal, allow for an approved
+ * re-issue); the hook's actual answer is recorded at effect time and any
+ * disagreement is kept in {@link CursorContractSubject.hookDisagreements} for
+ * the subject file to assert empty — a hook that allows an undecided action
+ * would show up there AND in `executionCount`, never be papered over.
+ */
+import type { HarnessAdapter } from "../../../harness/types.js";
+import type { HarnessContractSubject } from "../../../__test-utils__/harness-contract/types.js";
+import type { HermeticEnvironment } from "../../../__test-utils__/hermetic-activity.js";
+import { ScriptedCursorAgent } from "./scripted-agent.js";
+import { ScriptedCursorSdk } from "./scripted-sdk.js";
+export interface CursorContractSubject extends HarnessContractSubject {
+    readonly adapter: HarnessAdapter;
+    /** The SDK double the adapter is talking to, for the subject file's own observations. */
+    readonly sdk: ScriptedCursorSdk;
+    /** The scripted agent minted for a session, once the kit has arranged a turn for it. */
+    agentFor(sessionId: string): ScriptedCursorAgent | undefined;
+    /**
+     * Make the NEXT `propose` of `toolCallId` emit its call whatever the
+     * decision or the memory says — the disobedient model, for the observation
+     * the kit's vocabulary cannot express.
+     */
+    forceReissue(toolCallId: string): void;
+    /** Every proposal at which the hook answered other than the script expected; the subject file asserts it stays empty. */
+    readonly hookDisagreements: readonly string[];
+}
+/**
+ * Build the subject over one hermetic environment (the temp `HOME` the gate's
+ * per-session HITL artifacts land under, the temp workspace root). The
+ * environment is the caller's to create before and dispose after; the SDK
+ * double is bound for the module here, so a file holds one subject.
+ */
+export declare function createCursorContractSubject(env: HermeticEnvironment): CursorContractSubject;

package/dist/activities/execute-cursor/__test-utils__/contract-subject.js

@@ -0,0 +1,344 @@
+/**
+ * The Cursor harness as a `HarnessContractSubject` — the REAL `createCursorAdapter()`
+ * driven through the harness contract kit, with the kit's engine-neutral
+ * scenario vocabulary translated onto S0's scripted `@cursor/sdk` double.
+ *
+ * The sibling of `gateway-substrate.ts` (the Cursor side of the approval
+ * contract kit): the kit owns the invariants and the runtime stand-in, this
+ * module owns the ENGINE — what the next turn of a session's agent will do —
+ * and reports what the double observed. The adapter under test is the
+ * production one, untouched; it imports no `@temporalio/*` (the fence test
+ * pins that), which is what lets the kit run it outside any activity
+ * context.
+ *
+ * ── The engine is per session ───────────────────────────────────────────────
+ * One scripted agent per session, minted when the kit first arranges a turn
+ * for it and handed out by the double's `Agent.create` for THAT session (keyed
+ * by the SDK's `platform.workspaceRef`, computed the way the adapter computes
+ * it), then parked by the real session cache across turns exactly as in a live
+ * worker. Arranging a turn REPLACES the agent's next script, so a turn the
+ * adapter interrupts before its `send()` leaves no stale script for the
+ * session's next turn. Every session also gets the workspace directory the
+ * runtime's provisioner would give it (`<workspaceRootDir>/sessions/<id>`), so
+ * both halves of the kit gate in the same directory shape; the hook's
+ * active-turn pointer is per workspace, so concurrent sessions cannot repoint
+ * each other's hook.
+ *
+ * ── The translation, one rule per word ──────────────────────────────────────
+ *  - `say(text)`      → an `assistant` event. A first send opens with the
+ *                       `system/init` event; a resumed send does not (the
+ *                       `deny-and-retry` turn-2 script is the precedent).
+ *  - `propose(id, a)` → the STREAM tool call (`edit` / `shell` / `delete`, the
+ *                       kits' shared translation in `cursor-hook-harness.ts`),
+ *                       an `effect` that runs the REAL preToolUse hook the
+ *                       adapter installed against the session's workspace,
+ *                       and the call's completion event. `executionCount(id)`
+ *                       is the hook's `allow` answers for `id` — the SDK
+ *                       executes a tool iff the hook allows it, so this is the
+ *                       safety-critical observable. WHETHER the call is
+ *                       emitted is decided from the kit's view and this
+ *                       subject's own memory, as the model and the SDK would
+ *                       decide it (see {@link CursorContractSubject.proposeSteps}).
+ *  - `read(id, path)` → the `read` tool call, the REAL hook (which allows it —
+ *                       a read is never gated) and the completion; counted as
+ *                       run. The discrete event the adapter's loop flushes a
+ *                       persist on.
+ *  - `usage(delta)`   → a `turn-ended` delta; the adapter prices it.
+ *  - `hang`           → an `effect` parked on the run's own `cancelled`
+ *                       status, which the adapter's stop-signal listener
+ *                       (`turn-stream.ts` `cancelOnStop`) produces. Never a
+ *                       timer. Resolves `whenHanging`.
+ *  - `fail(msg, s)`   → `engine`: the run ends `{ status: "error" }` and
+ *                       `run.wait()` carries the message; `internal`: an
+ *                       `effect` throws mid-stream (the adapter's catch
+ *                       classifies it). `actionable` is refused as a test bug:
+ *                       only the unattributed-hook-block path produces that
+ *                       surface, and the kit's invariants do not ask for it.
+ *  - `cancelled`      → an `effect` calling `run.cancel()` from the SDK side
+ *                       (the `run-cancelled` golden's shape).
+ * Every script that does not end in `fail`, `cancelled` or `hang` closes with
+ * `finished({ result: <last say> })` so `run.wait()` has an answer.
+ *
+ * ── Two modelling decisions (S2 M4, Q-M4-4) ─────────────────────────────────
+ * A `propose` for an id this subject has already seen the hook ALLOW emits
+ * nothing: the real SDK does not re-run a completed tool on resume — the parked
+ * agent's conversation already holds the tool's result. A `propose` whose id
+ * carries a SKIP or REJECT decision emits nothing either: the resume prompt
+ * tells the model the user declined the action and an obedient model moves
+ * on. Both are what "the engine re-reaches the same call" and "the turn
+ * continues" MEAN for a deny-and-retry harness; neither hides anything from
+ * the safety observable, because a fresh identical command from a
+ * disobedient model IS a new gated act and Cursor re-gates it — the subject
+ * file proves that with {@link CursorContractSubject.forceReissue}.
+ *
+ * The completion event a `propose` emits is scripted from the answer the hook
+ * is EXPECTED to give (deny for an undecided proposal, allow for an approved
+ * re-issue); the hook's actual answer is recorded at effect time and any
+ * disagreement is kept in {@link CursorContractSubject.hookDisagreements} for
+ * the subject file to assert empty — a hook that allows an undecided action
+ * would show up there AND in `executionCount`, never be papered over.
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { ApprovalAction, ServiceTier, ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { createCursorAdapter } from "../adapter.js";
+import { resolvePlatformOptions } from "../session-lifecycle.js";
+import { hookInputFor, streamArgsFor, STREAM_NAME } from "./cursor-hook-harness.js";
+import { FIXTURE, SDK_CATALOG, hermeticCursorConfig, runWorkspaceHook } from "./hermetic-cursor.js";
+import { ScriptedCursorAgent, sdkEvents, step } from "./scripted-agent.js";
+import { ScriptedCursorSdk, bindScriptedSdk } from "./scripted-sdk.js";
+/** The user's message every kit turn asks; the prompt builder needs one and the kit has none to give. */
+const KIT_USER_MESSAGE = "Do what the scenario says.";
+/** What the double records the SDK "returning" for an allowed tool call. */
+const ALLOWED_RESULT = "ok (kit)";
+/** The error the SDK surfaces on a hook-denied call, as the goldens script it. */
+const HOOK_BLOCKED_RESULT = "Blocked by hook";
+/**
+ * Build the subject over one hermetic environment (the temp `HOME` the gate's
+ * per-session HITL artifacts land under, the temp workspace root). The
+ * environment is the caller's to create before and dispose after; the SDK
+ * double is bound for the module here, so a file holds one subject.
+ */
+export function createCursorContractSubject(env) {
+    return new CursorSubject(env);
+}
+class CursorSubject {
+    env;
+    name = "cursor";
+    harness = "cursor";
+    adapter;
+    config;
+    sdk;
+    hookDisagreements = [];
+    agents = new Map();
+    agentsByWorkspaceRef = new Map();
+    proposals = new Map();
+    forcedReissues = new Set();
+    hangWaiters = [];
+    mintCounter = 0;
+    constructor(env) {
+        this.env = env;
+        this.config = hermeticCursorConfig(env);
+        this.adapter = createCursorAdapter();
+        this.sdk = new ScriptedCursorSdk({
+            agents: [],
+            catalog: SDK_CATALOG,
+            agentForWorkspaceRef: (ref) => this.agentsByWorkspaceRef.get(ref),
+        });
+        bindScriptedSdk(this.sdk);
+    }
+    // ── HarnessContractSubject ────────────────────────────────────────────────
+    arrange(turn, view) {
+        const agent = this.agents.get(view.sessionId) ?? this.mintAgent(view.sessionId);
+        mkdirSync(this.workspaceRootOf(view.sessionId), { recursive: true });
+        agent.arrangeNextTurn(this.translate(turn, view, agent));
+    }
+    inputOverrides(view) {
+        return {
+            // The adapter validates the name against its catalog and prices against
+            // the registry fixture; both know exactly this model.
+            model: { requested: FIXTURE.model, serviceTier: ServiceTier.STANDARD, thinkingMode: ThinkingMode.DISABLED },
+            workspaceDir: this.workspaceRootOf(view.sessionId),
+            message: KIT_USER_MESSAGE,
+        };
+    }
+    whenHanging() {
+        return new Promise((resolve) => this.hangWaiters.push(resolve));
+    }
+    executionCount(toolCallId) {
+        return this.proposals.get(toolCallId)?.allowed ?? 0;
+    }
+    // ── The subject file's observations ──────────────────────────────────────
+    agentFor(sessionId) {
+        return this.agents.get(sessionId);
+    }
+    forceReissue(toolCallId) {
+        this.forcedReissues.add(toolCallId);
+    }
+    // ── The engine ────────────────────────────────────────────────────────────
+    /** The directory the runtime's provisioner gives a session with no workspace entries (`session-root.ts`). */
+    workspaceRootOf(sessionId) {
+        return join(this.env.workspaceRootDir, "sessions", sessionId);
+    }
+    mintAgent(sessionId) {
+        const agent = new ScriptedCursorAgent({ agentId: `agent-kit-${++this.mintCounter}`, turns: [] });
+        this.agents.set(sessionId, agent);
+        // The adapter asks the SDK to create an agent for the session under this
+        // ref; the double answers with this agent.
+        const { workspaceRef } = resolvePlatformOptions(sessionId, this.config.workspaceRootDir);
+        this.agentsByWorkspaceRef.set(workspaceRef, agent);
+        return agent;
+    }
+    translate(turn, view, agent) {
+        const ev = sdkEvents(agent.agentId, agent.nextRunId);
+        const script = [];
+        if (agent.sends.length === 0)
+            script.push(step.event(ev.init()));
+        let lastSay = "";
+        let ended = false;
+        for (const s of turn) {
+            switch (s.kind) {
+                case "say":
+                    script.push(step.event(ev.assistant(s.text)));
+                    lastSay = s.text;
+                    break;
+                case "propose":
+                    script.push(...this.proposeSteps(s.toolCallId, s.action, view, ev));
+                    break;
+                case "read":
+                    script.push(...this.readSteps(s.toolCallId, s.path, view, ev));
+                    break;
+                case "usage":
+                    script.push(step.turnEnded({
+                        inputTokens: s.delta.inputTokens,
+                        outputTokens: s.delta.outputTokens,
+                        cacheReadTokens: s.delta.cacheReadTokens,
+                        cacheWriteTokens: s.delta.cacheWriteTokens,
+                    }));
+                    break;
+                case "hang":
+                    script.push(step.effect("kit: hang until the adapter cancels the run", ({ run }) => this.park(run)));
+                    ended = true;
+                    break;
+                case "fail":
+                    switch (s.surface) {
+                        case "engine":
+                            script.push(step.errored({ result: s.message }));
+                            break;
+                        case "internal":
+                            script.push(step.effect("kit: the transport breaks mid-stream", () => {
+                                throw new Error(s.message);
+                            }));
+                            break;
+                        case "actionable":
+                            throw new Error(`${this.name}: fail(..., "actionable") is not producible by this subject (only the unattributed hook block reaches that surface); test bug`);
+                        default: {
+                            const exhaustive = s.surface;
+                            throw new Error(`${this.name}: unknown failure surface ${String(exhaustive)}`);
+                        }
+                    }
+                    ended = true;
+                    break;
+                case "cancelled":
+                    script.push(step.effect("kit: the SDK cancels its own run", ({ run }) => run.cancel()));
+                    ended = true;
+                    break;
+                default: {
+                    const exhaustive = s;
+                    throw new Error(`${this.name}: unknown scenario step ${JSON.stringify(exhaustive)}`);
+                }
+            }
+        }
+        if (!ended)
+            script.push(step.finished({ result: lastSay, model: { id: FIXTURE.model, params: [] } }));
+        return script;
+    }
+    /**
+     * Whether the model emits the gated call this turn, and what the hook is
+     * expected to answer — one rule per case (see the header). `undefined`
+     * means "nothing is emitted".
+     */
+    emissionFor(toolCallId, view) {
+        if (this.forcedReissues.delete(toolCallId)) {
+            // The disobedient model: emitted regardless; the hook decides on its own
+            // (a grant exists only for an APPROVE), so what to expect is the grant.
+            return { expectAllow: view.approvalDecisions.get(toolCallId) === ApprovalAction.APPROVE };
+        }
+        if ((this.proposals.get(toolCallId)?.allowed ?? 0) > 0)
+            return undefined;
+        const decision = view.approvalDecisions.get(toolCallId) ?? ApprovalAction.UNSPECIFIED;
+        switch (decision) {
+            case ApprovalAction.UNSPECIFIED:
+                return { expectAllow: false };
+            case ApprovalAction.APPROVE:
+            case ApprovalAction.APPROVE_ALL:
+                return { expectAllow: true };
+            case ApprovalAction.SKIP:
+            case ApprovalAction.REJECT:
+                return undefined;
+            default: {
+                const exhaustive = decision;
+                throw new Error(`${this.name}: unknown approval action ${String(exhaustive)}`);
+            }
+        }
+    }
+    proposeSteps(toolCallId, action, view, ev) {
+        const emission = this.emissionFor(toolCallId, view);
+        if (!emission)
+            return [];
+        if (action.kind === "read" || action.kind === "mcp") {
+            throw new Error(`${this.name}: propose(${action.kind}) is not a gated built-in on this harness; test bug`);
+        }
+        const gated = { ...action, kind: action.kind };
+        const memory = this.proposals.get(toolCallId) ?? { emitted: 0, allowed: 0 };
+        this.proposals.set(toolCallId, memory);
+        // The first emission carries the kit's id (the WAITING row the kit looks
+        // up); a re-issue carries a fresh call id, as the resumed SDK agent does,
+        // and the adapter reconciles it onto the committed row by identity.
+        const callId = memory.emitted === 0 ? toolCallId : `${toolCallId}#${memory.emitted}`;
+        memory.emitted += 1;
+        const name = STREAM_NAME[gated.kind];
+        const args = streamArgsFor(gated);
+        const workspaceRoot = this.workspaceRootOf(view.sessionId);
+        return [
+            step.event(ev.toolCall(callId, name, "running", args)),
+            step.effect(`kit: the real hook judges ${name} ${gated.resource}`, () => {
+                const { permission } = runWorkspaceHook(workspaceRoot, hookInputFor(gated));
+                if (permission === "allow")
+                    memory.allowed += 1;
+                if ((permission === "allow") !== emission.expectAllow) {
+                    this.hookDisagreements.push(`${toolCallId}: expected ${emission.expectAllow ? "allow" : "deny"}, hook answered ${permission}`);
+                }
+            }),
+            emission.expectAllow
+                ? step.event(ev.toolCall(callId, name, "completed", args, ALLOWED_RESULT))
+                : step.event(ev.toolCall(callId, name, "error", args, HOOK_BLOCKED_RESULT)),
+        ];
+    }
+    /**
+     * An ungated read: the stream tool call, the REAL hook (which allows every
+     * read — the gate's baked-in category set has no arm for it; asserted
+     * through the disagreement record like every other hook answer), and the
+     * completion with contents. The SDK executes what the hook allows, so the
+     * read counts as run.
+     */
+    readSteps(toolCallId, path, view, ev) {
+        const memory = this.proposals.get(toolCallId) ?? { emitted: 0, allowed: 0 };
+        this.proposals.set(toolCallId, memory);
+        memory.emitted += 1;
+        const args = { path };
+        const workspaceRoot = this.workspaceRootOf(view.sessionId);
+        return [
+            step.event(ev.toolCall(toolCallId, "read", "running", args)),
+            step.effect(`kit: the real hook judges read ${path}`, () => {
+                const { permission } = runWorkspaceHook(workspaceRoot, hookInputFor({ kind: "read", resource: path }));
+                if (permission === "allow")
+                    memory.allowed += 1;
+                else
+                    this.hookDisagreements.push(`${toolCallId}: expected allow for a read, hook answered ${permission}`);
+            }),
+            step.event(ev.toolCall(toolCallId, "read", "completed", args, `contents of ${path}`)),
+        ];
+    }
+    /**
+     * Park until the adapter cancels the run — the real shape of "the engine
+     * makes no progress until told to stop": the adapter's stop-signal listener
+     * calls `run.cancel()`, the double's status flips, and its stream breaks at
+     * the next step.
+     */
+    park(run) {
+        for (const waiter of this.hangWaiters.splice(0))
+            waiter();
+        if (run.status === "cancelled")
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const unsubscribe = run.onDidChangeStatus((status) => {
+                if (status !== "cancelled")
+                    return;
+                unsubscribe();
+                resolve();
+            });
+        });
+    }
+}
+//# sourceMappingURL=contract-subject.js.map