@primusclaw/connector 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,37 @@
+MIT License
+
+Copyright (c) 2025 Advanced Micro Devices, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Third-Party Tools and Agents
+
+PrimusClaw can drive third-party coding agents, including Cursor Agent
+(`cursor-agent`), Claude Code (`@anthropic-ai/claude-code`) and OpenAI Codex
+(`@openai/codex`). Those tools are not distributed as part of this repository;
+they are installed at runtime and are governed by their own separate license
+terms, which the MIT license above does not cover. Users are responsible for
+reviewing and complying with the individual license for each tool they enable.
+
+## Bundled Third-Party Code
+
+The `sandbox/` directory is a fork of
+[kubernetes-sigs/agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox),
+which is licensed under the Apache License 2.0 — not the MIT license above. See
+`sandbox/LICENSE`, `sandbox/NOTICE` and `sandbox/UPSTREAM.md`.

package/README.md

@@ -1,3 +1,419 @@
-# Temporary Holding Version
+<!--
+Copyright Advanced Micro Devices, Inc.
+SPDX-License-Identifier: MIT
+-->
 
-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.
+# claw-connector
+
+Lets you drive the coding agents on your own machine (Claude Code, Codex, Cursor) from Claw and the chat
+clients built on it, for example from your phone.
+
+The connector only makes **outbound HTTPS requests** to Claw. It opens no port, and your machine needs no public address. Claw relays
+the conversation and keeps an audit trail; the agent itself, your files, your checkout and your model credentials
+stay on your machine.
+
+```
+phone / chat client --> Claw (remote agents) <-- connector on your machine --> agent adapter (stdio) --> your agent
+```
+
+Claw's side is documented in [claw/docs/remote-agents.md](https://github.com/AMD-AGI/PrimusClaw/blob/main/claw/docs/remote-agents.md); the wire
+contract is `claw/packages/protocol/src/remote-agents.ts`, compiled into this package.
+
+## Quick start (about 5 minutes)
+
+You need Node.js 22 or newer, a coding agent that already works on this machine (Claude Code, Codex or the Cursor CLI), and the
+two addresses the people who run your Claw give you: the Claw API URL and the identity service URL. The addresses below are
+placeholders. The Claude and Codex adapters are fetched by `npx` the first time a session starts, so the machine needs
+access to the npm registry.
+
+**1. Install**
+
+```sh
+npm install -g @primusclaw/connector
+claw-connector --version
+```
+
+If npm answers `EACCES`, point its global prefix at a directory you own (`npm config set prefix ~/.npm-global`, then put
+`~/.npm-global/bin` on your `PATH`) instead of using `sudo`. To update later, run the same `npm install -g` again.
+
+**2. Choose what an agent may touch**
+
+```sh
+claw-connector init      # writes agents.toml and prints where: ~/.config/claw-connector/agents.toml unless XDG_CONFIG_HOME or CLAW_CONNECTOR_HOME is set
+claw-connector status    # after you edit it: prints a "problem:" line if the file is wrong
+```
+
+By default every agent asks before it writes a file or runs a command, and your phone answers each question. To let phone sessions run
+like your terminal instead, run `claw-connector init --approval never` (or set `approval = "never"` on an agent later); see
+[Running without per-step approval](#running-without-per-step-approval).
+
+Open the file `init` printed and set `roots`, the directories an agent may work in. The sample enables `claude`, working in `~/work`;
+remove the `#` in front of the `codex` or `cursor` block to offer those too. A root that does not exist is reported as a problem, so
+create it or change it. See [agents.toml](#agentstoml).
+
+**3. Sign in**
+
+```sh
+claw-connector login --server https://claw.example.com/claw-api --identity-url https://identity.example.com
+```
+
+`login` prints a link and a short code. Open the link in a browser where you are signed in to Claw, check the machine name shown
+there, and confirm; the command then prints `signed in as <machine name>`. The connector holds a rotating sign-in token (file mode
+0600) and refreshes its short-lived access token by itself. Put `server` and `identity_url` in `agents.toml` and the two
+options can be left out.
+
+If there is no browser sign-in to use (a development server), use a Claw API key instead. Pass it in `CLAW_CONNECTOR_KEY`
+(replace the placeholder value) rather than with `--key`, which would show it in the process list:
+
+```sh
+CLAW_CONNECTOR_KEY='replace-with-your-claw-api-key' claw-connector login --server https://claw.example.com/claw-api
+```
+
+The key is stored as it is in `credentials.json` (mode 0600) and is for trying things out; the device sign-in is the normal way.
+
+**4. Run**
+
+```sh
+claw-connector run
+```
+
+It prints `connecting claude to https://claw.example.com/claw-api as "<machine name>"` and stays in the foreground: keep it in a
+terminal tab, `tmux` or `screen`. Ctrl-C stops it and every agent it started. From another terminal, `claw-connector status` shows
+whether it is running and signed in.
+
+**5. See it in Clawy**
+
+In Clawy (or any chat client built on Claw), send `/agents`. The agents of this machine are listed, online while `run` is up.
+A session started there runs on this machine, inside one of your `roots`, and each permission request comes back as a card in the chat.
+
+To disconnect: `claw-connector pause` (stay offline until `resume`), `claw-connector stop`, or `claw-connector logout` (also
+asks the identity service to revoke the device sign-in; a saved key is deleted from this machine, not revoked at Claw).
+
+## agents.toml
+
+```toml
+# Everything that limits an agent lives here, on your machine. Nothing Claw sends can widen it.
+server = "https://claw.example.com/claw-api"      # optional: --server / CLAW_URL
+identity_url = "https://identity.example.com"     # optional: --identity-url / CLAW_IDENTITY_URL
+name = "my-laptop"                                # shown to you in Claw; defaults to the host name
+
+[[agents]]
+id = "claude"
+preset = "claude"                  # claude | codex | cursor, or a custom command (below)
+roots = ["~/work"]                 # required: a session's directory must be inside one of these
+approval = "never"                 # optional, "ask" (the default) or "never": see "Running without per-step approval"
+
+[[agents]]
+id = "codex"
+preset = "codex"
+roots = ["~/work/repo-a", "~/work/repo-b"]
+[agents.env]                       # passed to the adapter; the model settings live here, never in Claw
+OPENAI_API_KEY = "..."             # or leave your own environment / CODEX_HOME to supply it
+
+[[agents]]
+id = "mine"
+kind = "my-agent"                  # a label chat clients pick an icon from
+command = "my-agent-acp"           # any agent that speaks the Agent Client Protocol over stdio
+args = []
+ask_mode = "careful"               # the mode in which it asks before it writes (required for a custom agent)
+roots = ["~/work"]
+```
+
+Presets and the adapter versions they pin (override `command` and `args` to move):
+
+| Preset | Command | Mode every session is forced into | Modes a phone may select | With `approval = "never"` |
+|---|---|---|---|---|
+| `claude` | `npx @agentclientprotocol/claude-agent-acp@0.99.0` | `default` | `default`, `plan` | `bypassPermissions` |
+| `claude-attach` | `npx @agentclientprotocol/claude-agent-acp@0.99.0` | `default` | `default`, `plan` | `bypassPermissions` |
+| `codex` | `npx @agentclientprotocol/codex-acp@2.3.0` | `read-only` | `read-only` | `agent-full-access` |
+| `cursor` | `agent acp` (the Cursor CLI) | `ask` | `ask`, `plan` | `agent`, started as `agent --force acp` |
+
+`claude-attach` does not start new conversations: it takes over Claude Code conversations that already exist on this
+machine (see [Taking over an existing conversation](#taking-over-an-existing-conversation)).
+
+An agent with no `roots` is never offered. A configuration problem is reported at start-up, not skipped.
+
+## Running without per-step approval
+
+By default every agent asks before it writes a file or runs a command, and the phone answers each question. To let a
+phone session run like your own terminal session (Claude `bypassPermissions`, Codex full access, Cursor `agent` with
+`--force`), turn the questions off for that agent:
+
+```sh
+claw-connector init --approval never                  # every sample agent
+claw-connector init --approval claude=never           # only Claude (repeatable: --approval never --approval cursor=ask)
+```
+
+or set `approval = "never"` in an `[[agents]]` table of an existing `agents.toml`. It is per agent, so Claude can run
+unattended while Cursor keeps asking. For that agent the connector then:
+
+- starts every session in the preset's no-approval mode (the table above; for a custom agent, `ask_mode` names it);
+- lets a phone select any mode the adapter offers (without the setting a phone can only select the safe modes);
+- accepts an adapter's warning that it will not ask for permission, which happens when your own Claude settings default to
+  `bypassPermissions`, instead of refusing the session (`mode_not_enforced`). The warning is written to `audit.jsonl`
+  with `accepted: true`. Without the setting that refusal stays, except that `allow_unsafe_modes = true` in the file
+  accepts it too, for every agent that has no `approval` of its own (below);
+- tells the phone: every agent reports `unattended` in its capabilities, and `session_started`, `session_resumed` and
+  `mode_update` carry `unattended`, so a client can always show whether a session asks. `status` and the line `run` prints
+  at start-up name the agents without per-step approval.
+
+**The risk, in one sentence:** an agent without per-step approval acts on whatever it is told, including text it read in
+a file or a web page, with everything your account can do inside its roots (and `--force` or full access reach outside the
+sandbox the adapter would otherwise keep), and nobody is asked first.
+
+**To go back:** set `approval = "ask"` on the agent and restart the connector (`claw-connector stop`, then `run`). The
+policy is read again on start, so a session that was unattended resumes asking. Setting `"ask"` is the way back that
+always works. Deleting the `approval = "never"` line is enough only when the file does not set `allow_unsafe_modes = true`:
+that is the older, coarser form, which lets a phone select unsafe modes for every agent and accepts the warning for all
+of them (but starts sessions in the asking mode), so an agent without an `approval` line of its own still resumes an
+unattended session unattended (the phone shows it). `approval = "ask"` on an agent overrides it for that agent.
+
+**Upgrading.** Two things change for an `agents.toml` that already exists, with no setting needed:
+
+- A file with `allow_unsafe_modes = true` now also accepts an adapter's "will not ask for permission" warning for every
+  agent without its own `approval`. Such a session used to be closed with `mode_not_enforced`; now it opens and is
+  reported `unattended`. Set `approval = "ask"` on an agent to keep refusing it.
+- A preset agent whose `safe_modes` or `ask_mode` names a mode the preset does not know to ask (for example `claude`
+  with `safe_modes = ["default", "plan", "acceptEdits"]`) is now a configuration error, and `claw-connector run` does not
+  start. Remove the mode, or set `approval = "never"` on that agent (or `allow_unsafe_modes = true` in the file, for an
+  agent that does not say `approval = "ask"`).
+
+## What the connector enforces
+
+All of these run on your machine and fail closed.
+
+- **Directories.** A session's working directory is resolved (symlinks included) and must be inside one of the agent's
+  `roots`; otherwise no process is started and the session is closed with `cwd_outside_roots`. The agent runs in the
+  resolved path.
+- **Ask mode, read back.** After the adapter creates a session, the connector sets the agent's ask mode and reads the
+  mode back from the adapter. Your own agent settings may start an adapter in a mode that never asks (bypass, full
+  access); an adapter that does not confirm the ask mode, or that warns it will not invoke its permission callback, is
+  not opened, unless you set `approval = "never"` for that agent (above) or `allow_unsafe_modes = true` for the file,
+  either of which accepts the warning and records it. A mode
+  change the agent makes on its own to a mode outside the allowed list is undone at once. The adapter's
+  `session/resume` can reset the mode, so it is locked again after every resume.
+- **Unsafe modes.** Modes in which the agent does not ask before writing (`acceptEdits`, `bypassPermissions`, Codex write and full-access
+  modes, Cursor `agent`) cannot be selected from a phone. `approval = "never"` on an agent, or `allow_unsafe_modes = true`
+  for the whole file, in `agents.toml` is the only way, and it is yours alone. Flags that turn a tool's own approvals off
+  (`--force`, `--yolo`, ...) in an agent's `args` are refused unless one of those is set too. A session recorded in a mode
+  you no longer allow comes back in the ask mode. On a preset agent `safe_modes` can only narrow what the preset
+  knows to ask (naming another mode is a configuration error unless the agent has `approval = "never"` or the file has
+  `allow_unsafe_modes`), and a session in a mode the preset does not know to ask is reported `unattended`.
+- **Cursor.** Measured on `agent acp` 2026.10.22: in `agent` mode a shell command asks (options `allow-once`, `allow-always`,
+  `reject-once`) but a file edit is applied without asking, whatever the approval setting. So the preset starts in `ask`,
+  which cannot write. `approval = "never"` selects `agent` and starts `agent --force acp` (`--force` is a root flag of the
+  Cursor CLI, "force allow commands unless explicitly denied"; it is accepted before or after `acp`). Cursor
+  has no `session/resume`; the connector uses `session/load` and marks the replayed history `replay: true`.
+- **Permissions.** Each permission request becomes a card with the options **the adapter offered**, passed through with
+  their own ids and kinds (`allow_once`, `allow_always`, `reject_once`). An answer must be one of those ids; any other is refused
+  and the request stays open. An unanswered request is answered `cancelled` after 10 minutes, and a cancel,
+  a close or an adapter exit answers every waiting request `cancelled`. Cursor's `cursor/create_plan` and a single
+  `cursor/ask_question` are shown as cards; a question the phone cannot carry is skipped, visibly, so the agent never waits.
+- **Automatic approval, by rule.** `auto_allow = [{ kind = "edit", path_glob = "docs/**" }]` (at file level or per agent) lets
+  a call through without asking when its kind matches and every path it touches is inside the session directory and
+  matches the glob. It uses the one-time option, never an "always" one, is decided on your machine, is written to the
+  audit log and is shown on the phone. The default is no rules.
+- **Credentials go over HTTPS only.** The Claw URL and the identity URL must be `https://` (`http://` is accepted only for
+  localhost, for a development server); `login` and `run` refuse anything else before a token is saved or sent.
+- **Existing conversations.** Taken over only when no other process holds them open, only from inside the roots, only in the
+  directory the conversation itself records, and in the ask mode (see above).
+- **No remote shell.** Only these commands are carried out: `session.new`, `prompt`, `cancel`, `set_mode`, `resume`,
+  `close`, `decision`. Anything else is dropped and audited. Claw never sends a command line, an environment variable or a
+  key.
+- **What leaves the machine.** Agent output, tool calls, diffs and command output are uploaded to Claw's event store (so
+  your phone can show them), after credential-shaped strings (API keys, tokens, bearer headers, private keys, JWTs) are
+  masked and long tool output is cut to 8 KB. Adapter stderr never leaves; it goes to `logs/` under the state directory.
+  A prompt's text is not written to the local audit log, only its hash and length.
+
+## Taking over an existing conversation
+
+An agent made from the `claude-attach` preset lists the Claude Code conversations on this machine whose directory is inside
+its `roots`, and lets you continue one from your phone. It reports them to Claw as an opaque list (`capabilities.resumable`:
+reference, title, directory, last activity, and whether anything holds it open), newest first, at most a dozen, so that a
+chat client can offer a choice; `session.new` then names the chosen one (`resume_ref`). Claw and the chat client know no
+product: the agent's `kind` is the label `attach`.
+
+```toml
+[[agents]]
+id = "claude-attach"
+preset = "claude-attach"
+roots = ["~/work"]
+# attach_cli = "claude"        # the command asked which sessions are open (default: claude, from PATH)
+# [agents.env]
+# CLAUDE_CONFIG_DIR = "/home/me/.claude"   # where the conversations live, if not the default
+```
+
+A taken-over conversation asks before every write and command like any other session. `approval = "never"` in this table
+works as it does for `claude`: the conversation is resumed in `bypassPermissions` and the phone shows it as unattended
+(see [Running without per-step approval](#running-without-per-step-approval)).
+
+What you do: **exit the conversation in the terminal first** (`/exit`), then pick it on the phone. When you are done,
+close it from the phone and continue in the terminal with `claude --resume <id>`: the turns you took on the phone are in
+its history, because both sides read and append to the same transcript.
+
+Why the terminal must be closed: Claude Code does not stop a second process from resuming a conversation that is still
+open, and two writers fork the transcript; the next resume follows only one branch, so a turn is lost without any error
+(measured). The connector therefore refuses to take over a conversation that another process holds open, and it checks again
+before it starts the agent again after a pause and before every prompt. A prompt that meets a terminal is rejected, not sent
+(the session stays, and the prompt can be sent again once the terminal is closed), and the connector's agent for the
+conversation is discarded: what the terminal wrote is not in its memory, so the next prompt starts a fresh one that reads
+the transcript. The same happens when the transcript is no longer the size the connector left it, which is how a terminal
+that came and went between two prompts is noticed.
+
+While the connector's own agent is working on the conversation (starting, or running a turn) the size cannot say whether
+someone else wrote, because the agent's own writes grow it too. So during that time the registry is read every second and
+once more, in full, when the work ends. A terminal that held the conversation open for about a second or more during a turn
+is noticed even if it has exited by the next prompt: that prompt goes to a fresh agent, after the full check above. One seen
+while the agent is starting refuses the takeover (`session_live`) and stops the agent. A terminal that opens and closes the
+conversation between two reads, which is shorter than anything that can take a turn, is not seen.
+
+The first thing asked is the terminal itself. `claw-connector init` (or `claw-connector hooks install`) adds two Claude Code
+hooks, `SessionStart` and `SessionEnd`, to the user-level `settings.json` of the Claude config directory. Each runs a tiny
+program that keeps one row per terminal session, `<config dir>/claw-connector-terminals/<pid>.json`: the session id and the
+process that holds it, with that process's start time. Claude Code runs the same hooks for sessions started by an ACP adapter
+(this connector's own included) and by `claude -p`; they are told apart by `CLAUDE_CODE_ENTRYPOINT` in the hook's environment
+(`cli` in a terminal, `sdk-cli` otherwise), so only terminal sessions are recorded. `SessionEnd` runs on `/exit`, Ctrl-C and
+Ctrl-D twice, a closed terminal (SIGHUP) and a plain `kill`; it does not run after `kill -9` or a power cut, so a row counts
+only while the process it names is still the same process (same start time), and the next hook sweeps dead rows away. The
+hooks are merged into `settings.json` without touching anything else in it (a file that is not valid JSON is left alone), take
+under two seconds at most (`SessionStart` holds up the first turn, so they have timeouts of 2 s and 1 s), print nothing and
+always exit 0, so they cannot get in the way of a session. `claw-connector hooks uninstall` takes exactly those entries out
+again (they carry the mark `--managed-by claw-connector`; a hook of your own is never taken for one of them). The entries name this installation's node and program by absolute path, so install from a durable one (`npm i -g
+@primusclaw/connector`) rather than a throwaway `npx` cache; `hooks status` and `run` say when a path is gone, and installing
+again repairs it. A conversation that was opened before the hooks were installed is not in the rows, and neither is one under a
+different config directory or when Claude Code is configured not to run user hooks: the rows can only add a refusal, and
+everything below stays in force as the fallback (`claw-connector hooks status` says where they stand).
+
+Who holds the conversation open is then asked of Claude Code itself
+(`claude agents --json`, which lists the live processes of this machine and ignores the files a killed one leaves behind)
+and of the registry Claude Code keeps in `$CLAUDE_CONFIG_DIR/sessions/`, whose rows are each checked against the process they
+name. The command does not report a row from another host or container that shares the directory (it asks whether the pid is
+alive here), and such a row cannot be checked: it counts as open whatever the command says. If the command is missing or
+fails, the registry alone is the answer; if neither can be read, the answer is "cannot tell" and the takeover is refused.
+A transcript written within the last 10 seconds is refused too (a terminal that has only just exited may still be writing). The reasons Claw is told are
+`session_live`, `recently_written` and `twin_check_failed`; the agent that this connector itself started for the conversation
+is not mistaken for a twin.
+
+The ask mode still applies: a conversation keeps the mode it was left in, often one that never asks (`bypassPermissions`),
+and the adapter says so while it sets the session up. That warning describes the mode that is about to be replaced, so it is
+set aside until the ask mode (`default`) is locked and read back from the adapter; a warning that comes after that, or a mode
+that is not confirmed, closes the session. The phone can select only the safe modes, as for every agent. Closing the
+session stops the agent process; it never deletes the conversation.
+
+## Commands
+
+| Command | |
+|---|---|
+| `init [--approval ask\|never \| AGENT=ask\|never] [--no-hooks]` | Write a sample `agents.toml`; an existing file is never touched. `--approval never` turns per-step approval off (see above). Also installs the Claude Code session hooks (`--no-hooks` skips that). |
+| `hooks install\|uninstall\|status` | The `SessionStart`/`SessionEnd` hooks alone; `--config-dir DIR` names the Claude config directory (default: those of the `claude-attach` agents, else `$CLAUDE_CONFIG_DIR` or `~/.claude`). |
+| `login` | Device sign-in. `--key <api key>` (or `CLAW_CONNECTOR_KEY`) is for development only. After a revocation, run it again: it connects this machine as a new connector. |
+| `run` | Connect and serve. Exit code 3 means the connector was revoked. |
+| `status [--json]` | Running or not, paused, signed in, agents, adapter processes. |
+| `pause` / `resume` | Stop every agent within a second and stay offline, or undo that. |
+| `stop` | Stop the running connector and every agent it started. |
+| `logout` | Stop, ask the identity service to revoke the sign-in, delete it from this machine. The stored connector id stays, so the next sign-in reuses the same connector. |
+
+**Kill switch.** Every adapter is started in its own process group and recorded (pid and start time) in
+`children.json`. `stop`, `pause`, a revocation and Ctrl-C signal exactly those groups: a process that is not recorded, or
+whose pid has been reused, is never signalled, and nothing here uses a pattern kill. If an adapter's group leader (an `npx` wrapper) died but the
+agent it started is still in that group, the group is still stopped. If you disconnect the connector in Claw,
+the connector sees it within a heartbeat, stops every agent and exits without retrying.
+
+## Files
+
+`~/.config/claw-connector/` (or `$XDG_CONFIG_HOME/claw-connector/`): `agents.toml`, `credentials.json` (0600; a file other users can read is
+refused). `~/.local/state/claw-connector/` (or `$XDG_STATE_HOME/claw-connector/`): `connector.json` (the connector's identity and the
+commands handled), `sessions.json`, `outbox/` (events not yet acknowledged by Claw), `audit.jsonl` (spawn, directory
+decisions, every command received, every permission request and answer, every automatic approval, mode changes),
+`logs/`, `children.json`, `connector.pid`. `CLAW_CONNECTOR_HOME=/some/dir` keeps all of it under one directory.
+
+## Restarts and crashes
+
+A prompt counts as handled only when it reaches the agent (or is dropped by a cancel, a close or a stop), so a connector that
+dies with a prompt still queued is sent that prompt again by Claw instead of losing it. A permission request waiting
+for an answer lives in the adapter, which dies with the connector: the next run closes such a card (`cancelled`, by
+`connector_restart`), so a phone is not left with a button that does nothing. Session state, unacknowledged events and
+their sequence numbers are on disk; a session resumes in a fresh adapter on its next prompt.
+
+Known limit: the working-directory check resolves the path and starts the adapter in the resolved path, but another process of
+the same user that can rewrite a directory in that path could swap a symlink between the check and the start. The
+whitelist protects against what Claw (or a phone) asks for, not against another local process of the same user, which could already
+run the agent itself.
+
+## Connection behaviour
+
+One long-lived `text/event-stream` carries commands to the connector; events go back in batches (150 ms or 20 events,
+one request at a time). Every event has a per-session sequence number written to disk before it is queued, and stays
+there until Claw acknowledges it, so a dropped connection, a failed request or a restart loses nothing and, because Claw
+stores each `(session, seq)` once, repeats nothing. The connector sends a heartbeat every 30 s, drops a stream that is silent for 75 s
+and reconnects with a 1 s to 60 s backoff with jitter. Commands are delivered at least once and carried out once
+(by command id and number). A card still waiting after a reconnect is sent again with the same action id.
+
+## Development
+
+```sh
+cd connector
+npm ci
+npm run typecheck && npm test      # node:test against a stand-in Claw and a stand-in ACP adapter (real processes, real sockets)
+npm run build                      # dist/cli.js and dist/terminal-hook.js; the wire contract from claw/packages/protocol is compiled in
+node scripts/check-pack.mjs        # packs the tarball: it must hold only dist/cli.js, dist/terminal-hook.js, README.md, LICENSE and package.json
+npm pack && npm install -g ./primusclaw-connector-*.tgz   # the package as the registry serves it, from a checkout
+```
+
+## Releasing (maintainers)
+
+A release is a GitHub Release whose tag is `connector-vX.Y.Z`, cut the way Hyperloom's are. Publishing it starts
+[connector-release.yml](https://github.com/AMD-AGI/PrimusClaw/blob/main/.github/workflows/connector-release.yml): it builds, tests and
+checks the tarball, signs a build-provenance attestation for it, attaches it to the release and publishes it to npm with Trusted Publishing
+(an OIDC credential; no npm token is stored anywhere). Only stable `MAJOR.MINOR.PATCH` versions are released: a prerelease needs a dist-tag,
+which OIDC publishing sets only with a newer npm and a separate permission on the Trusted Publisher entry.
+
+**What stops an unreviewed publish.** A release runs the workflow file as it exists at its tag, and a tag can point at any commit, so the
+checks inside that file (tag shape, the commit being in `main`, the environment below having a reviewer) catch honest mistakes and are not the
+control. The control is the GitHub environment `npm-publish`: one of its required reviewers must approve the `publish` job, and the Trusted
+Publisher entry on npmjs.com names that environment, so npm hands the publish credential to no other job. Only the `publish` job, which checks out
+and installs nothing, runs behind it. Two more rules narrow who can get that far. The environment does not let administrators bypass its
+protection, and a tag ruleset limits creating `refs/tags/connector-v*` to repository admins, so only an admin can start a release run at all.
+Self-review is allowed: the maintainer who cuts a release may approve its publish, so the approval is an explicit decision by a listed reviewer
+and not a second person's check. `scripts/release-tests/connector-release-workflow.sh`, run on every change by the Connector packaging
+workflow, fails if the workflow file stops having that shape, or if its environment check would refuse the environment as set up below.
+
+**One-time setup** (a repository admin, and a member of the `primusclaw` npm organisation). The order matters.
+
+1. Create the environment `npm-publish` (repository Settings > Environments) with **Required reviewers** (the people who may publish) and
+   **Allow administrators to bypass** off. **Prevent self-review** is left off, so a reviewer who cuts a release may approve it (turning it on is
+   accepted too). The release run refuses to build unless the environment has at least one required reviewer and administrator bypass is off.
+   Then add a tag ruleset (Settings > Rules > Rulesets, target: tags) matching `refs/tags/connector-v*` that restricts creation to repository
+   admins: with self-review allowed this is what limits who can start a release run, and a deployment tag rule on the environment alone does
+   not help, since the tag of an unreviewed commit matches it too. Do not restrict the environment to "Protected branches only": a release's
+   ref is a tag, so it would be refused.
+2. Publish 0.1.0 once by hand from a clean checkout of the merged `main` (the package must exist before it can be given a Trusted Publisher):
+   `cd connector && npm ci && npm publish --access public`, logged in to npm with 2FA.
+3. On npmjs.com, Packages > `@primusclaw/connector` > Settings > Trusted publishing > GitHub Actions: Organization `AMD-AGI`, Repository
+   `PrimusClaw`, Workflow filename `connector-release.yml`, Environment `npm-publish` (all case-sensitive; create the entry only after step 1).
+   Allowed actions: `npm publish`, which is what the workflow runs; leave dist-tag management off. The entry must see its first successful
+   publish within 2 days or it expires.
+4. Settings > Publishing access: require two-factor authentication and disallow tokens.
+
+**Cutting a release.**
+
+1. Set the new version in `package.json` and `src/version.ts` (`scripts/check-pack.mjs` fails if they disagree) and merge that to `main`.
+2. Write the release notes from the PR descriptions, not from commit subjects: every change states in its PR what a user will now observe.
+   For the PRs that touched `connector/` since the previous release (`prev` is its tag, or for the first workflow release the commit 0.1.0 was
+   published from):
+   ```sh
+   prev=connector-v0.1.0
+   git fetch origin main --tags
+   for n in $(git log --first-parent --format=%s "$prev"..origin/main -- connector/ | grep -o '(#[0-9]*)$' | tr -d '(#)'); do
+     gh pr view "$n" --repo AMD-AGI/PrimusClaw --json number,title,body --jq '"## #\(.number) \(.title)\n\n\(.body)\n"'
+   done > notes.md
+   ```
+   Edit `notes.md` into the notes a user of the package wants to read.
+3. Publish the release on the merged commit (not as a pre-release):
+   `gh release create connector-v0.1.1 --target <sha-on-main> --title "claw-connector 0.1.1" --notes-file notes.md`
+4. The `package` job runs and writes a summary: the commit, whether the release workflow at that commit equals the one on `main`, and the
+   tarball's name, sha256 and files. A reviewer opens the run, checks that the tagged commit is the reviewed one on `main` and that the
+   workflow file is `main`'s (if the summary says it is different, read the diff first), and approves `publish`. The job then attests the
+   tarball, attaches it to the release and publishes it.
+5. Check it: `npm view @primusclaw/connector version`, and `gh attestation verify primusclaw-connector-0.1.1.tgz --repo AMD-AGI/PrimusClaw`
+   on the tarball attached to the release.