The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add deterministic runner conformance core (#12354)
Dotta773d357d8a83
diff --git a/packages/paperclip-runner/src/backends/harness-driver-backend.test.ts b/packages/paperclip-runner/src/backends/harness-driver-backend.test.tsindex 689800e54e..c439227f03 100644--- a/packages/paperclip-runner/src/backends/harness-driver-backend.test.ts+++ b/packages/paperclip-runner/src/backends/harness-driver-backend.test.ts@@ -1,7 +1,7 @@import { describe, expect, it } from "vitest";import type { HarnessDriver, HarnessSession, PersistedHarnessSession } from "../contracts/harness-driver.js";-import type { PrpEvent, PrpStructuredRunResult } from "../protocol/replay-contract.js";+import type { PrpEvent, PrpStructuredRunResult, PrpTerminalState } from "../protocol/replay-contract.js";import { HarnessDriverBackend } from "./harness-driver-backend.js";const result: PrpStructuredRunResult = {@@ -271,6 +271,105 @@ describe("HarnessDriverBackend", () => {expect(receivedSignal).toBe(controller.signal);});+ it("does not resurrect a settled turn across repeated backend recovery", async () => {+ const terminal: PrpTerminalState = {+ schema: "paperclip.prp.terminal.v1",+ turnTerminalState: "completed",+ runTerminalState: "succeeded",+ reportedWorkDisposition: "done",+ };+ const recoveredSnapshots: PersistedHarnessSession[] = [];++ class SettledRecoveredSession extends FakeHarnessSession {+ readonly #snapshot: PersistedHarnessSession;++ constructor(snapshot: PersistedHarnessSession) {+ super();+ this.#snapshot = structuredClone(snapshot);+ }++ override async *events() {+ // Model the deterministic driver's recovery rule: only an active turn+ // produces a reconstructed result/terminal sequence.+ if (this.#snapshot.activeTurnId === null || this.#snapshot.activeTurnId === undefined) return;+ yield prpEvent(3, "run.result.proposed", result);+ yield prpEvent(4, "turn.completed", { status: "completed" });+ yield prpEvent(5, "run.terminal", terminal);+ }++ override async snapshot(): Promise<PersistedHarnessSession> {+ return structuredClone(this.#snapshot);+ }+ }++ const recoveryDriver: HarnessDriver = {+ ...driver,+ async recoverSession(snapshot) {+ recoveredSnapshots.push(structuredClone(snapshot));+ return { recovered: true, session: new SettledRecoveredSession(snapshot) };+ },+ };+ const backend = new HarnessDriverBackend(recoveryDriver);+ const settledSnapshot = {+ backendKind: "runner" as const,+ driverKind: "fake",+ sessionId: "driver-1",+ providerSessionId: "provider-1",+ identity: {+ runId: "run-1",+ sessionId: "session-1",+ companyId: "company-1",+ issueId: "issue-1",+ agentId: "agent-1",+ },+ cursor: "2",+ semanticResult: result,+ terminal,+ activeTurnId: null,+ terminalTurns: [{ turnId: "turn-1", fingerprint: "terminal-1" }],+ };++ const recoveryOptions = { signal: new AbortController().signal };+ const firstRecovery = await backend.recoverSession(+ settledSnapshot,+ recoveryOptions,+ );+ expect(firstRecovery.recovered).toBe(true);+ const firstSession = firstRecovery.session!;+ const firstRecoveredSnapshot = await firstSession.snapshot();+ expect(firstRecoveredSnapshot).toMatchObject({+ activeTurnId: null,+ semanticResult: result,+ terminal,+ });+ await expect(firstSession.result()).resolves.toEqual({+ result,+ terminal,+ turnId: "turn-1",+ });++ const secondRecovery = await backend.recoverSession(+ firstRecoveredSnapshot,+ recoveryOptions,+ );+ expect(secondRecovery.recovered).toBe(true);+ const secondSession = secondRecovery.session!;+ await expect(secondSession.snapshot()).resolves.toMatchObject({+ activeTurnId: null,+ semanticResult: result,+ terminal,+ });+ const replayedEvents: PrpEvent[] = [];+ for await (const event of secondSession.events()) replayedEvents.push(event);+ expect(replayedEvents.filter((event) =>+ event.eventType === "run.result.proposed" || event.eventType === "run.terminal"+ )).toEqual([]);+ expect(recoveredSnapshots.map((snapshot) => snapshot.activeTurnId)).toEqual([null, null]);++ await secondSession.close({ reason: "double recovery complete" });+ await firstSession.close({ reason: "first recovery complete" });+ });+it("allows only the run id to change when a harness session is attached", async () => {const attachedRunIds: string[] = [];class AttachableHarnessSession extends FakeHarnessSession {diff --git a/packages/paperclip-runner/src/backends/harness-driver-backend.ts b/packages/paperclip-runner/src/backends/harness-driver-backend.tsindex c66e69b3ae..9c39f8ccb4 100644--- a/packages/paperclip-runner/src/backends/harness-driver-backend.ts+++ b/packages/paperclip-runner/src/backends/harness-driver-backend.ts@@ -70,6 +70,12 @@ export class HarnessDriverBackend implements NativeSessionBackend {if (this.#driver.recoverSession === undefined) {return { recovered: false, reason: "driver does not support recovery" };}+ // `null` is a durable "no active turn" checkpoint. Only an omitted legacy+ // field may use the compatibility fallback; nullish coalescing here would+ // otherwise turn the most recent terminal turn back into an active one.+ const activeTurnId = snapshot.activeTurnId === undefined+ ? snapshot.terminalTurns?.at(-1)?.turnId ?? null+ : snapshot.activeTurnId;const persisted: PersistedHarnessSession = {driverKind: snapshot.driverKind ?? snapshot.backendKind,driverSessionId: snapshot.sessionId,@@ -82,7 +88,7 @@ export class HarnessDriverBackend implements NativeSessionBackend {: { providerRecoveryPolicy: snapshot.providerRecoveryPolicy }),runId: snapshot.identity.runId,normalizedSessionId: snapshot.identity.sessionId,- activeTurnId: snapshot.activeTurnId ?? snapshot.terminalTurns?.at(-1)?.turnId ?? null,+ activeTurnId,lastSourceSequence: parseCursor(snapshot.cursor),...(snapshot.semanticResult === undefined || snapshot.semanticResult === null? {}@@ -90,7 +96,7 @@ export class HarnessDriverBackend implements NativeSessionBackend {semanticResult: {result: snapshot.semanticResult,fingerprint: canonicalJson(snapshot.semanticResult),- turnId: snapshot.activeTurnId ?? snapshot.terminalTurns?.at(-1)?.turnId ?? "recovered",+ turnId: activeTurnId ?? snapshot.terminalTurns?.at(-1)?.turnId ?? "recovered",},}),terminalTurns: snapshot.terminalTurns ?? [],@@ -125,6 +131,7 @@ export class HarnessDriverBackend implements NativeSessionBackend {session: new HarnessNativeSession({ identity: snapshot.identity },recovered.session,+ snapshot.terminal,),};}@@ -154,9 +161,14 @@ class HarnessNativeSession implements NativeSession {#terminal: PrpTerminalState | null = null;#explicitlyCancelled = false;- constructor(input: OpenNativeSessionInput, session: HarnessSession) {+ constructor(+ input: OpenNativeSessionInput,+ session: HarnessSession,+ terminal?: PrpTerminalState | null,+ ) {this.#input = structuredClone(input);this.#session = session;+ this.#terminal = terminal === undefined ? null : structuredClone(terminal);}identity() {@@ -410,7 +422,12 @@ class HarnessNativeSession implements NativeSession {: String(snapshot.lastSourceSequence),semanticResult: snapshot.semanticResult?.result ?? null,terminal: this.#terminal,- activeTurnId: snapshot.activeTurnId ?? snapshot.semanticResult?.turnId ?? null,+ // Harness snapshots use an explicit null to record a settled turn. Keep+ // the semantic-result fallback solely for legacy snapshots that omitted+ // activeTurnId, or a later recovery can replay the terminal turn.+ activeTurnId: snapshot.activeTurnId === undefined+ ? snapshot.semanticResult?.turnId ?? null+ : snapshot.activeTurnId,terminalTurns: snapshot.terminalTurns ?? [],pendingRuntimeRequests: snapshot.pendingRuntimeRequests ?? [],lineage: snapshot.lineage ?? [],diff --git a/packages/paperclip-runner/src/conformance/control-plane-port.test.ts b/packages/paperclip-runner/src/conformance/control-plane-port.test.tsnew file mode 100644index 0000000000..ceea2e8050--- /dev/null+++ b/packages/paperclip-runner/src/conformance/control-plane-port.test.ts@@ -0,0 +1,40 @@+import { describe, expect, it } from "vitest";++import { MockControlPlaneAdapter } from "../mock-core/mock-control-plane-adapter.js";+import {+ CONTROL_PLANE_CONFORMANCE_EVENTS,+ CONTROL_PLANE_CONFORMANCE_OPEN,+ runControlPlanePortConformance,+} from "./control-plane-port.js";++describe("ControlPlanePort conformance", () => {+ it("runs unchanged against the mock adapter", async () => {+ const adapter = new MockControlPlaneAdapter();+ await expect(runControlPlanePortConformance({+ port: adapter,+ start: () => adapter.start(),+ stop: () => adapter.stop(),+ })).resolves.toEqual({+ eventCount: 3,+ highestContiguousSourceSeq: 3,+ duplicateDisposition: "duplicate",+ terminalReplayIdempotent: true,+ openBindingRejected: true,+ eventIdMutationRejected: true,+ eventSequenceMutationRejected: true,+ replayBindingRejected: true,+ resultMutationRejected: true,+ });+ });++ it("fails closed when a source identity is replayed with different bytes", async () => {+ const adapter = new MockControlPlaneAdapter();+ await adapter.start();+ await adapter.openRun(CONTROL_PLANE_CONFORMANCE_OPEN);+ await adapter.appendEvent(CONTROL_PLANE_CONFORMANCE_EVENTS[0]);+ await expect(adapter.appendEvent({+ ...CONTROL_PLANE_CONFORMANCE_EVENTS[0],+ payload: { backend: "forged" },+ })).rejects.toThrow("native_event_replay_conflict");+ });+});diff --git a/packages/paperclip-runner/src/conformance/harness-driver.test.ts b/packages/paperclip-runner/src/conformance/harness-driver.test.tsnew file mode 100644index 0000000000..9e7a57f02c--- /dev/null+++ b/packages/paperclip-runner/src/conformance/harness-driver.test.ts@@ -0,0 +1,286 @@+import { describe, expect, it } from "vitest";++import { DeterministicHarnessDriver } from "../mock-core/deterministic-harness-driver.js";+import {+ loadHarnessDriverConformanceFixture,+ runHarnessDriverConformance,+} from "./harness-driver.js";++describe("harness-driver conformance V1", () => {+ it("ships a deterministic fixture covering the complete Evals hook set", async () => {+ const fixture = await loadHarnessDriverConformanceFixture();+ expect(fixture.requiredCapabilities).toContain("dynamicTools");+ expect(fixture.unsupportedFeatures).toContain("steering");++ const report = await runHarnessDriverConformance({+ driver: new DeterministicHarnessDriver(),+ fixture,+ });+ expect(report).toMatchObject({+ schema: "paperclip-runner/harness-driver-conformance-report/v1",+ contractVersion: 1,+ eventCount: 7,+ semanticToolCallCount: 1,+ checks: {+ capabilityDescription: true,+ configValidation: true,+ sessionLifecycle: true,+ sessionRecovery: true,+ semanticTools: true,+ eventValidation: true,+ interruptAndCancel: true,+ usage: true,+ transcriptCompleteness: true,+ unsupportedFeatures: true,+ },+ });+ });++ it("settles an actively recovered turn when event consumption resumes", async () => {+ const driver = new DeterministicHarnessDriver();+ const session = await driver.openSession({+ runId: "run_active_recovery",+ normalizedSessionId: "session_active_recovery",+ workingDirectory: "/deterministic/conformance",+ });+ const { turnId } = await session.startTurn({+ message: { role: "user", text: "[conformance:interrupt]" },+ });+ const snapshot = await session.snapshot();+ expect(snapshot).toMatchObject({ activeTurnId: turnId, lastSourceSequence: 2 });++ const firstRecovery = await driver.recoverSession(snapshot);+ expect(firstRecovery.recovered).toBe(true);+ expect(firstRecovery.session).toBeDefined();+ const repeatedSnapshot = await firstRecovery.session!.snapshot();+ expect(repeatedSnapshot).toMatchObject({+ activeTurnId: turnId,+ lastSourceSequence: 2,+ });+ const recovery = await driver.recoverSession(repeatedSnapshot);+ expect(recovery.recovered).toBe(true);+ expect(recovery.session).toBeDefined();+ const recovered = recovery.session!;+ const recoveredEventsPromise = (async () => {+ const events = [];+ for await (const event of recovered.events()) events.push(event);+ return events;+ })();++ const events = await recoveredEventsPromise;+ expect(events.map((event) => [event.sourceSeq, event.eventType])).toEqual([+ [3, "run.result.proposed"],+ [4, "turn.interrupted"],+ [5, "run.terminal"],+ ]);+ await expect(recovered.snapshot()).resolves.toMatchObject({+ activeTurnId: null,+ semanticResult: {+ result: { reportedWorkDisposition: "yielded" },+ turnId,+ },+ lastSourceSequence: 5,+ });+ expect(events[1]?.payload).toEqual({+ reason: "deterministic_active_turn_recovered_without_live_producer",+ });+ await expect(recovered.transcript?.()).resolves.toMatchObject({+ schema: "paperclip-runner/harness-transcript/v1",+ complete: false,+ eventCount: 3,+ events: events.map((event) => expect.objectContaining({+ sourceSeq: event.sourceSeq,+ eventType: event.eventType,+ })),+ omissionReason: "pre_recovery_events_not_reconstructed",+ });+ await recovered.close({ reason: "recovered_complete" });+ await firstRecovery.session!.close({ reason: "first_recovery_complete" });+ await session.close({ reason: "original_complete", force: true });+ });++ it("interrupts a recovered turn deterministically before event consumption", async () => {+ const driver = new DeterministicHarnessDriver();+ const session = await driver.openSession({+ runId: "run_recovery_interrupt",+ normalizedSessionId: "session_recovery_interrupt",+ workingDirectory: "/deterministic/conformance",+ });+ const { turnId } = await session.startTurn({+ message: { role: "user", text: "[conformance:interrupt]" },+ });+ const recovery = await driver.recoverSession(await session.snapshot());+ const recovered = recovery.session!;++ await new Promise<void>((resolve) => setImmediate(resolve));+ await expect(recovered.interrupt?.({+ turnId,+ reason: "cancel_before_consumption",+ })).resolves.toBeUndefined();+ const events = [];+ for await (const event of recovered.events()) events.push(event);+ expect(events.map((event) => [event.sourceSeq, event.eventType])).toEqual([+ [3, "run.result.proposed"],+ [4, "turn.interrupted"],+ [5, "run.terminal"],+ ]);+ await expect(recovered.snapshot()).resolves.toMatchObject({+ activeTurnId: null,+ semanticResult: {+ result: { reportedWorkDisposition: "yielded" },+ turnId,+ },+ lastSourceSequence: 5,+ });++ await recovered.close({ reason: "recovered_complete" });+ await session.close({ reason: "original_complete", force: true });+ });++ it("acknowledges interruption after recovered event settlement starts", async () => {+ const driver = new DeterministicHarnessDriver();+ const session = await driver.openSession({+ runId: "run_recovery_interrupt_race",+ normalizedSessionId: "session_recovery_interrupt_race",+ workingDirectory: "/deterministic/conformance",+ });+ const { turnId } = await session.startTurn({+ message: { role: "user", text: "[conformance:interrupt]" },+ });+ const recovery = await driver.recoverSession(await session.snapshot());+ const recovered = recovery.session!;+ const recoveredEvents = recovered.events()[Symbol.asyncIterator]();++ const first = await recoveredEvents.next();+ expect(first.value?.eventType).toBe("run.result.proposed");+ await expect(recovered.interrupt?.({+ turnId,+ reason: "cancel_after_event_settlement_started",+ })).resolves.toBeUndefined();++ const events = first.done || first.value === undefined ? [] : [first.value];+ for await (const event of { [Symbol.asyncIterator]: () => recoveredEvents }) {+ events.push(event);+ }+ expect(events.map((event) => event.eventType)).toEqual([+ "run.result.proposed",+ "turn.interrupted",+ "run.terminal",+ ]);+ expect(events.filter((event) => event.eventType === "run.terminal")).toHaveLength(1);++ await recovered.close({ reason: "recovered_complete" });+ await session.close({ reason: "original_complete", force: true });+ });++ it("preserves a completed result when its terminal checkpoint lagged", async () => {+ const driver = new DeterministicHarnessDriver();+ const session = await driver.openSession({+ runId: "run_result_first_recovery",+ normalizedSessionId: "session_result_first_recovery",+ workingDirectory: "/deterministic/conformance",+ });+ const { turnId } = await session.startTurn({+ message: { role: "user", text: "Complete deterministically." },+ });+ const completedSnapshot = await session.snapshot();+ const recovery = await driver.recoverSession({+ ...completedSnapshot,+ activeTurnId: turnId,+ terminalTurns: [],+ });+ const recovered = recovery.session!;+ const events = [];+ for await (const event of recovered.events()) events.push(event);++ expect(events.map((event) => event.eventType)).toEqual([+ "run.result.proposed",+ "turn.completed",+ "run.terminal",+ ]);+ expect(events[0]?.payload).toMatchObject({ reportedWorkDisposition: "done" });+ expect(events[2]?.payload).toMatchObject({ runTerminalState: "succeeded" });+ await expect(recovered.snapshot()).resolves.toMatchObject({+ activeTurnId: null,+ semanticResult: completedSnapshot.semanticResult,+ });+ await recovered.close({ reason: "recovered_complete" });+ await session.close({ reason: "original_complete" });+ });++ it("does not let an interrupt overwrite a completed result-first recovery", async () => {+ const driver = new DeterministicHarnessDriver();+ const session = await driver.openSession({+ runId: "run_result_first_interrupt",+ normalizedSessionId: "session_result_first_interrupt",+ workingDirectory: "/deterministic/conformance",+ });+ const { turnId } = await session.startTurn({+ message: { role: "user", text: "Complete deterministically." },+ });+ const completedSnapshot = await session.snapshot();+ const recovery = await driver.recoverSession({+ ...completedSnapshot,+ activeTurnId: turnId,+ terminalTurns: [],+ });+ const recovered = recovery.session!;++ await expect(recovered.interrupt?.({+ turnId,+ reason: "late cancellation",+ })).resolves.toBeUndefined();+ const events = [];+ for await (const event of recovered.events()) events.push(event);+ expect(events.map((event) => event.eventType)).toEqual([+ "run.result.proposed",+ "turn.completed",+ "run.terminal",+ ]);+ await expect(recovered.snapshot()).resolves.toMatchObject({+ activeTurnId: null,+ semanticResult: completedSnapshot.semanticResult,+ });+ await recovered.close({ reason: "recovered_complete" });+ await session.close({ reason: "original_complete" });+ });++ it("preserves an interrupted result when its terminal checkpoint lagged", async () => {+ const driver = new DeterministicHarnessDriver();+ const session = await driver.openSession({+ runId: "run_yielded_result_first_recovery",+ normalizedSessionId: "session_yielded_result_first_recovery",+ workingDirectory: "/deterministic/conformance",+ });+ const { turnId } = await session.startTurn({+ message: { role: "user", text: "[conformance:interrupt]" },+ });+ await session.interrupt?.({ turnId, reason: "checkpoint_after_result" });+ const interruptedSnapshot = await session.snapshot();+ const recovery = await driver.recoverSession({+ ...interruptedSnapshot,+ activeTurnId: turnId,+ terminalTurns: [],+ });+ const recovered = recovery.session!;+ const events = [];+ for await (const event of recovered.events()) events.push(event);++ expect(events.map((event) => event.eventType)).toEqual([+ "run.result.proposed",+ "turn.interrupted",+ "run.terminal",+ ]);+ expect(events[0]?.payload).toMatchObject({+ reportedWorkDisposition: "yielded",+ continuation: { kind: "same_agent" },+ });+ expect(events[2]?.payload).toMatchObject({+ turnTerminalState: "interrupted",+ runTerminalState: "cancelled",+ reportedWorkDisposition: "yielded",+ });+ await recovered.close({ reason: "recovered_complete" });+ await session.close({ reason: "original_complete" });+ });+});diff --git a/packages/paperclip-runner/src/mock-core/deterministic-harness-driver.ts b/packages/paperclip-runner/src/mock-core/deterministic-harness-driver.tsnew file mode 100644index 0000000000..4b4c88fd87--- /dev/null+++ b/packages/paperclip-runner/src/mock-core/deterministic-harness-driver.ts@@ -0,0 +1,483 @@+import {+ type HarnessDriver,+ type HarnessDriverConfigValidation,+ type HarnessDriverDescriptor,+ type HarnessSession,+ type HarnessSessionRecoveryResult,+ type HarnessTranscriptSnapshot,+ type OpenHarnessSessionInput,+ type PersistedHarnessSession,+} from "../contracts/harness-driver.js";+import {+ createPrpSemanticToolInputEnvelope,+ createPrpSemanticToolResultEnvelope,+} from "../protocol/semantic-tool-receipts.js";+import type {+ PrpEvent,+ PrpStructuredRunResult,+ PrpTerminalState,+} from "../protocol/replay-contract.js";++export const DETERMINISTIC_HARNESS_DRIVER_CONFIG_SCHEMA =+ "paperclip-runner/deterministic-harness-driver-config/v1" as const;++export interface DeterministicHarnessDriverConfig {+ schema: typeof DETERMINISTIC_HARNESS_DRIVER_CONFIG_SCHEMA;+ scenario: "semantic-tool-success";+}++const DEFAULT_CONFIG: DeterministicHarnessDriverConfig = {+ schema: DETERMINISTIC_HARNESS_DRIVER_CONFIG_SCHEMA,+ scenario: "semantic-tool-success",+};++function parseConfig(value: unknown): HarnessDriverConfigValidation {+ if (typeof value !== "object" || value === null || Array.isArray(value)) {+ return {+ ok: false,+ config: null,+ issues: [{ path: "/", code: "type", message: "config must be an object" }],+ };+ }+ const config = value as Record<string, unknown>;+ if (config.schema !== DETERMINISTIC_HARNESS_DRIVER_CONFIG_SCHEMA) {+ return {+ ok: false,+ config: null,+ issues: [{+ path: "/schema",+ code: "unsupported_schema",+ message: `schema must be ${DETERMINISTIC_HARNESS_DRIVER_CONFIG_SCHEMA}`,+ }],+ };+ }+ if (config.scenario !== "semantic-tool-success") {+ return {+ ok: false,+ config: null,+ issues: [{+ path: "/scenario",+ code: "unsupported_scenario",+ message: "scenario must be semantic-tool-success",+ }],+ };+ }+ return { ok: true, config: structuredClone(config), issues: [] };+}++/** Provider-free fake used by packed consumers and App/Evals conformance. */+export class DeterministicHarnessDriver implements HarnessDriver {+ readonly #config: DeterministicHarnessDriverConfig;++ constructor(config: DeterministicHarnessDriverConfig = DEFAULT_CONFIG) {+ const validation = parseConfig(config);+ if (!validation.ok) throw new Error(validation.issues[0]?.message ?? "invalid config");+ this.#config = structuredClone(config);+ }++ async descriptor(): Promise<HarnessDriverDescriptor> {+ return {+ kind: "paperclip-deterministic",+ displayName: "Paperclip deterministic harness driver",+ version: "1.0.0",+ protocolVersion: "prp.v1",+ capabilities: {+ resume: true,+ typedEvents: true,+ steering: false,+ interruption: true,+ structuredResult: true,+ read: true,+ reconciliation: true,+ usage: true,+ dynamicTools: true,+ runtimeRequestResolution: false,+ goals: false,+ threadLineage: false,+ unsupported: ["steering", "runtimeRequestResolution", "goals", "threadLineage"],+ },+ };+ }++ async validateConfig(config: unknown): Promise<HarnessDriverConfigValidation> {+ return parseConfig(config);+ }++ async openSession(input: OpenHarnessSessionInput): Promise<HarnessSession> {+ return new DeterministicHarnessSession(input, this.#config);+ }++ async recoverSession(+ snapshot: PersistedHarnessSession,+ ): Promise<HarnessSessionRecoveryResult> {+ if (+ snapshot.driverKind !== "paperclip-deterministic"+ || snapshot.runId === undefined+ || snapshot.normalizedSessionId === undefined+ ) {+ return { recovered: false, reason: "snapshot does not belong to the deterministic driver" };+ }+ return {+ recovered: true,+ session: new DeterministicHarnessSession({+ runId: snapshot.runId,+ normalizedSessionId: snapshot.normalizedSessionId,+ workingDirectory: "/deterministic/recovered",+ }, this.#config, snapshot),+ };+ }+}++class DeterministicHarnessSession implements HarnessSession {+ readonly #input: OpenHarnessSessionInput;+ readonly #config: DeterministicHarnessDriverConfig;+ #events: PrpEvent[] = [];+ #semanticResult: PrpStructuredRunResult | null = null;+ #turnId: string | null = null;+ #closed = false;+ #active = false;+ #recoveredActiveTurn = false;+ #recoveredTurnSettled = false;+ #nextSourceSeq = 1;+ readonly #transcriptOmissionReason: string | null;+ readonly #eventWaiters = new Set<() => void>();++ constructor(+ input: OpenHarnessSessionInput,+ config: DeterministicHarnessDriverConfig,+ snapshot?: PersistedHarnessSession,+ ) {+ this.#input = structuredClone(input);+ this.#config = structuredClone(config);+ this.#turnId = snapshot?.activeTurnId ?? snapshot?.semanticResult?.turnId ?? null;+ this.#semanticResult = snapshot?.semanticResult?.result ?? null;+ this.#active = snapshot?.activeTurnId !== null && snapshot?.activeTurnId !== undefined;+ this.#recoveredActiveTurn = this.#active;+ this.#nextSourceSeq = (snapshot?.lastSourceSequence ?? 0) + 1;+ this.#transcriptOmissionReason = snapshot === undefined+ ? null+ : "pre_recovery_events_not_reconstructed";+ }++ ids() {+ return {+ driverSessionId: `driver_${this.#input.normalizedSessionId}`,+ providerSessionId: null,+ displayId: this.#input.normalizedSessionId,+ };+ }++ async *events(): AsyncIterable<PrpEvent> {+ if (this.#recoveredActiveTurn && this.#active && this.#turnId !== null) {+ // The deterministic fake has no provider process that can continue an+ // in-flight turn after reconstruction. Produce one conservative terminal+ // outcome when consumption resumes so the native loop cannot wait until+ // its global timeout. An explicit interrupt issued before consumption+ // still wins and supplies its own reason.+ if (!this.#settleRecoveredSemanticResult()) {+ this.#recoveredActiveTurn = false;+ this.#semanticResult = interruptedResult(+ this.#input.runId,+ "The deterministic provider was unavailable after active-turn recovery.",+ );+ this.#appendEvents(+ this.#event("run.result.proposed", this.#semanticResult),+ this.#event("turn.interrupted", {+ reason: "deterministic_active_turn_recovered_without_live_producer",+ }),+ this.#event("run.terminal", cancelledTerminal(), { turn: false }),+ );+ this.#recoveredTurnSettled = true;+ }+ this.#active = false;+ }+ let index = 0;+ while (true) {+ while (index < this.#events.length) {+ const event = this.#events[index++]!;+ yield structuredClone(event);+ if (event.eventType === "run.terminal") return;+ }+ if (this.#closed) return;+ await new Promise<void>((resolve) => this.#eventWaiters.add(resolve));+ }+ }++ async startTurn(input: { message: { role: "user"; text: string } }): Promise<{ turnId: string }> {+ this.#assertOpen();+ if (this.#turnId !== null) throw new Error("deterministic session accepts one turn");+ this.#turnId = `turn_${this.#input.runId}`;+ this.#active = true;+ this.#appendEvents(+ this.#event("session.started", {}, { turn: false }),+ this.#event("turn.started", { message: input.message.text }),+ );+ if (input.message.text.includes("[conformance:interrupt]")) {+ return { turnId: this.#turnId };+ }++ const itemId = `item_${this.#input.runId}`;+ const callId = `call_${this.#input.runId}`;+ const correlation = {+ runId: this.#input.runId,+ normalizedSessionId: this.#input.normalizedSessionId,+ turnId: this.#turnId,+ itemId,+ };+ const inputEnvelope = createPrpSemanticToolInputEnvelope({+ operationId: "finish_task",+ callId,+ correlation,+ idempotencyKey: `finish_${this.#input.runId}`,+ content: { summary: "Deterministic conformance complete." },+ });+ const resultEnvelope = createPrpSemanticToolResultEnvelope({+ operationId: "finish_task",+ callId,+ correlation,+ idempotencyKey: `finish_${this.#input.runId}`,+ content: { disposition: "applied", status: "done" },+ outcome: "succeeded",+ code: "applied",+ retryable: false,+ authorizationBoundary: "active_task",+ auditReceiptId: `audit_${this.#input.runId}`,+ });+ this.#appendEvents(+ this.#event("mcp_app.tool_input", { semantic_tool: inputEnvelope }, { itemId }),+ this.#event("mcp_app.tool_result", { semantic_tool: resultEnvelope }, { itemId }),+ );+ this.#semanticResult = completedResult();+ const terminal = completedTerminal();+ this.#appendEvents(+ this.#event("run.result.proposed", this.#semanticResult),+ this.#event("turn.completed", {}),+ this.#event("run.terminal", terminal, { turn: false }),+ );+ this.#active = false;+ return { turnId: this.#turnId };+ }++ async interrupt(input: { turnId?: string; reason?: string }): Promise<void> {+ this.#assertOpen();+ if (this.#turnId === null) throw new Error("no active turn to interrupt");+ if (input.turnId !== undefined && input.turnId !== this.#turnId) {+ throw new Error(`turn ${input.turnId} is not active`);+ }+ // Event consumption can conservatively settle a reconstructed turn before+ // its first event is yielded. Treat a concurrent interrupt as an+ // idempotent acknowledgement once that recovered terminal is committed,+ // rather than making cancellation depend on iterator scheduling.+ if (!this.#active) {+ if (this.#recoveredTurnSettled) return;+ throw new Error("no active turn to interrupt");+ }+ if (this.#settleRecoveredSemanticResult()) return;+ this.#semanticResult = interruptedResult(+ this.#input.runId,+ input.reason ?? "The deterministic turn was interrupted.",+ );+ this.#appendEvents(+ this.#event("run.result.proposed", this.#semanticResult),+ this.#event("turn.interrupted", { reason: input.reason ?? "interrupted" }),+ this.#event("run.terminal", cancelledTerminal(), { turn: false }),+ );+ this.#active = false;+ }++ #settleRecoveredSemanticResult(): boolean {+ if (+ !this.#recoveredActiveTurn+ || !this.#active+ || this.#turnId === null+ || this.#semanticResult === null+ ) return false;+ this.#recoveredActiveTurn = false;+ // A result-first checkpoint can still carry activeTurnId when the+ // terminal checkpoint lagged behind the provider work. Preserve the+ // authoritative result even if cancellation races event consumption.+ if (this.#semanticResult.reportedWorkDisposition === "yielded") {+ this.#appendEvents(+ this.#event("run.result.proposed", this.#semanticResult),+ this.#event("turn.interrupted", {+ reason: "deterministic_active_turn_recovered_with_yielded_result",+ }),+ this.#event("run.terminal", cancelledTerminal(), { turn: false }),+ );+ } else {+ this.#appendEvents(+ this.#event("run.result.proposed", this.#semanticResult),+ this.#event("turn.completed", {}),+ this.#event(+ "run.terminal",+ completedTerminal(this.#semanticResult.reportedWorkDisposition),+ { turn: false },+ ),+ );+ }+ this.#recoveredTurnSettled = true;+ this.#active = false;+ return true;+ }++ async read(): Promise<Record<string, unknown>> {+ return { scenario: this.#config.scenario, eventCount: this.#events.length };+ }++ async reconcile(): Promise<Record<string, unknown>> {+ return { active: this.#active, closed: this.#closed, eventCount: this.#events.length };+ }++ async usage(): Promise<Record<string, unknown>> {+ return {+ inputTokens: this.#turnId === null ? 0 : 12,+ outputTokens: this.#semanticResult === null ? 0 : 8,+ totalTokens: this.#turnId === null ? 0 : this.#semanticResult === null ? 12 : 20,+ requestCount: this.#turnId === null ? 0 : 1,+ cost: { currency: "USD", amountMicros: 0 },+ };+ }++ async transcript(): Promise<HarnessTranscriptSnapshot> {+ return {+ schema: "paperclip-runner/harness-transcript/v1",+ complete: this.#transcriptOmissionReason === null,+ eventCount: this.#events.length,+ events: structuredClone(this.#events),+ omissionReason: this.#transcriptOmissionReason,+ };+ }++ async snapshot(): Promise<PersistedHarnessSession> {+ return {+ driverKind: "paperclip-deterministic",+ driverSessionId: `driver_${this.#input.normalizedSessionId}`,+ providerSessionId: null,+ runId: this.#input.runId,+ normalizedSessionId: this.#input.normalizedSessionId,+ activeTurnId: this.#active ? this.#turnId : null,+ lastSourceSequence: this.#nextSourceSeq - 1,+ semanticResult: this.#semanticResult === null || this.#turnId === null+ ? null+ : {+ result: structuredClone(this.#semanticResult),+ fingerprint: JSON.stringify(this.#semanticResult),+ turnId: this.#turnId,+ },+ terminalTurns: this.#events.some((event) => event.eventType === "run.terminal") && this.#turnId !== null+ ? [{ turnId: this.#turnId, fingerprint: `terminal_${this.#input.runId}` }]+ : [],+ };+ }++ async close(input: { reason: string; force?: boolean }): Promise<void> {+ if (this.#closed) return;+ if (this.#active) {+ await this.interrupt({ reason: input.reason });+ }+ this.#closed = true;+ this.#notifyEventWaiters();+ }++ #appendEvents(...events: PrpEvent[]): void {+ this.#events.push(...events);+ this.#notifyEventWaiters();+ }++ #notifyEventWaiters(): void {+ for (const resolve of this.#eventWaiters) resolve();+ this.#eventWaiters.clear();+ }++ #event(+ eventType: PrpEvent["eventType"],+ payload: Record<string, unknown> | PrpStructuredRunResult | PrpTerminalState,+ options: { itemId?: string; turn?: boolean } = {},+ ): PrpEvent {+ const sourceSeq = this.#nextSourceSeq++;+ return {+ schema: "paperclip.prp.event.v1",+ sourceEventId: `event_${this.#input.runId}_${sourceSeq}`,+ sourceSeq,+ sourceInstanceId: `runner_${this.#input.runId}`,+ sourceKind: "runner",+ runId: this.#input.runId,+ normalizedSessionId: this.#input.normalizedSessionId,+ ...(options.turn === false || this.#turnId === null ? {} : { turnId: this.#turnId }),+ ...(options.itemId === undefined ? {} : { itemId: options.itemId }),+ eventType,+ schemaVersion: 1,+ priority: eventType === "run.terminal" || eventType === "run.result.proposed" ? 0 : 1,+ emittedAt: new Date(Date.UTC(2026, 7, 11, 12, 0, sourceSeq)).toISOString(),+ payload: structuredClone(payload),+ } as PrpEvent;+ }++ #assertOpen(): void {+ if (this.#closed) throw new Error("deterministic session is closed");+ }+}++function completedResult(): PrpStructuredRunResult {+ return {+ schema: "paperclip.run_result.v1",+ reportedWorkDisposition: "done",+ summary: "Deterministic harness-driver conformance completed.",+ completionClaim: {+ contractRevision: "harness-driver-conformance-v1",+ objectiveSatisfied: true,+ criteria: [],+ remainingWork: [],+ },+ evidence: [],+ verification: [{ commandOrCheck: "deterministic harness flow", status: "passed" }],+ attentionRequests: [],+ artifacts: [],+ };+}++function completedTerminal(+ disposition: PrpTerminalState["reportedWorkDisposition"] = "done",+): PrpTerminalState {+ return {+ schema: "paperclip.prp.terminal.v1",+ turnTerminalState: "completed",+ runTerminalState: "succeeded",+ reportedWorkDisposition: disposition,+ };+}++function interruptedResult(runId: string, summary: string): PrpStructuredRunResult {+ return {+ schema: "paperclip.run_result.v1",+ reportedWorkDisposition: "yielded",+ summary,+ completionClaim: {+ contractRevision: "harness-driver-conformance-v1",+ objectiveSatisfied: false,+ criteria: [],+ remainingWork: [{+ description: "Resume the interrupted work in a live provider session.",+ blocksCompletion: true,+ }],+ },+ evidence: [],+ verification: [],+ attentionRequests: [],+ artifacts: [],+ continuation: {+ kind: "same_agent",+ summary: "Resume the interrupted deterministic turn.",+ idempotencyKey: `resume_deterministic_${runId}`,+ },+ };+}++function cancelledTerminal(): PrpTerminalState {+ return {+ schema: "paperclip.prp.terminal.v1",+ turnTerminalState: "interrupted",+ runTerminalState: "cancelled",+ reportedWorkDisposition: "yielded",+ };+}diff --git a/packages/paperclip-runner/src/mock-core/mock-control-plane-adapter.test.ts b/packages/paperclip-runner/src/mock-core/mock-control-plane-adapter.test.tsnew file mode 100644index 0000000000..605ea6b2b1--- /dev/null+++ b/packages/paperclip-runner/src/mock-core/mock-control-plane-adapter.test.ts@@ -0,0 +1,32 @@+import { describe, expect, it } from "vitest";++import { loadConformanceFixture } from "../protocol/conformance-fixture.js";+import { replayConformanceFixture } from "../tracer/conformance-runner.js";+import { MockControlPlaneAdapter } from "./mock-control-plane-adapter.js";++describe("MockControlPlaneAdapter", () => {+ it("exercises the complete control-plane contract path", async () => {+ const fixture = await loadConformanceFixture();+ const mockCore = new MockControlPlaneAdapter();++ await mockCore.start();+ await replayConformanceFixture(mockCore, fixture);++ expect(mockCore.snapshot()).toMatchObject({+ lifecycle: "running",+ openedRun: { identity: fixture.run, backendKind: "mock" },+ events: fixture.events,+ result: fixture.result,+ });+ await mockCore.stop();+ });++ it("rejects events before startup", async () => {+ const fixture = await loadConformanceFixture();+ const mockCore = new MockControlPlaneAdapter();++ await expect(mockCore.appendEvent(fixture.events[0]!)).rejects.toThrow(+ "mock control plane must be started first",+ );+ });+});diff --git a/packages/paperclip-runner/src/mock-core/mock-control-plane-adapter.ts b/packages/paperclip-runner/src/mock-core/mock-control-plane-adapter.tsnew file mode 100644index 0000000000..0ca497af6b--- /dev/null+++ b/packages/paperclip-runner/src/mock-core/mock-control-plane-adapter.ts@@ -0,0 +1,199 @@+import type {+ AppendedEventReceipt,+ CompleteControlPlaneRunInput,+ ControlPlanePort,+ OpenControlPlaneRunInput,+ ReplayControlPlaneEventsInput,+ ReplayedControlPlaneEvents,+} from "../contracts/control-plane-port.js";+import type { NativeRunEvent, NativeRunResult } from "../contracts/types.js";+import {+ validatePrpEvent,+ validatePrpStructuredRunResult,+ type PrpEvent,+} from "../protocol/replay-contract.js";++export interface MockControlPlaneSnapshot {+ lifecycle: "stopped" | "running";+ openedRun: OpenControlPlaneRunInput | null;+ events: Array<NativeRunEvent | PrpEvent>;+ result: NativeRunResult | CompleteControlPlaneRunInput | null;+}++/** In-memory control-plane shell used by standalone tests and tutorials. */+export class MockControlPlaneAdapter implements ControlPlanePort {+ #lifecycle: "stopped" | "running" = "stopped";+ #openedRun: OpenControlPlaneRunInput | null = null;+ #events: Array<NativeRunEvent | PrpEvent> = [];+ #result: NativeRunResult | CompleteControlPlaneRunInput | null = null;++ async start(): Promise<void> {+ if (this.#lifecycle === "running") {+ throw new Error("mock control plane is already running");+ }+ this.#lifecycle = "running";+ }++ async stop(): Promise<void> {+ this.#lifecycle = "stopped";+ }++ async openRun(input: OpenControlPlaneRunInput): Promise<void> {+ this.#assertRunning();+ if (this.#openedRun !== null) {+ throw new Error("mock control plane accepts one Conformance run");+ }+ this.#openedRun = structuredClone(input);+ }++ async appendEvent(event: NativeRunEvent | PrpEvent): Promise<AppendedEventReceipt> {+ const runId = this.#requireRunId();+ if (event.runId !== runId) {+ throw new Error("event runId does not match the opened run");+ }+ if ("sourceEventId" in event) {+ const validation = validatePrpEvent(event);+ if (!validation.ok) {+ throw new Error(`event failed validation: ${validation.issues[0]?.message ?? "invalid event"}`);+ }+ const sameId = this.#events.find(+ (candidate): candidate is PrpEvent =>+ "sourceEventId" in candidate && candidate.sourceEventId === event.sourceEventId,+ );+ const sameSequence = this.#events.find(+ (candidate): candidate is PrpEvent =>+ "sourceSeq" in candidate &&+ candidate.sourceInstanceId === event.sourceInstanceId &&+ candidate.sourceSeq === event.sourceSeq,+ );+ for (const candidate of [sameId, sameSequence]) {+ if (candidate !== undefined) {+ if (canonicalJson(candidate) !== canonicalJson(event)) {+ throw new Error("native_event_replay_conflict");+ }+ return {+ cursor: event.sourceSeq,+ highestContiguousSourceSeq: this.#highestContiguous(event.sourceInstanceId),+ disposition: "duplicate",+ };+ }+ }+ this.#events.push(structuredClone(event));+ return {+ cursor: event.sourceSeq,+ highestContiguousSourceSeq: this.#highestContiguous(event.sourceInstanceId),+ disposition: "committed",+ };+ }++ const expectedSequence = this.#events.length + 1;+ if (event.sequence !== expectedSequence) {+ throw new Error(`event sequence must be ${expectedSequence}`);+ }+ this.#events.push(structuredClone(event));+ return {+ cursor: event.sequence,+ highestContiguousSourceSeq: event.sequence,+ disposition: "committed",+ };+ }++ async replayEvents(+ input: ReplayControlPlaneEventsInput,+ ): Promise<ReplayedControlPlaneEvents> {+ const runId = this.#requireRunId();+ if (input.runId !== runId) {+ throw new Error("replay runId does not match the opened run");+ }+ const events = this.#events+ .filter(+ (event): event is PrpEvent =>+ "sourceSeq" in event &&+ event.sourceInstanceId === input.sourceInstanceId &&+ event.sourceSeq > input.afterSourceSeq,+ )+ .sort((left, right) => left.sourceSeq - right.sourceSeq)+ .slice(0, input.limit)+ .map((event) => structuredClone(event));+ return {+ events,+ highestContiguousSourceSeq: this.#highestContiguous(input.sourceInstanceId),+ };+ }++ async completeRun(result: NativeRunResult | CompleteControlPlaneRunInput): Promise<void> {+ const runId = this.#requireRunId();+ const resultRunId = "runId" in result ? result.runId : runId;+ if (resultRunId !== runId) {+ throw new Error("result runId does not match the opened run");+ }+ if ("terminal" in result) {+ const validation = validatePrpStructuredRunResult(result.result);+ if (!validation.ok) {+ throw new Error("native_result_invalid");+ }+ const terminalEvent = this.#events.find(+ (event) => "eventType" in event && event.eventType === "run.terminal",+ );+ if (terminalEvent === undefined) {+ throw new Error("run.terminal must be ingested before the result");+ }+ } else if (this.#events.at(-1)?.type !== "run.completed") {+ throw new Error("run.completed must be ingested before the result");+ }+ if (this.#result !== null) {+ if (canonicalJson(this.#result) === canonicalJson(result)) return;+ throw new Error("native_result_replay_conflict");+ }+ this.#result = structuredClone(result);+ }++ snapshot(): MockControlPlaneSnapshot {+ return {+ lifecycle: this.#lifecycle,+ openedRun: this.#openedRun === null ? null : structuredClone(this.#openedRun),+ events: structuredClone(this.#events),+ result: this.#result === null ? null : structuredClone(this.#result),+ };+ }++ #assertRunning(): void {+ if (this.#lifecycle !== "running") {+ throw new Error("mock control plane must be started first");+ }+ }++ #requireRunId(): string {+ this.#assertRunning();+ if (this.#openedRun === null) {+ throw new Error("a run must be opened first");+ }+ return this.#openedRun.identity.runId;+ }++ #highestContiguous(sourceInstanceId: string): number {+ const sequences = new Set(+ this.#events+ .filter(+ (event): event is PrpEvent =>+ "sourceSeq" in event && event.sourceInstanceId === sourceInstanceId,+ )+ .map((event) => event.sourceSeq),+ );+ let cursor = 0;+ while (sequences.has(cursor + 1)) cursor += 1;+ return cursor;+ }+}++function canonicalJson(value: unknown): string {+ if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;+ if (typeof value === "object" && value !== null) {+ const record = value as Record<string, unknown>;+ return `{${Object.keys(record)+ .sort()+ .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)+ .join(",")}}`;+ }+ return JSON.stringify(value) ?? "undefined";+}diff --git a/packages/paperclip-runner/src/protocol/conformance-fixture.test.ts b/packages/paperclip-runner/src/protocol/conformance-fixture.test.tsnew file mode 100644index 0000000000..58e81d18de--- /dev/null+++ b/packages/paperclip-runner/src/protocol/conformance-fixture.test.ts@@ -0,0 +1,53 @@+import { describe, expect, it } from "vitest";++import {+ loadConformanceFixture,+ validateConformanceFixture,+} from "./conformance-fixture.js";++describe("Conformance fixture validation", () => {+ it("accepts the package-owned fixture", async () => {+ const fixture = await loadConformanceFixture();++ expect(fixture.run.runId).toBe("run_conformance_0001");+ expect(fixture.events.map((event) => event.type)).toEqual([+ "run.started",+ "run.completed",+ ]);+ expect(fixture.result.status).toBe("succeeded");+ });++ it("rejects a non-contiguous event sequence", () => {+ expect(() =>+ validateConformanceFixture({+ schemaVersion: "paperclip.runner.conformance.fixture.v1",+ run: {+ runId: "run_conformance_0001",+ sessionId: "session_conformance_0001",+ companyId: "company_conformance",+ issueId: "issue_conformance",+ agentId: "agent_conformance",+ },+ events: [+ {+ eventId: "event_conformance_0001",+ runId: "run_conformance_0001",+ sequence: 2,+ type: "run.started",+ },+ {+ eventId: "event_conformance_0002",+ runId: "run_conformance_0001",+ sequence: 3,+ type: "run.completed",+ },+ ],+ result: {+ runId: "run_conformance_0001",+ status: "succeeded",+ summary: "Standalone Conformance fixture accepted.",+ },+ }),+ ).toThrow("events[0].sequence must be 1");+ });+});diff --git a/packages/paperclip-runner/src/protocol/conformance-fixture.ts b/packages/paperclip-runner/src/protocol/conformance-fixture.tsnew file mode 100644index 0000000000..4303a9d58d--- /dev/null+++ b/packages/paperclip-runner/src/protocol/conformance-fixture.ts@@ -0,0 +1,127 @@+import { readFile } from "node:fs/promises";++import type {+ NativeRunEvent,+ NativeRunEventType,+ NativeRunIdentity,+ NativeRunResult,+ NativeRunStatus,+} from "../contracts/types.js";++export const CONFORMANCE_FIXTURE_SCHEMA = "paperclip.runner.conformance.fixture.v1";++export interface ConformanceFixture {+ schemaVersion: typeof CONFORMANCE_FIXTURE_SCHEMA;+ run: NativeRunIdentity;+ events: NativeRunEvent[];+ result: NativeRunResult;+}++export const conformanceFixtureUrl = new URL(+ "../../protocol/fixtures/conformance-minimal-run.json",+ import.meta.url,+);++function asRecord(value: unknown, path: string): Record<string, unknown> {+ if (typeof value !== "object" || value === null || Array.isArray(value)) {+ throw new Error(`${path} must be an object`);+ }+ return value as Record<string, unknown>;+}++function asIdentifier(value: unknown, path: string): string {+ if (typeof value !== "string" || !/^[a-z][a-z0-9_]*$/.test(value)) {+ throw new Error(`${path} must be a stable lowercase identifier`);+ }+ return value;+}++function asString(value: unknown, path: string): string {+ if (typeof value !== "string" || value.trim().length === 0) {+ throw new Error(`${path} must be a non-empty string`);+ }+ return value;+}++function parseRun(value: unknown): NativeRunIdentity {+ const run = asRecord(value, "run");+ return {+ runId: asIdentifier(run.runId, "run.runId"),+ sessionId: asIdentifier(run.sessionId, "run.sessionId"),+ companyId: asIdentifier(run.companyId, "run.companyId"),+ issueId: asIdentifier(run.issueId, "run.issueId"),+ agentId: asIdentifier(run.agentId, "run.agentId"),+ };+}++function parseEvents(value: unknown, runId: string): NativeRunEvent[] {+ if (!Array.isArray(value) || value.length < 2) {+ throw new Error("events must contain at least run.started and run.completed");+ }++ const allowedTypes = new Set<NativeRunEventType>(["run.started", "run.completed"]);+ const events = value.map((entry, index) => {+ const event = asRecord(entry, `events[${index}]`);+ const type = asString(event.type, `events[${index}].type`) as NativeRunEventType;+ if (!allowedTypes.has(type)) {+ throw new Error(`events[${index}].type is unsupported`);+ }+ if (event.runId !== runId) {+ throw new Error(`events[${index}].runId must match run.runId`);+ }+ if (event.sequence !== index + 1) {+ throw new Error(`events[${index}].sequence must be ${index + 1}`);+ }+ return {+ eventId: asIdentifier(event.eventId, `events[${index}].eventId`),+ runId,+ sequence: index + 1,+ type,+ };+ });++ if (events[0]?.type !== "run.started") {+ throw new Error("the first event must be run.started");+ }+ if (events.at(-1)?.type !== "run.completed") {+ throw new Error("the final event must be run.completed");+ }+ return events;+}++function parseResult(value: unknown, runId: string): NativeRunResult {+ const result = asRecord(value, "result");+ if (result.runId !== runId) {+ throw new Error("result.runId must match run.runId");+ }+ const status = asString(result.status, "result.status") as NativeRunStatus;+ if (status !== "succeeded") {+ throw new Error("the Conformance fixture result must be succeeded");+ }+ return {+ runId,+ status,+ summary: asString(result.summary, "result.summary"),+ };+}++export function validateConformanceFixture(value: unknown): ConformanceFixture {+ const fixture = asRecord(value, "fixture");+ if (fixture.schemaVersion !== CONFORMANCE_FIXTURE_SCHEMA) {+ throw new Error(`schemaVersion must be ${CONFORMANCE_FIXTURE_SCHEMA}`);+ }+ const run = parseRun(fixture.run);+ return {+ schemaVersion: CONFORMANCE_FIXTURE_SCHEMA,+ run,+ events: parseEvents(fixture.events, run.runId),+ result: parseResult(fixture.result, run.runId),+ };+}++export async function loadConformanceFixture(+ url: URL = conformanceFixtureUrl,+): Promise<ConformanceFixture> {+ const contents = await readFile(url, "utf8");+ return validateConformanceFixture(JSON.parse(contents) as unknown);+}diff --git a/packages/paperclip-runner/src/testing.ts b/packages/paperclip-runner/src/testing.tsindex cfc6a4bb0b..14a11890a1 100644--- a/packages/paperclip-runner/src/testing.ts+++ b/packages/paperclip-runner/src/testing.ts@@ -9,4 +9,8 @@ export * from "./index.js";export * from "./conformance/control-plane-port.js";export * from "./conformance/harness-driver.js";export * from "./conformance/semantic-conformance.js";+export * from "./mock-core/deterministic-harness-driver.js";+export * from "./mock-core/mock-control-plane-adapter.js";+export * from "./protocol/conformance-fixture.js";export * from "./protocol/replay-loader.js";+export * from "./tracer/conformance-runner.js";diff --git a/packages/paperclip-runner/src/tracer/conformance-runner.test.ts b/packages/paperclip-runner/src/tracer/conformance-runner.test.tsnew file mode 100644index 0000000000..6470818d78--- /dev/null+++ b/packages/paperclip-runner/src/tracer/conformance-runner.test.ts@@ -0,0 +1,21 @@+import { readFile } from "node:fs/promises";++import { describe, expect, it } from "vitest";++import { MockControlPlaneAdapter } from "../mock-core/mock-control-plane-adapter.js";+import { runConformanceTracer } from "./conformance-runner.js";++const expectedOutputUrl = new URL(+ "../../protocol/fixtures/conformance-expected-output.json",+ import.meta.url,+);++describe("Conformance tracer", () => {+ it("prints a stable identity and result and stops the mock core", async () => {+ const mockCore = new MockControlPlaneAdapter();+ const expectedOutput = (await readFile(expectedOutputUrl, "utf8")).trimEnd();++ await expect(runConformanceTracer(mockCore)).resolves.toBe(expectedOutput);+ expect(mockCore.snapshot().lifecycle).toBe("stopped");+ });+});diff --git a/packages/paperclip-runner/src/tracer/conformance-runner.ts b/packages/paperclip-runner/src/tracer/conformance-runner.tsnew file mode 100644index 0000000000..a598a8ea2d--- /dev/null+++ b/packages/paperclip-runner/src/tracer/conformance-runner.ts@@ -0,0 +1,59 @@+import type { ControlPlanePort } from "../contracts/control-plane-port.js";+import { MockControlPlaneAdapter } from "../mock-core/mock-control-plane-adapter.js";+import {+ loadConformanceFixture,+ type ConformanceFixture,+} from "../protocol/conformance-fixture.js";++export const CONFORMANCE_OUTPUT_SCHEMA = "paperclip.runner.conformance.output.v1";++export interface ConformanceTracerOutput {+ schemaVersion: typeof CONFORMANCE_OUTPUT_SCHEMA;+ runIdentity: {+ runId: string;+ sessionId: string;+ };+ result: {+ status: "succeeded";+ summary: string;+ };+}++export async function replayConformanceFixture(+ controlPlane: ControlPlanePort,+ fixture: ConformanceFixture,+): Promise<void> {+ await controlPlane.openRun({ identity: fixture.run, backendKind: "mock" });+ for (const event of fixture.events) {+ await controlPlane.appendEvent(event);+ }+ await controlPlane.completeRun(fixture.result);+}++export function formatConformanceOutput(fixture: ConformanceFixture): string {+ const output: ConformanceTracerOutput = {+ schemaVersion: CONFORMANCE_OUTPUT_SCHEMA,+ runIdentity: {+ runId: fixture.run.runId,+ sessionId: fixture.run.sessionId,+ },+ result: {+ status: "succeeded",+ summary: fixture.result.summary,+ },+ };+ return JSON.stringify(output);+}++export async function runConformanceTracer(+ mockCore = new MockControlPlaneAdapter(),+): Promise<string> {+ const fixture = await loadConformanceFixture();+ await mockCore.start();+ try {+ await replayConformanceFixture(mockCore, fixture);+ return formatConformanceOutput(fixture);+ } finally {+ await mockCore.stop();+ }+}