feat: add agent relay bridge plugin

[khaliqgant]

Summary

• add an optional Node 22 Herdr pane plugin backed by @agent-relay/sdk
• forward status transitions only for explicitly configured Herdr workspaces to an existing Relay channel
• expose a read-only herdr.session_summary action with strict input/output schemas
• reconnect through a private persisted token, serialize state writes, retry failed delivery safely, and prevent duplicate bridge processes
• keep pane output, cwd, environment, titles, prompts, shell input, and raw socket controls outside the integration boundary
• test the plugin on Linux, macOS, and Windows with full-SHA-pinned Actions

Validation

• mise x node@22 -- node --test — 9/9 passed
• npm audit --omit=dev --audit-level=high — 0 vulnerabilities
• syntax checks for all plugin modules — passed
• actionlint .github/workflows/agent-relay-plugin.yml — passed
• git diff --check — passed
• isolated public install from AgentWorkforce/herdr/plugins/agent-relay --ref feat/agent-relay-sdk — passed at b033ea3
• hosted core checks on Ubuntu, macOS, and Windows — passed

Scope and workflow

The stable root docs/changelog are intentionally unchanged; setup and security documentation is plugin-local. The implementation was built by a Fleet team on finn-mini, transferred with checksums over Agent Relay, and independently reviewed across Fleet nodes without SSH.

---

Summary by cubic

Adds the optional agent-relay.herdr-bridge plugin to forward selected Herdr agent status updates to Agent Relay and provide a read-only herdr.session_summary action. Improves restart reliability and hardens runtime/tests; core behavior is unchanged.

• New Features

  • Node 22 sidecar using @agent-relay/sdk forwards pane.agent_status_changed for allowlisted workspaceIds to the configured channel, and registers herdr.session_summary with strict input/output schemas.
  • Simple config via agent-relay.json (workspaceKey, HTTPS baseUrl with loopback exception, #channel, unique workspaceIds); includes plugin manifest, README, and a CI workflow running tests on Linux/macOS/Windows.

• Safety and Reliability

  • Avoids lifecycle replay loops by rebuilding per-pane subscriptions from session.snapshot; auto-resubscribes on socket drop; supports Windows named pipe sockets.
  • Persists and reuses the Relay agent token; prevents duplicate bridge processes with a state lock and secure file permissions; releases the lock early for fast restarts and cleans up stale/stuck locks.
  • Idempotent, deduped transitions per pane with rollback on delivery failure; serialized state writes; keeps pane output, cwd, environment, titles, prompts, shell input, and raw socket controls outside the integration boundary.
  • Scopes the lifecycle-replay test fixture to its specific test to avoid cross-test replays.

^{Written for commit c9d8076. Summary will update on new commits.}

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c6dde068f7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a2f55543-9730-4873-b90f-f9fe06c3c200

📥 Commits

Reviewing files that changed from the base of the PR and between e7fc85b and c9d8076.

⛔ Files ignored due to path filters (5)

• plugins/agent-relay/dist/bridge.mjs is excluded by !**/dist/**
• plugins/agent-relay/dist/config.mjs is excluded by !**/dist/**
• plugins/agent-relay/dist/herdr-socket.mjs is excluded by !**/dist/**
• plugins/agent-relay/dist/state.mjs is excluded by !**/dist/**
• plugins/agent-relay/package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (7)

• .github/workflows/agent-relay-plugin.yml
• plugins/agent-relay/.gitignore
• plugins/agent-relay/README.md
• plugins/agent-relay/config.example.json
• plugins/agent-relay/herdr-plugin.toml
• plugins/agent-relay/package.json
• plugins/agent-relay/test/bridge.test.mjs

---

📝 Walkthrough

Walkthrough

Adds the Agent Relay plugin package configuration, secure setup documentation, cross-platform CI testing, and comprehensive bridge tests covering configuration, locking, status processing, subscriptions, persistence, and reconnection.

Changes

Agent Relay plugin

Layer / File(s)	Summary
Plugin package and runtime setup .github/workflows/..., plugins/agent-relay/package.json, plugins/agent-relay/herdr-plugin.toml, plugins/agent-relay/config.example.json, plugins/agent-relay/README.md, plugins/agent-relay/.gitignore	Defines the private Node 22 package, Herdr pane, sample configuration, setup and security documentation, dependency ignore rules, and cross-platform npm test workflow.
Bridge configuration and state safeguards plugins/agent-relay/test/bridge.test.mjs	Tests configuration parsing and redaction, secure file permissions, interprocess locking, stale-lock recovery, and Windows socket naming.
Status normalization and transition handling plugins/agent-relay/test/bridge.test.mjs	Tests workspace filtering, snapshot aggregation, idempotent status handling, and transition rollback.
Subscription and reconnection validation plugins/agent-relay/test/bridge.test.mjs	Adds a fake Herdr server and integration tests for subscription refresh, persisted-token reuse, action emission, shutdown, and resubscription after disconnects.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Poem

I’m a rabbit hopping through the bridge,
With tidy locks along the ridge.
Status hops once, then waits its turn,
While relay lights and test panes burn.
Node twenty-two keeps watch tonight—
CI thumps its paws: all right!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding the Agent Relay bridge plugin.
Description check	✅ Passed	The description is directly related to the plugin, tests, workflow, and safety changes in the pull request.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/agent-relay-sdk

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[khaliqgant]

Public-install E2E passed on exact head c9d80761495514cdaf1b1c2fb0b84007a61a0d27:

• A fresh isolated Herdr 0.7.5 session installed AgentWorkforce/herdr/plugins/agent-relay --ref feat/agent-relay-sdk; the installer resolved that exact commit and ran the declared npm ci --omit=dev build.
• A real pane.report-agent working transition from w1:p1 arrived exactly once in the configured Relay channel.
• Agent-scoped Relay invocation of herdr.session_summary completed with structured output: one working agent and zero in the other status buckets.
• Closing the real plugin pane reproduced Herdr PTY teardown with a lock owned by a verified-dead PID. Reopening from the untouched GitHub-installed artifact recovered that lock automatically, retained the identical persisted token fingerprint and Relay sender identity, and replayed no historical status.
• A post-restart idle transition arrived exactly once; a second action invocation returned one idle agent.
• Config and state files were mode 0600. The isolated plugin pane, Herdr server, Relay channel, and test lock were cleaned up afterward.

The live run also verified the action fix that returns results through Relay invocation output instead of attempting to DM the transport caller label. Local plugin tests pass 11/11, plus Node syntax checks, cargo fmt --check, and git diff --check.