@bastani/atomic 0.7.17 → 0.8.0

package/dist/builtin/intercom/README.md

@@ -0,0 +1,484 @@
+<p>
+  <img src="banner.png" alt="pi-intercom" width="1100">
+</p>
+
+# Pi Intercom
+
+Direct 1:1 messaging between pi sessions on the same machine. Send context, findings, or requests from one session to another — whether you're driving the conversation or letting agents coordinate.
+
+```text
+User flow: press Alt+M or run /intercom to pick a session and send a message
+```
+
+## Why
+
+Sometimes you're running multiple pi sessions — one researching, one executing, one reviewing. Pi-intercom lets you:
+
+- **User-driven orchestration** — Send context or findings from your research session to your execution session
+- **Agent collaboration** — An agent can reach out to another session when it needs help or wants to share results
+- **Session awareness** — See what other pi sessions are running and their current status
+
+Unlike pi-messenger (a shared chat room for multi-agent swarms), pi-intercom is for targeted 1:1 communication where you pick the recipient.
+
+Pi-intercom also integrates well with [pi-subagents](https://github.com/nicobailon/pi-subagents): delegated child agents get a child-only `contact_supervisor` tool when `pi-subagents` supplies bridge metadata. Use `reason: "need_decision"` for blocking clarification, `reason: "interview_request"` for multiple structured supervisor answers, and `reason: "progress_update"` for meaningful plan-changing updates. Normal sessions only see the regular `intercom` tool.
+
+## In One Minute
+
+Each pi session that has `pi-intercom` loaded and enabled connects to a tiny local broker over a local IPC transport. The broker keeps track of connected sessions and routes direct messages to the one you target by name or session ID. The extension gives you both a tool (`intercom`) and a small overlay UI (`/intercom` or `Alt+M`). Incoming messages are rendered inline inside the recipient session, can trigger a turn immediately, and are also stored in Pi session history as extension entries.
+
+## Install
+
+```bash
+pi install npm:pi-intercom
+```
+
+Then restart Pi. The extension auto-connects to the broker on startup and registers the bundled `pi-intercom` skill for common coordination patterns.
+
+**Recommended:** Add this snippet to your project's `AGENTS.md` to help agents understand when to coordinate across sessions:
+
+```xml
+<pi-intercom>
+Coordinate with other local pi sessions on related codebases. Use `/skill:pi-intercom` for patterns.
+
+**When:** Same codebase (parallel work), reference codebase (consulting patterns), related repos (shared libraries).
+
+**Not when:** Unrelated codebases, trivial questions, or when you can proceed independently.
+
+**Principle:** Prefer `send` for notifications; `ask` only when blocked waiting for input.
+</pi-intercom>
+```
+
+A session becomes intercom-connected when all of these are true:
+- the `pi-intercom` extension is installed and loaded in that session
+- `enabled` is not set to `false` in `~/.pi/agent/intercom/config.json`
+- the session has started or reloaded after the extension was installed
+- the local broker is running or can be auto-started
+
+The session list only shows intercom-connected sessions, not every open Pi process on the machine.
+
+If a session is unnamed, pi-intercom now exposes a runtime-only fallback alias like `subagent-chat-1a2b3c4d` so other sessions can still target it. That alias is not persisted as the Pi session title, so `pi --resume` can keep showing the transcript snippet instead of a generic `session-...` name.
+
+## Quick Start
+
+### From the Keyboard
+
+Press **Alt+M** or type `/intercom` to open the session list overlay:
+
+1. **Select a session** — Use arrow keys to pick a target session
+2. **Compose message** — Write your message in the compose overlay
+3. **Send** — Press Enter to send, Escape to cancel
+
+### From the Agent
+
+The agent can list sessions and send messages using the `intercom` tool. Tool calls and results render as compact transcript rows so send/ask/reply flows are easy to scan. For common patterns like planner-worker delegation, the bundled `pi-intercom` skill provides copy-paste ready examples:
+
+```typescript
+// List active sessions
+intercom({ action: "list" })
+// → **Current session:**
+// → • executor (20d43841) — ~/projects/api (claude-sonnet-4) [self, idle]
+// → **Other sessions:**
+// → • research (6332faab) — ~/projects/api (claude-sonnet-4) [same cwd, thinking]
+
+// Send a message
+intercom({ action: "send", to: "research", message: "Check if UserService.validate() handles null" })
+// → Message sent to research
+
+// Check connection status
+intercom({ action: "status" })
+// → Connected: Yes, Session ID: abc123, Active sessions: 3
+
+// Send with attachments (code snippets, files, or context)
+intercom({
+  action: "send",
+  to: "worker",
+  message: "Here's the fix:",
+  attachments: [{
+    type: "snippet",
+    name: "auth.ts",
+    language: "typescript",
+    content: "function validate(user: User) { ... }"
+  }]
+})
+```
+
+### Receiving Messages
+
+When a message arrives, it appears inline in your chat with the sender's info and a reply hint:
+
+```
+**From research** (~/projects/api)
+
+To reply, use the intercom tool: intercom({ action: "reply", message: "..." })
+
+Found the issue — UserService.validate() doesn't check for null input.
+See auth.ts:142-156.
+```
+
+The reply hint (enabled by default) points to `intercom({ action: "reply", ... })`, so recipients do not need raw sender or `replyTo` IDs. Idle recipients get a new turn immediately; busy interactive recipients receive the message once they go idle. Attachment content is included in the agent-visible body, and messages are rendered inline and stored in Pi session history.
+
+## Workflow: Planner-Worker Coordination
+
+The most natural use of pi-intercom is splitting a task between two sessions — one holds the big picture, the other does the hands-on work. When the worker hits an ambiguity ("should I optimize for readability or performance here?"), they ask without losing context.
+
+### Setup
+
+Open two terminals and start pi in each. Name them so they can find each other:
+
+```
+# Terminal 1                    # Terminal 2
+/name planner                   /name worker
+```
+
+Verify they see each other from either session:
+
+```typescript
+intercom({ action: "list" })
+// → • worker — ~/projects/api (claude-sonnet-4) [idle]
+```
+
+### The Conversation
+
+Here's how a typical exchange looks. The planner delegates with `send` (fire-and-forget). The worker uses `ask` for anything that needs a response — questions, discoveries, completion reports. `ask` sends the message and blocks until the planner replies, so the worker gets the answer as a tool result and continues in the same turn.
+
+**Planner sends a task:**
+```typescript
+intercom({
+  action: "send",
+  to: "worker",
+  message: "Task-3: Add retry logic to API client. Key files: src/api/client.ts, src/api/types.ts. Ask if anything's unclear."
+})
+```
+
+**Worker hits an ambiguity — asks and waits:**
+```typescript
+intercom({
+  action: "ask",
+  to: "planner",
+  message: "Should retry apply to all endpoints or just idempotent ones? Also, max retry count and backoff strategy?"
+})
+// → Reply from planner: Only GET/PUT/DELETE — never POST. Max 3 retries, exponential backoff starting at 100ms.
+// Worker continues implementing with the answer, same turn, full context.
+```
+
+**Worker finds something unexpected — escalates and waits:**
+```typescript
+intercom({
+  action: "ask",
+  to: "planner",
+  message: "Found: fetchWithTimeout swallows network errors. Fixing this changes the error shape. OK to proceed?"
+})
+// → Reply from planner: Yes, surface the error types. The current behavior is a bug.
+```
+
+**Worker reports completion:**
+```typescript
+intercom({
+  action: "ask",
+  to: "planner",
+  message: "Task-3 done. Added RetryPolicy type, applied to GET/PUT/DELETE, surfaced NetworkError, 4 tests passing."
+})
+// → Reply from planner: Looks good. Move on to task-4.
+```
+
+### Communication Patterns
+
+| Pattern | Action | Why |
+|---------|--------|-----|
+| **Task Delegation** | Planner uses `send` | Fire-and-forget. Planner doesn't need to wait for an ack. |
+| **Clarification Request** | Worker uses `ask` | Worker needs the answer to proceed. Blocks until reply. |
+| **Discovery Escalation** | Worker uses `ask` | Worker needs approval before changing course. |
+| **Completion Report** | Worker uses `ask` | Planner might have follow-up instructions or the next task. |
+
+### Reply Hints
+
+When `replyHint` is enabled (the default), incoming messages include the exact `intercom()` call to respond:
+
+```
+**From planner** (~/projects/api)
+
+To reply, use the intercom tool: intercom({ action: "reply", message: "..." })
+
+Only GET/PUT/DELETE — never POST. Max 3 retries with exponential backoff starting at 100ms.
+```
+
+This matters because the agent receiving the message doesn't need to reconstruct raw `to` and `replyTo` IDs — the hint is right there. Combined with idle-gated `triggerTurn` delivery, it enables real back-and-forth conversation without interrupting work in progress. If the reply happens later instead of in the triggered turn, `intercom({ action: "reply" })` falls back to the single unresolved inbound ask, and `intercom({ action: "pending" })` shows who is still waiting.
+
+### `send` vs `ask`
+
+`send` is fire-and-forget — the tool returns immediately after delivery. By default, it sends immediately even in interactive sessions. If you want an approval dialog before non-reply sends, set `confirmSend: true` in config. Replies that include `replyTo` still skip confirmation so reply-hint flows can continue without an extra approval step.
+
+`ask` sends the message and blocks until the recipient responds (10-minute timeout). The reply comes back as the tool result, so the agent continues in the same turn with full context. No confirmation dialog — if you're asking and waiting, the intent is clear.
+
+`reply` is receiver-side sugar for replying to an inbound ask. In the turn triggered by an incoming intercom ask, `intercom({ action: "reply", message: "..." })` targets that exact sender and message automatically. If you reply later, it falls back to the single unresolved inbound ask. If multiple asks are pending, use `intercom({ action: "pending" })` to inspect them and then call `reply` with `to` to disambiguate.
+
+The planner typically uses `send`. If you prefer manual approval for outgoing non-reply messages, turn on `confirmSend: true`. The worker uses `ask` for everything (no confirmation needed, gets answers inline), so it can operate autonomously either way.
+
+## Workflow: Subagent-to-Supervisor Escalation
+
+This workflow requires [`pi-subagents`](https://github.com/nicobailon/pi-subagents) to be installed and to supply child bridge metadata. When `pi-subagents` spawns a delegated child with that metadata, the child session gets a subagent-only `contact_supervisor` tool in addition to the regular `intercom` tool. Normal sessions never see `contact_supervisor`.
+
+### When the Tool Appears
+
+`contact_supervisor` only registers when `pi-subagents` sets all of these environment variables:
+
+- `PI_SUBAGENT_ORCHESTRATOR_TARGET` — the supervisor session name or ID
+- `PI_SUBAGENT_RUN_ID` — the run identifier
+- `PI_SUBAGENT_CHILD_AGENT` — the agent type
+- `PI_SUBAGENT_CHILD_INDEX` — the child index within the run
+
+If any are missing, the session falls back to the regular `intercom` tool.
+
+### Three Reasons
+
+| Reason | Behavior | Use When |
+|--------|----------|----------|
+| `need_decision` | Sends an ask and blocks until the supervisor replies (10-minute timeout) | The subagent is blocked, uncertain, needs approval, or faces a product/API/scope decision |
+| `interview_request` | Sends structured questions and blocks until the supervisor replies | The subagent needs multiple machine-readable answers from the supervisor in one exchange |
+| `progress_update` | Fire-and-forget update to the supervisor | Meaningful progress or unexpected discoveries that change the plan |
+
+Do not use `contact_supervisor` for routine completion handoffs. Return the final subagent result normally through `pi-subagents`.
+
+### Example: Blocked Subagent Asks for Guidance
+
+```typescript
+contact_supervisor({
+  reason: "need_decision",
+  message: "The auth service returns 403 instead of 401 for expired tokens. Should I treat 403 as a re-auth trigger or a hard failure?"
+})
+// → Reply from supervisor: Treat 403 as re-auth trigger. Update the token refresh logic.
+```
+
+### Example: Structured Supervisor Interview
+
+```typescript
+contact_supervisor({
+  reason: "interview_request",
+  message: "Please answer these before I continue the migration.",
+  interview: {
+    title: "API migration choices",
+    questions: [
+      { id: "api", type: "single", question: "Which API should I target?", options: ["Stable API", "Experimental API"] },
+      { id: "constraints", type: "text", question: "What constraints should I preserve?" }
+    ]
+  }
+})
+// → Reply from supervisor: { "responses": [{ "id": "api", "value": "Stable API" }, ...] }
+```
+
+### Example: Progress Update
+
+```typescript
+contact_supervisor({
+  reason: "progress_update",
+  message: "Discovered the bug is in the retry wrapper, not the API client. Fixing the wrapper will also close issue #42."
+})
+// → Progress update sent to supervisor planner
+```
+
+### What the Supervisor Sees
+
+The supervisor receives a formatted message with run metadata:
+
+```
+**From subagent-worker-78f659a3-1**
+
+Subagent needs a supervisor decision.
+Run: 78f659a3
+Agent: worker
+Child index: 0
+
+Which API should I use?
+```
+
+Reply hints work the same as regular `intercom` ask/reply flows. The supervisor can reply with `intercom({ action: "reply", message: "..." })` and the subagent receives the answer as the tool result.
+
+For `interview_request`, the supervisor message includes the structured questions plus a fenced JSON answer example using this stable shape:
+
+```json
+{
+  "responses": [
+    { "id": "api", "value": "Stable API" },
+    { "id": "constraints", "value": "Keep the public error shape unchanged." }
+  ]
+}
+```
+
+The supervisor can reply with plain JSON or a fenced `json` block. If the reply matches the `{ "responses": [...] }` shape and references valid question ids/options, the child tool result includes it in `details.structuredReply` while still showing the raw reply text.
+
+## Tool Reference
+
+### intercom
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `action` | string | `"list"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, or `"status"` |
+| `to` | string | Target session name or ID (for send/ask, or to disambiguate reply) |
+| `message` | string | Message text (for send/ask/reply) |
+| `attachments` | array | Optional `file`, `snippet`, or `context` attachments |
+| `replyTo` | string | Optional message ID for threading or replying to an `ask` |
+
+### contact_supervisor
+
+Only registered in sessions where `pi-subagents` supplied the required child bridge metadata. Contacts the supervisor session that delegated the current task.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `reason` | string | `"need_decision"` (blocking), `"interview_request"` (blocking structured questions), or `"progress_update"` (fire-and-forget) |
+| `message` | string | The decision request, optional interview note, or progress update |
+| `interview` | object | Required for `interview_request`: `{ title?, description?, questions: [...] }` |
+
+**`need_decision`** — Sends a formatted ask to the supervisor and blocks until it replies (10-minute timeout). The reply comes back as the tool result. Includes run metadata in the message so the supervisor knows which subagent is asking.
+
+**`interview_request`** — Sends a formatted, agent-readable interview to the supervisor and blocks until it replies. Questions use a local pi-interview-like shape: `{ id, type, question, options?, context? }` where `type` is `single`, `multi`, `text`, `image`, or `info`. `info` questions are context-only and do not need responses. The supervisor reply should be JSON with `{ "responses": [{ "id": "...", "value": ... }] }`. Parsed JSON replies are returned in `details.structuredReply`.
+
+**`progress_update`** — Sends a non-blocking update to the supervisor. Returns immediately after delivery. Use only for meaningful progress or unexpected discoveries that change the plan.
+
+### intercom actions
+
+**`list`** — Returns the current session plus other active intercom-connected sessions with name, short ID, working directory, model, and live status. Status is derived automatically from Pi lifecycle events: `idle`, `thinking`, or `tool:<name>`.
+
+**`send`** — Sends a message to the specified session. By default it sends immediately, including in interactive sessions. Set `confirmSend: true` in config if you want a confirmation dialog for non-reply sends. Replies that include `replyTo` skip confirmation. Returns delivery confirmation.
+
+**`ask`** — Sends a message and waits for the recipient to reply (10-minute timeout). The reply is returned as the tool result. No confirmation dialog. Only one pending `ask` is allowed per session at a time. Use this when the agent needs the answer to continue working.
+
+**`reply`** — Replies to the current intercom-triggered message if there is one. Otherwise it falls back to the single unresolved inbound ask. If multiple asks are pending, pass `to` or inspect them with `pending` first. Under the hood this is still a normal `send` with the exact `replyTo` value.
+
+**`pending`** — Lists unresolved inbound asks with sender, message ID, elapsed time, and a short preview. Useful when replying after the original triggered turn.
+
+**`status`** — Shows connection status, session ID, and total count of active sessions (including the current session).
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| Alt+M | Open session list overlay |
+| ↑/↓ | Navigate session list |
+| Enter | Select session / Send message |
+| Escape | Cancel / Close overlay |
+
+## Config
+
+Create `~/.pi/agent/intercom/config.json`:
+
+```json
+{
+  "brokerCommand": "npx",
+  "brokerArgs": ["--no-install", "tsx"],
+  "confirmSend": false,
+  "enabled": true,
+  "replyHint": true,
+  "status": "researching"
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `brokerCommand` | `"npx"` | Command used to start the local broker process |
+| `brokerArgs` | `["--no-install", "tsx"]` | Arguments passed to `brokerCommand` before the broker script path |
+| `confirmSend` | false | Show a confirmation dialog before non-reply sends from an interactive session with UI |
+| `enabled` | true | Enable/disable intercom entirely |
+| `replyHint` | true | Include reply instruction in incoming messages |
+| `status` | — | Optional custom status suffix shown after the automatic lifecycle status, for example `thinking · researching` |
+
+For example, if you have Bun installed and want it to start the broker directly, use:
+
+```json
+{
+  "brokerCommand": "bun",
+  "brokerArgs": []
+}
+```
+
+Pi-intercom publishes live session status automatically. Sessions register as `idle`, switch to `thinking` while the agent is running, show `tool:<name>` during tool execution, and return to `idle` on agent completion. If `status` is set in config, it is appended as context instead of replacing the lifecycle status.
+
+## How It Works
+
+```mermaid
+graph TB
+    subgraph A["Pi Session A"]
+        A1[Intercom Client]
+        A2[intercom tool]
+        A3[UI overlays]
+    end
+
+    subgraph Broker["Intercom Broker"]
+        B1[Session Registry]
+        B2[Message Router]
+    end
+
+    subgraph B["Pi Session B"]
+        B3[Intercom Client]
+        B4[intercom tool]
+        B5[UI overlays]
+    end
+
+    A1 <-->|Local Socket/Pipe| B1
+    B1 --- B2
+    B2 <-->|Local Socket/Pipe| B3
+```
+
+The broker is a standalone TypeScript process that manages session registration and message routing. It auto-spawns when the first intercom-enabled session needs it and exits after 5 seconds when the last connected session disconnects. Clients now reconnect automatically if the broker disappears and later comes back.
+
+Messages use length-prefixed JSON over a local socket/pipe transport (4-byte length + JSON payload) to handle fragmentation properly. The protocol includes request correlation for session listing, explicit delivery failures, and validation for malformed or out-of-order messages.
+
+Async extension work (startup, inbound flushes, reconnects, overlays, and relays) no-ops if the session shuts down or reloads before it settles.
+
+Runtime files live at `~/.pi/agent/intercom/`:
+- `broker.sock` — Unix domain socket for communication (macOS/Linux only; Windows uses a named pipe instead)
+- `broker-launch.vbs` — Windows helper script used to launch the broker without a console window
+- `broker.pid` — Broker process ID
+- `config.json` — User configuration
+
+## Design Decisions
+
+**Local IPC instead of TCP.** Same-machine only by design. `pi-intercom` uses Unix sockets on macOS/Linux and a named pipe on Windows, which keeps setup simple and avoids port management.
+
+**Auto-spawn with file lock.** The broker starts on first connection and exits after 5 seconds idle. There is no daemon to manage. A spawn lock file, keyed by PID and timestamp, prevents duplicate brokers when multiple sessions start at once.
+
+**`ask` stays client-side.** The broker still routes plain messages; it does not have a special request/response mode for `ask`. The client waits for a matching reply before it triggers a new turn, then returns that reply as the tool result. Reply hints make that flow practical by showing the recipient the exact `send` call to use. Separately, `list` / `sessions` now carry a `requestId` so a delayed session-list reply cannot be mistaken for a newer one.
+
+## pi-intercom vs pi-messenger
+
+| Aspect | pi-intercom | pi-messenger |
+|--------|-------------|--------------|
+| **Model** | Direct 1:1 messaging | Shared chat room |
+| **Primary use** | User orchestrating sessions | Autonomous agent coordination |
+| **Discovery** | Broker-based (real-time) | File-based registry |
+| **Messages** | Private, session-to-session | Broadcast to all agents |
+| **Persistence** | In Pi session history | Shared coordination files |
+
+Use pi-messenger for multi-agent swarms working on a shared task. Use pi-intercom when you want to manually coordinate your own sessions or have one agent reach out to another specific session.
+
+## File Structure
+
+```
+~/.pi/agent/extensions/pi-intercom/
+├── package.json
+├── index.ts              # Extension entry point
+├── types.ts              # SessionInfo, Message, protocol types
+├── config.ts             # Config loading
+├── broker/
+│   ├── broker.ts         # Broker process
+│   ├── client.ts         # IntercomClient class
+│   ├── framing.ts        # Length-prefixed JSON protocol
+│   ├── paths.ts          # Platform-specific socket/pipe paths
+│   ├── spawn.ts          # Auto-spawn logic with lock file
+│   ├── spawn.test.ts     # Broker spawn tests
+│   └── paths.test.ts     # Path resolution tests
+├── ui/
+│   ├── session-list.ts   # Session selection overlay
+│   ├── compose.ts        # Message composition overlay
+│   └── inline-message.ts # Received message display
+└── skills/
+    └── pi-intercom/
+        └── SKILL.md      # Bundled skill for common patterns
+```
+
+## Limitations
+
+- **Same machine only** — Uses local sockets/pipes, no network support
+- **No dedicated intercom log** — Messages are kept in Pi session history, but there is no separate intercom transcript or inbox
+- **No attachments UI** — `file`, `snippet`, and `context` attachments are supported in the protocol, but not in the compose overlay
+- **Only connected sessions appear** — The list shows Pi sessions that have loaded `pi-intercom` and successfully registered with the broker, not every open Pi process on the machine
+- **Broker lifecycle** — The broker auto-spawns on first use and exits when idle; sessions reconnect automatically if the broker restarts