# @agimon-ai/doompi-team

Discover agents, run them in the background, exchange messages, and enforce model and tool policy.

Part of the [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi).

Team does not own Task's graph. When both packages are loaded, Team fulfills Task delegation
requests while Task remains the source of truth for task status and dependencies.

> **Alpha:** run, policy, and intercom contracts may change between releases.

## Requirements

- Node.js 22.19.0 or newer
- `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`,
  `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` 0.85.0

## Install

Define a layer and select it in `.doom/modes.yaml`. Add Task separately for graph-backed delegation:

```yaml
layers:
  coordination:
    packages:
      - '@agimon-ai/doompi-task'
      - name: '@agimon-ai/doompi-team'
        config:
          models:
            - model: provider/model-id
              thinking: high
          excludeTools: [ask_user_question]

majorMode:
  development:
    description: Development with tasks and delegated agents.
    layers: [coordination]
```

For Team without Task in standalone Pi:

```bash
pi install npm:@agimon-ai/doompi-team
```

Team-only sessions can launch and manage agents directly; they simply have no Task-owned graph to
update.

## Commands and tools

Slash commands include:

```text
/run
/parallel
/subagents-doctor
/subagents-steer <run-id> <message>
/subagents-stop
/subagents-list
/subagents-fleet
```

Use `/run` for one agent and `/parallel` for several. `/subagents-doctor` reports diagnostics,
`/subagents-steer` sends guidance to a running agent, and `/subagents-stop` requests a stop.
`/subagents-list` shows available agents, and `/subagents-fleet` shows current runs.

The `subagent` tool exposes `agents`, `run`, `status`, `steer`, `stop`, `suspended`, and `restore`.
The `intercom` tool exposes `members`, `send`, `ask`, `pending`, and `reply`.

Use `SPC a l` to browse agents and `SPC a r` to inspect current-session runs. TUI views require an
interactive host; tools and commands support headless orchestration.

## Run lifecycle

Runs are asynchronous. The parent receives a run identifier and later completion or failure rather
than an inline child transcript. A shutdown requests suspension and writes restorable state. A later
session can list suspended work and explicitly restore it. Reopening does not automatically restart
children, and Team does not promise that every run continues after its parent exits.

## Agent identity

Every spawned agent is given a generated identity of the form `{name}-{role}-{number}`, for example
`alan-reviewer-3`. The role comes from the agent name with its package prefix dropped, and the number
counts every agent in the session, so no two agents share an identity. An agent defined inline, with
no agent file on disk, is shown as `bea-developer-2 (inline)`.

The identity is the intercom member id, not a label beside one, so a peer can address exactly what it
is shown:

```text
intercom({ action: "send", to: "alan-reviewer-3", message: "..." })
subagent({ action: "status", id: "alan-reviewer-3" })
```

Run ids keep working everywhere, and they win when a name and an id collide. A restored run keeps the
identity its peers already know rather than being renamed. Identities are unique within one root
session and are not reused when a run ends.
The root session scopes run results, transcripts, control inboxes, membership, intercom, and
suspended records. State is stored in private, per-user temporary directories with per-session
subdirectories. Suspended records are recoverable only while those temporary files remain. Launch
contracts can contain full prompts and are written with private permissions, then removed after
handoff. Intercom messages expire after 24 hours; liveness checks remove stale membership and run
state.

## Model and tool policy

Package configuration belongs on the Team package entry. When several selected entries contribute
configuration, later entries replace the `models` list and `excludeTools` values are combined in
layer order.

Agent configuration, explicit launch options, Team policy, and provider availability determine the
final model and tools. A child cannot exceed the capability ceiling supplied by its parent or
provider policy. Allowed MCP and stdio tools can execute commands, so treat agent definitions and
the inherited environment as trusted configuration.

## Task delegation bridge

With Task installed:

1. Task selects a pending, unblocked task and sends a delegation request.
2. Team resolves the named agent, context, model, skills, and capability policy.
3. Team owns the background run, messaging, steering, and suspension.
4. Task records the terminal result on its own task.

This is a named Cordis service relationship, not shared persistence. Team provides
`doom/delegation`, `doom/background-work`, `doom/subagent-policy`, and `doom/fable-plan` for the
active session. Consumers disconnect and reconnect automatically when that provider changes.

## Public API

```ts
import { resolveSubagentLaunchContract } from '@agimon-ai/doompi-team';
```

Focused subpaths include `/api/capability-ceiling`, `/api/delegation`, `/api/team-snapshot`,
and `/env`. Live cross-extension collaboration contracts come from
`@agimon-ai/doompi-core`; Pi loads `/extensions/pi` through package metadata.

## Development

Run from this package directory in the workspace:

```bash
pnpm build
pnpm typecheck
pnpm test
pnpm lint
```

Maintained by [Agimon](https://agimon.ai/about).

## License

MIT

## Source and lifecycle

The host entries are generated from `src/extensions/`. Pi commands, tools, hooks, and its root live under `workspaces/sessions/(backend)` because they serve the active Pi session. The session frontend owns message renderers, the fleet and catalog `overlay/*.cli.ts` views, their private presentation helpers, and the `tool/subagent.cli.ts` renderer. The CLI and server session roots hold state, service injection, startup work, and cleanup. The server session backend also owns its API and resources. Team's hub relay channels live in the global backend tree. `src/services` holds platform-agnostic logic, and public capabilities live in flat `src/exports` files.

The routed files own contribution registration. Team's collaboration service replaces session fibers explicitly, uses the injected session only when its session manager matches, and otherwise mounts in the standalone plugin context. Losing that injected session disposes its collaboration fiber.