@openma/common 0.0.0-stage → 0.9.1

package/LICENSE

@@ -0,0 +1,202 @@
+                                 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 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 Support. 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 support.
+
+   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 2025 Open Managed Agents Contributors
+
+   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,392 @@
-# Temporary Holding Version
+# OpenMA Common
 
-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.
+Shared, product-agnostic contracts used by OpenMA Desktop and Open Managed Agents.
+This repository is consumed directly from Git; it is intentionally not published
+to npm.
+
+The Agent-facing architecture is additive and vendor-neutral:
+
+```text
+OpenMA Agent Contract
+├── commands, capabilities, session handles, and canonical OpenMA events
+├── ACP wire adapter + existing ACP runtime
+└── Claude Managed Agents wire adapter
+```
+
+ACP and Managed Agents remain bindings. Consumers orchestrate against the
+OpenMA Agent Contract instead of leaking either provider's session identifiers
+or wire-event shapes into product state.
+
+## Exports
+
+- `@openma/common/brand` — canonical token names, light/dark values, and brand RGB.
+- `@openma/common/brand/tokens.css` — matching CSS custom properties.
+- `@openma/common/brand/openma-logo-mark.svg` — canonical OpenMA vector mark.
+- `@openma/common/protocol/managed` — v2 Managed Agents ↔ OpenMA codec, typed against the official Anthropic SDK event unions.
+- `@openma/common/protocol/acp` — ACP v1 ↔ OpenMA codec, typed against the official Agent Client Protocol SDK message unions.
+- `@openma/common/protocol/openai-agents` — OpenAI Agents items, turns, and session stream events decoded into OpenMA events. The mapping matches backchat `direct-agent-runtime` at `64fd74d`.
+- `@openma/common/protocol/cursor-cloud` — Cursor Cloud Agents API v1 run SSE events decoded into OpenMA events.
+- `@openma/common/session-events/managed` — deprecated legacy Managed event projector plus a compatibility re-export of the v2 codec.
+- `@openma/common/session-events/acp` — deprecated ACP parser/turn projector plus a compatibility re-export of the SDK codec.
+- `@openma/common/session-events/openma` — OpenMA canonical event envelope, Vendor/raw records, and WorkItem lifecycle reducer.
+- `@openma/common/agent-contract` — immutable Agent facts, connector commands, and lifecycle helpers.
+- `@openma/common/agent-contract/acp` — ACP wire events translated into Agent facts.
+- `@openma/common/agent-contract/managed` — Claude Managed wire events translated into Agent facts.
+- `@openma/common/agent-ui` — replayable headless Agent UI reducer and subscribable framework-neutral store.
+- `@openma/common/session-kernel` — canonical local/cloud lifecycle, relay commands, and wire conversion.
+- `@openma/common/acp-fork` — browser-safe inclusive ACP fork client API: `forkSupport()`, `acpForkPointsFromMessages()`, `ACP_INCLUSIVE_FORK_CAPABILITY`, capability metadata helpers, and `AcpForkPoint` types. No Node built-ins and no SHA-256 fingerprinting; pass the selected `forkPoint` to the Node runtime (for example via `@openma/common/acp-runtime`) which builds `jetbrains.air.fork` request meta. See [docs/fork-support.md](./docs/fork-support.md).
+- `@openma/common/acp-runtime` — shared ACP session/runtime implementation used by both Backchat and OpenManaged. It exports `sessionConfigOptionsFromResponse()` (legacy `models` catalog → model select), `acpForkRequestMeta()` (`jetbrains.air.fork` v1, Node-only), re-exports the `acp-fork` client helpers, `probeAgentAuthStatus()`, and `authenticateAgent()`. Sessions expose `legacyModels` and `forkSupport`, and accept an optional `clientCapabilityOverlay` and `forkPoint`. See [docs/fork-support.md](./docs/fork-support.md).
+- `@openma/common/acp-runtime/node-spawner` — shared Node subprocess adapter for the ACP runtime. On POSIX it starts each agent in its own process group and signals that group on kill and on host shutdown. A pure Node process with no other listener for that `SIGHUP`, `SIGINT`, or `SIGTERM` re-raises the signal after cleanup, so the process still exits with it. The Electron main process keeps its own handlers; children are reaped from the `exit` hook when that process actually quits.
+- `@openma/common/acp-harnesses` — shared PATH-based ACP harness catalog (`DEFAULT_ACP_HARNESSES`) and persisted-catalog cloning and validation.
+- `@openma/common/acp-harnesses/registry` — official ACP registry fetch/cache plus OpenMA overlay (`known-agents`), and managed-bin / PATH detection.
+- `@openma/common/acp-harnesses/installer` — registry-backed npm/uvx/binary installs into a managed bin directory (host-agnostic `npmCommand` / `npmEnv`).
+- `@openma/common/acp-harnesses/headless-launch` — `buildAcpHeadlessLaunch(entry, options)`: the launch arguments and variables for one unattended run, built from the harness's own recipe (`KnownAgentEntry.headless`). See [Unattended runs and pinned installs](#unattended-runs-and-pinned-installs).
+- `@openma/common/acp-harnesses/agent-setup` — install/upgrade/uninstall and capability inspection service used by Backchat. See [Managed ACP harness installation](#managed-acp-harness-installation).
+- `@openma/common/acp-harnesses/custom-agents` — shared store for custom ACP agent definitions under `~/.oma`: `config.toml` `[[agents]]` override rows plus compatible reads of Martty `settings.json` `harnesses[]` rows (migrated on write). Versions in `args` are kept verbatim.
+- `@openma/common/session-ui` — shared Session turn frame, OpenMA/harness icons, live ACP configuration controls, and status semantics with product-specific content slots.
+
+`projectCanonicalChatTurns()` adapts Managed events into the same `TurnRender`
+model used by Backchat. This is the migration seam for a shared Session GUI;
+the current OpenManaged Console can move to it without changing its API wire
+format.
+
+Adapters keep wire-protocol differences at the boundary. Consumers may add
+product-specific presentation after normalization, but should not fork the
+shared parsing and reduction logic.
+
+The v2 event path is deliberately bidirectional only through the canonical
+protocol; harness adapters never map directly to each other:
+
+```text
+Managed SessionEvent / StreamSessionEvents ──decode──┐
+ACP notifications / requests / responses  ──decode──┤
+                                                         ├──▶ OpenMAEvent
+Managed EventParams                         ◀─encode──┤
+ACP request / notification / response       ◀─encode──┘
+                                                                  │
+                                                                  ▼
+                                                        headless AgentUIState
+                                                                  │
+                                                       React / Vue / CLI bindings
+```
+
+Codec results declare `exact`, `lossy`, or `unsupported` fidelity. Current
+official events without a harness-neutral projection are retained as
+`vendor.event`; unknown future or malformed records are retained as
+`raw.event`, so replay never silently discards evidence. The Anthropic SDK is
+an optional peer and a development dependency: the public codec declarations
+track its official unions without adding a runtime SDK import.
+Every official Managed Session event discriminant is classified explicitly as
+canonical or vendor-preserved, so an SDK union change fails typecheck until the
+mapping policy is reviewed.
+
+The `session-events/openma` export is the harness-neutral event boundary. It
+distinguishes canonical events from `vendor.event` records and opaque
+`raw.event` records; vendor/raw records do not imply GUI lifecycle semantics.
+
+## ACP inclusive fork
+
+Clients ask `forkSupport()` whether an agent can fork a whole session or from one assistant message. They do not hardcode harness names or versions. `SessionOptions.forkPoint` is valid only with `forkFromAcpSessionId`. After `initialize`, the runtime refuses the fork when `forkSupport()` is not `"message"` — it does not fall back to a whole-session fork. The same refusal applies when the caller puts `jetbrains.air.fork` on `sessionRequestMeta` directly. A supported `forkPoint` is deep-merged into that metadata for the `session/fork` request only, so other keys such as `claudeCode` stay in place.
+
+Adapters that implement the request advertise `sessionCapabilities.fork` together with `agentCapabilities._meta.jetbrains.air.fork = { "version": 1, "inclusive": true }`. The nested object is the capability. A flat `"jetbrains.air.fork"` key is not. Own adapters copy `ACP_INCLUSIVE_FORK_CAPABILITY` and keep it byte-identical; they do not depend on this private package.
+
+Truncation keeps the selected assistant message and everything before it, and drops everything after it. If that message contains tool calls whose results sit after the message, adapters remove those tool calls from the truncated message. The new session stays a legal model transcript, and `session/load` replay still ends on the target message. Tool calls that already completed before that message stay as they were. The contract, client example, and dependency order are in [docs/fork-support.md](./docs/fork-support.md).
+
+## Install from npm
+
+```json
+{
+  "dependencies": {
+    "@openma/common": "^0.9.1"
+  }
+}
+```
+
+Release tags are published to npm by CI with provenance. Built `dist/` output
+is what ships, so installs do not run package lifecycle scripts.
+
+## Install from Git
+
+Git installs keep working for pinned commits. Use an immutable release tag in `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@openma/common": "github:openma-ai/openma-common#v0.9.1"
+  }
+}
+```
+
+The lockfile resolves that tag to an exact commit. Built `dist/` output is
+committed, so consumer installs do not run package lifecycle scripts. Never
+move an existing tag; create a new one for every consumer-visible change.
+
+## Fast local development
+
+No npm or GitHub release is needed while iterating. From this repository, the
+single-command flow links all consumers, starts the common watch build, and
+restores the original dependencies on exit:
+
+```bash
+pnpm install
+pnpm dev:consumers
+```
+
+Run the consumer's normal dev server in another terminal, for example
+`pnpm --dir ../openma-desktop dev` or `pnpm --dir ../open-managed-agents/apps/console dev`.
+Press `Ctrl+C` in the common terminal when finished.
+
+For more control, `pnpm dev` starts only the common watch build;
+`pnpm link:consumers` and `pnpm unlink:consumers` can be run independently.
+The helper expects `openma-common`, `openma-desktop`, and
+`open-managed-agents` to be siblings. It swaps only each consumer's
+`node_modules/@openma/common` symlink (including the two ACP wrapper packages)
+and never edits a manifest or lockfile.
+
+## Change lifecycle
+
+1. Add or update tests here before implementation.
+2. Run `pnpm verify`.
+3. Link the package locally and verify both consumers.
+4. Merge the common change, bump `version`, then create an immutable `vX.Y.Z` tag.
+5. Update each consumer's Git ref and lockfile in an ordinary reviewed PR.
+
+Compatibility policy:
+
+- patch: fixes or additive fields that do not change existing output;
+- minor: new tokens, exports, normalized event variants, or optional behavior;
+- major: removed/renamed tokens, exports, types, or changed reducer semantics.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the release checklist.
+
+## Shared local runtime
+
+`@openma/common/local-runtime` owns the host-neutral ACP session execution loop,
+checkpoints, daemon connection state and graceful shutdown. CLI and desktop
+adapters provide process spawning, persistence, directory authorization, logging
+and UI. Sharing this code does not give an observer ownership of another process.
+
+`@openma/common/managed-runtime` owns the Managed Agents Work lease lifecycle,
+Session HTTP control channel, ACP event projection and semantic recovery. These
+modules use scoped Work credentials and the canonical `/v1/sessions` API. The
+legacy reverse-WebSocket connection remains separate for existing installations;
+importing this package alone does not migrate a daemon to the Work protocol.
+
+The runtime modules were extracted from open-managed-agents `af45e233` with their
+behavioral tests. Product adapters must depend on these exports rather than copy
+source snapshots. The package does not install services, select a tenant, or
+start a daemon on import.
+
+## Public website design
+
+Import `@openma/common/brand/website.css` for the Backchat-led marketing theme.
+It supplies `--site-*` colors, Geist/monospace stacks, 1180px content width,
+10px controls, 14px panels and 160ms transitions. Both public websites consume
+these values; app and Console themes continue using `brand/tokens.css`.
+
+Use `data-site-theme="light"` or `"dark"` for explicit selection; otherwise
+the palette follows the OS. Keep editorial content and product components in
+the consuming site. Use coral for the primary action, neutral bordered
+secondary actions, sans-serif headings, thin separators and generous sections.
+
+## Versioned ACP artifacts
+
+`@openma/common/acp-artifacts` prepares published ACP harnesses independently of
+the environment image. Execution still uses the existing shared ACP runtime.
+
+```ts
+const release = await resolveAcpRelease(
+  { id: "goose", version: "1.50.0" },
+  { type: "registry" },
+);
+// Persist the complete release with the Session before preparing/launching it.
+const prepared = await prepareAcpRelease(release, { root: "/tmp/acp-artifacts", signal });
+// Give command, args and env to the existing ACP runtime.
+```
+
+Supported sources:
+
+| Source | Resolution and preparation |
+| --- | --- |
+| `npm` / `npx` | Exact npm version and SHA-512 tarball integrity; isolated local install |
+| `uvx` | Exact PyPI version and artifact SHA-256 hashes; relocatable uv virtual environment |
+| `registry` | Official ACP `agent.json`, including exact historical/preview releases; binary → npx → uvx preference |
+| Binary manifest | Platform-specific archive/command from an ACP manifest; SHA-256 verified before extraction |
+
+`parseAcpReleaseSource()` accepts npm package strings for compatibility, or typed
+sources such as `{ type: "uvx", package: "python-agent", command: "agent", python: "3.12" }`.
+A registry source can set `preference: ["uvx", "npx", "binary"]`, or an operator's
+HTTPS `manifestUrl` with `{id}` / `{version}` placeholders. Custom manifests must
+identify the exact requested release. The public registry resolves historical
+versions through GitHub file history; it never substitutes the current version.
+The low-level `resolveNpmAcpRelease`, `resolveUvxAcpRelease` and
+`resolveBinaryAcpRelease` APIs remain available for hosts with their own catalogs.
+
+Binary formats: raw executable, zip, tar, tar.gz/tgz, tar.bz2/tbz2 and tar.xz/txz.
+Platform selection follows ACP's OS/architecture keys. Paths are checked before
+extraction; tar links and special files are rejected. Installer formats such as
+dmg, pkg, deb, rpm and msi are not executable distributions. Published checksums
+are verified. For an older registry entry without a checksum, the first HTTPS
+download's SHA-256 is recorded and subsequent preparation verifies that digest;
+this records content identity, rather than claiming publisher attestation.
+
+All release records have a digest. `validateAcpRelease()` validates restored
+records, and `acpReleaseMatchesSource()` checks that a Session's catalog binding
+has not changed. Publication is atomic, failed preparation remains unlaunchable,
+and different versions coexist. Caches are separated by OS/CPU; npm adds Node
+ABI and uvx adds Python runtime/interpreter identity. Already-prepared artifacts
+can be used offline. Registry-provided arguments and environment are preserved;
+hosts must still remove their own control-plane secrets from the final agent
+environment. Installer subprocesses receive only the minimal system environment.
+
+npm installs accept an optional `nodePath` (any Node-compatible executable) and
+`env` map; the installer runs the bundled `npm` CLI through that executable.
+Hosts that embed Node (for example Electron) pass their executable and whatever
+environment that runtime requires.
+
+The host environment needs Node/npm for npm sources when `nodePath` is omitted,
+uv plus a compatible Python interpreter for uvx, and bzip2/xz when those archive
+formats are used. Python
+interpreters may be provisioned with `uv python install`. uvx virtual environments
+use `bin/python` on POSIX and `Scripts\python.exe` on Windows. uvx handles console
+entry points and wheel-packaged scripts, verifies package ownership of the selected
+executable, and keeps entry points valid when a completed virtual environment is published.
+
+The release pins the top-level package/artifact. npm/uv resolve transitive
+packages on first installation; identical dependency trees across independently
+prepared sandboxes require bundled/shrinkwrapped or otherwise locked releases.
+A native package may additionally require system libraries from its environment.
+
+Artifact integration tests use actual npm/uv processes and local fixture
+registries. Running `pnpm verify` requires uv, Python 3, gzip, bzip2, xz and OpenSSL.
+Archive fixtures are built with the `tar` package. Product extraction uses that
+package as well; it does not shell out to system tar.
+
+Artifact installers retain `SSL_CERT_FILE`, `SSL_CERT_DIR` and
+`NODE_EXTRA_CA_CERTS` from the sandbox so its trusted outbound-proxy CA remains
+available. uv uses native TLS trust. Certificate verification stays enabled;
+Work/model credentials and arbitrary host environment variables remain excluded.
+
+## Managed ACP harness installation
+
+The harness modules vend Backchat's ACP registry and installer into
+`@openma/common` so Clash, Martty, and Backchat can share one implementation.
+`loadRegistry()` merges the official CDN registry with `OVERLAY_AGENTS` (pi/dsh
+npm overlays, featured metadata, and other curated entries). `detect()` /
+`detectAll()` resolve commands from the managed bin directory or system PATH as
+in Backchat.
+
+Hosts that bundle their own Node pass `npmCommand`, `npmCommandArgs`, and
+`npmEnv` into `installAcpRegistryAgent()` or `createAcpAgentSetupService()`.
+`@openma/common/acp-artifacts` remains the low-level release resolver for
+session-scoped artifact preparation; the harness installer uses registry
+snapshots and npm shims the same way Backchat does.
+
+```ts
+import { loadRegistry, detect } from "@openma/common/acp-harnesses/registry";
+import { installAcpRegistryAgent } from "@openma/common/acp-harnesses/installer";
+import { createAcpAgentSetupService } from "@openma/common/acp-harnesses/agent-setup";
+
+await loadRegistry({ cachePath: "/var/acp/.registry/official.json" });
+const claude = await detect("claude-acp", { managedBinDirs: ["/var/acp/bin"] });
+
+await installAcpRegistryAgent({
+  registryId: "codex-acp",
+  shimName: "openma-codex-acp",
+  binDir: "/var/acp/bin",
+  npmCommand: "/path/to/node",
+  npmCommandArgs: ["/path/to/npm-cli.js"],
+});
+
+const setup = createAcpAgentSetupService({
+  registryCachePath: "/var/acp/.registry/official.json",
+  acpBinDir: "/var/acp/bin",
+  acpInstallRoot: "/var/acp/install",
+});
+await setup.warmup();
+await setup.installAgent("pi");
+```
+
+## Unattended runs and pinned installs
+
+A host that runs a harness without a person at the keyboard (a benchmark trial,
+a CI job) names the harness id and passes generic options. Flags and variable
+names stay in the registry entry:
+
+```ts
+import { resolveKnownAgent } from "@openma/common/acp-harnesses/registry";
+import { buildAcpHeadlessLaunch } from "@openma/common/acp-harnesses/headless-launch";
+import {
+  acpLauncherInvocation,
+  installPinnedAcpHarness,
+  pinnedAcpHarnessPaths,
+  readAcpHarnessPinState,
+} from "@openma/common/acp-harnesses/installer";
+
+const entry = resolveKnownAgent("pi-acp")!;
+const { commandPath, version, dependencies } = await installPinnedAcpHarness({ entry, binDir });
+const { args, env, unsupported } = buildAcpHeadlessLaunch(entry, {
+  agentDir,        // the agent's user-level configuration directory
+  sessionDir,
+  trustProject: true,
+  provider: "deepseek",
+  model: "deepseek-v4-pro",
+  thinkingLevel: "medium",
+});
+if (unsupported.length > 0) throw new Error(`cannot express: ${unsupported.join(", ")}`);
+const { file, args: argv, windowsVerbatimArguments } = acpLauncherInvocation(commandPath, args);
+```
+
+**Launch.** `unsupported` lists every requested option the launch does not
+carry: one the recipe has no flag or variable for, and a `provider` or
+`thinkingLevel` given without a `model` (both are written inside the model
+value). A host that depends on an option, such as `agentDir` for isolation,
+must stop when the list is not empty. An entry without a recipe throws.
+
+**Pinned install.** `installPinnedAcpHarness` installs `entry.pinned`: the
+adapter package at one exact version, with `entry.pinned.dependencies` written
+as npm `overrides` in the install prefix and checked against what npm
+installed. It fails when a pinned package is missing or at another version,
+including when it reuses an existing install directory. The result carries
+`version` and `dependencies` (the installed versions), which a host should
+record with its run.
+
+A pinned install never uses the product install's names. Its launcher is
+`<shim>-pinned` (`openma-acp-pi-acp-pinned`) and its state is
+`registry/<id>-pinned/` (`install.json` and the versioned prefix), from
+`pinnedAcpHarnessPaths(entry, binDir)`. It can share a bin directory and
+install root with a product install without either overwriting the other.
+Hosts should still give benchmark installs a directory of their own.
+
+`readAcpHarnessPinState({ entry, shimPath })` compares an existing pinned
+install with the pins from local files only. It returns `null` for an entry
+that pins nothing and throws, like the installer, for pins that are not exact
+versions. Pins are applied in code-point order, so the install directory name
+is the same on every machine.
+
+`npmOverrides` on `installAcpRegistryAgent` applies to npm installs only. For
+a harness that installs as a binary or through uvx on the current platform the
+call throws instead of installing an unpinned agent.
+
+**Windows.** The pinned launcher is a `.cmd` file
+(`openma-acp-pi-acp-pinned.cmd`) that sets the entry's variables and calls the
+package's `.cmd` bin. A `.cmd` file cannot be started by `CreateProcess`, so
+start it with `acpLauncherInvocation(commandPath, args)`, which returns
+`cmd.exe /d /s /c "<line>"` with `windowsVerbatimArguments` on Windows and the
+launcher itself elsewhere. `npm` given as a bare name or a `.cmd` path runs
+through `cmd.exe` the same way; an executable path such as a bundled
+`node.exe` (`npmCommand` + `npmCommandArgs`) starts directly. The pinned
+install tests run on `verify-windows`. Product installs
+(`installAcpRegistryAgent`, `AcpAgentSetupService`) still write a POSIX shell
+shim and still follow `registryDistribution` and npm's latest.
+
+Only `pi-acp` has a recipe and pins today. The pins cover `@openma/pi-acp` and
+the `@earendil-works/*` packages it resolves. Other transitive dependencies
+still follow their own ranges. Update the pins in the same PR that moves the
+adapter to a new Pi SDK.
+
+## Coverage
+
+`pnpm test:coverage` writes `coverage/lcov.info`. CI uploads it to Codecov,
+and `codecov.yml` requires 100% coverage of the lines a pull request changes
+(`patch` target). The project-wide number is informational.

package/dist/acp-artifacts/binary.d.ts

@@ -0,0 +1,35 @@
+import { type ArtifactOptions } from "./shared.js";
+export type BinaryFormat = "raw" | "zip" | "tar" | "tar.gz" | "tar.bz2" | "tar.xz";
+export interface BinaryAcpRelease {
+    schema: "openma.acp.binary.v1";
+    id: string;
+    version: string;
+    platform: string;
+    archive: string;
+    sha256: string;
+    format: BinaryFormat;
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    digest: string;
+}
+export interface BinaryAcpReleaseInput {
+    id: string;
+    version: string;
+    platform: string;
+    archive: string;
+    sha256: string;
+    format?: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export declare function binaryFormat(address: string): BinaryFormat;
+export declare function resolveBinaryAcpRelease(input: BinaryAcpReleaseInput): BinaryAcpRelease;
+export declare function validateBinaryAcpRelease(value: unknown): BinaryAcpRelease;
+export declare function prepareBinaryAcpRelease(input: BinaryAcpRelease, options: ArtifactOptions & {
+    root: string;
+}): Promise<import("./shared.js").Launch & {
+    release: BinaryAcpRelease;
+}>;
+//# sourceMappingURL=binary.d.ts.map

package/dist/acp-artifacts/binary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.d.ts","sourceRoot":"","sources":["../../src/acp-artifacts/binary.ts"],"names":[],"mappings":"AAQA,OAAO,EAAkH,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnK,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AACnF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAC9C,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IACvE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;CAC7D;AACD,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjF;AACD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAS1D;AACD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,GAAG,gBAAgB,CAWtF;AACD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAMzE;AACD,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;;GAiDjH"}