Skip to content

refactor(cli): decompose the two largest CLI god files into cohesive modules #1166

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
willwashburn merged 5 commits into from
Jun 19, 2026
Merged

refactor(cli): decompose the two largest CLI god files into cohesive modules #1166

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f7715d3
refactor(cli): decompose agent-relay-mcp god file into mcp/ modules
claude Jun 18, 2026
f5e538c
refactor(cli): extract dashboard management into broker-dashboard.ts
claude Jun 19, 2026
afdc289
refactor(cli): extract messaging MCP tools into messaging-tools.ts
claude Jun 19, 2026
90f0445
chore(trail): record architecture-refactor trajectory
claude Jun 19, 2026
5a41a0a
style: auto-format with Prettier
github-actions[bot] Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
281 changes: 281 additions & 0 deletions .agentworkforce/trajectories/completed/2026-06/traj_h4wj3doqp0ra.trace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,281 @@
{
"version": "1.0.0",
"id": "35467489-5fde-46b4-b686-b372747b0eb9",
"timestamp": "2026-06-19T00:16:10.852Z",
"trajectory": "traj_h4wj3doqp0ra",
"files": [
{
"path": ".agentworkforce/trajectories/active/traj_h4wj3doqp0ra/trajectory.json",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 70,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/agent-relay-mcp.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 4,
"end_line": 44,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
},
{
"start_line": 79,
"end_line": 84,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
},
{
"start_line": 284,
"end_line": 289,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
},
{
"start_line": 352,
"end_line": 357,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
},
{
"start_line": 536,
"end_line": 542,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/lib/broker-dashboard.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 570,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/lib/broker-lifecycle.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 4,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
},
{
"start_line": 10,
"end_line": 24,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
},
{
"start_line": 275,
"end_line": 280,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
},
{
"start_line": 700,
"end_line": 705,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/mcp/action-schema.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 157,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/mcp/action-tools.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 151,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/mcp/inbox.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 56,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/mcp/messaging-tools.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 428,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/mcp/resources.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 209,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/mcp/telemetry.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 216,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/mcp/tool-results.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 52,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/mcp/tool-shapes.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 17,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/mcp/types.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 44,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
},
{
"path": "packages/cli/src/cli/mcp/workspace.ts",
"conversations": [
{
"contributor": {
"type": "ai"
},
"ranges": [
{
"start_line": 1,
"end_line": 48,
"revision": "afdc289bdcd2b7de860699df39dd0df5eec94d99"
}
]
}
]
}
]
}
52 changes: 52 additions & 0 deletions .agentworkforce/trajectories/completed/2026-06/traj_h4wj3doqp0ra/summary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Trajectory: Architecture refactor of Relay monorepo

> **Status:** ✅ Completed
> **Confidence:** 90%
> **Started:** June 18, 2026 at 11:36 PM
> **Completed:** June 19, 2026 at 12:16 AM

---

## Summary

Decomposed the two largest Agent Relay CLI god files into cohesive single-responsibility modules: agent-relay-mcp.ts (2215->969 lines, 10 mcp/ modules) and broker-lifecycle.ts (1879->1320, dashboard extracted). Three pure-move refactors, each verified with tsc + full test suite (968 pass) + live MCP probe + independent autoreview. No behavior change.

**Approach:** Standard approach

---

## Key Decisions

### Decomposed agent-relay-mcp.ts god file into cohesive mcp/ modules

- **Chose:** Decomposed agent-relay-mcp.ts god file into cohesive mcp/ modules
- **Reasoning:** 2215-line file mixed 8 concerns (schema adapter, telemetry, resources, inbox, workspace, action tools); split into single-responsibility modules behind unchanged public surface. Verified pure move via dual autoreview, tsc, full test suite, and live MCP stdio probe.

### Extracted dashboard management from broker-lifecycle.ts into broker-dashboard.ts

- **Chose:** Extracted dashboard management from broker-lifecycle.ts into broker-dashboard.ts
- **Reasoning:** 1879-line broker-lifecycle mixed broker start/stop/status with ~550 lines of dashboard discovery/spawn/asset-refresh logic. Moved the self-contained dashboard cluster behind a 7-function boundary. Verified byte-identical move via structural function diff (69->69), dual checks, tsc, full suite, and direct module live test of all 7 exports.

### Extracted messaging MCP tools into mcp/messaging-tools.ts

- **Chose:** Extracted messaging MCP tools into mcp/messaging-tools.ts
- **Reasoning:** registerAgentRelayTools was a 720-line god function; split out the 20 homogeneous messaging tools (channels/messages/threads/DMs/reactions/search/inbox) which depend only on getAgentClient, plus shared zod shapes into mcp/tool-shapes.ts. Main file 2215->969 lines overall. Verified byte-identical move, all 28 tools register live, full suite 968 pass, dual reviewer APPROVE.

---

## Chapters

### 1. Work

_Agent: default_

- Decomposed agent-relay-mcp.ts god file into cohesive mcp/ modules: Decomposed agent-relay-mcp.ts god file into cohesive mcp/ modules
- Extracted dashboard management from broker-lifecycle.ts into broker-dashboard.ts: Extracted dashboard management from broker-lifecycle.ts into broker-dashboard.ts
- Extracted messaging MCP tools into mcp/messaging-tools.ts: Extracted messaging MCP tools into mcp/messaging-tools.ts

---

## Artifacts

**Commits:** afdc289, f5e538c, f7715d3
**Files changed:** 14
Loading
Loading