feat: add agent team core — Team namespace, messaging, recovery, and events by ugoenyioha · Pull Request #12730 · anomalyco/opencode

ugoenyioha · 2026-02-08T18:20:32Z

Summary

Adds the foundational layer for agent teams (Fixes #12711), gated behind OPENCODE_EXPERIMENTAL_AGENT_TEAMS=1.

This is PR 1/3 in the agent teams stack. It introduces the core Team namespace with full CRUD, persistence, recovery, and inter-agent messaging — everything downstream PRs (#12731 tools, #12732 TUI) build on top of.

What's included

Team namespace (`team/index.ts` — 392 lines)

CRUD: create, get, list, addMember, removeMember, cleanup
Storage-backed persistence: Teams stored via the Storage namespace with project-scoped keys (["team", projectId, name] and ["team_tasks", projectId, name]). No raw Bun.file/Bun.write or filesystem paths — Storage handles atomicity and locking internally.
Runtime validation: create and get wrapped with fn() for Zod input validation
Atomic mutations: All state changes (addMember, setMemberStatus, setDelegate, setMemberPlanApproval, removeMember) use Storage.update() — read-modify-write under lock
addMember validations: Case-insensitive name duplicate check, sessionID duplicate check, reserved name "lead" rejection — all inside Storage.update callback for atomicity
setMemberStatus guard: Optional { guard: true } parameter prevents overwriting "shutdown" status (TOCTOU prevention for teammate completion callbacks)
Single-team-per-session constraint: A session cannot lead multiple teams, and teammates cannot create nested teams
Member status tracking: active, idle, shutdown, interrupted states with atomic updates
Delegate mode: setDelegate() toggles lead's write permissions — when enabled, the lead is restricted to coordination-only tools
Plan approval state: setMemberPlanApproval() manages none → pending → approved/rejected flow per member
Event-based cleanup: cleanup() publishes TeamEvent.Cleaned with leadSessionID and delegate fields so listeners can handle side-effects (e.g. restoring lead session permissions) — no direct Session import in the cleanup path

Task system (`TeamTasks` in `team/index.ts`)

Shared task list: list, add, update, complete, claim — all use Storage.update for concurrency safety
Atomic task claiming: claim() checks status, assignee, and dependency resolution inside a Storage.update callback
Dependency resolution: Same depends_on logic as the per-session Todo system — auto-blocks tasks with unresolved deps, auto-unblocks when deps complete
Event publishing: TaskUpdated and TaskClaimed events propagate to TUI in real-time

Messaging (`team/messaging.ts` — 134 lines)

Directed messaging: send() routes messages between teammates and the lead by injecting synthetic user messages into the recipient's session
Broadcast: broadcast() sends to all active members (skips shutdown and interrupted), includes the lead if sender isn't the lead
Auto-wake: When a message is injected into an idle session, autoWake() starts a new prompt loop so the LLM picks up and processes the message immediately
Session injection: Messages arrive as [Team message from <name>]: <text> user messages with synthetic: true

Events (`team/events.ts` — 130 lines)

Zod-validated bus events: team.created, team.member.spawned, team.member.status, team.message, team.broadcast, team.task.updated, team.task.claimed, team.shutdown.request, team.plan.approval, team.cleaned
Full type safety: TeamInfoSchema, TeamMemberSchema, TeamTaskSchema with Zod, re-exported for downstream use
Expanded Cleaned event: TeamEvent.Cleaned includes leadSessionID and delegate fields for event-based permission restoration
Member schema: name, sessionID, agent, status, prompt, model (providerID/modelID format), planApproval

Bootstrap hook (`project/bootstrap.ts`)

Fire-and-forget Team.recover() call during instance startup

Recovery (`Team.recover()`)

Scans all teams for members with status: "active" (stale from a crash)
Marks them as interrupted
Injects a synthetic notification into the lead session: "The following teammates were interrupted and need to be resumed"
Lead's LLM sees the notification on next prompt and can re-spawn or message them

Feature flag (`flag/flag.ts`)

OPENCODE_EXPERIMENTAL_AGENT_TEAMS — dynamic getter from environment variable, gates all team functionality

Tests

4 test files, 26 tests:

team-autowake.test.ts — Auto-wake behavior when messages arrive for idle sessions
team-persistence.test.ts — Storage persistence, config read/write, task serialization (verified via API, not raw file paths)
team-recovery.test.ts — Recovery logic for interrupted teammates after server restart (with Storage cleanup)
team-recovery-e2e.test.ts — End-to-end recovery scenarios with session injection

Files changed

File	Change	Lines
`src/team/index.ts`	New	+392
`src/team/messaging.ts`	New	+134
`src/team/events.ts`	New	+130
`src/flag/flag.ts`	Modified	+12
`src/project/bootstrap.ts`	Modified	+11
`test/team/team-autowake.test.ts`	New	+639
`test/team/team-persistence.test.ts`	New	+198
`test/team/team-recovery.test.ts`	New	+324
`test/team/team-recovery-e2e.test.ts`	New	+321
Total		+2,161

Stack

PR 1/3 — merge in order:

This PR — Core team primitives
feat: add team tools, HTTP routes, and tool registry integration #12731 — Tools + routes
feat: add team TUI integration — sidebar, header, sync, and team dialog #12732 — TUI integration

github-actions · 2026-02-08T18:20:43Z

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

Open an issue describing the bug/feature (if one doesn't exist)
Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

github-actions · 2026-02-08T18:21:28Z

The following comment was made by an LLM, it may be inaccurate:

No duplicate PRs found

…updates

- Reorder in autoWake: add .then() handler to transition shutdown_requested → shutdown - Remove ready from shutdown_requested transitions (prevent overwrite race) - cancelMember: accept shutdown_requested in addition to busy - Wrap autoWake in try/catch (prevent unhandled rejections from fire-and-forget calls)

- Add inbox.ts (JSONL inbox for O(1) writes) - Add core-only tests (autowake, cancel, persistence, recovery) - Update core files to latest dev versions (events, index, messaging) - Adapt to upstream Session API (no teammate field, no LoopResult) - Includes shutdown race condition fix - Move tool-dependent tests to team-tools PR

iamhenry · 2026-02-14T19:36:46Z

im hoping the opencode team is considering something like this. thx for taking the first step into it

sandeepdatalume · 2026-02-25T15:08:03Z

This is needed , I am using a markdown shared file between different models-sessions atm

ubuntupunk · 2026-03-23T10:52:40Z

bump

kamushadenes · 2026-03-23T20:42:33Z

Can we please get this merged?

…malyco#12732 to v1.3.0 Port the agent teams feature from the blog post three PRs onto the latest OpenCode v1.3.0 codebase. Adapts to current architecture: Effect patterns, branded IDs, and service refactoring. Core (PR anomalyco#12730): Team state, messaging, recovery, events Tools (PR anomalyco#12731): 9 MCP tools, HTTP routes, registry integration TUI (PR anomalyco#12732): Team dialog, sync store extension Gated behind OPENCODE_EXPERIMENTAL_AGENT_TEAMS flag.

m407 · 2026-04-14T06:52:28Z

No chance to merge?

liquidsnakeblue · 2026-04-21T15:13:44Z

Why hasn't this merged yet?

JayRovacsek · 2026-04-26T04:08:19Z

Extremely keen, thanks for this PR 🙇

wilsncc · 2026-05-04T00:49:24Z

Very interested in this

coldsaber · 2026-05-05T11:28:18Z

I also wonder why hasn't this merged yet? I really need an agent taam to discuss something, not only subagents.

petterannerwall · 2026-05-07T10:26:23Z

Let me also express my interest in this, can we get it merged anytime soon?

sudashannon · 2026-06-09T11:26:50Z

Let me also express my interest in this, can we get it merged anytime soon?

MunMunMiao · 2026-06-09T11:28:37Z

Really looking forward to it.

github-actions Bot added the needs:issue label Feb 8, 2026

This was referenced Feb 8, 2026

feat: add team tools, HTTP routes, and tool registry integration #12731

Closed

feat: add team TUI integration — sidebar, header, sync, and team dialog #12732

Open

ugoenyioha force-pushed the feature/team-core branch 2 times, most recently from a6f186b to db0179f Compare February 9, 2026 07:46

github-actions Bot removed the needs:issue label Feb 9, 2026

ugoenyioha mentioned this pull request Feb 9, 2026

[DESIGN]: Agent Teams — flat teams with named messaging, multi-model support, and TUI integration #12711

Open

ugoenyioha force-pushed the feature/team-core branch 2 times, most recently from ce90bed to aed05dd Compare February 10, 2026 04:40

claude added 3 commits February 10, 2026 14:57

feat(team-core): add finalized team state, recovery, and reliability …

da05fe9

…updates

fix(team-core): align with upstream session and test dependencies

b0cc628

ugoenyioha force-pushed the feature/team-core branch from 17f2522 to e8c8647 Compare February 10, 2026 22:59

ugoenyioha marked this pull request as ready for review February 10, 2026 23:06

github-actions Bot mentioned this pull request Feb 26, 2026

feat(opencode): add agent teams — DB-based parallel multi-session collaboration #15205

Closed

6 tasks

jacquesbh mentioned this pull request Mar 31, 2026

[FEATURE]: Add Agent Teams Equivalent or Better #12661

Open

1 task

opencode-agent Bot force-pushed the dev branch from 2f2ed11 to 9f201d6 Compare April 16, 2026 21:55

github-actions Bot mentioned this pull request May 12, 2026

feat: implement Agent Teams (Experimental) feature #27053

Closed

5 tasks

Conversation

ugoenyioha commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's included

Team namespace (team/index.ts — 392 lines)

Task system (TeamTasks in team/index.ts)

Messaging (team/messaging.ts — 134 lines)

Events (team/events.ts — 130 lines)

Bootstrap hook (project/bootstrap.ts)

Recovery (Team.recover())

Feature flag (flag/flag.ts)

Tests

Files changed

Stack

Uh oh!

github-actions Bot commented Feb 8, 2026

Uh oh!

github-actions Bot commented Feb 8, 2026

Uh oh!

iamhenry commented Feb 14, 2026

Uh oh!

sandeepdatalume commented Feb 25, 2026

Uh oh!

ubuntupunk commented Mar 23, 2026

Uh oh!

kamushadenes commented Mar 23, 2026

Uh oh!

m407 commented Apr 14, 2026

Uh oh!

liquidsnakeblue commented Apr 21, 2026

Uh oh!

JayRovacsek commented Apr 26, 2026

Uh oh!

wilsncc commented May 4, 2026

Uh oh!

coldsaber commented May 5, 2026

Uh oh!

petterannerwall commented May 7, 2026

Uh oh!

sudashannon commented Jun 9, 2026

Uh oh!

MunMunMiao commented Jun 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

14 participants

ugoenyioha commented Feb 8, 2026 •

edited

Loading

Team namespace (`team/index.ts` — 392 lines)

Task system (`TeamTasks` in `team/index.ts`)

Messaging (`team/messaging.ts` — 134 lines)

Events (`team/events.ts` — 130 lines)

Bootstrap hook (`project/bootstrap.ts`)

Recovery (`Team.recover()`)

Feature flag (`flag/flag.ts`)