@anureo/sdk 0.2.0 → 0.3.0

package/README.md

@@ -1,79 +1,177 @@
 # @anureo/sdk
 
-The runtime core of the Anureo SDK. `createHarnessRuntime(adapter)` wraps any `HarnessAdapter` — Codex, Claude, ACP, an external AHP harness, or your own — behind the unified `HarnessRuntime` / `HarnessSession` interface, and enforces the AHP semantics that hosts should not have to re-implement:
+`@anureo/sdk` runs agent sessions through a harness adapter. Applications use it
+to submit input, stream events, collect results, and control native executions.
+The SDK validates AHP requests and events, tracks which execution handles each
+submission, and owns session observation and cleanup. The adapter provides the
+native execution and reports its progress.
 
-- Request, result, binding, and capability validation; turn and item lifecycle state machines
-- Event delivery with `streamId`, `seq`, and timestamps through a bounded queue (backpressure is explicit, never silent)
-- Interaction registration, answering, and cancellation, with cleanup on timeout, turn end, or disconnection
-- Per-method request caching, waiting timeouts, typed errors, and recovery state
-- Secret redaction for events, histories, and file-change materials marked as secret
+This guide describes the revised workspace API. The published 0.2.0 release has a
+different lifecycle API. See the [workspace guide](../../README.md) and the
+[lifecycle migration notes](../../draft/docs/native-harness-lifecycle.md).
 
-> Part of the [Anureo SDK workspace](../../README.md). Install with `npm install @anureo/sdk`.
+## Quick start
 
-## Exports
+This example requires an authenticated Codex CLI on PATH and the
+[Codex adapter](../adapter/codex/README.md). For a streaming version, run
+`bun run example` from the workspace root or read the
+[greeting example](../../examples/greeting.ts).
 
-| Entry | Contents |
-|---|---|
-| `@anureo/sdk` | `createHarnessRuntime`, `HarnessRuntime`, `HarnessSession`, `ManagedHarnessSession`, `HarnessAdapter`, `BackendSession`, `SessionEventSink`, `RuntimeOptions`, `HarnessSdkError`, `BoundedEventQueue`, `SecretRedactor`, and related types |
-| `@anureo/sdk/process` | `spawnHarnessProcess` — child-process helper used by the stdio adapters |
-| `@anureo/sdk/queue` | The bounded event queue used for host consumption and stream buffering |
-| `@anureo/sdk/diagnostics` | `catalogPhase` and helpers for progress-reporting probes (model catalog sessions) |
+```typescript
+import { createClient } from '@anureo/sdk'
+import { createCodexAdapter } from '@anureo/adapter-codex'
 
-Core never imports a concrete adapter. Adapters implement `HarnessAdapter` (initialize / openSession / dispose) and receive a `SessionEventSink` (`emit`, `tryEmit`, `requestInteraction`, `resolveInteraction`, `fail`) to publish into the managed session. The dependency direction is one-way: adapters depend on core and protocol.
+const client = await createClient({
+  adapter: createCodexAdapter({ command: 'codex' }),
+  identity: { adapterId: 'codex', runtimeConfigId: 'local' },
+})
 
-## Usage
+try {
+  const session = await client.sessions.create({ cwd: process.cwd() })
+  const turn = await session.submit({ input: 'Say hello in one sentence.' })
+  const result = await turn.result()
 
-The scripted adapter from `@anureo/conformance` runs without a model or credentials; replace it with any real adapter to talk to a live backend.
+  if (result.status === 'failed') throw new Error(result.error.message)
+  if (result.status === 'interrupted') throw new Error('Turn interrupted')
+  console.log(result.text)
 
-```typescript
-import { createHarnessRuntime } from '@anureo/sdk'
-import { createScriptedAdapter } from '@anureo/conformance'
-
-const runtime = createHarnessRuntime(createScriptedAdapter())
-try {
-  await runtime.initialize({
-    protocolVersions: [1],
-    clientInfo: { name: 'my-host', version: '0.1.0' },
-  })
-  const session = await runtime.openSession({
-    requestId: 'open', mode: 'new', cwd: process.cwd(),
-    binding: { sessionId: 's1', adapterId: 'scripted', runtimeConfigId: 'local' },
-  })
-
-  // Start consuming events before submitting input: the queue is bounded.
-  const consume = (async () => {
-    for await (const event of session.events()) {
-      if (event.type === 'item/completed' && event.payload.item.type === 'agentMessage') {
-        console.log(event.payload.item.text)
-      }
-      if (event.type === 'turn/completed') return
-    }
-  })()
-  void consume.catch(() => {})
-
-  await session.startTurn({
-    requestId: 'start', sessionId: session.binding.sessionId, turnId: 't1',
-    input: [{ type: 'text', text: 'Hello' }],
-  })
-  await consume
   await session.close()
 } finally {
-  await runtime.dispose()
+  await client.dispose()
 }
 ```
 
-The runnable version lives at [examples/standalone.ts](../../examples/standalone.ts) (run with `bun run example` from the workspace root).
-
-## Session surface
-
-`HarnessSession` exposes `startTurn`, `steer`, `interrupt`, `respond`, `cancelInteraction`, `setConfig`, `revert`, `readHistory`, `setGoal`, `clearGoal`, `compact`, `review`, and `close`. The interface existing does not mean the backend supports the operation: every optional method is gated on the capabilities negotiated at initialization, and calls that exceed them fail with typed errors rather than undefined behavior.
-
-Operational notes hosts should rely on:
-
-- **Event identity.** Sequence numbers belong to a `streamId`; a new open produces a new stream. Do not treat `seq` across streams as one persistent log.
-- **Backpressure.** The queue bounds both queued events and waiters. Non-pausable sources use `tryEmit()` and observe failure; slow consumers surface as explicit errors.
-- **Outcome ambiguity.** Stopping a wait after a request was sent can yield `outcomeUnknown`; that never implies the backend did not act. Cancelling a wait and interrupting backend execution are distinct operations.
-- **Session binding.** A session is bound to one adapter and runtime config. Resume and fork must honor the binding; switching backends inside a session is not supported.
+## Application API
+
+Import the application API and its types from `@anureo/sdk`.
+
+### Client
+
+| API | Purpose |
+| --- | --- |
+| `createClient(options, wait?)` | Initialize an adapter and return a `Client` ready to open sessions. |
+| `new Client(options)`, `client.initialize(wait?)` | Construct a client without I/O, then negotiate adapter capabilities explicitly. |
+| `client.identity` | Read the adapter and runtime configuration IDs used to validate session bindings. |
+| `client.sessions.create(options, wait?)` | Open a new session with a fresh binding. |
+| `client.sessions.resume(reference, wait?)` | Reopen the session identified by a saved `session.reference`, when supported. |
+| `client.sessions.fork(reference, { boundary }, wait?)` | Open a new session from a specified boundary in an existing session, when supported. |
+| `client.openSession(params, wait?)` | Open a session with explicit AHP open parameters and binding. |
+| `client.dispose()` | Release the client's sessions and adapter. Call it in `finally`. |
+
+[`ClientOptions`](src/client-options.ts) configures the adapter, client identity,
+runtime hooks, interaction handlers, and retention limits.
+[`RuntimeOptions`](src/ports.ts) configures timeouts, resource budgets, and host
+hooks such as ID generation and history redaction.
+
+### Session
+
+A `Session` represents a conversation opened through the client.
+
+| API | Purpose |
+| --- | --- |
+| `session.submit(options, wait?)` | Send input and return a `Turn` once the adapter associates the input with an execution. |
+| `session.review({ target }, wait?)` | Start a supported native review and return its associated `Turn`. |
+| `session.events(options?)` | Subscribe to future session events, including submission progress and interaction requests. Subscribe before submitting to observe those events. |
+| `session.id`, `session.binding`, `session.reference` | Read the session ID, its adapter binding, or a reference for resuming or forking it. |
+| `session.capabilities`, `session.snapshot` | Check the session's current capabilities or read its current privacy-filtered state. |
+| `session.interrupt(options?, wait?)` | Request a session-wide interrupt. Pass `cancelQueued` only when supported. An acknowledgement alone cannot establish that execution stopped or that queued input was withdrawn. |
+| `session.request(method, params, wait?)` | Send a typed, lower-level AHP session request for operations such as history reads or manual interaction responses. |
+| `session.close(wait?)` | Request native close and release observation and backend resources after the receipt. The receipt reports `observationClosed` and `executionStopped` separately. |
+| `session.dispose()` | Release local observation and backend resources without asserting that native execution stopped. |
+
+`Input` accepts a string or an array of AHP input blocks. [`SubmitOptions`](src/client-options.ts)
+also accepts capability-gated `delivery`, `overrides`, and `outputSchema`.
+Delivery defaults to `native`, so a backend can queue input or merge it into an
+existing execution. Two submissions can return handles with the same `turn.id`.
+Count the execution and its usage once. Use `delivery: 'afterTurn'` when
+`session.capabilities.input?.delivery` includes `afterTurn`.
+The SDK tracks submission IDs internally. `submit()` waits for an execution
+association, which can arrive before an acceptance receipt or after the execution
+has already ended.
+
+Pass a JSON Schema as `outputSchema` when `session.capabilities.turn?.outputSchema`
+is enabled. A successful result carries JSON in `result.text`. The SDK uses native
+schemas where available, a direct output tool on Pi, or a session-scoped MCP bridge
+on supported ACP and Hermes sessions. The [structured output example](../../examples/structured-output.ts)
+shows how to submit and parse a result.
+
+Configure supported interactions through `ClientOptions.interactions`.
+An `InteractionHandlers` function handles its kind automatically. An explicit
+key with value `undefined` enables manual responses through session events and
+`session.request('interaction/respond', params)`. An omitted kind is unsupported.
+
+### Turn
+
+| API | Purpose |
+| --- | --- |
+| `turn.id` | Read the execution ID shared by all handles observing that execution. |
+| `turn.result(wait?)` | Wait for the execution's terminal result or read it if already retained. |
+| `turn.events(options?)` | Subscribe to future events for this execution. |
+| `turn.steer({ input }, wait?)` | Wait for native confirmation that input was appended to this exact execution. Requires `session.capabilities.input?.steer?.atomicMatch` and rejects stale targets. |
+| `turn.interrupt(wait?)` | Request interruption of this exact execution when supported. Use `result()` to observe its terminal status. |
+| `turn.observe()` | Create an independent handle for the same execution. |
+| `turn.dispose()` | Stop this handle's waits and subscriptions. Native execution and other handles can continue. |
+
+[`TurnResult`](src/types.ts) is an immutable snapshot with text, items,
+and any available usage. Its status is `completed`, `interrupted`, or `failed`.
+An interrupted result can carry a native error reason.
+
+[`RequestOptions`](src/types.ts) sets a caller's wait deadline and abort signal.
+A timeout after dispatch can leave the native outcome unknown. Check
+`HarnessSdkError.outcomeUnknown` before retrying to avoid duplicate work.
+[`EventSubscriptionOptions`](src/types.ts) controls cancellation and
+per-subscription queue limits.
+
+## Adapter API
+
+Adapters import their contracts from `@anureo/sdk` and use the types in
+[`@anureo/protocol`](../protocol/README.md) for AHP requests, results, and events.
+
+| Contract | Who implements and calls it |
+| --- | --- |
+| `HarnessAdapter` | The adapter implements `initialize()`, `openSession()`, and `dispose()`. The client calls them to negotiate capabilities, open native sessions, and release client-wide resources. |
+| `BackendSession` | The adapter returns this from `openSession()`. Core reads its binding, capabilities, and optional state, and calls `execute()` and `dispose()` for native requests and cleanup. `SessionMethod` identifies requests routed through an open session. |
+| `SessionEventSink` | Core supplies this to the adapter at open. The adapter calls `emit()` or `tryEmit()` to publish events, `bindSubmission()` to associate input with an execution, and `fail()` to report observation failure. `EventScope` supplies turn or item context for an event. |
+| `NativeInteractionResponder` | The adapter supplies this callback to `sink.requestInteraction()`. Core calls it to deliver a response or request cancellation. The adapter calls `sink.resolveInteraction()` when the native peer has already settled a request. |
+| `StructuredOutputToolPort`, `StructuredOutputToolDefinition`, `StructuredOutputToolResult` | An adapter can expose a tool port on `BackendSession`. Core calls `configure()` to install or disable the tool. The adapter presents the definition and calls its `execute()` to validate a candidate. |
+
+`HarnessAdapter.outputBridgeTransport()` lets an adapter opt into the session MCP
+bridge. `SessionEventSink.projectOutput()` is an optional hook for privacy-filtering
+output before final schema validation. See [the port definitions](src/ports.ts)
+for ordering, failure, and ownership contracts.
+
+## Supporting exports
+
+| Purpose | Import path | Exports |
+| --- | --- | --- |
+| Errors and caller waits | `@anureo/sdk` | `HarnessSdkError` carries a safe code and outcome metadata. `sdkError()` normalizes a failure. `waitForRequest()` applies a caller-scoped wait using `RequestOptions`. |
+| Unattended approvals | `@anureo/sdk` | `approveWithNarrowestScope()` can be explicitly registered as `interactions.approval`. It chooses allow-once, then session, then rule grants, and rejects when none is offered. Clients never enable it automatically. |
+| Host logging | `@anureo/sdk` | LogTape's `configure`, `configureSync`, `getLogger`, `drain`, `dispose`, `disposeSync`, `reset`, and `resetSync`, plus `Config`, `LogLevel`, `LogRecord`, `Logger`, and `Sink`. The application configures logging sinks. |
+| Native subprocesses | `@anureo/sdk/process` or `@anureo/sdk` | `spawnHarnessProcess()` launches and owns stdio subprocess I/O and cleanup. The module also exports `ProcessPortError`, `ProcessExit`, `HarnessProcess`, and `HarnessProcessOptions`. |
+| Bounded buffering | `@anureo/sdk/queue` or `@anureo/sdk` | `BoundedEventQueue` provides a bounded, single-reader async queue. `QueueLimits` configures its budgets. |
+| Model catalog diagnostics | `@anureo/sdk/diagnostics` | `catalogPhase()` reports probe timing and outcomes. `emitCatalogPhase()` publishes a diagnostic, and `safeCatalogErrorCode()` projects an error to a safe code. `CatalogProbeOptions` and `CatalogProbeEvent` describe observers and their events. |
+
+### Implementation helpers
+
+The root currently exports `NativeIdentityMap` for native-to-SDK ID mapping,
+`InteractionRegistry` for tracking native interaction responses, and
+`SecretRedactor` for filtering marked secrets.
+`@anureo/sdk/structured-output-stdio` is an internal package entry that core
+resolves to launch the stdio bridge subprocess.
+
+## Code structure
+
+| Source | Responsibility |
+| --- | --- |
+| [`package.json`](package.json), [`src/index.ts`](src/index.ts) | Define the package entry points and assemble the root exports. |
+| [`src/client.ts`](src/client.ts), [`src/session.ts`](src/session.ts), [`src/turn.ts`](src/turn.ts) | Implement the application API for opening sessions, dispatching requests, and observing and controlling executions. |
+| [`src/client-options.ts`](src/client-options.ts), [`src/types.ts`](src/types.ts), [`src/ports.ts`](src/ports.ts) | Define public configuration, input, result, and observation types, plus adapter contracts. |
+| [`src/errors.ts`](src/errors.ts), [`src/request.ts`](src/request.ts) | Provide SDK errors, failure normalization, and caller-scoped waits. |
+| [`src/lifecycle/`](src/lifecycle/) | Supports the application API with event subscriptions, result accumulation, and interaction settlement. |
+| [`src/adapter/`](src/adapter/), [`src/requests/`](src/requests/) | Provide native-to-SDK ID mapping and request validation against session bindings and capabilities. |
+| [`src/privacy/`](src/privacy/) | Redacts marked secrets from observed data and bounds retained file change content. |
+| [`src/structured-output/`](src/structured-output/) | Wraps adapters for schema validation and manages the direct-tool and MCP fallback paths. |
+| [`src/process.ts`](src/process.ts), [`src/queue.ts`](src/queue.ts), [`src/diagnostics.ts`](src/diagnostics.ts) | Implement the subprocess, bounded queue, and model catalog diagnostics subpaths. |
 
 ## Development
 
@@ -83,7 +181,6 @@ bun run typecheck
 bun test src
 ```
 
-## Documentation
-
-- [Architecture](../../docs/architecture.md) — interfaces, turn/approval sequences, and safety boundaries (currently in Chinese)
-- [AHP v1 protocol](../../spec/ahp-v1.md)
+See the [architecture notes](../../draft/docs/architecture.md) for package
+responsibilities and the [AHP v1 schema](../protocol/schema/v1/ahp.schema.json)
+for wire contracts.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anureo/sdk",
-  "version": "0.2.0",
   "description": "Runtime core of the Anureo SDK: unified HarnessRuntime and HarnessSession over any adapter, enforcing AHP semantics",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "keywords": [
     "anureo",
@@ -26,38 +26,43 @@
   "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"
     },
     "./process": {
-      "types": "./dist/process.d.ts",
-      "import": "./dist/process.js",
-      "default": "./dist/process.js"
+      "types": "./src/process.d.ts",
+      "import": "./src/process.js",
+      "default": "./src/process.js"
     },
     "./queue": {
-      "types": "./dist/queue.d.ts",
-      "import": "./dist/queue.js",
-      "default": "./dist/queue.js"
+      "types": "./src/queue.d.ts",
+      "import": "./src/queue.js",
+      "default": "./src/queue.js"
     },
     "./diagnostics": {
-      "types": "./dist/diagnostics.d.ts",
-      "import": "./dist/diagnostics.js",
-      "default": "./dist/diagnostics.js"
-    }
+      "types": "./src/diagnostics.d.ts",
+      "import": "./src/diagnostics.js",
+      "default": "./src/diagnostics.js"
+    },
+    "./structured-output-stdio": "./src/structured-output/stdio.mjs"
   },
-  "files": [
-    "dist",
-    "schema",
-    "protocol",
-    "examples",
-    "README.md",
-    "LICENSE"
-  ],
   "dependencies": {
-    "@anureo/protocol": "0.2.0"
+    "@anureo/protocol": "0.3.0",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "ajv": "8.20.0"
   },
   "engines": {
     "node": ">=22"
-  }
+  },
+  "peerDependencies": {
+    "@logtape/logtape": ">=2.0.0 <3"
+  },
+  "files": [
+    "src",
+    "bin",
+    "schema",
+    "protocol",
+    "examples"
+  ]
 }

package/src/adapter/identity.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Translate opaque native turn and item IDs when implementing an adapter. Keep one
+ * map per native session and use it for events that share those identities. The
+ * adapter owns event ordering, failure handling and clearing the map once its
+ * identities are no longer needed.
+ */
+export declare class NativeIdentityMap {
+    private readonly createId;
+    /**
+     * Supply an allocator that returns unique, nonempty SDK item IDs. item() invokes it
+     * synchronously on a cache miss and propagates failures. The allocator owns uniqueness.
+     */
+    constructor(createId: () => string);
+    /**
+     * Record a turn pair before translating it through turn() or nativeTurn(). Rebinding
+     * the same pair is harmless. A conflicting nonempty stored ID throws HarnessSdkError
+     * with code PROTOCOL_ERROR before either lookup changes. Empty stored values permit
+     * rebinding, which writes only the supplied pair. The adapter handles conflicts.
+     */
+    bindTurn(turnId: string, nativeTurnId: string): void;
+    /** Adapters translate a native turn ID to its stored SDK ID, or undefined, without mutation or allocation. */
+    turn(nativeTurnId: string): string | undefined;
+    /** Adapters translate an SDK turn ID to its stored native ID, or undefined, without mutation or allocation. */
+    nativeTurn(turnId: string): string | undefined;
+    /**
+     * Reuse the SDK item ID for a native item within an SDK turn. The turn can be unbound.
+     * The allocator runs synchronously when the pair has no nonempty cached ID. An empty
+     * result is returned and triggers another allocation on the next lookup. Allocator
+     * failures propagate unchanged and leave the adapter free to retry.
+     */
+    item(turnId: string, nativeItemId: string): string;
+    /**
+     * Forget both turn directions and all cached item IDs once pending events no longer
+     * need them. Later calls can bind and allocate again with the same allocator.
+     * Repeated clears are harmless. The adapter remains responsible for native cleanup.
+     */
+    clear(): void;
+    private readonly turnIdsByNativeTurnId;
+    private readonly nativeTurnIdsByTurnId;
+    private readonly items;
+}

package/src/adapter/identity.js

@@ -0,0 +1,71 @@
+// Maps opaque native identities to SDK identities within an adapter-owned session.
+import { HarnessSdkError } from "../errors.js";
+/**
+ * Translate opaque native turn and item IDs when implementing an adapter. Keep one
+ * map per native session and use it for events that share those identities. The
+ * adapter owns event ordering, failure handling and clearing the map once its
+ * identities are no longer needed.
+ */
+export class NativeIdentityMap {
+    createId;
+    /**
+     * Supply an allocator that returns unique, nonempty SDK item IDs. item() invokes it
+     * synchronously on a cache miss and propagates failures. The allocator owns uniqueness.
+     */
+    constructor(createId) {
+        this.createId = createId;
+    }
+    /**
+     * Record a turn pair before translating it through turn() or nativeTurn(). Rebinding
+     * the same pair is harmless. A conflicting nonempty stored ID throws HarnessSdkError
+     * with code PROTOCOL_ERROR before either lookup changes. Empty stored values permit
+     * rebinding, which writes only the supplied pair. The adapter handles conflicts.
+     */
+    bindTurn(turnId, nativeTurnId) {
+        const existingTurnId = this.turnIdsByNativeTurnId.get(nativeTurnId);
+        const existingNativeTurnId = this.nativeTurnIdsByTurnId.get(turnId);
+        if ((existingTurnId && existingTurnId !== turnId) ||
+            (existingNativeTurnId && existingNativeTurnId !== nativeTurnId)) {
+            throw new HarnessSdkError("PROTOCOL_ERROR", "Conflicting native turn identity");
+        }
+        this.turnIdsByNativeTurnId.set(nativeTurnId, turnId);
+        this.nativeTurnIdsByTurnId.set(turnId, nativeTurnId);
+    }
+    /** Adapters translate a native turn ID to its stored SDK ID, or undefined, without mutation or allocation. */
+    turn(nativeTurnId) {
+        return this.turnIdsByNativeTurnId.get(nativeTurnId);
+    }
+    /** Adapters translate an SDK turn ID to its stored native ID, or undefined, without mutation or allocation. */
+    nativeTurn(turnId) {
+        return this.nativeTurnIdsByTurnId.get(turnId);
+    }
+    /**
+     * Reuse the SDK item ID for a native item within an SDK turn. The turn can be unbound.
+     * The allocator runs synchronously when the pair has no nonempty cached ID. An empty
+     * result is returned and triggers another allocation on the next lookup. Allocator
+     * failures propagate unchanged and leave the adapter free to retry.
+     */
+    item(turnId, nativeItemId) {
+        // Encode the pair so delimiter characters inside opaque IDs cannot alias another pair.
+        const key = JSON.stringify([turnId, nativeItemId]);
+        let itemId = this.items.get(key);
+        if (!itemId) {
+            itemId = this.createId();
+            this.items.set(key, itemId);
+        }
+        return itemId;
+    }
+    /**
+     * Forget both turn directions and all cached item IDs once pending events no longer
+     * need them. Later calls can bind and allocate again with the same allocator.
+     * Repeated clears are harmless. The adapter remains responsible for native cleanup.
+     */
+    clear() {
+        this.turnIdsByNativeTurnId.clear();
+        this.nativeTurnIdsByTurnId.clear();
+        this.items.clear();
+    }
+    turnIdsByNativeTurnId = new Map();
+    nativeTurnIdsByTurnId = new Map();
+    items = new Map();
+}

package/src/client-options.d.ts

@@ -0,0 +1,71 @@
+import type { AhpRequestMap, InteractionRequested, InteractionResponse, SessionBinding } from '@anureo/protocol';
+import type { HarnessAdapter, RuntimeOptions } from "./ports.js";
+import type { Input } from "./types.js";
+/**
+ * Register automatic interaction handlers in ClientOptions.interactions. An enumerable own key
+ * with value undefined advertises manual handling through interaction/requested events and
+ * Session.request('interaction/respond', ...). Omit a kind to leave it unsupported.
+ *
+ * Session.requestInteraction publishes interaction/requested before scheduling a handler with a
+ * detached native request, including any private fields needed to answer it. Resolve an answer
+ * matching the request kind for native delivery. Rejection triggers cancellation while actionable.
+ * Stop host work when the signal aborts on settlement or teardown. The SDK ignores late answers
+ * and holds the handler slot until the handler's promise settles.
+ */
+export type InteractionHandlers = {
+    [K in InteractionRequested['kind']]?: (request: Extract<InteractionRequested, {
+        kind: K;
+    }>, context: {
+        signal: AbortSignal;
+    }) => Promise<Extract<InteractionResponse, {
+        kind: K;
+    }>>;
+};
+/**
+ * Configure an SDK client and transfer adapter cleanup to it when construction succeeds.
+ * Client validates identity, interaction registrations and retention limits before native setup.
+ * Await Client.dispose to release owned resources. Host callbacks retain responsibility for their
+ * own effects and cleanup.
+ */
+export interface ClientOptions {
+    /** Client-owned native integration, initialized before opens and disposed after owned sessions. */
+    adapter: HarnessAdapter;
+    /** Nonblank adapter and runtime configuration IDs that every session binding must match. */
+    identity: Pick<SessionBinding, 'adapterId' | 'runtimeConfigId'>;
+    /** Host hooks and resource budgets used by this client and each opened session. */
+    runtime?: RuntimeOptions;
+    /** Interaction kinds and automatic handlers to advertise during initialization. */
+    interactions?: InteractionHandlers;
+    /** Positive safe-integer retention budgets; capacity checks reject rather than evict unresolved work. */
+    limits?: {
+        /** Maximum tracked executions per session, including active executions and pinned results. Defaults to 128. */
+        maxExecutions?: number;
+        /** Maximum retained submission/association records per session; defaults to 1024. */
+        maxSubmissions?: number;
+        /**
+         * Budget for retained execution item snapshots in serialized UTF-8 bytes. Defaults to 16 MiB.
+         * Applies within each execution and across the session. Structured output uses a separate
+         * retention budget of the same size.
+         */
+        maxResultBytes?: number;
+        /** Maximum distinct retained items per execution; defaults to 2048. */
+        maxItems?: number;
+    };
+}
+/**
+ * Supply input and per-submission policy to Session.submit. It validates the request before dispatch
+ * and resolves with a Turn when it observes the native execution association, which can precede
+ * the receipt or follow completion. Invalid input, unsupported policy and wait failures reject.
+ * Dispatch failure can reject an unresolved association. Use Turn.result for the terminal outcome,
+ * including structured-output validation, and dispose the Turn to release its local observations.
+ */
+export interface SubmitOptions {
+    /** Text or protocol blocks to detach and validate before native dispatch. */
+    input: Input;
+    /** Capability-gated delivery policy. Omission selects 'native', which can queue input or join an existing execution. */
+    delivery?: AhpRequestMap['input/submit']['delivery'];
+    /** Per-turn overrides checked against advertised capability keys. */
+    overrides?: AhpRequestMap['input/submit']['overrides'];
+    /** Require valid JSON matching this schema in the final result. Requires session.capabilities.turn.outputSchema. */
+    outputSchema?: AhpRequestMap['input/submit']['outputSchema'];
+}

package/src/client.d.ts

@@ -0,0 +1,106 @@
+import { type AhpRequestMap, type SessionBinding, type SessionOpenParams } from '@anureo/protocol';
+import type { RequestOptions } from "./types.js";
+import type { ClientOptions } from "./client-options.js";
+import { Session } from "./session.js";
+export { Session } from "./session.js";
+export type { ClientOptions, InteractionHandlers, SubmitOptions } from "./client-options.js";
+/**
+ * Open and manage sessions through one adapter. Use createClient for an initialized client, or
+ * construct and initialize it explicitly. Await dispose to release owned sessions and the adapter.
+ */
+export declare class Client {
+    private readonly options;
+    /**
+     * Take ownership of the adapter without starting native I/O. Invalid identity, interaction
+     * registrations or retention limits throw INVALID_PARAMS. Direct callers must await initialize
+     * before opening sessions and later await dispose, including after failed initialization.
+     */
+    constructor(options: ClientOptions);
+    /** Read a fresh copy of the adapter and runtime configuration IDs used to check session bindings. */
+    get identity(): ClientOptions['identity'];
+    /**
+     * Negotiate adapter capabilities before opening sessions. Each call invokes adapter negotiation
+     * once if admitted and stores the validated capability snapshot on success. The wait defaults to
+     * 30 seconds unless configured by runtime.requestTimeoutMs. Invalid waits, adapter or protocol
+     * failures, abort and timeout reject. A negotiation that finishes after a failed wait cannot update
+     * the client's capabilities. createClient awaits this method and handles cleanup on failure.
+     */
+    initialize(wait?: RequestOptions): Promise<void>;
+    /**
+     * Open with explicit request and binding IDs. Resolve with the client-owned Session after backend
+     * attachment and initial state publication. Invalid input, unsupported mode, setup or wait failure
+     * rejects. The attachment wait defaults to 120 seconds unless configured by runtime.openTimeoutMs.
+     * If the wait ends early, the SDK closes local observation and still releases a late backend.
+     */
+    openSession(params: SessionOpenParams, wait?: RequestOptions): Promise<Session>;
+    /**
+     * Release the client and its sessions. Stop admitting opens immediately and share the disposal
+     * promise across calls. Await all owned session disposal attempts before releasing the adapter.
+     * Reject with RESOURCE_RELEASE_FAILED if release fails. Disposal ends local observation and leaves
+     * native execution stop unconfirmed. An open that delivers a backend after teardown releases it
+     * on its own attachment path.
+     */
+    dispose(): Promise<void>;
+    private initialized?;
+    private closed;
+    private disposing?;
+    private readonly owned;
+    private readonly createId;
+    /** Open sessions using generated request IDs and the same attachment wait and ownership as openSession. */
+    readonly sessions: {
+        /** Open a new session with a fresh binding. A throwing ID generator fails the call synchronously. */
+        create: (options: Omit<SessionOpenParams, "requestId" | "binding" | "mode">, wait?: RequestOptions) => Promise<Session>;
+        /** Reopen a saved session reference when supported. Foreign bindings reject and ID-generator throws propagate synchronously. */
+        resume: (reference: {
+            binding: SessionBinding;
+            cwd: string;
+        }, wait?: RequestOptions) => Promise<Session>;
+        /** Open a fresh session at a supported boundary in the referenced session. Foreign bindings reject before ID generation, which can throw synchronously. */
+        fork: (reference: {
+            binding: SessionBinding;
+            cwd: string;
+        }, options: {
+            boundary: AhpRequestMap["session/revert"]["boundary"];
+        }, wait?: RequestOptions) => Promise<Session>;
+    };
+    /**
+     * sessions.create and sessions.fork use this for a fresh destination after generating the request
+     * ID. Snapshot the configured identity before invoking the host's session ID generator.
+     */
+    private newBinding;
+    /**
+     * dispose caches this release attempt. Close admission before taking the session snapshot and
+     * keep the adapter alive until all session disposals settle. Report failures in session order,
+     * followed by the adapter failure, through the shared disposal promise.
+     */
+    private disposeOwnedResources;
+    /**
+     * openSession and sessions.create/resume/fork return this promise to hosts. Validate before
+     * allocating a Session, then own it before native callbacks or disposal can race attachment.
+     * Resolve the attached session, or remove it and await disposal before rejecting setup/wait failure
+     * (aggregated if cleanup fails). attachSession continues to release late backends after wait failure.
+     */
+    private open;
+    /**
+     * Client.open uses the returned negotiated capabilities to construct Session. Preserve admission
+     * precedence: wait validity, abort, client state, protocol shape, binding, then mode capability.
+     * Throws before session allocation/native dispatch; open exposes that failure as its rejection.
+     */
+    private validateOpen;
+    /**
+     * Client.open passes this operation to waitForRequest. Give the wrapped adapter a separate params
+     * clone and the Session sink, then await attachment/publication. This work outlives caller abort or
+     * timeout: OutputSession.open or Session.attach disposes a backend arriving after teardown.
+     * Native/attachment failures reject the operation and remain observed by waitForRequest.
+     */
+    private attachSession;
+}
+/**
+ * Create and initialize a client before opening sessions. A pre-aborted wait rejects before the
+ * client takes ownership of the adapter. Once construction succeeds, initialization failure triggers
+ * disposal before rejection. The original cause is preserved unless disposal also fails, in which
+ * case both failures are reported as RESOURCE_RELEASE_FAILED. Await dispose on the returned client.
+ * createRefactorClient and createReviewClient return this promise to their CLI commands, which
+ * await disposal after the run and report output.
+ */
+export declare function createClient(options: ClientOptions, wait?: RequestOptions): Promise<Client>;