{"_id":"@aryanbhargav/pi-orch-cmux","name":"@aryanbhargav/pi-orch-cmux","dist-tags":{"latest":"0.4.1"},"versions":{"0.4.1":{"name":"@aryanbhargav/pi-orch-cmux","version":"0.4.1","description":"CMUX-native peer-to-peer Pi agent mesh extension","type":"module","license":"MIT","author":{"name":"Aryan Bhargav"},"keywords":["pi-package","pi-extension","pi-coding-agent","cmux","agent-to-agent","peer-to-peer","multi-agent","orch"],"scripts":{"check":"bun build extensions/orch-cmux.ts --target=node --outfile /tmp/pi-orch-cmux-check.js --external @earendil-works/pi-coding-agent --external @earendil-works/pi-tui --external @sinclair/typebox","pack:dry":"npm pack --dry-run"},"publishConfig":{"access":"public"},"pi":{"extensions":["./extensions/orch-cmux.ts"]},"dependencies":{"@sinclair/typebox":"^0.34.41"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*"},"peerDependenciesMeta":{"@earendil-works/pi-coding-agent":{"optional":true},"@earendil-works/pi-tui":{"optional":true}},"_id":"@aryanbhargav/pi-orch-cmux@0.4.1","_nodeVersion":"24.14.1","_npmVersion":"11.12.1","dist":{"integrity":"sha512-AwZeih5n0hTBSVxMOXFOmH8XpV+n+hIdLDYFpu0Gs4+bq5kbNyYkcpGo7oGMdJvLApnBifBsz/TiPpMABnizKQ==","shasum":"7849d607426d6411009be7fb5319b32ea63757c2","tarball":"https://registry.npmjs.org/@aryanbhargav/pi-orch-cmux/-/pi-orch-cmux-0.4.1.tgz","fileCount":4,"unpackedSize":78323,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDOPCtW77RdhVQjgqjGr3MzJVgj68uw3viJrwNiYQnaQQIhAIff/MxoTM0679RR+rcDqtWlOC5/p+aUSuV+43UcPEqZ"}]},"_npmUser":{"name":"aryanbhargav","email":"hey@aryanbhargav.com"},"directories":{},"maintainers":[{"name":"aryanbhargav","email":"hey@aryanbhargav.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-orch-cmux_0.4.1_1779443906332_0.11617860478148279"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-22T09:58:26.166Z","0.4.1":"2026-05-22T09:58:26.468Z","modified":"2026-05-22T09:58:26.689Z"},"maintainers":[{"name":"aryanbhargav","email":"hey@aryanbhargav.com"}],"description":"CMUX-native peer-to-peer Pi agent mesh extension","keywords":["pi-package","pi-extension","pi-coding-agent","cmux","agent-to-agent","peer-to-peer","multi-agent","orch"],"author":{"name":"Aryan Bhargav"},"license":"MIT","readme":"# ORCH Agents Extension\n\nCMUX-native peer-to-peer Pi agent communication.\n\nThis is **not** an orchestrator/sub-agent extension. Every Pi instance that loads the extension is an independent peer in the current CMUX workspace. Peers can discover each other, keep persistent logical connections, message each other, wait for replies, and spawn missing peers as visible CMUX splits.\n\n## Install / run\n\n### From npm\n\nAfter publishing:\n\n```bash\npi install npm:@aryanbhargav/pi-orch-cmux\n```\n\nOr try it for one session without installing:\n\n```bash\npi -e npm:@aryanbhargav/pi-orch-cmux\n```\n\nIf your npm scope is different, change the `name` field in `package.json` before publishing.\n\n### From a local checkout\n\nFrom this directory:\n\n```bash\npi -e extensions/orch-cmux.ts\n```\n\nOr install the local package into Pi from inside this directory:\n\n```bash\npi install .\n```\n\nFrom the parent repo root, use:\n\n```bash\npi install ./ORCH-Agents-extension\n```\n\nNamed peer example:\n\n```bash\npi -e extensions/orch-cmux.ts \\\n  --orch-name planner \\\n  --orch-role planner \\\n  --orch-purpose \"Plans work and asks peers for implementation/review help\"\n```\n\n## Mental model\n\n```txt\nplanner  ↔  coder\n   ↕          ↕\nreviewer ↔  tester\n```\n\nNot:\n\n```txt\norchestrator\n  ├── coder\n  └── reviewer\n```\n\nThe first/default agent can bootstrap the mesh, but it does not own the other agents.\n\n## Transport\n\nNo HTTP/SSE server. No Bun hub. No sockets.\n\nThe extension uses:\n\n- CMUX identity: workspace, pane, and surface refs\n- CMUX split creation for visible peer spawning\n- Local mailbox files for reliable prompt/response exchange\n- Background registry heartbeat for persistent peer connections\n\nDefault state directory:\n\n```txt\n~/.pi/orch-cmux/workspaces/<workspace-key>/\n  peers/                 # live peer registry\n  inbox/<session-id>/    # inbound prompt envelopes\n  responses/<session-id>/# response envelopes\n```\n\n## Footer\n\nThe extension replaces Pi's default footer with a compact ORCH footer:\n\n```txt\n@coder · gpt-5.5 · think:high                       [#####-------] 42%\n```\n\nSpawned peers display their own `@name` because `orch_spawn_peer` launches them with `--orch-name`, `--orch-role`, and `--orch-purpose`.\n\n## Tools\n\n### `orch_peers`\n\nDiagnostics view of connected peers. The model should not call this before every send because `orch_send` uses the persistent peer cache internally.\n\n### `orch_spawn_peer`\n\nCreates a CMUX split and launches another Pi peer with this same extension.\n\nIf `model` is omitted, ORCH uses the configured model default for that peer's role/name. If no default exists and Pi is interactive, ORCH asks which model to use. In non-interactive mode, it falls back to the current model.\n\nExample target shape:\n\n```json\n{\n  \"name\": \"coder\",\n  \"role\": \"coder\",\n  \"purpose\": \"Writes code\",\n  \"direction\": \"right\"\n}\n```\n\n### `orch_send`\n\nSends a task/prompt to a peer.\n\nIf the peer is missing and you want it created, set:\n\n```json\n{\n  \"create_if_missing\": true\n}\n```\n\nOptional:\n\n```json\n{\n  \"await_response\": true\n}\n```\n\n### `orch_get`\n\nNon-blocking poll for a response by `msg_id`.\n\n### `orch_await`\n\nBlock until the response arrives or the timeout fires.\n\n## Footer UI\n\nORCH replaces Pi's default footer with a compact CMUX-style status line:\n\n- left side: model name, thinking level, and context usage, e.g. `gpt-5.5 · think:xhigh · 12.4k/200k 6%`\n- default/main agent badge: live peer count, e.g. `3 live agents`\n- spawned peer badge: peer identity, e.g. `@coder`\n\nThe old expanded mesh widget is hidden by default to keep the editor clean. If you want it back for debugging:\n\n```bash\nORCH_CMUX_SHOW_PEER_WIDGET=1 pi -e npm:@aryanbhargav/pi-orch-cmux\n```\n\n## Slash commands\n\n### `/orch`\n\nStatus and diagnostics:\n\n```txt\n/orch\n/orch refresh\n/orch whoami\n```\n\n### `/orch-model-default`\n\nConfigure default models for spawned peer roles/names:\n\n```txt\n/orch-model-default\n/orch-model-default list\n/orch-model-default set coder deepseek/deepseek-v4-pro\n/orch-model-default set reviewer kimi/kimi-k2.6\n/orch-model-default set planner openai-codex/gpt-5.5\n/orch-model-default clear coder\n```\n\nDefaults are stored at:\n\n```txt\n~/.pi/orch-cmux/model-defaults.json\n```\n\nLookup order when spawning is:\n\n1. explicit `model` argument\n2. role default, e.g. `coder`\n3. name default, e.g. `CodingRiver`\n4. wildcard default `*`\n5. interactive prompt\n6. current model fallback in non-interactive mode\n\n## Flags\n\nAll flags are namespaced to avoid extension collisions:\n\n| Flag | Description |\n| --- | --- |\n| `--orch-name` | Peer name. Defaults to `default` with collision suffixing. |\n| `--orch-role` | Role/persona, e.g. `planner`, `coder`, `reviewer`. |\n| `--orch-purpose` | Human-readable purpose. |\n| `--orch-project` | Registry namespace. Defaults to current CMUX workspace. |\n| `--orch-color` | Hex color for widgets. |\n| `--orch-explicit` | Hide from broad discovery; exact addressing still works. |\n\n## Example workflow\n\nUser tells the default peer:\n\n> Send this task to coder agent: implement the login form.\n\nExpected tool flow:\n\n```txt\norch_send target=\"coder\" create_if_missing=true prompt=\"Implement the login form...\"\n```\n\nIf no `coder` exists, the extension:\n\n1. Checks the configured model default for `coder`; if none exists, asks which model to use.\n2. Creates a new CMUX split with focus disabled.\n3. Launches Pi in that split with `--orch-name coder`.\n4. Waits for `coder` to register.\n5. Sends the prompt to `coder` through the local mailbox.\n6. `coder` receives an ORCH inbound message and replies normally.\n7. `coder`'s final assistant message is automatically written back as the response.\n8. The sender can use `orch_await`/`orch_get`, or `orch_send` can wait directly with `await_response=true`.\n\n## Safety / loop rules\n\n- Inbound messages tell the receiving agent to reply normally.\n- The receiver should not call `orch_send` back to the original sender as a reply.\n- The extension auto-returns the final assistant message at `agent_end`.\n- `orch_send` increments hop count when forwarding from an inbound turn.\n- `ORCH_CMUX_MAX_HOPS` defaults to `5` to limit ping-pong chains.\n\n## Publishing\n\nThis directory is a Pi package. The package manifest is in `package.json`:\n\n```json\n{\n  \"keywords\": [\"pi-package\"],\n  \"pi\": {\n    \"extensions\": [\"./extensions/orch-cmux.ts\"]\n  }\n}\n```\n\nBefore publishing:\n\n```bash\ncd ORCH-Agents-extension\nnpm run check\nnpm pack --dry-run\nnpm publish\n```\n\nFor a scoped package, `publishConfig.access` is already set to `public`.\n\n## Environment variables\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `ORCH_CMUX_DIR` | `~/.pi/orch-cmux` | Registry/mailbox root. |\n| `ORCH_CMUX_HEARTBEAT_MS` | `10000` | Peer heartbeat interval. |\n| `ORCH_CMUX_REFRESH_MS` | `3000` | Peer cache refresh interval. |\n| `ORCH_CMUX_INBOX_SCAN_MS` | `1000` | Inbox polling interval. |\n| `ORCH_CMUX_TIMEOUT_MS` | `1800000` | Default await timeout. |\n| `ORCH_CMUX_MAX_HOPS` | `5` | Forwarding hop limit. |\n","readmeFilename":"README.md","_rev":"1-0880e6fa3eec473ab861b824b4b0d5a6"}