@mdsohail99/opencode-agent-teams 2.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +64 -120
- package/CHANGELOG.md +158 -137
- package/README.md +165 -348
- package/agents/orchestrators/agent-teams.md +198 -198
- package/bin/cli.js +351 -351
- package/package.json +9 -4
- package/src/index.ts +115 -115
- package/src/state/tracker.ts +102 -102
- package/src/tools/broadcast.ts +58 -58
- package/src/tools/delegate.ts +154 -154
- package/src/tools/status.ts +25 -25
- package/src/tools/terminate.ts +70 -70
- package/src/tui.ts +9 -9
- package/src/worktree/manager.ts +142 -142
- package/agents/orchestrators-fork/orchestrator-agent-teams.md +0 -203
- package/bin/install.mjs +0 -418
- package/bin/lib/config-root.mjs +0 -51
- package/bin/lib/merge-commands.mjs +0 -138
- package/bin/lib/merge-env-flags.mjs +0 -92
- package/bin/lib/merge-schema.mjs +0 -77
- package/bin/lib/merge-subagent-depth.mjs +0 -133
- package/bin/lib/plugin-park.mjs +0 -48
- package/bin/lib/relay-process.mjs +0 -116
- package/bin/lib/runtime-state.mjs +0 -118
- package/bin/menu.mjs +0 -582
- package/bin/uninstall.mjs +0 -360
package/AGENTS.md
CHANGED
|
@@ -1,123 +1,67 @@
|
|
|
1
1
|
<!-- agent-teams-orchestration:start -->
|
|
2
|
-
# Department Team-Lead Orchestration (Agent-Teams
|
|
3
|
-
|
|
4
|
-
The agent system is organized
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
## OpenCode
|
|
17
|
-
OpenCode
|
|
18
|
-
- **Depth 0 (Root Orchestrator):** `
|
|
19
|
-
- **Depth 1 (Department Leads):** Department Leads (`
|
|
20
|
-
- **Depth 2 (
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
2. Decide the owner:
|
|
35
|
-
- Is that department's lead ALREADY running (an active/prior task_id in this session)?
|
|
36
|
-
→ Route the escalation to THAT existing lead (resume its task_id with the context).
|
|
37
|
-
- Not running → spawn that lead via the Task tool with the escalation as its prompt.
|
|
38
|
-
3. NEVER spawn a second instance of a department lead that's already running —
|
|
39
|
-
reusing the running lead prevents two writers editing the same module (conflict).
|
|
40
|
-
4. Hand the resolution back to the originating team so it can continue.
|
|
41
|
-
5. Keep a running mental registry of which leads are active in this session.
|
|
42
|
-
|
|
43
|
-
## Visible Parallel Batch `Task` Fan-Out (Recommended Visible Mode)
|
|
44
|
-
On Stock OpenCode, the premier execution mode for `Agent-Teams` (and whenever visual transparency is preferred) is **Visible Parallel Batch Task Fan-Out**:
|
|
45
|
-
- **Batch Concurrent Emission**: When independent departmental workstreams exist (e.g. Frontend UI, Backend API, QA verification), `Agent-Teams` emits all `Task` tool calls **concurrently in the same assistant turn** (omitting `background: true`). Parameters: `Task(subagent_type="<Lead>", description="<Short description>", prompt="<Detailed prompt>")`.
|
|
46
|
-
- **Interactive TUI UX**: OpenCode renders live interactive `│ Task` widgets with animated spinners, live toolcall indicators (`↳ Edit src/...`, `↳ Run pytest`), and one-click inspection directly in the main TUI timeline.
|
|
47
|
-
- **Nested Visibility (`subagent_depth = 2`)**: Department Leads (Depth 1) also dispatch their Specialists (Depth 2) via nested `Task` tool calls, maintaining live visibility down through the subagent tree.
|
|
48
|
-
|
|
49
|
-
## Fan-out is ESCALATION-DRIVEN by default — main agent may parallelize when it fits
|
|
50
|
-
The DEFAULT for single-agent sessions (or when departments have sequential dependencies) is one lead at a time: spawn a lead, and only spawn another department when a running lead escalates and explicitly requests it. This is correct whenever the cross-department dependency is only discovered DURING the work (e.g. QA finds a backend bug mid-testing). Concurrency is produced by the RESUME pattern, not by pre-spawning teams.
|
|
51
|
-
|
|
52
|
-
### When the main agent MAY parallelize (spawn leads in the same message)
|
|
53
|
-
Parallel spawn is allowed when the main agent can already see, from the user's
|
|
54
|
-
request, that two departments have INDEPENDENT work that can run at the same time
|
|
55
|
-
with no write conflict — e.g. frontend UI + backend API are both clearly needed AND
|
|
56
|
-
touch different modules. Use judgment: if the tracks are coupled or one waits on the
|
|
57
|
-
other, do NOT parallelize — use the default one-lead + escalation flow instead.
|
|
58
|
-
|
|
59
|
-
### The default flow — single-lead with on-demand escalation
|
|
60
|
-
1. Main agent spawns the ONE lead whose task is the user's request (e.g. QA).
|
|
61
|
-
2. The lead does all its independent work, then returns `ESCALATE: <dept> | ...`
|
|
62
|
-
only if it actually hit a blocker requiring another department.
|
|
63
|
-
3. ONLY THEN does the main agent spawn (or resume) the requested department lead.
|
|
64
|
-
4. When the fix returns, the main agent resumes the requesting lead to finish.
|
|
65
|
-
|
|
66
|
-
### Yield-and-resume (how concurrency happens without pre-spawning)
|
|
67
|
-
When a lead escalates mid-task:
|
|
68
|
-
1. Lead does all work that does NOT depend on the other department (e.g. QA runs
|
|
69
|
-
all tests except test X), then returns early with
|
|
70
|
-
`ESCALATE: <dept> | ... | CONTEXT: I've done A,B,C; only X is blocked`.
|
|
71
|
-
It does NOT block or wait — its session ends cleanly (main agent keeps task_id).
|
|
72
|
-
2. Main agent, in ONE parallel batch, BOTH:
|
|
73
|
-
- resumes the requesting lead's task_id ("keep going on anything else you can; X pending"), AND
|
|
74
|
-
- spawns the needed lead ("fix X for the QA team").
|
|
75
|
-
If the requesting lead has no more independent work, skip the resume and only spawn.
|
|
76
|
-
3. When the fixing lead returns, main agent resumes the requesting lead's task_id
|
|
77
|
-
with the fix → it finishes the blocked item.
|
|
78
|
-
4. Never keep a lead idle: if a lead can do more work while another department fixes
|
|
79
|
-
its blocker, RESUME it to keep working rather than leaving it paused.
|
|
80
|
-
5. When the escalation is a mid-task discovery (like our QA → Backend test case),
|
|
81
|
-
do NOT start both leads together — the dependent lead starts first, escalates,
|
|
82
|
-
and only then is the second lead spawned. Parallel spawn is reserved for work
|
|
83
|
-
the main agent can see is independent from the start.
|
|
84
|
-
|
|
85
|
-
### Resumption discipline & Deterministic Error Recovery
|
|
86
|
-
- Resuming a lead by `task_id` preserves its session context — it knows what it already did.
|
|
87
|
-
- **Deterministic Error Resumption Format**: When a subagent fails, encounters a timeout, or throws an unhandled error, OpenCode returns:
|
|
88
|
-
```
|
|
89
|
-
Subagent failed (task_id: <id>): <error>
|
|
2
|
+
# Department Team-Lead Orchestration (Agent-Teams v2 Pattern)
|
|
3
|
+
|
|
4
|
+
The agent system is organized into departments, each led by an orchestrator (Department Lead):
|
|
5
|
+
`backend`, `frontend`, `security`, `qa`, `devops`, `ai-data`.
|
|
6
|
+
The primary entry point is the root orchestrator: `agent-teams`.
|
|
7
|
+
|
|
8
|
+
## Two Operational Modes:
|
|
9
|
+
1. **Agent-Teams Mode (Primary / Swarm Mode):**
|
|
10
|
+
`agent-teams` IS the root delegating orchestrator and central **Escalation Resolver**. It receives high-level user requests, fans out work to department leads, catches cross-department escalations, routes blockers to fixer leads, and synthesizes the final consolidated result.
|
|
11
|
+
2. **Specialized Single-Lead Mode:**
|
|
12
|
+
When a user directly invokes a department lead (e.g. `@backend` or `@frontend`), that lead acts as the primary agent for the session and fans out to its domain specialists directly.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## OpenCode v2 Hierarchical Swarms (`subagent_depth = 2`)
|
|
17
|
+
OpenCode v2 natively supports nested subagents up to `subagent_depth = 2` (configured in `opencode.json` via `"subagent_depth": 2`):
|
|
18
|
+
- **Depth 0 (Root Orchestrator):** `agent-teams` orchestrates high-level departmental workflows, monitors progress, and resolves cross-department blockers.
|
|
19
|
+
- **Depth 1 (Department Leads):** Department Leads (`backend`, `frontend`, `security`, `qa`, `devops`, `ai-data`) receive departmental scopes and dispatch specialists via `team_delegate` or native `subagent` tools.
|
|
20
|
+
- **Depth 2 (Domain Specialists):** 68 domain specialists (e.g. `backend-architect`, `frontend-developer`, `database-optimizer`, `api-tester`, `a11y-auditor`) execute focused implementation, testing, or auditing tasks inside isolated Git worktrees.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Core Architecture: Hub-and-Spoke with Delegating Agent as Resolver
|
|
25
|
+
|
|
26
|
+
### Rule 1: No Lead Launches Another Lead Directly
|
|
27
|
+
- Each department lead's scope is strictly confined to its own domain specialists.
|
|
28
|
+
- Leads cannot launch peer department leads directly. This prevents circular execution loops and write collisions.
|
|
29
|
+
|
|
30
|
+
### Rule 2: Management by Exception & Structured Escalation
|
|
31
|
+
- If a lead hits a cross-functional blocker (e.g. QA finds an unhandled backend route error, or Frontend needs a new authentication endpoint), it yields immediately with a structured escalation:
|
|
32
|
+
```text
|
|
33
|
+
ESCALATE: <department> | WHAT: <need> | WHERE: <file/module> | CONTEXT: <what it did + what the other team must know>
|
|
90
34
|
```
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
35
|
+
- **Escalate Early:** Yield the escalation as soon as the blocker is identified while continuing any unblocked parallel work.
|
|
36
|
+
|
|
37
|
+
### Rule 3: The Delegating Agent is the Central Resolver
|
|
38
|
+
When `agent-teams` receives an `ESCALATE: <dept>` result from a lead:
|
|
39
|
+
1. **Identify the Fixer:** Checks if that department lead is already active in the session registry.
|
|
40
|
+
- If already running: Resumes that lead's existing session with the escalation context.
|
|
41
|
+
- If not running: Spawns the required department lead via `team_delegate` in a dedicated Git worktree.
|
|
42
|
+
2. **One-Writer-Per-Module Discipline:** Never spawn duplicate instances of the same department lead on the same module.
|
|
43
|
+
3. **Context Handoff:** Once the fixing lead verifies the resolution and auto-merges the worktree, `agent-teams` passes the resolution back to the originating lead to complete its blocked work.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Swarm Concurrency & Git Worktree Sandboxing
|
|
48
|
+
|
|
49
|
+
1. **Parallel Independent Fan-Out:**
|
|
50
|
+
When independent departmental requirements exist (e.g. Backend API endpoints in `src/routes/` and Frontend UI in `src/components/`), `agent-teams` dispatches both leads concurrently in the same turn.
|
|
51
|
+
2. **Isolated Git Worktrees (`worktree: true`):**
|
|
52
|
+
Mutating tasks execute in dedicated `swarm/<team>-<task_id>` branches within isolated worktrees. Once changes are verified, they are committed and merged back into the base working branch automatically.
|
|
53
|
+
3. **Strict Read-Only Mode (`worktree: false`):**
|
|
54
|
+
For architectural audits, code reviews, and testability evaluations, tasks execute in-place read-only without creating worktree directories or Git commits.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Swarm Control Tools & Slash Commands
|
|
59
|
+
|
|
60
|
+
In OpenCode v2, orchestration runs 100% in-process via `@opencode/plugin` and `@opencode/client`:
|
|
61
|
+
- `team_delegate` — Dispatches tasks to department specialists with optional Git worktree sandboxing.
|
|
62
|
+
- `team_status` — Inspects the live hierarchical status tree, active workers, and Git worktrees.
|
|
63
|
+
- `team_broadcast` — Broadcasts steering guidance to active teammates simultaneously.
|
|
64
|
+
- `team_terminate` — Gracefully halts running workers and cleans up temporary worktrees.
|
|
65
|
+
|
|
66
|
+
Slash commands (`/team`, `/team-status`, `/team-stop`) provide real-time TUI progress monitoring and emergency swarm control.
|
|
123
67
|
<!-- agent-teams-orchestration:end -->
|
package/CHANGELOG.md
CHANGED
|
@@ -1,137 +1,158 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
All notable changes to **`opencode-agent-teams-relay`** will be documented in this file.
|
|
4
|
-
|
|
5
|
-
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
-
and this project adheres to [Semantic Versioning](https://semver.org/spec/v1.0.0.html).
|
|
7
|
-
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
## [
|
|
11
|
-
|
|
12
|
-
### Added
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
###
|
|
22
|
-
- **
|
|
23
|
-
- **
|
|
24
|
-
- **
|
|
25
|
-
- **
|
|
26
|
-
- **
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
- **
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
- **
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
- **
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
- **
|
|
53
|
-
-
|
|
54
|
-
- **
|
|
55
|
-
- **
|
|
56
|
-
|
|
57
|
-
###
|
|
58
|
-
- **
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
- **
|
|
70
|
-
-
|
|
71
|
-
-
|
|
72
|
-
- **
|
|
73
|
-
- **
|
|
74
|
-
-
|
|
75
|
-
- **
|
|
76
|
-
- **
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
-
|
|
130
|
-
|
|
131
|
-
###
|
|
132
|
-
- (
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
-
|
|
136
|
-
-
|
|
137
|
-
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to **`opencode-agent-teams-relay`** will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v1.0.0.html).
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## [2.0.1] - 2026-10-22
|
|
11
|
+
|
|
12
|
+
### Added & Documented
|
|
13
|
+
- **Hub-and-Spoke Delegating Agent as Escalation Resolver:** Formally documented and codified the central escalation resolution workflow in README.md and AGENTS.md (no lead-to-lead calls, early ESCALATE yielding, worktree sandboxing per blocker, and context handoff back to caller).
|
|
14
|
+
- **In-Process Swarm Test Suite:** Added test/v2-swarm.spec.ts testing global hierarchy tracking, tool dispatch (team_status, team_broadcast, team_terminate), and worktree sandboxing.
|
|
15
|
+
- **Repository Standardization:** Completely pruned legacy v1 relay daemon files, obsolete fork agents, and temporary scratch documentation. Added test and typecheck npm scripts.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## [2.0.0] - 2026-10-22
|
|
20
|
+
|
|
21
|
+
### Changed & Re-Architected (Major)
|
|
22
|
+
- **100% Native OpenCode v2 Architecture:** Complete rewrite as an in-process plugin utilizing official `@opencode/plugin@2.1.1` and `@opencode/client@2.1.1` APIs.
|
|
23
|
+
- **Relay Daemon Completely Deprecated:** Removed external Node.js relay server, port 20129/25800 listener, socket tokens, and orphaned process reaping. Zero background processes or port overhead.
|
|
24
|
+
- **Simplified Agent Identifiers:** Renamed all Department Leads from `orchestrator-*.md` to clean, native IDs (`agent-teams`, `backend`, `frontend`, `security`, `qa`, `devops`, `ai-data`).
|
|
25
|
+
- **Dynamic In-Memory Registration:** Replaced hardcoded commands and prompt blocks in `opencode.json` and `AGENTS.md` with runtime transforms (`ctx.command.transform`, `ctx.agent.transform`). Global configs stay clean.
|
|
26
|
+
- **Modernized Swarm Tools:** Introduced semantic tools (`team_delegate`, `team_status`, `team_broadcast`, `team_terminate`) with direct Git worktree sandboxing and automatic merge-back.
|
|
27
|
+
- **New Interactive CLI:** Added interactive terminal TUI menu in `bin/cli.js` with manifest-tracked clean uninstall and global-by-default targeting.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## [1.0.8] - 2026-10-10
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
- **OpenCode 1.18.34+ Stock Native Hierarchical Depth (`subagent_depth = 2`):** Configured natively at root in `opencode.json` across both `full` and `agents` install modes, enabling Depth 0 (Root Orchestrator) → Depth 1 (Department Leads) → Depth 2 (Specialists) out of the box on upstream stock OpenCode.
|
|
35
|
+
- **Visible Parallel Batch Task Mode:** Optimized orchestrators to emit concurrent `Task` calls in the same assistant turn. OpenCode natively renders live interactive `│ Task` widgets with animated spinners and toolcall indicators (`↳ Edit src/...`).
|
|
36
|
+
- **Swarm Slash Command Palette:** Injected `/tree`, `/report`, `/ask`, `/resume`, `/stop`, and `/errors` commands into `opencode.json` for live ASCII org-chart tracking, mid-flight worker steering, and emergency stopping.
|
|
37
|
+
- **Fast-Path Capability Probing:** Modernized `probeInlineSupport()` in `plugins/agent-teams.ts` to query `/experimental/capabilities` directly instead of creating throwaway `__agent_teams_subtask_probe__` sessions, eliminating the 5-second startup lag and ghost session leaks on SQLite.
|
|
38
|
+
- **Native Git Worktree Sandboxing:** Integrated `relay/agent-teams-relay.mjs` with OpenCode 1.18.34+ native worktree endpoints (`POST /experimental/worktree/create` and `remove`), allocating isolated git sandboxes per mutating task to prevent write collisions.
|
|
39
|
+
- **Deterministic Error Resumption:** Standardized `Task(task_id="<id>", prompt="...")` for recovering failed tasks (`Subagent failed (task_id: <id>): <error>`), preserving all accumulated context, tools, and code diffs.
|
|
40
|
+
- **Total Sandbox & XDG Isolation:** Set `$env:XDG_CONFIG_HOME` in sandbox and test launcher scripts to guarantee 100% clean isolation from machine-global user profile configs.
|
|
41
|
+
|
|
42
|
+
### Fixed
|
|
43
|
+
- **Subagent Completion Stall Resolution:** Added a synthetic tool-action summary fallback in `readSessionOutput()` (`relay/agent-teams-relay.mjs`) when turns conclude with tool executions (`edit`, `write`, `bash`) rather than conversational text. Unblocks the `session.idle` handler and routes the session to `done` immediately.
|
|
44
|
+
- **Resilient 404 Notification Queue Handling:** Implemented a 3-attempt retry loop with 4-second backoff in `drainParentNotifications()` (`relay/agent-teams-relay.mjs`). Prevents transient 404 responses during parent status checks or `promptAsync` delivery from permanently deleting the orchestrator's notification queue.
|
|
45
|
+
- **Cross-Session Target Scoping in Resume & Restart:** Passed `parentID: context.sessionID` in `resume_agent` and `manage_agents restart` (`plugins/agent-teams.ts`) and configured default resume prompts (`"Resume and continue from where you left off."`). Resolves targets strictly to the current active session, preventing accidental resumption of stale historical ghost agents.
|
|
46
|
+
- **Session Preservation on Operator Kill:** Replaced `deleteServerSession` with `abortServerSession` across `manage_agents kill` and `kill_all` (`relay/agent-teams-relay.mjs`). Aborts in-flight execution upstream while preserving SQLite session records and WAL history intact for subsequent resumption.
|
|
47
|
+
- **Enriched Out-of-Band `/ask` Snapshots:** Formatted tool calls, arguments, outputs, and thinking snippets into the ephemeral transcript snapshot in `agent-teams-relay.mjs`, ensuring operator inquiries reflect active background work and tool execution rather than appearing idle.
|
|
48
|
+
|
|
49
|
+
## [1.0.6] - 2026-09-04
|
|
50
|
+
|
|
51
|
+
### Added
|
|
52
|
+
- **Reactive Orchestrator Protocol (`orchestrator-agent-teams.md`):** Mandated non-blocking fanout where the Main Orchestrator dispatches department leads asynchronously via `Task(background=true)` and immediately yields the turn to the user (permanently preserving terminal interactivity). Forbids calling `next_agent` in foreground turns.
|
|
53
|
+
- **File Touch Scope Protocol:** Adds explicit decision rules for worktree isolation: `worktree: true` when subagents touch shared files (`package.json`, shared schemas); `worktree: false` for disjoint directories or read-only tasks to eliminate disk I/O and temporary git branch overhead.
|
|
54
|
+
- **Swarm Management & Side Query Directives:** Equipped the Orchestrator with `agents_status` (hierarchical tree snapshots and stall detection), `manage_agents` (`kill`, `kill_all`, `inspect`, `restart`), and `ask_agent` for out-of-band side queries.
|
|
55
|
+
- **Autonomous Department Leads (Level 1 Depth):** Upgraded all 6 Department Leads (`Backend`, `Frontend`, `DevOps`, `QA`, `AI & Data`, `Security`) to autonomous middle managers that supervise specialists in background worktrees, run compile/typecheck/test verification gates inside department sandboxes, and report consolidated outcomes upward.
|
|
56
|
+
|
|
57
|
+
### Fixed
|
|
58
|
+
- **Root `subagent_depth` Schema Alignment:** Configured `subagent_depth = 2` directly at the root level of `opencode.json` in `bin/lib/merge-subagent-depth.mjs` and `install.ps1` to align with the official OpenCode V2 schema (`https://opencode.ai/config.json`) and SDK types. Eliminates editor schema validation warnings (`Property subagent_depth is not allowed`) while auto-migrating any misplaced `experimental.subagent_depth` back to root and pruning empty `experimental` blocks.
|
|
59
|
+
|
|
60
|
+
## [1.0.5] - 2026-09-03
|
|
61
|
+
|
|
62
|
+
### Fixed
|
|
63
|
+
- **OpenCode V2 Subagent Depth Alignment:** Updated installer logic (`bin/lib/merge-subagent-depth.mjs` and `install.ps1`) to configure `experimental.subagent_depth = 2` matching the official OpenCode V2 (`v1.18.x+`) schema (`https://opencode.ai/config.json`).
|
|
64
|
+
- **Legacy Config Auto-Migration:** Automatically detects legacy root `subagent_depth` in existing user configs, migrates it into `experimental.subagent_depth`, and removes the root key to eliminate schema validation errors while preserving custom user values and existing experimental keys.
|
|
65
|
+
|
|
66
|
+
## [1.0.4] - 2026-08-20
|
|
67
|
+
|
|
68
|
+
### Added
|
|
69
|
+
- **Durable WAL + checkpoint state store.** The relay persists its entire picture of the world (`nodes`, `teams`, plus an append-only `events` diary) to `<state-dir>/agent-teams-relay.wal` (append-only write-ahead log) with periodic atomic checkpoints to `<state-dir>/agent-teams-relay-state.json` — every state transition is mirrored transactionally, and a relay that is killed and restarted replays its full state, including completed results, drained flags, and retry budgets. The in-memory Maps remain the runtime source of truth for logic; the store survives restarts. (`relay/agent-teams-relay.mjs`)
|
|
70
|
+
- **Full-instance visibility (`/reconcile`).** A new plugin-side **supervisor loop** (started at plugin load, not on tool calls) checks relay health every 10s, respawns a dead relay, and pushes the opencode server's *entire* live session list to the relay's new `/reconcile` endpoint — so the relay tracks every session on the instance (including human-started ones), not just children it spawned itself, and corrects drifted statuses. (`plugins/agent-teams.ts`, `relay/agent-teams-relay.mjs`)
|
|
71
|
+
- **Confirmed-deletion cascade.** Deletion is now triggered **only** by a confirmed parent deletion — either the SSE `session.deleted` event or a parent missing from two consecutive reconciliation passes *and* an explicit `session.get` returning 404. Unreachability is never treated as deletion. Pending `/await-any` waiters are resolved with `disposed` status; child sessions are deleted with an audit trail in the `events` diary.
|
|
72
|
+
- **30-day confirmed-orphan sweep.** A low-frequency safety net (`ORPHAN_SWEEP_INTERVAL_MS`, default 24h cadence) revisits stale nodes but only cascades them through the same confirmed-deletion gate — never on age alone.
|
|
73
|
+
- **Event-diary retention.** The append-only `events` table is pruned on boot and on the maintenance tick (default 24h): rows older than 90 days are removed (`EVENT_RETENTION_DAYS` to override, e.g. for tests).
|
|
74
|
+
- **`/resume` + `resume_agent` tool.** Any existing, still-alive session can receive a follow-up instruction and continue with its accumulated context; status/drained/result reset and a fresh completion promise is registered so `next_agent`/`agents_status` pick it back up. Network failure to the upstream server returns `502 upstream_unreachable` (never treated as "not found").
|
|
75
|
+
- **Per-agent failure isolation.** Retry budgets are now **per-node** (`retry_count`, capped at 3): one agent exhausting its budget goes `error` with a `needs_attention` event while every sibling keeps working. The global circuit breaker is reserved solely for SSE-transport failures; `/reset-circuit {sessionID}` revives a single node's budget. (`relay/agent-teams-relay.mjs`)
|
|
76
|
+
- **Test suite growth:** 28 automated tests (relay lifecycle, reconcile, cascade, orphan sweep, resume, failure isolation, installer scenarios 1–6) via `node --test`.
|
|
77
|
+
|
|
78
|
+
### Changed
|
|
79
|
+
- **Architectural Upgrade: Replaced HTTP Heartbeat Polling with OS Kernel Process Supervision.** Relays no longer issue `GET /global/health` probes over local HTTP connections to check parent liveness. Instead, the plugin passes `PARENT_PID` to the relay, which monitors the parent OpenCode Process ID directly via OS Kernel liveness checks (`process.kill(parentPid, 0)`). Zero false-positive relay exits during CPU or AI spikes. As long as the parent OpenCode process exists in the OS process table, the relay stays 100% alive indefinitely (even if idle for days). The moment the user closes the parent OpenCode application or terminal, the kernel monitor detects process termination (`ESRCH`) and shuts down the relay immediately. (`relay/agent-teams-relay.mjs`, `plugins/agent-teams.ts`)
|
|
80
|
+
- **Single config root + disabled-plugin parking.** Both install modes now target `~/.config/opencode` — one config world, no more separate `.config/ocd` for agents-only. In `agents` (native-fork) mode the plugin is **parked** into `plugins-disabled/agent-teams.ts`, outside the core's `{plugin,plugins}/*.{ts,js}` autodiscovery, so the fork's compiled-in `Task`/`next_agent`/`agents_status` run collision-free (no tool collision between the plugin and the native fork). `full` mode restores it into `plugins/`, removes any parked copy, and strips stale `subagent_depth`. Legacy `.config/ocd` installs are still auto-detected for reinstall/uninstall. (`bin/install.mjs`, `bin/menu.mjs`, `bin/uninstall.mjs`, `install.ps1`, `bin/lib/config-root.mjs`, new `bin/lib/plugin-park.mjs`)
|
|
81
|
+
- **Runtime floor raised to `node >= 20.19`** (for the WAL + checkpoint durable store). (`package.json`)
|
|
82
|
+
- **State & Runtime Cleanup Alignment:** Synchronized runtime state allowlists across `bin/lib/runtime-state.mjs` and `install.ps1` to cover the WAL + checkpoint state files (`agent-teams-relay.wal`, `agent-teams-relay-state.json` and transient `.tmp` variants) and temporary tokens (`token.tmp`).
|
|
83
|
+
- `scripts/test-relay-cascade.mjs` replaces the obsolete `test-relay-dispose.mjs` integration script.
|
|
84
|
+
|
|
85
|
+
### Removed
|
|
86
|
+
- `/dispose` endpoint and `evictStale()` (the 30-minute TTL eviction) — both replaced by the confirmed-deletion cascade above. Nothing is ever deleted automatically without a confirmed parent deletion.
|
|
87
|
+
|
|
88
|
+
### Fixed
|
|
89
|
+
- **Auxiliary-server split-brain on startup.** When the real opencode server wasn't answering yet at plugin load (boot race), the plugin immediately spawned a second `opencode serve` and pointed the relay at it — the relay silently watched the wrong server while `/reconcile` pushes to the real one failed. The upstream probe now retries (~5s window) before any auxiliary fallback, the fallback is logged when it does happen, and the supervisor **self-heals**: once pushes reach the real server again, an aux-backed relay is killed and respawned on the real URL (lossless — the WAL + checkpoint store replays state). (`plugins/agent-teams.ts`)
|
|
90
|
+
- **Relay heartbeat exit threshold raised from 12 → 36 (3 minutes) and made env-tunable.** Previously, aux-backed relays (spawned when the real opencode upstream was down) exited after only 12 × 5 s = 60 seconds of upstream unreachability. Under heavy parallel AI workloads, the aux `opencode serve` process becomes transiently unreachable for longer than 60 s, causing the relay to self-terminate. The plugin then re-ran `ensureRelay`, found the upstream still down, and spawned a *new* aux server on a new random port — triggering a new relay on a new port. Every cycle broke `next_agent`'s long-poll connection. 8+ relay/aux pairs were created in a single session. Default is now 36 failures (3 minutes). `HEARTBEAT_MAX_FAILURES` env var allows custom tuning without code changes. (`relay/agent-teams-relay.mjs`)
|
|
91
|
+
- **`next_agent` now retries `/await-any` up to 5 times across relay restarts.** When the relay is respawned mid-poll the HTTP connection drops. The execute handler now retries with a 2 s pause + `ensureRelay` health re-check between attempts, so a relay that restarted and recovered its persisted state is found on the next attempt. (`plugins/agent-teams.ts`)
|
|
92
|
+
- **`reconcileMissedCompletions` called immediately at relay boot.** Previously this ran only after the SSE event stream connected (which can take several seconds). An `/await-any` call arriving in that window could block to timeout even if sub-agents already finished while the relay was down. Now the recovery runs right after `openDatabase()` / `loadDurableState()` so persisted completions are resolved before the first tool call is served. (`relay/agent-teams-relay.mjs`)
|
|
93
|
+
- **Relay health check no longer gates on `eventsReady`.** `/health` now always returns `ok: true` when the relay process is alive (i.e. it responded). `eventsReady` remains in the payload as an informational field about the SSE stream. Previously, any transient SSE reconnect caused the plugin's `health()` check to return `false`, which deleted the relay cache entry and tried to respawn a relay that was already running — a duplicate that then immediately exited on `EADDRINUSE`. (`relay/agent-teams-relay.mjs`, `plugins/agent-teams.ts`)
|
|
94
|
+
- **Ghost `__agent_teams_subtask_probe__` sessions no longer appear in the session list.** `probeVersionFastPath()` now conservatively returns `tooOld: true` whenever the core version cannot be determined (endpoint unhealthy, no `version` field, unparseable string, or network error). On stock opencode 1.2.27 the version is not published on `/global/health`, so the fast-path now short-circuits before creating any throwaway session — the probe session creation is skipped entirely. (`plugins/agent-teams.ts`)
|
|
95
|
+
- **Probe session DELETE is delayed 5 s.** When the full probe path does run (native fork ≥ 1.18.x), the `finally` cleanup now waits 5 seconds before issuing the DELETE. An immediate DELETE on a session that just received `prompt_async` fails silently on some cores, leaving a ghost session in the list. The delay gives the session time to reach idle. (`plugins/agent-teams.ts`)
|
|
96
|
+
- **Relay reconcile skips probe sessions.** `handleReconcileSessions()` now filters out any session whose title is `__agent_teams_subtask_probe__` before folding it into the node tree. Previously these sessions accumulated in the relay's durable store across restarts and triggered unnecessary status-API polling on every reconcile pass. (`relay/agent-teams-relay.mjs`)
|
|
97
|
+
- **Fixed `serverUrl` undefined hashing to port 25821 on startup.** Added `isValidServerUrl()` validation to prevent attempting relay startup or spawning auxiliary servers on undefined server URLs. (`plugins/agent-teams.ts`)
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## [1.0.3] - 2026-08-09
|
|
102
|
+
|
|
103
|
+
### Changed
|
|
104
|
+
- **Mode-aware config directory:** the installer now targets `.config/ocd` in `agents` mode (native fork) and `.config/opencode` in `full` mode (stock opencode), so both modes can coexist on the same machine without clobbering each other's state. (`bin/install.mjs`, `install.ps1`)
|
|
105
|
+
- `install.ps1` uses `$PSScriptRoot` for the package root and `$USERPROFILE` first for the home dir (more robust under non-standard shells).
|
|
106
|
+
|
|
107
|
+
### Fixed
|
|
108
|
+
- **Mode-aware `subagent_depth` merge in `install.ps1`:** `full` mode now strips a stale `subagent_depth` key instead of writing it (the stock core rejects the unrecognized key and refuses to start); `agents` mode creates `opencode.json` with `subagent_depth=2` when missing.
|
|
109
|
+
- **Hidden console on Windows:** the relay process now spawns a hidden console at startup (`hide_console.ps1`), so the background relay no longer pops a terminal window.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## [1.0.2] - 2026-08-07
|
|
114
|
+
|
|
115
|
+
### Added
|
|
116
|
+
- README: **"Performance & Measured Impact"** section — real measured numbers from an in-repo orchestration run (18 concurrent sessions, ~15 min wall-clock to synthesis, 8 concurrent escalations), with explicit **measured vs modeled** labeling and the honest tokens-for-throughput trade-off.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## [1.0.1] - 2026-08-07
|
|
121
|
+
|
|
122
|
+
### Fixed
|
|
123
|
+
- `subagent_depth` merge is now **mode-aware**: the key is only applied in `agents` mode (native fork core, which understands it). `full` mode (stock opencode core) no longer writes it — the stable core rejects `subagent_depth` as an unrecognized key and refuses to start. Full-mode installs/reverts also **strip** a stale `subagent_depth` to self-heal configs broken by an earlier agents-mode install.
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## [1.0.0] - 2026-08-07
|
|
128
|
+
|
|
129
|
+
Initial public release — async department-lead orchestration and parallel sub-agent relay for OpenCode.
|
|
130
|
+
|
|
131
|
+
### Added
|
|
132
|
+
- 🚀 **Async Parallel Fan-Out:** `running_agents` tool launches unlimited child sessions in parallel without freezing the OpenCode TUI; results collected with `next_agent` (drain) / `agents_status` (snapshot).
|
|
133
|
+
- 📡 **Detached SDK Relay Engine:** External Node.js background process (relay/agent-teams-relay.mjs) connecting via `@opencode-ai/sdk`, tracking `session.idle` / `session.error` events via SSE.
|
|
134
|
+
- 🏢 **7 Department Leads & 67 Specialists:** Pre-configured orchestrators (`Agent-Teams`, `Frontend`, `Backend`, `Security`, `DevOps`, `AI & Data`, `QA`) routing tasks to specialized domain agents.
|
|
135
|
+
- ⚡ **Management by Exception:** Unblocked work digests silently; blockers trigger immediate escalations so fixer leads dispatch in parallel.
|
|
136
|
+
- 🛡️ **Relay Resilience & Self-Healing:**
|
|
137
|
+
- Heartbeat tolerates transient upstream blips (5 consecutive failures before exit) instead of dying on a single one.
|
|
138
|
+
- Stale-team eviction never deletes teams with running/undrained children.
|
|
139
|
+
- Plugin re-probes relay health on every tool call and respawns a dead relay.
|
|
140
|
+
- Token persisted atomically (tmp+rename+fsync, `0o600`) after a successful listen; capped exponential reconnect backoff; missed completions reconciled on resubscribe.
|
|
141
|
+
- 🔄 **Auto-Continue on Transient Provider Errors:** `reasoning_content ... must be passed back` (DeepSeek thinking mode), `AI_JSONParseError` / `JSON parsing failed`, and `[503] request queue is full` are automatically resumed with a minimal "continue" prompt instead of failing the task (bounded retries, genuine failures still surface).
|
|
142
|
+
- 🧵 **Inline Sub-Agent Mode:** `running_agents({ inline: true })` renders a child as a native `│ Task` widget with automatic fallback to the relay path on cores that don't support subtask parts.
|
|
143
|
+
- ⚙️ **Two-Mode Installer:** `full` (agents + AGENTS.md + plugin + relay + npm dep) and `agents` / `--agents-only` (agents + AGENTS.md only, for native-fork users). Writes a `.installed-mode` marker.
|
|
144
|
+
- 🗑️ **Mode-Aware Uninstall:** removes only the artifacts the installed mode manages; preserves other user plugins, `opencode.json`, `package.json`, and `node_modules`. `status` reports the installed mode.
|
|
145
|
+
- 📦 **Safe Installer:** non-destructive with full timestamped backups, rollback, and marked-block `AGENTS.md` merging; keeps the last 5 backups.
|
|
146
|
+
- 🔒 **Shared-Secret Security:** 32-byte token authentication; unique hash-derived relay ports per server URL (20000–50000) for multi-session isolation.
|
|
147
|
+
|
|
148
|
+
### Changed
|
|
149
|
+
- `install.ps1` is mode-aware (`-AgentsOnly`).
|
|
150
|
+
- README documents installation modes; `MANIFEST.txt` lists both.
|
|
151
|
+
|
|
152
|
+
### Removed
|
|
153
|
+
- (n/a — initial release)
|
|
154
|
+
|
|
155
|
+
### Fixed
|
|
156
|
+
- Relay no longer exits on a single transient upstream heartbeat failure.
|
|
157
|
+
- Token file no longer world-readable, and is written only after the relay is listening (no clobber on port collisions).
|
|
158
|
+
- Sub-agent sessions hitting transient provider errors resume automatically instead of dying.
|