feat: add agent relay bridge plugin

.github/workflows/agent-relay-plugin.yml

@@ -0,0 +1,50 @@
+name: Agent Relay Plugin
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/agent-relay-plugin.yml"
+      - "plugins/agent-relay/**"
+  push:
+    branches: [master]
+    paths:
+      - ".github/workflows/agent-relay-plugin.yml"
+      - "plugins/agent-relay/**"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: agent-relay-plugin-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    defaults:
+      run:
+        working-directory: plugins/agent-relay
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+
+      - name: Install Node.js 22
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: plugins/agent-relay/package-lock.json
+
+      - name: Install production dependencies
+        run: npm ci --omit=dev
+
+      - name: Run plugin tests
+        run: npm test

plugins/agent-relay/.gitignore

@@ -0,0 +1 @@
+node_modules/

plugins/agent-relay/README.md

@@ -0,0 +1,64 @@
+# Agent Relay bridge plugin
+
+This optional Herdr plugin runs a Node 22+ sidecar in an explicitly opened tab.
+It forwards agent status changes for configured workspaces to one Agent Relay
+channel and exposes a read-only `herdr.session_summary` Relay action.
+
+The bridge never reads pane output, cwd, environment, or terminal titles. It
+does not expose prompt, key-send, shell, or raw-socket controls.
+It discovers pane membership from periodic session snapshots rather than
+replaying Herdr's retained lifecycle-event history.
+
+## Setup
+
+Install dependencies when authoring a linked checkout:
+
+```bash
+npm ci --omit=dev
+herdr plugin link /path/to/agent-relay
+```
+
+Herdr runs the same `npm ci --omit=dev` command automatically for GitHub
+installs. The plugin requires Node 22 or newer.
+
+Install the plugin from this public fork with:
+
+```bash
+herdr plugin install AgentWorkforce/herdr/plugins/agent-relay
+```
+
+Copy `config.example.json` to the directory reported by:
+
+```bash
+herdr plugin config-dir agent-relay.herdr-bridge
+```
+
+Name the copied file `agent-relay.json`, replace `workspaceKey`, and list only
+the Herdr workspace IDs that may be forwarded. The configured Relay channel
+must already exist; the bridge joins it before forwarding any status. Keep the
+workspace key private:
+
+```bash
+chmod 600 "$(herdr plugin config-dir agent-relay.herdr-bridge)/agent-relay.json"
+```
+
+Custom Relay endpoints must use HTTPS, except for loopback addresses used in
+local development. Then open the sidecar:
+
+```bash
+herdr plugin pane open --plugin agent-relay.herdr-bridge --entrypoint bridge
+```
+
+Closing that pane stops the bridge. It does not run from a startup hook.
+
+## State and safety
+
+The Relay agent token and status-transition dedupe state are stored only in
+`HERDR_PLUGIN_STATE_DIR`. The state file is mode 0600 on POSIX; on Windows it
+inherits the account-scoped ACL of Herdr's plugin state directory. Subsequent
+starts reconnect with that token rather than registering another Relay agent.
+An exclusive state-directory lock prevents two bridge panes from racing to
+rotate that token. A later start removes the lock automatically when its owner
+PID is no longer running; live or unidentifiable lock owners still fail closed.
+The configuration file belongs in `HERDR_PLUGIN_CONFIG_DIR`; do not commit a
+real workspace key.

plugins/agent-relay/config.example.json

@@ -0,0 +1,6 @@
+{
+  "workspaceKey": "rk_live_replace_me",
+  "baseUrl": "https://gateway.relaycast.dev",
+  "channel": "#agent-status",
+  "workspaceIds": ["w1"]
+}