@anureo/sdk 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Yoichi
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+# @anureo/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@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.
+
+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).
+
+## Quick start
+
+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).
+
+```typescript
+import { createClient } from '@anureo/sdk'
+import { createCodexAdapter } from '@anureo/adapter-codex'
+
+const client = await createClient({
+  adapter: createCodexAdapter({ command: 'codex' }),
+  identity: { adapterId: 'codex', runtimeConfigId: 'local' },
+})
+
+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()
+
+  if (result.status === 'failed') throw new Error(result.error.message)
+  if (result.status === 'interrupted') throw new Error('Turn interrupted')
+  console.log(result.text)
+
+  await session.close()
+} finally {
+  await client.dispose()
+}
+```
+
+## 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
+
+```sh
+cd packages/core
+bun run typecheck
+bun test src
+```
+
+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,6 +1,68 @@
 {
   "name": "@anureo/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+    "ahp",
+    "harness",
+    "agent",
+    "sdk",
+    "runtime"
+  ],
+  "homepage": "https://github.com/hi-youichi/anureo-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hi-youichi/anureo-sdk.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/hi-youichi/anureo-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./process": {
+      "types": "./src/process.d.ts",
+      "import": "./src/process.js",
+      "default": "./src/process.js"
+    },
+    "./queue": {
+      "types": "./src/queue.d.ts",
+      "import": "./src/queue.js",
+      "default": "./src/queue.js"
+    },
+    "./diagnostics": {
+      "types": "./src/diagnostics.d.ts",
+      "import": "./src/diagnostics.js",
+      "default": "./src/diagnostics.js"
+    },
+    "./structured-output-stdio": "./src/structured-output/stdio.mjs"
+  },
+  "dependencies": {
+    "@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'];
+}