@agimon-ai/po-team

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

Part of the Po distribution.

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 24 or newer
• @earendil-works/pi-agent-core, @earendil-works/pi-ai, @earendil-works/pi-coding-agent 1.0.2

Install

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

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

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

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

Commands and tools

Slash commands include:

/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, and stop. The intercom tool exposes members, send, ask, pending, and reply.

ask is asynchronous in every direction (child to main, main to child, child to sibling). It returns at once with a requestId. The answer arrives later as an intercom message that wakes the asker. A child with an open ask stays alive after its turn ends. If no reply lands within 180 seconds, the asker gets one notice and a turn to decide: keep working, ask again, or finish. The ask stays open, so a late reply still lands while the asker is alive. If the target finishes without replying, the asker is told right away.

Run lifecycle

Runs are asynchronous. The parent receives a run identifier and later completion or failure rather than an inline child transcript. A native child is a conversation in its parent session's own storage, so it survives a restart: when the session reopens, the child resumes where it stopped and its completion still reaches the parent once. An external runtime is a separate process, and a session that ends stops it.

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:

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. 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, and intercom. State is stored in private, per-user temporary directories with per-session subdirectories. 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 po/delegation, po/background-work, po/subagent-policy, and po/fable-plan for the active session. Consumers disconnect and reconnect automatically when that provider changes.

Public API

import { resolveSubagentLaunchContract } from '@agimon-ai/po-team';

Focused subpaths include /api/capability-ceiling, /api/delegation, /api/team-snapshot, and /env. Live cross-extension collaboration contracts come from @agimon-ai/po-core.

Development

Run from this package directory in the workspace:

pnpm build
pnpm typecheck
pnpm test
pnpm lint

Maintained by Agimon.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.

Source and lifecycle

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.