@relaymessenger/cli 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Companion 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.

package/README.md

@@ -0,0 +1,139 @@
+# relaymessenger
+
+Message your local coding agent from your phone. `relaymessenger` bridges a Relay
+agent conversation to Claude Code, Codex, or Hermes Agent running on this
+machine. It also installs native Relay channels for Claude Code and OpenClaw.
+Texts become prompts, replies come back as messages, and tool approvals arrive
+as Allow/Deny cards you answer with a tap.
+
+Relay is messaging for agents — https://relayapp.im. API reference:
+https://docs.relayapp.im.
+
+## Quickstart
+
+```sh
+npm install -g @relaymessenger/cli
+
+# 1. Pair this machine with the Relay app (QR + short code, ~30 s)
+relaymessenger pair
+
+# 2. Start the bridge in the repo you want the agent to work in
+cd ~/code/my-project
+relaymessenger start --engine claude    # or: --engine codex | --engine hermes
+```
+
+Now text the agent from the Relay app. Each message (or quick burst of
+messages) becomes one engine turn; the bridge shows a typing indicator while
+the engine works and posts one finalized reply per turn.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `relaymessenger pair` | `POST /v1/pairings`, shows a terminal QR + code, long-polls until you claim it in the app, stores the Agent Token in `~/.relaymessenger/config.json` (chmod 600) and pins your user id as the bridge owner (from `GET /v1/agents/me`; override with `RELAY_OWNER_USER_ID`). If owner lookup is interrupted after the token is saved, running the command again resumes that saved token without creating another agent. The token never appears on the phone. |
+| `relaymessenger start` | Receive loop: long-polls `GET /v1/events`, drives the engine over ACP, replies via `POST /v1/messages` with an `Idempotency-Key`. Flags: `--engine claude\|codex\|hermes`, `--dir <path>`. Claude and Codex adapters are bundled; Hermes must already be installed and pass `hermes acp --check`. |
+| `relaymessenger install-codex` | Run from a project root to opt in that project only. Merges — never clobbers — `[mcp_servers.relay]` + `notify` into `~/.codex/config.toml` (comments preserved; a `.bak` of the original is kept) and a `PermissionRequest` hook into `~/.codex/hooks.json`. Other projects are suppressed until installed separately. Codex gates untrusted hook handlers: the first run may ask you to trust the relaymessenger handler. |
+| `relaymessenger install-claude` | After pairing, strictly validates the Claude plugin bundled in the installed npm package, persists its local marketplace under the paired account's private runtime directory, installs `relay@relaymessenger-bundled`, and writes the token/API origin/owner pin to `~/.claude/channels/relay/.env` with mode 600 without printing the token. It refuses to overwrite a different configured identity. |
+| `relaymessenger install-openclaw` | After pairing, persists and installs the OpenClaw plugin archive bundled in the npm package, adds only Relay's plugin/channel fields to `~/.openclaw/openclaw.json`, and writes the paired token to an owner-only file. Existing unrelated config is preserved and a different configured identity is refused. |
+| `relaymessenger doctor` | Checks Node, pairing, token file permissions, API reachability, installed adapter pins, and durable-state health. |
+
+## How the wire works
+
+Everything rides Relay's public agent API — the same surface you can drive
+with curl:
+
+```sh
+# what the bridge polls (agent bearer auth; long-poll, cursor acks ≤ N)
+curl -H "Authorization: Bearer $AGENT_TOKEN" \
+  "https://api.relayapp.im/v1/events?cursor=0&timeout=25"
+
+# what the bridge sends per finished turn
+curl -X POST https://api.relayapp.im/v1/messages \
+  -H "Authorization: Bearer $AGENT_TOKEN" \
+  -H "Idempotency-Key: relay-turn-<sha256(conversation,event-id-batch)>" \
+  -H "Content-Type: application/json" \
+  -d '{"conversation_id":"cnv_…","parts":[{"type":"text","text":"done"}]}'
+```
+
+- **Engines**: Claude and Codex are spawned as ACP adapters over
+  stdio (`@agentclientprotocol/claude-agent-acp`,
+  `@agentclientprotocol/codex-acp`). Both adapters are exact runtime
+  dependencies resolved from the installed package; the bridge never runs
+  mutable registry `latest` code. Adapter subprocesses receive platform and
+  engine/provider variables, not the complete parent environment. Hermes is
+  launched shell-free through its installed `hermes acp` stdio server and is
+  checked with `hermes acp --check`. Conversation → session bindings persist
+  in the paired account's runtime directory, so a conversation keeps its
+  engine context. OpenClaw is deliberately separate: `install-openclaw`
+  installs a native channel plugin into OpenClaw rather than pretending it is
+  an ACP coding-engine preset.
+- **Approvals**: an engine `session/request_permission` becomes a Relay
+  message with a text part plus an `agent_permission_request` data part
+  (origin-tagged Allow/Deny options and quick-reply chips). Tap a chip or text
+  `yes <id>` / `no <id>`. The full security-relevant tool input and affected
+  paths must fit in the card; an operation that cannot be represented in full
+  is denied instead of shown partially. No answer within 10 minutes → deny.
+- **Owner gate**: only the user pinned at pair time can prompt the engine or
+  answer an approval card; messages from anyone else are ignored before their
+  content is interpreted.
+- **Reliability**: the receive cursor advances only in the same atomic
+  (fsync + rename) write that persists the event queue
+  (`~/.relaymessenger/accounts/<origin-agent-hash>/state.json`), event ids are deduped, rapid messages debounce
+  ~800 ms into one turn, and the poll loop restarts with capped exponential
+  backoff + jitter. Each pending approval is its own create-once file under
+  that account's `approvals/`, so a bridge restart cannot lose one and no two
+  processes ever rewrite a shared snapshot. Engine/tool turns are at-most-once:
+  an attempt marker is durable before execution, so a crash never silently
+  repeats a deploy, deletion, command, or external send. Completed replies use
+  a durable outbox and stable idempotency key, so delivery can retry without
+  rerunning those tools. An interrupted turn is reported and must be retried
+  explicitly by the owner.
+- Long-poll is exclusive: an enabled webhook endpoint or a second poller gets
+  `409` (Telegram semantics). One consumer per token. A `401` stops the loop
+  with re-pair guidance instead of retrying.
+- **Codex notification privacy**: `install-codex` stores an explicit local
+  allowlist entry for the current project root in
+  `~/.relaymessenger/codex-notify.json`. A completed turn from any other project is
+  suppressed. For an allowed project, Relay receives the project directory's
+  basename plus Codex's complete `last-assistant-message`; input messages and
+  the absolute working-directory path are not sent. That text is retained in
+  Relay message history. There is no global-all-projects opt-in; run
+  `install-codex` in each
+  project you choose to disclose.
+- **Codex MCP sends**: `relay_send_message` requires a caller-chosen stable
+  `send_id`. Reuse the same `send_id`, conversation, and text only after an
+  unknown outcome; a changed payload is rejected. The mapping and
+  idempotency key live in the paired account's private runtime directory, so
+  a process restart cannot turn one logical send into two messages.
+
+## Development and testing
+
+- `RELAY_API_ORIGIN` points `pair`, `start`, and `doctor` at a
+  non-production Relay API origin, e.g. a local dev server:
+  `RELAY_API_ORIGIN=http://127.0.0.1:8787 relaymessenger pair`. This is a
+  development/testing mechanism only — production
+  (`https://api.relayapp.im`) stays the default, the value must be an
+  origin with no path/query/credentials, and plain HTTP is accepted only
+  for loopback hosts (same rule as every other origin the bridge uses).
+  Durable bridge state is scoped per effective origin, so an override
+  never replays or advances production cursors and ledgers.
+- With `--engine claude`, the bundled adapter inherits your Claude Code
+  settings. If the resolved `permissions.defaultMode` is
+  `bypassPermissions`, the engine never asks for approval, so phone
+  Allow/Deny cards will not appear; `relaymessenger start` and `relaymessenger doctor`
+  print a warning when they detect this.
+
+## Files
+
+```
+~/.relaymessenger/config.json    agent token, API origin, pinned owner   (chmod 600)
+~/.relaymessenger/codex-notify.json  locally allowed Codex project roots (not sent)
+~/.relaymessenger/accounts/<hash>/state.json     cursor, queued events/replies,
+                                           owner conversation (start-only)
+~/.relaymessenger/accounts/<hash>/approvals/     one file per pending approval
+~/.relaymessenger/accounts/<hash>/sessions.json  conversation → session bindings
+~/.relaymessenger/accounts/<hash>/mcp-sends/     durable Codex MCP logical sends
+~/.relaymessenger/accounts/<hash>/installed-plugins/  stable bundled plugin sources
+```
+
+Requires Node >= 22.18.

package/claude-plugin/marketplace/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "relaymessenger-bundled",
+  "description": "Bundled Relay channel plugin for Claude Code",
+  "owner": {
+    "name": "Relay"
+  },
+  "plugins": [
+    {
+      "name": "relay",
+      "source": "./plugins/relay",
+      "description": "Text your Claude Code from Relay: chat bridge and phone Allow/Deny permission relay"
+    }
+  ]
+}

package/claude-plugin/marketplace/plugins/relay/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "relay",
+  "description": "Relay channel for Claude Code — message your Claude Code session from your Relay agent conversation, with remote Allow/Deny permission relay. Run /relay:configure to set up.",
+  "version": "0.2.0",
+  "author": { "name": "Relay" },
+  "keywords": ["relay", "messaging", "channel", "mcp"],
+  "mcpServers": {
+    "relay": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/runtime/server.mjs"]
+    }
+  },
+  "channels": [
+    {
+      "server": "relay"
+    }
+  ]
+}

package/claude-plugin/marketplace/plugins/relay/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Companion 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.

package/claude-plugin/marketplace/plugins/relay/README.md

@@ -0,0 +1,173 @@
+# Relay channel for Claude Code
+
+Message a running Claude Code session through your Relay agent conversation.
+The plugin is a self-contained MCP stdio server for Claude Code's experimental
+[channels contract](https://code.claude.com/docs/en/channels-reference).
+
+- Owner-authenticated Relay messages enter the session as
+  `notifications/claude/channel` events.
+- The `reply` tool sends a logical message back with retry-safe idempotency.
+- Permission prompts can be reviewed and denied from Relay. Remote Allow is
+  available only when Claude supplies a complete, verifiable tool-input JSON;
+  otherwise approval remains local.
+
+## Requirements
+
+- Node.js 20.11 or newer
+- Claude Code with channel support (channels remain a research preview)
+- A Relay agent and Agent Token
+- No webhook enabled for that agent: Relay permits one event consumer, so
+  long-polling and webhook delivery are mutually exclusive
+
+## Install
+
+Install the published CLI, pair once, and install its bundled local
+marketplace:
+
+```sh
+npm install -g @relaymessenger/cli
+relaymessenger pair
+relaymessenger install-claude
+```
+
+`install-claude` strictly validates the bundled source, copies it to a stable
+content-addressed directory under the paired account's private Relay runtime,
+registers the local `relaymessenger-bundled` marketplace, and installs
+`relay@relaymessenger-bundled`. It does not depend on this GitHub repository or on
+the npm package remaining at its original install path. The installed plugin
+already contains `runtime/server.mjs` with all runtime dependencies bundled;
+do not locate a plugin cache or run `npm install` after installation.
+
+## Configure
+
+The install command also configures the channel without exposing the token:
+
+```text
+relaymessenger install-claude
+```
+
+That command writes the paired token, API origin, and owner pin to the
+platform-equivalent of:
+
+```text
+~/.claude/channels/relay/.env
+```
+
+with owner-only permissions and these values:
+
+```dotenv
+RELAY_AGENT_TOKEN=<your agent token>
+RELAY_BASE_URL=https://api.relayapp.im
+# Optional explicit owner pin. Otherwise GET /v1/agents/me must return one.
+#RELAY_OWNER_USER_ID=usr_...
+# Optional stable session namespace. Defaults to the Claude project directory.
+#RELAY_CHANNEL_SESSION_ID=my-repository
+# Explicit opt-in for a private agent only: trust the first user sender.
+#RELAY_ALLOW_TOFU=1
+```
+
+The file is mode 600/current-user-only. The command never prints the token and
+refuses to overwrite a different existing channel identity. Run
+`/relay:configure` for verification or for manual setup when relaymessenger is not
+available and you already have a token through another secure route.
+
+`RELAY_BASE_URL` must be an HTTPS origin with no path, query, fragment, or
+embedded credentials. Plain HTTP is accepted only for `localhost`,
+`127.0.0.1`, or `::1` development servers.
+
+Verify without printing the token:
+
+```text
+node <installed-plugin-directory>/runtime/server.mjs --check
+```
+
+## Run
+
+Custom channels require Claude Code's development-channel flag during the
+research preview:
+
+```text
+claude --dangerously-load-development-channels plugin:relay@relaymessenger-bundled
+```
+
+Use `server:relay` instead when registered as a bare MCP server.
+
+Only one live Claude session may consume an agent's event stream. A second
+session fails closed instead of stealing the long-poll consumer. Use a
+different Relay agent when two sessions must receive messages concurrently.
+
+## Delivery and retry contract
+
+Channel notifications are unacknowledged at the Claude transport layer. This
+plugin therefore stages each inbound event in an atomic local ledger before
+notifying Claude and includes `delivery_id="evt_..."` on the channel tag.
+Claude calls the `acknowledge` tool after fully handling it. Until then, the
+delivery is re-notified every 30 seconds and replayed after a channel restart.
+This is **at-least-once**, not exactly-once, delivery.
+
+A crash after an external side effect but before acknowledgement can replay the
+request. Before repeating a deploy, deletion, payment, shell command, or other
+non-idempotent action, reconcile whether it already succeeded. The bridge
+cannot make arbitrary tools exactly-once.
+
+Outbound `reply` calls require a `send_id`. Reuse the same `send_id`,
+conversation, and text for an unknown-outcome retry; use a new `send_id` for an
+intentional repeat. The mapping is persisted before the HTTP request, and
+reusing an id with different content is rejected.
+
+## Permission safety and data boundary
+
+Claude's channel permission notification exposes `input_preview`, documented
+as JSON truncated at 200 characters. The plugin no longer truncates or folds
+that field: it sends every character it receives and makes invisible controls
+visible. When the value is shorter than the truncation boundary and parses as
+complete JSON, the Relay card offers Allow and Deny. Otherwise it clearly says
+the input may be incomplete, offers only Deny, and requires local-terminal
+review to approve. This prevents a hidden destructive suffix from being
+approved remotely.
+
+Permission cards cross a data boundary: tool names, descriptions, shell
+commands, local paths, and prefixes or complete contents supplied in the input
+are uploaded to the configured Relay API and retained in Relay message history.
+Do not enable permission relay for repositories or commands whose details must
+not leave the machine. The Agent Token itself remains only in the local `.env`.
+
+Only the agent owner's Relay user id can inject messages or verdicts. The owner
+comes from `RELAY_OWNER_USER_ID` or `GET /v1/agents/me`; without one, startup
+fails closed unless `RELAY_ALLOW_TOFU=1` was explicitly set. TOFU is suitable
+only for an agent no one else can message.
+
+## Durable state
+
+State lives below `~/.claude/channels/relay/state/`, namespaced first by the
+canonical API origin and Relay agent id. The account directory contains:
+
+- `consumer-state.json` for the shared cursor and TOFU owner pin
+- `consumer-ledger.json` for unacknowledged deliveries and recent event ids
+
+Those two files are account-scoped so a later Claude session inherits the
+consumer position instead of replaying retained history. Each hashed session
+subdirectory separately contains `routing.json` and `session-ledger.json` for
+last-conversation routing, permission registrations, and logical outbound
+sends. A new session cannot answer an old session's permission card.
+
+Writes use owner-only files and atomic rename. If consumer cursor state or
+either security-critical ledger is corrupt, startup fails closed and preserves
+a block marker plus the quarantined file instead of resetting the cursor or
+silently replaying old events. Session routing state may be quarantined and
+reset because it does not guard event delivery or external side effects.
+
+## Development
+
+```text
+npm ci
+npm run check
+npm test
+npm run build
+npm run pack:smoke
+```
+
+`npm run build` produces the checked-in, self-contained
+`runtime/server.mjs`. `npm pack` runs that build again through `prepack`. The
+root release checks also run Claude Code's pinned `plugin validate --strict`
+against both the plugin and marketplace before npm publication.

package/claude-plugin/marketplace/plugins/relay/commands/configure.md

@@ -0,0 +1,71 @@
+---
+description: Configure and verify the self-contained Relay channel
+---
+
+Configure Relay without asking the user to paste or echo a secret in chat.
+
+1. Use the paired relaymessenger flow. Ask the user to run these locally if needed:
+
+   ```text
+   npm install -g @relaymessenger/cli
+   relaymessenger pair
+   relaymessenger install-claude
+   ```
+
+   `install-claude` installs the bundled local marketplace as
+   `relay@relaymessenger-bundled`, then copies the paired token, API origin, and
+   pinned owner into the channel `.env` with current-user-only permissions. It
+   never prints the token and refuses to overwrite a different configured
+   channel identity.
+
+2. Determine the user's channel directory using their platform conventions:
+   `~/.claude/channels/relay` on macOS/Linux or
+   `%USERPROFILE%\.claude\channels\relay` on Windows. Create it with access
+   restricted to the current user.
+
+   Verify that `.env` exists. Do not read or display its contents.
+
+3. If relaymessenger is unavailable and the user already obtained an Agent Token
+   through another secure route, they may create `.env` themselves with
+   current-user-only access:
+
+   ```dotenv
+   RELAY_AGENT_TOKEN=
+   RELAY_BASE_URL=https://api.relayapp.im
+   #RELAY_OWNER_USER_ID=usr_...
+   #RELAY_CHANNEL_SESSION_ID=my-repository
+   #RELAY_ALLOW_TOFU=1
+   ```
+
+   `RELAY_ALLOW_TOFU=1` is an explicit fallback only for an agent no one else
+   can message. Normally the owner comes from `GET /v1/agents/me`.
+
+   Never request, print, or place the token in a command argument.
+
+4. Do not run `npm install`. The installed plugin's
+   `runtime/server.mjs` already contains its runtime dependencies.
+
+5. After the user confirms the file is ready, run this from the installed
+   plugin directory using a platform-native path:
+
+   ```text
+   node runtime/server.mjs --check
+   ```
+
+   Report only success, agent id, or the sanitized error. Never display the
+   `.env` file or token. The check also rejects non-HTTPS remote origins.
+
+6. Explain how to start the research-preview channel:
+
+   ```text
+   claude --dangerously-load-development-channels plugin:relay@relaymessenger-bundled
+   ```
+
+   Use `server:relay` for a bare MCP registration. The agent must not have a
+   webhook enabled, and only one live Claude session can consume that agent.
+
+7. Ask the user to message the agent from Relay. Explain that messages are
+   delivered at least once until Claude acknowledges them. Permission cards
+   upload the displayed tool details to Relay history; an incomplete
+   200-character Claude preview can be denied remotely but must be approved at
+   the local terminal.