@anureo/conformance 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,11 @@
 # @anureo/conformance
 
-The shared conformance suite for the Anureo SDK. It drives any `HarnessAdapter` through the public runtime API and verifies the behavioral contract that AHP implies — so "implements AHP" has a concrete, repeatable meaning: pass the suite, and every host built on the SDK can use your backend.
+The Anureo SDK conformance suites drive the revised AHP v1 client through the public runtime API.
+The shared suite, `runConformance`, drives any `HarnessAdapter` to verify the shared behavioral contract that AHP implies.
+Passing the shared suite establishes conformance only within that shared acceptance scope.
+Full adapter conformance also requires the native suite, `runNativeConformance`, which covers overlap,
+active close and independent observations, with native evidence supplied by adapter fixtures.
+Passing a subset does not establish full adapter conformance. See the [acceptance plan](../../docs/native-harness-lifecycle.md#9-实施顺序与验收).
 
 > Part of the [Anureo SDK workspace](../../README.md). Install with `npm install @anureo/conformance`.
 
@@ -28,7 +33,7 @@ if (!report.passed) {
 
 Each case returns `passed`, `failed`, or `not-applicable`:
 
-- A scenario is **not-applicable** when its capability was not declared at initialization (e.g. `steer` for a backend without `turn.steer`).
+- A scenario is **not-applicable** when its capability was not declared at initialization (e.g. `steer` for a backend without `input.steer.atomicMatch`).
 - A **declared** capability must actually pass its scenario — a missing fixture is a failure, not a skip. Declaring fork without a working fork is exactly the bug this suite exists to catch.
 
 ## Scenarios
@@ -49,7 +54,7 @@ Also included: `ScriptedClaudeQuery` / `createFakeClaudeQuery` — a minimal inj
 
 ## Scripted backends under scripts/
 
-`scripts/` contains standalone fake backend processes (`fake-acp.ts`, `fake-ahp.ts`, `fake-codex.ts`, `fake-wire.ts`) that speak their real native wire protocols over stdio. They power the pack-verification flows: a clean npm install of the built packages must complete real ACP and AHP conversations — text, rejected approvals, interrupts — against these processes.
+`scripts/` contains standalone fake backend processes (`fake-acp.ts`, `fake-ahp.ts`, `fake-codex.ts`, `fake-wire.ts`) that speak their real native wire protocols over stdio. Conformance tests use these processes to exercise real wire conversations over stdio.
 
 ## Development
 
@@ -57,7 +62,6 @@ Also included: `ScriptedClaudeQuery` / `createFakeClaudeQuery` — a minimal inj
 cd packages/conformance
 bun run typecheck
 bun test src
-bun examples/standalone.ts   # scripted round-trip without any backend
 ```
 
 ## Documentation

package/examples/standalone.d.ts

@@ -0,0 +1 @@
+export {};

package/examples/standalone.js

@@ -0,0 +1,16 @@
+import { createClient } from '@anureo/sdk';
+import { createScriptedAdapter } from '@anureo/conformance/fake';
+// Runs a scripted backend without an account or model service.
+const client = await createClient({
+    adapter: createScriptedAdapter(),
+    identity: { adapterId: 'scripted', runtimeConfigId: 'local' },
+});
+try {
+    const session = await client.sessions.create({ cwd: process.cwd() });
+    const turn = await session.submit({ input: 'Hello from Anureo SDK' });
+    console.log((await turn.result()).text);
+    await session.close();
+}
+finally {
+    await client.dispose();
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anureo/conformance",
-  "version": "0.2.0",
   "description": "Shared conformance suite and scripted fixtures for Anureo SDK adapters and AHP implementations",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "keywords": [
     "anureo",
@@ -26,34 +26,33 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
     },
     "./fake": {
-      "types": "./dist/fake.d.ts",
-      "import": "./dist/fake.js",
-      "default": "./dist/fake.js"
+      "types": "./src/fake.d.ts",
+      "import": "./src/fake.js",
+      "default": "./src/fake.js"
     },
     "./fixtures": {
-      "types": "./dist/fixtures.d.ts",
-      "import": "./dist/fixtures.js",
-      "default": "./dist/fixtures.js"
+      "types": "./src/fixtures.d.ts",
+      "import": "./src/fixtures.js",
+      "default": "./src/fixtures.js"
     }
   },
-  "files": [
-    "dist",
-    "schema",
-    "protocol",
-    "examples",
-    "README.md",
-    "LICENSE"
-  ],
   "dependencies": {
-    "@anureo/protocol": "0.2.0",
-    "@anureo/sdk": "0.2.0"
+    "@anureo/protocol": "0.3.0",
+    "@anureo/sdk": "0.3.0"
   },
   "engines": {
     "node": ">=22"
-  }
+  },
+  "files": [
+    "src",
+    "bin",
+    "schema",
+    "protocol",
+    "examples"
+  ]
 }

package/src/fake-claude.d.ts

@@ -0,0 +1,78 @@
+import type { JsonObject, JsonValue } from "@anureo/protocol";
+/** Configure the initial output, input behavior and simulated capabilities of a Claude query fixture. */
+export interface ClaudeQueryScript {
+    /** Initial messages cloned and buffered in order within the default BoundedEventQueue limits. */
+    messages: JsonObject[];
+    /**
+     * Supply a response script that streamInput awaits after recording each input.
+     * Await emit to buffer a message or deliver it to a waiting reader. It can wait for
+     * queue capacity and reject on closure or admission failure. Keep emitted objects stable
+     * while buffered. Callback failures reject streamInput and leave admitted output available.
+     */
+    onInput?: (input: JsonValue, emit: (message: JsonObject) => Promise<void>) => Promise<void>;
+    /** Returned by reference when supplied, including an empty list; omission selects the fake model. */
+    models?: Array<{
+        value: string;
+        displayName: string;
+        description: string;
+    }>;
+    /** Set true to allow simulated rewind. Omission or false returns a "No checkpoint" denial. */
+    canRewind?: boolean;
+}
+/**
+ * Script a Claude query for a test without launching a peer. Controls record observations
+ * for assertions. To use one with a Claude adapter's queryFactory, bridge the factory's
+ * prompt into streamInput, project the output as native SDK messages and supply additional
+ * Query methods the adapter requires, such as applyFlagSettings.
+ * Direct callers end output with finish or close and drain or return the output iterator.
+ */
+export declare class ScriptedClaudeQuery implements AsyncIterable<JsonObject> {
+    private readonly script;
+    /** Ordered input/control observations; input values are retained by reference. */
+    readonly calls: Array<{
+        method: string;
+        value?: JsonValue;
+    }>;
+    /** Clone and buffer initial messages; cloning or queue admission failures throw synchronously. */
+    constructor(script: ClaudeQueryScript);
+    /**
+     * Claim exclusive output reads. A second acquisition throws EVENT_STREAM_ALREADY_OWNED
+     * until the first iterator releases ownership. Overlapping pending reads reject with
+     * CONCURRENT_EVENT_READ. Call return when stopping early. If finish or close settled
+     * an already pending read, call return or next again to release ownership.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<JsonObject>;
+    /**
+     * Consume one input stream in order, resolving at EOF after its onInput calls complete.
+     * Input, callback and awaited emit failures reject without closing output. The caller
+     * owns input cancellation and output closure; consume output concurrently if emits fill the queue.
+     */
+    streamInput(stream: AsyncIterable<JsonValue>): Promise<void>;
+    /** Record an interrupt without cancelling input or ending output. */
+    interrupt(): Promise<void>;
+    /** Record a model selection; omitted or empty model strings produce a call without a value. */
+    setModel(model?: string): Promise<void>;
+    /** Record a permission mode without validating or applying it. */
+    setPermissionMode(mode: string): Promise<void>;
+    /** Record a thinking-token budget, including null, without validating or applying it. */
+    setMaxThinkingTokens(tokens: number | null): Promise<void>;
+    /** Record the checkpoint ID and return configured availability; denial is a result, and no files change. */
+    rewindFiles(id: string): Promise<{
+        canRewind: boolean;
+        error?: string;
+    }>;
+    /** Resolve with the supplied list by reference or a fresh single-model list. This adds no call record. */
+    supportedModels(): Promise<{
+        value: string;
+        displayName: string;
+        description: string;
+    }[]>;
+    /** End output admission once and wake blocked emits to reject. Buffered messages still drain and input stays open. */
+    finish(): void;
+    /** Record close once and end output admission; buffered messages still drain and input is not cancelled. */
+    close(): void;
+    private readonly queue;
+    private closeCalled;
+}
+/** Create a query with its own call log and output queue. Initial cloning or admission failures throw synchronously. */
+export declare function createFakeClaudeQuery(script: ClaudeQueryScript): ScriptedClaudeQuery;

package/src/fake-claude.js

@@ -0,0 +1,68 @@
+import { BoundedEventQueue } from "@anureo/sdk";
+/**
+ * Script a Claude query for a test without launching a peer. Controls record observations
+ * for assertions. To use one with a Claude adapter's queryFactory, bridge the factory's
+ * prompt into streamInput, project the output as native SDK messages and supply additional
+ * Query methods the adapter requires, such as applyFlagSettings.
+ * Direct callers end output with finish or close and drain or return the output iterator.
+ */
+export class ScriptedClaudeQuery {
+    script;
+    /** Ordered input/control observations; input values are retained by reference. */
+    calls = [];
+    /** Clone and buffer initial messages; cloning or queue admission failures throw synchronously. */
+    constructor(script) {
+        this.script = script;
+        for (const message of script.messages)
+            this.queue.push(structuredClone(message));
+    }
+    /**
+     * Claim exclusive output reads. A second acquisition throws EVENT_STREAM_ALREADY_OWNED
+     * until the first iterator releases ownership. Overlapping pending reads reject with
+     * CONCURRENT_EVENT_READ. Call return when stopping early. If finish or close settled
+     * an already pending read, call return or next again to release ownership.
+     */
+    [Symbol.asyncIterator]() { return this.queue[Symbol.asyncIterator](); }
+    /**
+     * Consume one input stream in order, resolving at EOF after its onInput calls complete.
+     * Input, callback and awaited emit failures reject without closing output. The caller
+     * owns input cancellation and output closure; consume output concurrently if emits fill the queue.
+     */
+    async streamInput(stream) {
+        for await (const input of stream) {
+            this.calls.push({ method: "input", value: input });
+            await this.script.onInput?.(input, (message) => this.queue.write(message));
+        }
+    }
+    /** Record an interrupt without cancelling input or ending output. */
+    async interrupt() { this.calls.push({ method: "interrupt" }); }
+    /** Record a model selection; omitted or empty model strings produce a call without a value. */
+    async setModel(model) { this.calls.push({ method: "setModel", ...(model ? { value: model } : {}) }); }
+    /** Record a permission mode without validating or applying it. */
+    async setPermissionMode(mode) { this.calls.push({ method: "setPermissionMode", value: mode }); }
+    /** Record a thinking-token budget, including null, without validating or applying it. */
+    async setMaxThinkingTokens(tokens) { this.calls.push({ method: "setMaxThinkingTokens", value: tokens }); }
+    /** Record the checkpoint ID and return configured availability; denial is a result, and no files change. */
+    async rewindFiles(id) {
+        this.calls.push({ method: "rewindFiles", value: id });
+        return this.script.canRewind ? { canRewind: true } : { canRewind: false, error: "No checkpoint" };
+    }
+    /** Resolve with the supplied list by reference or a fresh single-model list. This adds no call record. */
+    async supportedModels() { return this.script.models ?? [{ value: "fake-model", displayName: "Fake", description: "Fixture" }]; }
+    /** End output admission once and wake blocked emits to reject. Buffered messages still drain and input stays open. */
+    finish() { this.queue.end(); }
+    /** Record close once and end output admission; buffered messages still drain and input is not cancelled. */
+    close() {
+        if (this.closeCalled)
+            return;
+        this.closeCalled = true;
+        this.calls.push({ method: "close" });
+        this.queue.end();
+    }
+    queue = new BoundedEventQueue();
+    closeCalled = false;
+}
+/** Create a query with its own call log and output queue. Initial cloning or admission failures throw synchronously. */
+export function createFakeClaudeQuery(script) {
+    return new ScriptedClaudeQuery(script);
+}

package/src/fake.d.ts

@@ -0,0 +1,122 @@
+import { type BackendSession, type HarnessAdapter, type SessionEventSink, type SessionMethod } from "@anureo/sdk";
+import { type Capabilities, type AhpRequestMap, type AhpResultMap, type HistoryItem, type InitializeParams, type InitializeResult, type SessionBinding, type SessionOpenParams, type SessionState, type AhpEventPayload } from "@anureo/protocol";
+import type { ConformanceFactory } from "./suite.js";
+/** One backend dispatch, recorded before any custom hook runs. */
+export interface FakeCall {
+    method: SessionMethod;
+    /** The dispatched object also used by the default handler if the hook returns undefined. */
+    params: AhpRequestMap[SessionMethod];
+}
+/** Configure an injectable in-memory backend for SDK, workflow and application fixtures. */
+export interface FakeAdapterOptions {
+    /** Replaces the complete default capability set. Adapter capability reads clone it. */
+    capabilities?: Capabilities;
+    /**
+     * ScriptedBackendSession.execute awaits this hook after recording a call. Return undefined to
+     * continue with default dispatch, or return a method-matching result to supply the entire
+     * response. In the latter case the hook owns the call's events and state changes. A throw or
+     * rejection rejects backend dispatch.
+     */
+    execute?: (call: FakeCall, sink: SessionEventSink) => Promise<AhpResultMap[SessionMethod] | undefined>;
+    /**
+     * Publish setup events or hold session acquisition. ScriptedHarnessAdapter.openSession awaits
+     * this hook after recording the backend and copying any fork history. A throw or rejection
+     * rejects acquisition and leaves the recorded fixture state available.
+     */
+    onOpen?: (params: SessionOpenParams, sink: SessionEventSink) => Promise<void>;
+}
+/** Default advertised capabilities. Adapter reads clone the current contents of this mutable template. */
+export declare const FAKE_CAPABILITIES: Capabilities;
+/** Create a fresh adapter to pass to createClient. Await disposal of the client when the fixture is done. */
+export declare function createScriptedAdapter(options?: FakeAdapterOptions): ScriptedHarnessAdapter;
+/**
+ * Supply runConformance with a fresh in-memory adapter per case, including held turns and
+ * observation faults. A supplied capability set replaces the defaults for applicability checks.
+ * The runner owns each client and its adapter.
+ */
+export declare function createScriptedConformanceFactory(capabilities?: Capabilities): ConformanceFactory;
+/**
+ * Exercise the SDK with an in-memory adapter that records opens and backend dispatches. By default
+ * a submission echoes text and publishes completion before acknowledging it. Hooks can supply
+ * other behavior. Await Client.dispose to release SDK ownership while retaining fixture records
+ * for assertions.
+ */
+export declare class ScriptedHarnessAdapter implements HarnessAdapter {
+    readonly options: FakeAdapterOptions;
+    /** Retain fixture options by reference for subsequent capability reads, opens and dispatches. */
+    constructor(options?: FakeAdapterOptions);
+    /** Backend dispatches in arrival order, including calls intercepted by execute. */
+    readonly calls: FakeCall[];
+    /** Detached open attempts, including attempts whose hook or fork validation fails. */
+    readonly opened: SessionOpenParams[];
+    /** Latest supplied event sink per session ID, retained for fixture-controlled publication/failure. */
+    readonly sinks: Map<string, SessionEventSink>;
+    /** Latest created backend per session ID, recorded before fork validation and onOpen. */
+    readonly backends: Map<string, ScriptedBackendSession>;
+    /** Number of disposal calls received, including any repeated direct calls. */
+    disposeCount: number;
+    /** Return detached declared capabilities, using FAKE_CAPABILITIES when omitted. */
+    get capabilities(): Capabilities;
+    /**
+     * Return scripted runtime metadata and cloned capabilities after negotiating AHP v1. The SDK
+     * adapter wrapper forwards the result to Client.initialize for validation and storage. Malformed
+     * requests and unsupported versions reject.
+     */
+    initialize(params: InitializeParams): Promise<InitializeResult>;
+    /**
+     * Supply OutputSession.open with a backend for SDK attachment. Record the backend and sink
+     * before copying fork history so a failed setup is observable. Missing source or boundary
+     * rejects with SESSION_NOT_FOUND or TURN_NOT_FOUND, respectively. Await onOpen before returning
+     * the backend. Hook failures reject and leave the recorded fixture state available.
+     */
+    openSession(params: SessionOpenParams, sink: SessionEventSink): Promise<BackendSession>;
+    /** Count adapter release. The SDK wrapper calls this after session cleanup attempts. */
+    dispose(): Promise<void>;
+    /**
+     * Give openSession a detached prefix of the source history before setup hooks run. A missing
+     * source or boundary throws so open rejects with the fork's fixture records still available.
+     */
+    private copyForkHistory;
+}
+/**
+ * Inspect or customize the in-memory session recorded by ScriptedHarnessAdapter.openSession.
+ * OutputSession dispatches validated SDK requests to this backend. Direct fixture calls to execute
+ * bypass those SDK guards.
+ */
+export declare class ScriptedBackendSession implements BackendSession {
+    private readonly adapter;
+    /** Callbacks supplied at open for event publication, interactions and source faults. */
+    readonly sink: SessionEventSink;
+    /** Requested identity with a deterministic scripted nativeRef, adopted by the SDK at attachment. */
+    readonly binding: SessionBinding;
+    /** Capabilities cloned from the adapter at construction and shared with the fixture state. */
+    readonly capabilities: Capabilities;
+    /** Mutable native history. Default backend history/read returns this array by reference. */
+    readonly history: HistoryItem[];
+    /** Number of disposal calls received, including any repeated direct calls. */
+    disposeCount: number;
+    /** Initial attachment snapshot. Default configuration dispatch replaces it without publishing a state event. */
+    state: SessionState;
+    /** Build a ready attachment snapshot and retain the adapter and event sink for dispatch. */
+    constructor(adapter: ScriptedHarnessAdapter, params: SessionOpenParams, 
+    /** Callbacks supplied at open for event publication, interactions and source faults. */
+    sink: SessionEventSink);
+    /** Await ordered sink publication. Supply the owning turn ID for item events. Sink failures reject. */
+    emit(payload: AhpEventPayload, turnId?: string): Promise<void>;
+    /**
+     * Resolve a scripted result for OutputSession.execute, which uses receipts to bind submissions
+     * before returning to Session for request-result validation. Record the call and await the
+     * custom hook before using defaults. Defaults that publish events await them before returning
+     * a receipt. Sink and hook failures reject dispatch. Default interaction dispatch rejects
+     * because Session handles it in its registry.
+     */
+    execute<M extends SessionMethod>(method: M, params: AhpRequestMap[M]): Promise<AhpResultMap[M]>;
+    /** Count backend release calls from the SDK or direct fixture callers and retain state for assertions. */
+    dispose(): Promise<void>;
+    /**
+     * Produce the default submission receipt after publishing start, preview, final item and terminal.
+     * Reuse an item ID across turns to exercise SDK scoping. Store the completed item before terminal
+     * publication, where a sink failure can still reject the dispatch.
+     */
+    private submitInput;
+}