@fradser/pi-agent-teams 0.5.0

package/.memory/MEMORY.md

@@ -0,0 +1,3 @@
+# Memory Index
+
+- `openai_teammate_api_reference.md` — OpenAI external Teammate / Workspace Agents API reference (Workspace Agents API, Files API, file search, vector stores, Threads API). Reference only, not for Pi extension usage guidance.

package/.memory/openai_teammate_api_reference.md

@@ -0,0 +1,118 @@
+# OpenAI Teammate API Reference
+
+> Reference documentation for OpenAI's external Teammate / Workspace Agents API surface.
+> This is a reference for the API surface OpenAI documents on developers.openai.com — not the Pi extension tools.
+
+## Scope and terminology
+
+In OpenAI's current developer documentation, a "teammate" is an AI teammate in the ChatGPT workspace. The Codex use-case guides describe setting up a teammate as a work chief of staff ([Set up a teammate](https://developers.openai.com/codex/use-cases/proactive-teammate)) and as a dedicated project teammate ([Set up a project teammate](https://developers.openai.com/codex/use-cases/project-teammate)). These teammates are ChatGPT workspace agents: shared agents that run repeatable workflows across ChatGPT and independently complete end-to-end tasks ([Building workspace agents in ChatGPT](https://developers.openai.com/cookbook/articles/chatgpt-agents-sales-meeting-prep)).
+
+The developer API surface for teammates documented on developers.openai.com is the Workspace Agents API for triggering published workspace agents ([Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)), together with the agent-building APIs that supply knowledge and conversation state: the Files API, file search, vector stores, and the Threads API.
+
+**Terminology note.** The current OpenAI API reference defines no `/teammates` resource: there is no teammate endpoint group in the API reference. Requests that mention a Teammate API endpoint map to the Workspace Agents API and the agent-building APIs documented below. Likewise, the current developer documentation does not define a `workflow.md` file format; workflow configuration for teammates is expressed through the surfaces described in the next section. Do not assume undocumented endpoints or file formats.
+
+## Teammates in the ChatGPT workspace
+
+ChatGPT workspace agents are available in research preview for ChatGPT Business, Enterprise, and Edu customers; they are evolutions of GPTs that can work across tools to complete high-value tasks, and they can use connected apps, follow skills, run on a schedule, and be shared with colleagues in the workspace ([Building workspace agents in ChatGPT](https://developers.openai.com/cookbook/articles/chatgpt-agents-sales-meeting-prep)). The Codex use-case guides show two teammate configurations: a work chief of staff that checks connected messages, email, calendar, documents, and project trackers on an hourly schedule ([Set up a teammate](https://developers.openai.com/codex/use-cases/proactive-teammate)), and a project teammate with a dedicated task for one project or workstream that reviews relevant sources, tracks meaningful changes on a schedule, prepares the next step, and waits for approval before taking action ([Set up a project teammate](https://developers.openai.com/codex/use-cases/project-teammate)). Both guides ship a starter prompt and name the connected work tools the teammate may review.
+
+## Workflow as code
+
+The current developer documentation does not document a `workflow.md` file. Workflow configuration for teammates is expressed through the documented surfaces below, and those are the surfaces to use:
+
+- **Workspace agents in ChatGPT.** Agents are created through a conversational builder, given access to the team's connected apps and knowledge bases, tested before publishing, scheduled to run on a recurring schedule, and shared with the workspace ([Building workspace agents in ChatGPT](https://developers.openai.com/cookbook/articles/chatgpt-agents-sales-meeting-prep)).
+- **The Workspace Agents API.** The programmatic entry point: a trigger request carries the message text passed to the agent and an optional caller-defined conversation key that continues the same conversation across trigger events ([Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)).
+- **Agent Builder workflows.** Agent Builder is a visual canvas for building multi-step agent workflows; a workflow is a combination of agents, tools, and control-flow logic that encapsulates the steps and actions for handling a task, and it is published as an object with an ID and versioning. Note that OpenAI is deprecating Agent Builder and schedules the product to shut down on November 30, 2026 ([Agent Builder](https://developers.openai.com/api/docs/guides/agent-builder)).
+
+## Workspace Agents API
+
+The Workspace Agents API triggers a published ChatGPT workspace agent from an external system or automation ([Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)).
+
+- **Endpoints.** `POST https://api.chatgpt.com/v1/workspace_agents/{id}/trigger` starts a run; `GET https://api.chatgpt.com/v1/workspace_agents/{id}/runs/{run_id}` polls run status ([Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)).
+- **Identifiers.** `id` is the stable public API trigger identifier for the published API channel, in an `agtch_XXX` format; `run_id` is the trigger run identifier returned by a trigger request, in an `apirun_XXX` format ([Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)).
+- **Authentication.** Authenticate with a Workspace Agent access token as a bearer credential on `api.chatgpt.com` ([Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs), [Authenticate with Workspace Agent access tokens](https://developers.openai.com/workspace-agents/authentication)).
+- **Request body.** `input` (string, required): message text passed to the agent as trigger input. `conversation_key` (string, optional): a caller-defined stable identifier for continuing the same agent conversation across multiple trigger events. To safely retry the same trigger event, send an optional `Idempotency-Key` header and reuse the same key only when retrying the same event; a retried request with the same key returns the original accepted outcome instead of adding a second trigger event to the queue ([Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)).
+- **Response.** The API durably queues the trigger event and returns `202 Accepted` with a `conversation_url` link to the ChatGPT conversation, for example `{ "conversation_url": "https://chatgpt.com/c/123" }`. The agent's response cannot currently be retrieved through the API ([Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)).
+- **Run status polling (beta).** Include the header `OpenAI-Beta: workspace_agent_runs=v1` when triggering to receive an `agent_trigger_run_id` in the trigger response, then poll the run endpoint until a terminal status. The run object is `workspace_agent.trigger_run` with `id`, `status`, `created_at`, `agent_id`, `api_trigger_id`, `conversation_url`, and `error`; status values are `queued`, `in_progress`, `suspended`, `completed`, and `failed`, where `completed` and `failed` are terminal ([Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)).
+
+**Workspace Agent access tokens.** Tokens are provisioned from the ChatGPT admin access-token flow and are scoped for workspace use. A workspace admin must first enable workspace agents and turn on "Allow users to create personal access tokens" in Admin > Permissions & roles, then create an access token in Admin > Access tokens with the **Workspace Agents** scope. The token is used as a bearer credential and is scoped to Workspace Agents API operations only ([Authenticate with Workspace Agent access tokens](https://developers.openai.com/workspace-agents/authentication)).
+
+## Knowledge files: the Files API
+
+Files are used to upload documents that can be used with features like Assistants and Fine-tuning ([Files](https://developers.openai.com/api/reference/resources/files)).
+
+### FileObject
+
+The `File` object represents a document that has been uploaded to OpenAI ([Files](https://developers.openai.com/api/reference/resources/files)). The live `FileObject` schema lists these fields:
+
+- `id` — string; the file identifier, which can be referenced in API endpoints.
+- `bytes` — number; the size of the file, in bytes.
+- `created_at` — number; the Unix timestamp (in seconds) for when the file was created.
+- `filename` — string; the name of the file.
+- `object` — always `"file"`.
+- `purpose` — the intended purpose of the file: `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, or `user_data`.
+- `status`, `expires_at`, and `status_details` — documented on the current schema and marked deprecated.
+
+The schema exposes the file length through `bytes`; there is no separate size field on `FileObject` ([Files](https://developers.openai.com/api/reference/resources/files)).
+
+### POST /files
+
+Upload a file as multipart form data with `file` (the File object, not the file name) and `purpose`, plus an optional `expires_after` object with `anchor` and `seconds`. Documented `purpose` values for upload are `assistants`, `batch`, `fine-tune`, `vision`, `user_data`, and `evals`. Individual files can be up to 512 MB, each project can store up to 2.5 TB of files in total, there is no organization-wide storage limit, and uploads to this endpoint are rate-limited to 1,000 requests per minute per authenticated user. The Assistants API supports files up to 2 million tokens and of specific file types; the Fine-tuning and Batch APIs only support `.jsonl` files. Vector store attachment has separate limits, including 2,000 attached files per minute per organization ([Upload file](https://developers.openai.com/api/reference/resources/files/methods/create)).
+
+### GET /files and related endpoints
+
+- `GET /files` lists files. The optional `purpose` query parameter limits the list to files with the given purpose; pagination is controlled by `limit` (1 to 10,000, default 10,000), `order` (asc or desc by the `created_at` timestamp), and `after`. The response `data` field is an array of `FileObject` ([List files](https://developers.openai.com/api/reference/resources/files/methods/list)).
+- `GET /files/{file_id}` retrieves a file as a `FileObject` ([Retrieve file](https://developers.openai.com/api/reference/resources/files/methods/retrieve)).
+- `DELETE /files/{file_id}` deletes a file and returns a `FileDeleted` object with `id`, `deleted`, and `object` ([Delete file](https://developers.openai.com/api/reference/resources/files/methods/delete)).
+
+## File search and vector stores
+
+File search is a tool available in the Responses API. It enables models to retrieve information in a knowledge base of previously uploaded files through semantic and keyword search; by creating vector stores and uploading files to them, you give the model access to these knowledge bases, or vector stores. It is a hosted tool managed by OpenAI, so no code is required to handle its execution ([File search](https://developers.openai.com/api/docs/guides/tools-file-search)).
+
+A vector store is a collection of processed files used by the `file_search` tool ([Vector Stores](https://developers.openai.com/api/reference/resources/vector_stores)). Adding a file to a vector store automatically parses, chunks, embeds, and stores the file in a vector database capable of both keyword and semantic search; each vector store can hold up to 10,000 files, and for vector stores created starting in November 2025 the limit is 100,000,000 files. Vector stores can be attached to both assistants and threads, at most one per assistant and at most one per thread ([File Search tool](https://developers.openai.com/api/docs/assistants/tools/file-search)). By default `max_chunk_size_tokens` is 800 and `chunk_overlap_tokens` is 400; chunking is configurable per file through `chunking_strategy`, where `max_chunk_size_tokens` must be between 100 and 4096 inclusive. The maximum file size is 512 MB and each file should contain no more than 5,000,000 tokens ([File Search tool](https://developers.openai.com/api/docs/assistants/tools/file-search)).
+
+Vector Stores endpoints, all documented in the reference ([Vector Stores](https://developers.openai.com/api/reference/resources/vector_stores)):
+
+- `POST /vector_stores` — create a vector store ([Create vector store](https://developers.openai.com/api/reference/resources/vector_stores/methods/create)).
+- `GET /vector_stores` — list vector stores ([List vector stores](https://developers.openai.com/api/reference/resources/vector_stores/methods/list)).
+- `GET /vector_stores/{vector_store_id}` — retrieve a vector store ([Retrieve vector store](https://developers.openai.com/api/reference/resources/vector_stores/methods/retrieve)).
+- `POST /vector_stores/{vector_store_id}` — modify a vector store ([Modify vector store](https://developers.openai.com/api/reference/resources/vector_stores/methods/update)).
+- `DELETE /vector_stores/{vector_store_id}` — delete a vector store ([Delete vector store](https://developers.openai.com/api/reference/resources/vector_stores/methods/delete)).
+- `POST /vector_stores/{vector_store_id}/search` — search a vector store for relevant chunks based on a query and file attributes filter. The body takes `query` (a string or array of strings) and an optional `filters` value, either a `ComparisonFilter` with an operator (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`) or a `CompoundFilter`; results are returned as `vector_store.search_results.page` objects with `file_id`, `filename`, `score`, `attributes`, `content`, `has_more`, and `next_page` ([Search vector store](https://developers.openai.com/api/reference/resources/vector_stores/methods/search)).
+- Subresources for adding files: vector store files ([Vector Store Files](https://developers.openai.com/api/reference/resources/vector_stores/subresources/files), [Create vector store file](https://developers.openai.com/api/reference/resources/vector_stores/subresources/files/methods/create)) and vector store file batches for attaching many files in one request ([Vector Store File Batches](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches), [Create vector store file batch](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create)).
+
+## Threads and thread attachment
+
+Threads and messages represent a conversation session between an assistant and a user ([Assistants API deep dive](https://developers.openai.com/api/docs/assistants/deep-dive)). The Threads API is documented in the Beta Threads reference group ([Threads](https://developers.openai.com/api/reference/resources/beta/subresources/threads)) and belongs to the Assistants API, which the reference labels as deprecated in favor of the Responses API ([Create thread](https://developers.openai.com/api/reference/resources/beta/subresources/threads/methods/create)).
+
+### POST /threads
+
+`POST /threads` creates a thread ([Create thread](https://developers.openai.com/api/reference/resources/beta/subresources/threads/methods/create)). The documented request body:
+
+- `messages` — optional array of objects with `content`, `role`, `attachments`, and `metadata`: a list of messages to start the thread with.
+  - `content` — string, or an array of content parts: `TextContentBlockParam` with `text` and `type` (`"text"`), `ImageFileContentBlock` with `image_file` and `type` (`"image_file"`), or `ImageURLContentBlock` with `image_url` and `type` (`"image_url"`).
+  - `role` — `"user"` or `"assistant"`.
+  - `attachments` — optional array of objects with `file_id` (optional string) and `tools` (optional array of `CodeInterpreterTool` with `type` `"code_interpreter"` or `FileSearchTool` with `type` `"file_search"`), or null: the files attached to the message and the tools they should be added to.
+  - `metadata` — a set of up to 16 key-value pairs; keys have a maximum length of 64 characters and values a maximum length of 512 characters.
+- `tool_resources` — optional object with `code_interpreter.file_ids` (a list of file IDs, up to 20 files) and `file_search.vector_store_ids` (up to 1 vector store attached to the thread), or the `file_search.vector_stores` helper that creates a vector store from `file_ids` and attaches it to the thread, with an optional `chunking_strategy` (`auto`, or `static` with `max_chunk_size_tokens` and `chunk_overlap_tokens`).
+
+The response is a `Thread` object with `id`, `created_at`, `metadata`, `object` (`"thread"`), and `tool_resources` ([Create thread](https://developers.openai.com/api/reference/resources/beta/subresources/threads/methods/create)).
+
+### Limits and truncation
+
+There is a limit of 100,000 messages per thread. Once the size of the messages exceeds the context window of the model, the thread attempts smart truncation — the documentation describes the thread attempting to "smartly truncate" messages — before fully dropping the messages it considers the least important ([Assistants API deep dive](https://developers.openai.com/api/docs/assistants/deep-dive)).
+
+### Thread and message endpoints
+
+- Threads: create ([Create thread](https://developers.openai.com/api/reference/resources/beta/subresources/threads/methods/create)), retrieve ([Retrieve thread](https://developers.openai.com/api/reference/resources/beta/subresources/threads/methods/retrieve)), modify ([Modify thread](https://developers.openai.com/api/reference/resources/beta/subresources/threads/methods/update)), and delete ([Delete thread](https://developers.openai.com/api/reference/resources/beta/subresources/threads/methods/delete)).
+- Messages: create ([Create message](https://developers.openai.com/api/reference/resources/beta/subresources/threads/subresources/messages/methods/create)), list ([List messages](https://developers.openai.com/api/reference/resources/beta/subresources/threads/subresources/messages/methods/list)), plus retrieve, update, and delete ([Messages](https://developers.openai.com/api/reference/resources/beta/subresources/threads/subresources/messages)).
+- Runs, run steps, and tool outputs are documented under the thread runs resource ([Runs](https://developers.openai.com/api/reference/resources/beta/subresources/threads/subresources/runs)).
+
+## API stability and availability
+
+Mirror the documentation's own labeling when describing these surfaces:
+
+- **Workspace agents** — research preview for ChatGPT Business, Enterprise, and Edu customers ([Building workspace agents in ChatGPT](https://developers.openai.com/cookbook/articles/chatgpt-agents-sales-meeting-prep)).
+- **Run status polling** — in beta, opt-in via the `OpenAI-Beta: workspace_agent_runs=v1` header ([Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)).
+- **Threads, Messages, and Runs** — Beta Threads reference group; the Assistants API is deprecated in favor of the Responses API ([Threads](https://developers.openai.com/api/reference/resources/beta/subresources/threads), [Create thread](https://developers.openai.com/api/reference/resources/beta/subresources/threads/methods/create)).
+- **FileObject** — `status`, `expires_at`, and `status_details` are marked deprecated on the current schema ([Files](https://developers.openai.com/api/reference/resources/files)).
+- **Agent Builder** — deprecated and scheduled to shut down on November 30, 2026 ([Agent Builder](https://developers.openai.com/api/docs/guides/agent-builder)).

package/.memory/run-centric-design.md

@@ -0,0 +1,22 @@
+---
+name: teammate-autonomous-and-tui
+description: Agent Teams (packages/agent-teams) — run-centric: declarative agent files, single-call DAG dispatch, bounded child-process nodes, one-way leader inbox reports, session-wide worker cap, per-spawn identity validation
+type: project
+---
+
+`packages/agent-teams` (0.3.0) is a run-centric multi-agent system: the Pi session is the leader; agents are declarative Markdown files; each run is a dependency-aware task graph dispatched in one call, where each node is a bounded child Pi process and a session-wide cap limits total workers to 8.
+
+**Why:**
+The teammate-registry model (runtime `teammate_register`/`create_task`/`start_task` ceremony, session-scoped identities, read receipts) was replaced after a design review. The ceremony critique: a one-off delegation cost 4 tool calls (list/register/create/start), identities were session-ephemeral so registration cost was paid per session, and both competitor packages (pi-maestro-teammate, @gcoder1991/pi-mesh) proved single-call DAG dispatch + declarative markdown agents. The later simplification removed the remaining half-channels: workers report only to the leader, upstream DAG results replace peer delivery, and live run status is not injected into every system prompt.
+
+**How to apply:**
+1. **Agents are declarative files** (`src/agents.ts`): frontmatter `name`/`description`/`tools`/`model` (inline `#` comments stripped), body = role prompt. Discovery precedence per name: project `.pi/agents/` > user `~/.pi/agent/agents/` > bundled `agents/`. Bundled: worker/reviewer/specialist/observer.
+2. **Single-call DAG dispatch** (`teammate_run`): `tasks` with `id`/`agent`/`prompt`/`paths`/`access` (default read)/`dependsOn`/`model`/`timeoutMs`, plus `concurrency` (default 4), `worktree`, `background`, `timeoutMs`, `summarize`, and `summaryAgent`. Validates dup ids, unknown dependsOn, cycles, bad paths before any spawn. Root nodes start immediately; `scheduleRun` auto-starts dependents on completion; write nodes with overlapping paths are deferred across all runs in the session unless worktree-isolated (`findSharedWorkspaceWriteConflict`).
+3. **Leader tools (3)**: `teammate_run`, `teammate_cancel` (run or `nodeId` node-level cancel; marks cancelled BEFORE terminating workers; SIGTERM→SIGKILL; console `x` reuses `cancelNodeAndTerminate`), and `teammate_retry` (retries failed/cancelled nodes without re-running completed ones). No leader message tool exists.
+4. **Worker protocol (1 capability tool)**: worker-only `teammate_message` has only `subject`/`body`/optional `status` and always reports to the leader. Per-spawn identity: `PI_TEAMMATE_WORKER_NAME` = `runId:nodeId`, `PI_TEAMMATE_SPAWN_ID` = fresh UUID; `applyWorkerEvents` rejects stale-spawn events. Reports enter one leader inbox; there are no peer mailboxes, worker inboxes, or leader broadcasts. Upstream DAG results are injected into downstream prompts (`=== UPSTREAM HANDOFF ===`).
+
+5. **Outcomes authoritative & non-polling leader**: workers message `team-leader` (`teammate_message`) with their deliverables upon completion, delivered automatically as a follow-up turn. The team leader does not sleep while tasks execute. One canonical terminal result per node built by the harness after child close; reported completion + SIGTERM close stays completed; failed node cancels its transitive pending dependents (`cancelBlockedDependents`) and fails the run. Worktree per node (`createWorktree(run.cwd, "${runId}-${nodeId}")`), diff captured for integration review. State snapshots are dirty-gated and worker task temp files are removed after close. Background runs deliver one run-completion follow-up; foreground gather (`background: false`) blocks the tool call (detaches after 5 min so turn is never hung).
+6. **UI**: passive widget (display-only) + `/teammate` full-screen console (owns input via `ctx.ui.custom`, no global interception) — rows are nodes, detail = node lifecycle + leader reports, live activity streams tool calls and thinking deltas, SGR mouse-wheel scrolling. Follows `@packages/btw` style language.
+7. **Testing**: BDD in `features/agent-teams.feature`, package tests in `tests/test_teammate_package.py` including node-eval runtime tests of state.ts/spawner.ts; typecheck via `npx tsc --noEmit --strict ... src/*.ts`.
+
+**Related:** [[pi-cli-print-json-usage]] [[no-global-input-interception]] [[pi-kitty-csi-u-keys]] [[pi-custom-component-rendering]] [[pi-package-conventions]]

package/README.md

@@ -0,0 +1,111 @@
+# Agent Teams Pi Package
+
+Run-centric multi-agent system for Pi — declarative agents, single-call DAG dispatch, bounded child-process nodes, and one-way worker reports to the leader.
+
+**Display Name**: Agent Teams
+
+## What This Package Does
+
+Agents are declarative Markdown files (bundled, user, and project scopes). A run is a dependency-aware task graph dispatched in **one call**: root nodes start immediately, concurrency is bounded, overlapping shared-workspace writes are deferred (advisory coordination across all runs in the session) unless worktree-isolated, and downstream nodes auto-start when their dependencies complete. Each node is a bounded child Pi process with per-spawn identity validation.
+
+## Install
+
+```bash
+pi install /path/to/pi-packages/packages/agent-teams
+```
+
+Then run `/reload` in Pi.
+
+## Agents are declarative files
+
+Agent definitions are Markdown files with frontmatter; the body is the worker's role prompt.
+
+```markdown
+---
+name: security-auditor
+description: Read-only security reviewer; use after security-sensitive edits
+tools: read,bash
+model: provider/model   # optional
+---
+Review the assigned scope for exploitable security problems. Do not edit files.
+```
+
+Discovery precedence per name: **project `.pi/agents/` > user `~/.pi/agent/agents/` > bundled package `agents/`**. Bundled agents: `worker`, `reviewer`, `specialist`, `observer`. Available agents are dynamically injected into prompt guidance via `before_agent_start`.
+
+## Dispatch a run in one call
+
+```text
+teammate_run({
+  tasks: [
+    { id: "inspect", agent: "reviewer", prompt: "Review the auth middleware", paths: ["packages/api/src"], access: "read" },
+    { id: "fix", agent: "worker", prompt: "Apply the review findings", paths: ["packages/api"], access: "write", dependsOn: ["inspect"] },
+    { id: "verify", agent: "reviewer", prompt: "Verify the fix", paths: ["packages/api"], access: "read", dependsOn: ["fix"] },
+  ],
+  concurrency: 2,
+  worktree: false,
+  background: true
+})
+```
+
+- `access` defaults to `read`; declare `write` explicitly.
+- `dependsOn` edges must form a DAG (duplicate ids, unknown references, and cycles are rejected before any worker starts).
+- `worktree: true` runs every node in its own git worktree and captures each diff for integration review.
+- `background` defaults to `true`: teammates always run in the background — the call returns the run id immediately, the model turn stays free, and workers report their deliverables through the worker-only `teammate_message` capability, delivered automatically as a follow-up turn. The team leader does not sleep or busy-wait while tasks execute. Pass `background=false` to block and gather inline (it detaches after 5 minutes so the turn is never hung).
+- `timeoutMs` is a run-level hard cap: when exceeded, the run fails and live workers are terminated.
+- A session-wide cap of 8 worker processes applies in addition to each run's `concurrency` limit.
+- Multi-node runs append a `__summary` node by default (`summarize=false` to skip). Single-task runs stay compact unless `summarize=true`.
+- Completing a node hands its result to pending dependents through the spawned worker prompt. Workers have no peer-message or inbound-reply path.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `teammate_run` | Dispatch a dependency-aware task graph in one call |
+| `teammate_cancel` | Cancel a run, or one node (`nodeId`) while the rest continues |
+| `teammate_retry` | Re-run only the failed/cancelled nodes of a settled run |
+| `/teammate` | Full-screen console: run/node status, node detail, worker reports, cancel node |
+
+Spawned workers receive one additional capability, `teammate_message`, for progress notes and final reports to the team leader.
+
+Messaging is deliberately one-way: workers append validated reports to their own outbox, and the leader drains them into one leader inbox. There is no peer mailbox, worker inbox, leader broadcast tool, or worker-to-worker delivery path. Dependency results are delivered through the DAG prompt (`=== UPSTREAM HANDOFF ===`) when the dependent starts.
+
+## Reliability protocol
+
+- **Per-spawn identity validation**: every worker event must match the node's current spawn id; stale events from an older process cannot affect a newer spawn.
+- **One-way message storage**: worker event ids and per-spawn identities are validated and deduplicated; every accepted report lands in the single leader inbox. No read flags, receipts, peer mailboxes, or leader-to-worker inboxes exist.
+- **One canonical terminal result per node**: built by the harness from node state + captured output after the child closes; a worker's message with status alone is not final delivery.
+- **Advisory write-conflict coordination (session-wide)**: the scheduler never starts a shared-workspace write node while another shared-workspace write node with overlapping paths is running — checked across **all runs in the session**, not just the same run. This is scheduling-level coordination, not isolation.
+- **`access`/`paths` are metadata, not enforcement**: they drive conflict scheduling and prompts; a worker's real capabilities come from its agent definition's `tools` list. A `read` node whose agent has `write`/`bash` tools can still write. Use `worktree: true` or a restricted agent tool list when you need actual isolation.
+- **Failure semantics**: a failed node cancels its not-yet-started transitive dependents and fails the run; other nodes finish. Cancelling a run or node reports the outcome in the tool call itself — it does not fire an extra completion follow-up.
+
+## State and sessions
+
+State is session-scoped and dies with the session (`~/.pi/agent/teammate/<sessionKey>/`); runs do not survive restarts. `background: true` runs notify via one follow-up; worker messages and node outcomes are recorded in the leader transcript and visible in `/teammate`. Agents, by contrast, live in files and survive across sessions — that is the persistent layer.
+
+## Structure
+
+```
+agent-teams/
+├── package.json       — Pi package manifest
+├── agents/            — bundled agent definitions (worker/reviewer/specialist/observer)
+├── src/
+│   ├── index.ts       — composition root: Pi hooks and session lifecycle
+│   ├── tools.ts       — leader tool and /teammate command registration
+│   ├── run-machine.ts — DAG scheduler, worker lifecycle, persistence, session cap
+│   ├── ui.ts          — passive widget and /teammate console
+│   ├── worker.ts      — worker identity binding and report capability
+│   ├── guidance.ts    — static leader/worker protocol guidance
+│   ├── agents.ts      — declarative agent discovery (frontmatter parsing, scope precedence)
+│   ├── state.ts       — runs/nodes state machine, leader inbox, dirty tracking
+│   ├── spawner.ts     — child Pi worker spawner (JSON-mode, usage accounting)
+│   ├── statefile.ts   — leader snapshot + worker outbox IO
+│   ├── worktree.ts    — git worktree isolation
+│   ├── console-viewport.ts — console viewport math (wrap, scroll clamp, ranges)
+│   └── terminal.ts    — canonical per-node terminal result builder
+├── features/          — BDD contract
+└── tests/             — package E2E tests
+```
+
+## License
+
+MIT

package/agents/observer.md

@@ -0,0 +1,10 @@
+---
+name: observer
+description: Read-only monitor of activity, logs, or processes; use when the task is to observe, watch, or report state rather than change it
+tools: read
+---
+You are an observer agent. Observe and report on the assigned scope without
+changing anything. Take the required snapshots or readings, summarize what you
+observed, and report notable events or anomalies with timestamps and evidence
+via teammate_message to team-leader with status="completed". You have no edit,
+write, or command tools.

package/agents/reviewer.md

@@ -0,0 +1,11 @@
+---
+name: reviewer
+description: Read-only code or content reviewer; use after implementation or plan changes to check for correctness, regressions, and security
+tools: read,bash
+---
+You are a reviewer agent. Read the relevant code and tests first, then review
+the assigned scope for correctness, regressions, and security problems. Do not
+edit files. Report only confirmed findings with severity, evidence, exact
+paths, and a minimal fix recommendation via teammate_message to team-leader with
+status="completed". When no issue is confirmed, say so and list the checks
+you performed.

package/agents/specialist.md

@@ -0,0 +1,10 @@
+---
+name: specialist
+description: Read-only domain expert for a specific technical area (security, performance, data, platform); use when a task needs deep domain judgment rather than broad implementation
+tools: read,bash
+---
+You are a specialist agent. Apply deep domain judgment to the assigned scope:
+investigate, analyze, and produce findings or recommendations with evidence via
+teammate_message to team-leader with status="completed". Do not edit files.
+State your assumptions, the evidence you used, and the bounds of your expertise
+for this task.

package/agents/worker.md

@@ -0,0 +1,11 @@
+---
+name: worker
+description: General executor that implements changes and verifies them; use when a task needs code or file modifications, or when no more specific agent fits
+tools: read,bash,edit,write
+---
+You are a worker agent. Implement the assigned task end to end within the
+declared paths and access scope, then verify your own work by running the
+relevant tests or commands. Follow the task's ordered procedure. Report what
+you changed, what you verified, and any risks or follow-up work via
+teammate_message to team-leader with status="completed". Do not touch
+files outside the assigned scope.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@fradser/pi-agent-teams",
+  "version": "0.5.0",
+  "description": "Multi-agent team system for Pi — DAG orchestration, leader inbox, and one-way worker reports",
+  "keywords": [
+    "pi-package",
+    "teammates",
+    "openai",
+    "workspace-agents",
+    "agents",
+    "multi-agent",
+    "team",
+    "orchestration"
+  ],
+  "author": "Frad LEE <fradser@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FradSer/pi-packages.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "agents",
+    ".memory",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/agents.ts

@@ -0,0 +1,138 @@
+/**
+ * Declarative agent definitions: Markdown files with YAML-style frontmatter.
+ *
+ * Discovery scopes (later scopes override earlier ones for the same name):
+ *   1. bundled  — agents shipped with this package (agents/)
+ *   2. user     — ~/.pi/agent/agents/  (respects PI_CODING_AGENT_DIR)
+ *   3. project  — <cwd>/.pi/agents/
+ *
+ * Frontmatter fields:
+ *   name        — unique agent id (required)
+ *   description — routing contract: when the leader should choose this agent
+ *   tools       — comma-separated list or YAML list of Pi tool ids
+ *   model       — optional provider/model pin
+ * The Markdown body is the worker's role prompt.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface AgentDefinition {
+  name: string;
+  description: string;
+  tools: string[];
+  model?: string;
+  /** The Markdown body, trimmed; used as the worker role prompt. */
+  prompt: string;
+  /** Scope that supplied this definition ("bundled" | "user" | "project"). */
+  scope: "bundled" | "user" | "project";
+  /** Absolute path of the definition file. */
+  source: string;
+}
+
+const BUNDLED_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "agents");
+
+function agentsDir(scope: "user" | "project", cwd?: string): string {
+  if (scope === "user") {
+    const base = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+    return path.join(base, "agents");
+  }
+  return path.join(cwd || process.cwd(), ".pi", "agents");
+}
+
+function parseFrontmatter(raw: string): { fields: Record<string, string | string[]>; body: string } {
+  const fields: Record<string, string | string[]> = {};
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+  if (!match) return { fields, body: raw.trim() };
+  for (const line of match[1].split("\n")) {
+    const separator = line.indexOf(":");
+    if (separator <= 0) continue;
+    const key = line.slice(0, separator).trim();
+    // Strip inline YAML comments (# ...) and surrounding whitespace/quotes.
+    let value = line.slice(separator + 1).replace(/\s+#.*$/, "").trim();
+    if (key === "tools") {
+      const tools = value
+        .replace(/^\[|\]$/g, "")
+        .split(",")
+        .map((tool) => tool.trim().replace(/^["']|["']$/g, ""))
+        .filter(Boolean);
+      fields.tools = tools;
+      continue;
+    }
+    fields[key] = value.replace(/^["']|["']$/g, "");
+  }
+  return { fields, body: match[2].trim() };
+}
+
+function loadDir(scope: "bundled" | "user" | "project", dir: string, agents: Map<string, AgentDefinition>): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return; // A missing agents directory is not an error.
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const source = path.join(dir, entry.name);
+    let raw: string;
+    try {
+      raw = fs.readFileSync(source, "utf8");
+    } catch {
+      continue;
+    }
+    const { fields, body } = parseFrontmatter(raw);
+    const name = typeof fields.name === "string" ? fields.name : entry.name.replace(/\.md$/, "");
+    if (!name || !body) continue;
+    const tools = Array.isArray(fields.tools) ? fields.tools : [];
+    const model = typeof fields.model === "string" && fields.model ? fields.model : undefined;
+    agents.set(name, {
+      name,
+      description: typeof fields.description === "string" ? fields.description : "",
+      tools,
+      model,
+      prompt: body,
+      scope,
+      source,
+    });
+  }
+}
+
+/**
+ * Resolve all agent definitions visible from the given cwd, with later scopes
+ * overriding earlier ones per name: project > user > bundled.
+ */
+export function discoverAgents(cwd?: string): Map<string, AgentDefinition> {
+  const agents = new Map<string, AgentDefinition>();
+  loadDir("bundled", BUNDLED_AGENTS_DIR, agents);
+  loadDir("user", agentsDir("user", cwd), agents);
+  loadDir("project", agentsDir("project", cwd), agents);
+  return agents;
+}
+
+/** Resolve one agent by name, or undefined when no scope defines it. */
+export function resolveAgent(name: string, cwd?: string): AgentDefinition | undefined {
+  return discoverAgents(cwd).get(name);
+}
+
+/** True when the agent name is defined in any scope. */
+export function hasAgent(name: string, cwd?: string): boolean {
+  return resolveAgent(name, cwd) !== undefined;
+}
+
+/**
+ * Format discovered agents as Markdown for prompt injection in before_agent_start.
+ */
+export function formatAgentGuidance(cwd?: string): string {
+  const agents = discoverAgents(cwd);
+  if (agents.size === 0) return "(none found in bundled, user, or project scopes)";
+  const lines: string[] = [];
+  for (const agent of agents.values()) {
+    const model = agent.model ? ` | Model: ${agent.model}` : "";
+    lines.push(`- **${agent.name}** (${agent.scope})`);
+    if (agent.description) lines.push(`  ${agent.description}`);
+    lines.push(`  Tools: ${agent.tools.join(", ") || "(role defaults)"}${model}`);
+  }
+  return lines.join("\n");
+}

package/src/console-viewport.ts

@@ -0,0 +1,30 @@
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** Leave room for the console borders, title, spacing, and footer. */
+export function maxConsoleBody(rows: number): number {
+  return Math.max(3, rows - 5);
+}
+
+/** Wrap source records before calculating scroll positions. */
+export function wrapConsoleDetail(lines: string[], width: number): string[] {
+  const contentWidth = Math.max(10, width - 4);
+  return lines.flatMap((line) => {
+    const wrapped = wrapTextWithAnsi(line, contentWidth);
+    return wrapped.length > 0 ? wrapped : [""];
+  });
+}
+
+export function clampConsoleScroll(offset: number, total: number, viewport: number): number {
+  return Math.max(0, Math.min(Math.max(0, total - viewport), offset));
+}
+
+export function scrollConsoleDetail(offset: number, delta: number, total: number, viewport: number): number {
+  return clampConsoleScroll(offset + delta, total, viewport);
+}
+
+export function consoleScrollRange(offset: number, total: number, viewport: number): string {
+  if (total === 0) return "no activity";
+  const start = clampConsoleScroll(offset, total, viewport);
+  const end = Math.min(total, start + viewport);
+  return total <= viewport ? `${total} lines` : `${start + 1}–${end}/${total}`;
+}

package/src/guidance.ts

@@ -0,0 +1,77 @@
+import { formatAgentGuidance } from "./agents";
+
+export const WORKER_GUIDANCE = `
+## Spawned Teammate Protocol
+
+You are a teammate, not the team leader. Work only on the task bound to
+this process and its declared access/paths. Communication is one-way to the
+team leader:
+
+- Report: call teammate_message for plans, progress, and blockers without a
+  terminal status. For the final deliverable, use status="completed"; for a
+  blocked or failed task, use status="failed" and explain the error. The
+  final report MUST contain the full deliverable.
+- There is no peer or leader-to-worker message channel. DAG upstream results
+  are already injected into your task prompt. Make decisions within the
+  assigned task and report blockers instead of waiting for a reply.
+
+Do not use leader coordination tools, claim new tasks, or overwrite files
+outside your assigned scope.
+`;
+
+export function buildTeamLeaderGuidance(cwd?: string): string {
+  const agents = formatAgentGuidance(cwd);
+  return `
+## Agent Teams Orchestration
+
+You are the team leader: the current Pi session owns decomposition,
+delegation, synchronization, and the final user-facing answer. Workers are
+isolated child processes; they do not see this conversation unless you put the
+needed context in their task.
+
+### Agents are declarative files
+
+Agents live in Markdown files with frontmatter (name, description, tools,
+optional model); the body is the role prompt. Discovery precedence per name:
+project .pi/agents > user ~/.pi/agent/agents > bundled package agents.
+Prefer a bundled or existing agent; add a project agent under .pi/agents
+only when its role materially differs. Never register runtime identities.
+
+Available agents:
+${agents}
+
+### Dispatch a run in one call
+
+Use teammate_run with a tasks array: each task has id, agent, prompt, paths,
+access (read default, write explicit), optional dependsOn, model, and
+timeoutMs. The scheduler starts root nodes immediately, bounds concurrency,
+defers overlapping shared-workspace writes — advisory coordination across all
+runs, not file-access isolation — unless worktree=true, and auto-starts
+downstream nodes when their dependencies complete. access and paths coordinate
+scheduling only; a worker's real capabilities come from its agent definition's
+tools list.
+
+Teammates run in the background by default: the call returns the run id
+immediately, and the main session is free. When a teammate finishes, it sends
+its final deliverable to team-leader through its append-only outbox. The
+harness delivers the run completion automatically as a follow-up turn. Pass
+background=false only when you strictly need inline synchronous blocking (it
+detaches after 5 minutes so the turn is never hung). A session-wide cap of 8
+worker processes applies in addition to each run's concurrency. Multi-node runs
+append a __summary node by default; pass summarize=false to skip it.
+
+### DO NOT poll status
+
+- When tasks run in the background, do not run sleep commands, and do not
+  execute repetitive read/grep busywork to pass time.
+- Teammates will report their final deliverables and the harness will deliver
+  the completion follow-up automatically.
+- Once you dispatch background tasks, if you have no other independent
+  foreground work, end your turn immediately and wait for the follow-up.
+- teammate_cancel stops a run or one node; teammate_retry re-runs only failed
+  or cancelled nodes of a settled run.
+- After a run completes and the message is delivered, inspect the artifacts
+  yourself: a worker's claim is not proof until its deliverable and tests are
+  checked. Treat failed, timed-out, cancelled, and missing nodes explicitly.
+`;
+}