Add Bridge & Staffing design for multi-project orchestration by khaliqgant · Pull Request #9 · AgentWorkforce/relay

khaliqgant · 2025-12-21T10:03:34Z

Introduces the "bridge" command for cross-project agent coordination:

Architect/Principal role as orchestrator connecting multiple projects
Leads with spawn capability to dynamically create worker agents
Standup protocol for daily work coordination
Multi-project dashboard visibility

Introduces the "bridge" command for cross-project agent coordination: - Architect/Principal role as orchestrator connecting multiple projects - Leads with spawn capability to dynamically create worker agents - Standup protocol for daily work coordination - Multi-project dashboard visibility

- bridge: just project paths as args - lead: just your name - System handles all complexity underneath

- Add bridge module with MultiProjectClient for multi-socket connections - Add AgentSpawner for lead agents to spawn/release workers - Add 'bridge' command: agent-relay bridge ~/project1 ~/project2 - Add 'lead' command: agent-relay lead Alice claude - Support config file for project defaults (~/.agent-relay/bridge.json) - Support --cli override for all projects

Add Multi-Project Orchestration section with: - Bridge command usage - Lead command usage - Cross-project messaging syntax - Spawn/release worker patterns - Link to full design doc

- agent-relay-spawn-handler: Wire up spawn/release in lead mode - agent-relay-cross-project-parser: Add project:agent syntax - agent-relay-multi-project-dashboard: Bridge view for dashboard

Copilot

Pull request overview

This PR introduces a multi-project orchestration layer that enables a single "Architect" agent to coordinate work across multiple projects, each managed by a "Lead" who can dynamically spawn worker agents.

Key Changes:

New bridge command for cross-project agent coordination via multi-socket connections
New lead command for project leads with worker spawning capabilities
Infrastructure for dynamic agent spawning and release via tmux

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
src/cli/index.ts	Added `bridge` and `lead` CLI commands with multi-project connection and spawn management
src/bridge/config.ts	Configuration loading and project resolution logic for bridge mode
src/bridge/multi-project-client.ts	Client for connecting to multiple project daemons simultaneously
src/bridge/spawner.ts	Agent spawning service for creating/releasing worker agents in tmux windows
src/bridge/types.ts	Type definitions for bridge, spawn, and worker management
src/bridge/utils.ts	Utility functions for shell escaping, sleep, and target parsing
src/bridge/index.ts	Module exports for bridge functionality
docs/DESIGN_BRIDGE_STAFFING.md	Comprehensive design document for the bridge and staffing feature
README.md	Updated with multi-project orchestration usage examples
.beads/issues.jsonl	Added tracking issues for remaining implementation work

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-21T10:43:45Z

+
+ // Handle messages from projects
+ client.onMessage = (projectId, from, payload, messageId) => {
+ console.log(`[${projectId}] ${from}: ${payload.body.substring(0, 80)}...`);


Potential error if payload.body is undefined or not a string. Add a check or default value before calling substring().
Suggested change
console.log(`[${projectId}] ${from}: ${payload.body.substring(0,80)}...`);
constbodyText=
payload&&typeofpayload.body==='string'
? payload.body
: String(payload?.body??'');
console.log(`[${projectId}] ${from}: ${bodyText.substring(0,80)}...`);

Copilot · 2025-12-21T10:43:45Z

+ const [mainCommand, ...commandArgs] = cli.split(':');
+
+ const wrapper = new TmuxWrapper({
+ name,
+ command: mainCommand,


The variable name mainCommand is ambiguous as it could be confused with a system command. Consider renaming to cliTool or baseCli to clarify it represents the CLI tool portion.
Suggested change
const[mainCommand, ...commandArgs]=cli.split(':');
constwrapper=newTmuxWrapper({
name,
command: mainCommand,
const[cliTool, ...commandArgs]=cli.split(':');
constwrapper=newTmuxWrapper({
name,
command: cliTool,

Copilot · 2025-12-21T10:43:46Z

+export function escapeForShell(str: string): string {
+ return str
+ .replace(/\\/g, '\\\\')
+ .replace(/"/g, '\\"')
+ .replace(/\$/g, '\\$')
+ .replace(/`/g, '\\`')
+ .replace(/!/g, '\\!');
+}


The shell escaping implementation may not handle all edge cases for shell injection. Consider using a well-tested library or adding single quote escaping and newline handling for more robust protection.

Copilot · 2025-12-21T10:43:46Z

+ try {
+ await execAsync(`tmux has-session -t ${this.tmuxSession} 2>/dev/null`);
+ } catch {
+ // Session doesn't exist, create it
+ await execAsync(
+ `tmux new-session -d -s ${this.tmuxSession} -c "${this.projectRoot}"`


The tmux session name is not escaped before being used in a shell command. If this.tmuxSession contains shell metacharacters, it could lead to command injection. Use proper escaping or validate the session name format.
Suggested change
try{
awaitexecAsync(`tmux has-session -t ${this.tmuxSession} 2>/dev/null`);
}catch{
// Session doesn't exist, create it
awaitexecAsync(
`tmux new-session -d -s ${this.tmuxSession} -c "${this.projectRoot}"`
constsafeSession=escapeForTmux(this.tmuxSession);
try{
awaitexecAsync(`tmux has-session -t ${safeSession} 2>/dev/null`);
}catch{
// Session doesn't exist, create it
awaitexecAsync(
`tmux new-session -d -s ${safeSession} -c "${this.projectRoot}"`

Copilot · 2025-12-21T10:43:46Z

+ } catch {
+ // Session doesn't exist, create it
+ await execAsync(
+ `tmux new-session -d -s ${this.tmuxSession} -c "${this.projectRoot}"`


Both this.tmuxSession and this.projectRoot are interpolated into shell commands without proper escaping. Use the escapeForShell utility function to prevent command injection.

Copilot · 2025-12-21T10:43:47Z

+ ).catch(() => {});
+
+ // Wait a bit for graceful shutdown
+ await sleep(2000);


Another hardcoded sleep duration. Define this as a named constant (e.g., GRACEFUL_SHUTDOWN_DELAY_MS) for better maintainability.

Copilot · 2025-12-21T10:43:47Z

+ type: 'PONG',
+ id: uuid(),
+ ts: Date.now(),
+ payload: (envelope.payload as { nonce?: string }) ?? {},


The nullish coalescing operator (??) here is unnecessary because envelope.payload as { nonce?: string } will never be null or undefined from a type cast. If the intent is to provide a default when payload is missing, check envelope.payload directly.
Suggested change
payload: (envelope.payloadas{nonce?: string})??{},
payload: envelope.payload ? (envelope.payloadas{nonce?: string}):{},

Copilot · 2025-12-21T10:43:47Z

+ await execAsync(`cd "${project.path}" && agent-relay up &`, {
+ timeout: 5000,


The project.path is interpolated into a shell command without escaping. Use proper escaping to prevent command injection if the path contains shell metacharacters.
Suggested change
awaitexecAsync(`cd "${project.path}" && agent-relay up &`,{
timeout: 5000,
awaitexecAsync('agent-relay up &',{
timeout: 5000,
cwd: project.path,

Copilot · 2025-12-21T10:43:48Z

+ // Start daemon in background
+ await execAsync(`cd "${project.path}" && agent-relay up &`, {


Using & to background the process in a shell command passed to execAsync may not work as intended. The parent process will complete immediately, and the backgrounded process may not be properly managed. Consider using a proper process spawning mechanism or handling the async nature differently.
Suggested change
// Start daemon in background
awaitexecAsync(`cd "${project.path}" && agent-relay up &`,{
// Start daemon; let agent-relay manage its own backgrounding if needed
awaitexecAsync(`cd "${project.path}" && agent-relay up`,{

Copilot · 2025-12-21T10:43:48Z

+ │ auth-service │ │ frontend │ │ api-service │
+ │ Project Daemon │ │ Project Daemon │ │ Project Daemon │
+ │ │ │ │ │ │
+ │ Socket: │ │ Socket: │ │ Socket: │


The ASCII diagram uses inconsistent line styles (box-drawing characters). While functional, using consistent Unicode box-drawing characters throughout would improve visual consistency.

- config.test.ts: Tests for path resolution, lead naming, project resolution - utils.test.ts: Tests for target parsing, shell escaping 26 tests passing

Tests actual socket connections with real daemons for: - Connection management across multiple projects - Message routing to specific project agents - Lead alias resolution - Broadcast to all leads

Track implementation of Slack-style thread replies with parent_message_id tracking, nested UI display, and notification badges.

Frontend changes: - Complete redesign with Slack-inspired layout (sidebar + main panel) - Channel-based navigation (#general, #broadcasts, agent DMs) - Command palette with Cmd+K for quick actions and search - Presence indicators (online/offline) on agent avatars - Message bubbles with avatars, timestamps, and hover actions - Date dividers and thread indicators (UI ready for threads feature) - Auto-resizing composer with target selector - Typing indicator UI (infrastructure ready) Backend changes: - Add presence table for real-time status tracking - Add read_state table for unread message counts - Add presence management methods (updatePresence, getAllPresence) - Add typing indicator support (setTypingIndicator) - Add read state tracking (updateReadState, getUnreadCounts) Design system: - CSS custom properties for theming - Inter font for UI, JetBrains Mono for code - Slack-accurate color palette and spacing

Frontend TypeScript modules: - types.ts: Type definitions for Agent, Message, AppState, DOMElements - utils.ts: Utility functions (escapeHtml, formatTime, getAvatarColor, etc.) - state.ts: Reactive state management with subscribe/notify pattern - websocket.ts: WebSocket connection with reconnection logic - components.ts: UI rendering (agents, messages, command palette) - app.ts: Application entry point and event listeners - index.ts: Module exports Testing: - utils.test.ts: Comprehensive tests for utility functions - state.test.ts: Tests for state management and message filtering - vitest.config.ts: Added jsdom environment for frontend tests Build configuration: - Added esbuild for bundling frontend TypeScript - Added build:frontend script to package.json - Added jsdom dev dependency for DOM testing - Created frontend-specific tsconfig.json HTML updated to load bundled /js/app.js module

- Exclude src/dashboard/frontend from main tsconfig to prevent DOM type errors - Fix project-namespace test to check for .project marker instead of just data dir - Add built frontend bundle

- .env.example: Environment variables reference - cli-usage.sh: CLI command examples - programmatic-usage.ts: Library usage in TypeScript - docker-compose.yml: Docker deployment example - agent-relay.service: Systemd service file - README.md: Examples documentation

…:khaliqgant/agent-relay into claude/review-pr-9-6HyEY

Add beads task for threaded conversations feature

- computeNeedsAttention: derive agents needing attention from message history - findAgentConfig: auto-detect agent role from .claude/agents/ or .openagents/ - Includes full test coverage for both utilities - Enables agent-relay-9w0 (auto-detect role) implementation - Tests passing: 452/453 ✓

@project

Major Changes: - Cross-project message support (@project:agent syntax) - Bridge interface for project-based messaging - Dashboard display with project badges - Agent auto-detection from .claude/agents config - Needs-attention indicators for pending messages Features: - computeNeedsAttention: Heuristic for pending message detection - Agent config detection from frontmatter - Project namespace support in relay messages - Enhanced bridge header and navigation Tests: - 452/453 tests passing ✓ - Full coverage for new utilities - Integration tests complete Issues Created: - agent-relay-9uq: Project chat targeting - agent-relay-1t7: Project name display - agent-relay-vxc: Navigation consistency - agent-relay-290: Interface parity [bd-agent-relay] Dashboard + Bridge improvements complete

@project

Bridge Features Completed: - Project connection status (Online/Reconnecting/Offline with pulsing) - Project chat targeting (message composer with project/agent dropdowns) - Project name display in bridge header (with back link + highlighting) - Navigation consistency (Dashboard ↔ Bridge seamless transitions) - Interface parity audit (bridge vs dashboard features locked) - Multi-project client reconnection (exponential backoff, configurable) Dashboard Features: - needsAttention indicators (pulsing badge, real-time updates) - Project-based communication (selective targeting) - Cross-project messaging (@project:agent syntax) - Agent auto-detection from .claude/agents config All tests passing (457+). Bridge UI production-ready.

- POST /api/spawn - Create new agent with name, cli, task - GET /api/workers - List active spawned workers - DELETE /api/workers/:name - Release a worker Enable with: agent-relay up --spawn

- Remove --spawn flag requirement, API always enabled - Rename /api/workers to /api/spawned for consistency - Update response field from 'workers' to 'agents'

…tart Three bug fixes reported during MCP testing: 1. **Spawn race condition fix** (Bug #10): Added spawningAgents mutex to prevent concurrent spawn requests for the same agent from both passing the activeWorkers.has() check before either completes. 2. **SIGKILL diagnostics** (Bug #7, #10): Added gatherSigkillDiagnostics() to capture memory usage, process count, and OOM killer messages when exit code 137 or SIGKILL is detected. This helps diagnose resource exhaustion issues. 3. **Orphan cleanup** (Bug #8, #9): Added cleanupOrphanedWorkers() that runs on spawner startup to kill relay-pty processes from a previous daemon run. This ensures a clean slate after daemon restarts. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

claude added 6 commits December 21, 2025 09:43

Simplify bridge/lead CLI to minimal interface
84423ef
- bridge: just project paths as args - lead: just your name - System handles all complexity underneath

Update package-lock.json
635460e

Document bridge and lead commands in README
ebd8940
Add Multi-Project Orchestration section with: - Bridge command usage - Lead command usage - Cross-project messaging syntax - Spawn/release worker patterns - Link to full design doc

Add beads issues for bridge/staffing next steps
9c5a263
- agent-relay-spawn-handler: Wire up spawn/release in lead mode - agent-relay-cross-project-parser: Add project:agent syntax - agent-relay-multi-project-dashboard: Bridge view for dashboard

khaliqgant requested a review from Copilot December 21, 2025 10:42

CopilotAI reviewed Dec 21, 2025
View reviewed changes

claudeand others added 22 commits December 21, 2025 10:45

Add unit tests for bridge module
b45fb93
- config.test.ts: Tests for path resolution, lead naming, project resolution - utils.test.ts: Tests for target parsing, shell escaping 26 tests passing

Add integration tests for MultiProjectClient
0ad8646
Tests actual socket connections with real daemons for: - Connection management across multiple projects - Message routing to specific project agents - Lead alias resolution - Broadcast to all leads

Remove .local_version from git tracking (now in .gitignore)
94efaeb

Add interactions.jsonl to .gitignore
d16e870

add claude skills
586b3a2

bd sync: merge beads changes
65ce06f

bridge and agent logic
3b0e150

fix tests and add testing note for bridge logic
f449c64

Add beads task for threaded conversations feature
c527500
Track implementation of Slack-style thread replies with parent_message_id tracking, nested UI display, and notification badges.

Fix CI: exclude frontend from tsc and fix flaky test
99f1b33
- Exclude src/dashboard/frontend from main tsconfig to prevent DOM type errors - Fix project-namespace test to check for .project marker instead of just data dir - Add built frontend bundle

Add architecture decisions doc comparing subagents vs agent-relay
3bb0da2

Merge branch 'claude/multi-project-agent-sockets-RCkNs' of github.com…
7df9666
…:khaliqgant/agent-relay into claude/review-pr-9-6HyEY

Merge pull request#14from khaliqgant/claude/review-pr-9-6HyEY
152bcdf
Add beads task for threaded conversations feature

update files
fa99d01

fix lock
90cbb9d

dashboard improvements and websocket skill and tightening
f2fc5d8

positioning
310e243

khaliqgantand others added 7 commits December 24, 2025 12:01

additional fixes
c014a0f

Add REST API for spawning agents via dashboard
cb547e5
- POST /api/spawn - Create new agent with name, cli, task - GET /api/workers - List active spawned workers - DELETE /api/workers/:name - Release a worker Enable with: agent-relay up --spawn

Enable spawn API by default and rename workers to agents
2f34b53
- Remove --spawn flag requirement, API always enabled - Rename /api/workers to /api/spawned for consistency - Update response field from 'workers' to 'agents'

final adjustments
a3a541c

update app.js.map -- should be ignored
676a2aa

ignore
6c4b8ce

khaliqgant merged commit e7ae9a7 into mainDec 25, 2025
6 checks passed

khaliqgant deleted the claude/multi-project-agent-sockets-RCkNs branch December 25, 2025 13:49

willwashburn mentioned this pull request Jun 25, 2026
feat(broker): node-only delivery for relaycast v5.0.1 #1201
Merged

willwashburn mentioned this pull request Jul 13, 2026
Reminder/prompt injection system: map current behavior, close the evidence gaps, and add "no response expected" semantics #1255
Open

Navigation Menu

Uh oh!

Add Bridge & Staffing design for multi-project orchestration - #9

Add Bridge & Staffing design for multi-project orchestration#9
khaliqgant merged 35 commits into
mainfrom
claude/multi-project-agent-sockets-RCkNs

khaliqgant commented Dec 21, 2025

Uh oh!

CopilotAI left a comment

Uh oh!

CopilotAIDec 21, 2025

Uh oh!

CopilotAIDec 21, 2025

Uh oh!

CopilotAIDec 21, 2025

Uh oh!

CopilotAIDec 21, 2025

Uh oh!

CopilotAIDec 21, 2025

Uh oh!

CopilotAIDec 21, 2025

Uh oh!

CopilotAIDec 21, 2025

Uh oh!

CopilotAIDec 21, 2025

Uh oh!

CopilotAIDec 21, 2025

Uh oh!

CopilotAIDec 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-console.log(`[${projectId}] ${from}: ${payload.body.substring(0,80)}...`);
+constbodyText=
+payload&&typeofpayload.body==='string'
+ ? payload.body
+ : String(payload?.body??'');
+console.log(`[${projectId}] ${from}: ${bodyText.substring(0,80)}...`);

-const[mainCommand, ...commandArgs]=cli.split(':');
-constwrapper=newTmuxWrapper({
-name,
-command: mainCommand,
+const[cliTool, ...commandArgs]=cli.split(':');
+constwrapper=newTmuxWrapper({
+name,
+command: cliTool,

-try{
-awaitexecAsync(`tmux has-session -t ${this.tmuxSession} 2>/dev/null`);
-}catch{
-// Session doesn't exist, create it
-awaitexecAsync(
-`tmux new-session -d -s ${this.tmuxSession} -c "${this.projectRoot}"`
+constsafeSession=escapeForTmux(this.tmuxSession);
+try{
+awaitexecAsync(`tmux has-session -t ${safeSession} 2>/dev/null`);
+}catch{
+// Session doesn't exist, create it
+awaitexecAsync(
+`tmux new-session -d -s ${safeSession} -c "${this.projectRoot}"`

	payload: (envelope.payloadas{nonce?: string})??{},
	payload: envelope.payload ? (envelope.payloadas{nonce?: string}):{},

		await execAsync(`cd "${project.path}" && agent-relay up &`, {
		timeout: 5000,

-awaitexecAsync(`cd "${project.path}" && agent-relay up &`,{
-timeout: 5000,
+awaitexecAsync('agent-relay up &',{
+timeout: 5000,
+cwd: project.path,

		// Start daemon in background
		await execAsync(`cd "${project.path}" && agent-relay up &`, {

Uh oh!

Conversation

khaliqgant commented Dec 21, 2025

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

CopilotAIDec 21, 2025

Choose a reason for hiding this comment

Uh oh!

CopilotAIDec 21, 2025

Choose a reason for hiding this comment

Uh oh!

CopilotAIDec 21, 2025

Choose a reason for hiding this comment

Uh oh!

CopilotAIDec 21, 2025

Choose a reason for hiding this comment

Uh oh!

CopilotAIDec 21, 2025

Choose a reason for hiding this comment

Uh oh!

CopilotAIDec 21, 2025

Choose a reason for hiding this comment

Uh oh!

CopilotAIDec 21, 2025

Choose a reason for hiding this comment

Uh oh!

CopilotAIDec 21, 2025

Choose a reason for hiding this comment

Uh oh!

CopilotAIDec 21, 2025

Choose a reason for hiding this comment

Uh oh!

CopilotAIDec 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants