@agimon-ai/po-team 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Vuong Ngo
+
+Portions of this software are derived from pi-subagents
+(https://github.com/nicobailon/pi-subagents), Copyright (c) 2026 Nico Bailon,
+distributed under the MIT License.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# @agimon-ai/po-team
+
+Discover agents, run them in the background, exchange messages, and enforce model and tool policy.
+
+Part of the [Po distribution](https://www.npmjs.com/package/@agimon-ai/po).
+
+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:
+
+```yaml
+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:
+
+```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`.
+
+`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 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/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:
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
+
+Maintained by [Agimon](https://agimon.ai/about).
+
+## License
+
+MIT
+
+## 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.