relay-claude-channel 0.2.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "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/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,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/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.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "relay-claude-channel",
+  "version": "0.2.1",
+  "type": "module",
+  "description": "Relay channel for Claude Code. Bridges a Relay agent conversation into a Claude Code session over the experimental claude/channel MCP contract.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/relaymessenger/Relay-SDK.git",
+    "directory": "integrations/claude-code"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "files": [
+    ".claude-plugin/",
+    "commands/",
+    "runtime/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "check": "npm run typecheck",
+    "prepack": "npm run build",
+    "start": "node runtime/server.mjs",
+    "dev": "tsx server.ts",
+    "pack:smoke": "node scripts/pack-smoke.mjs",
+    "test": "node scripts/test.mjs",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@types/node": "^26.2.0",
+    "esbuild": "^0.28.2",
+    "tsx": "^4.23.11",
+    "typescript": "^7.0.2",
+    "zod": "4.4.3"
+  }
+}