pi-gang 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lachlan Jacobs
+
+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/NOTICE

@@ -0,0 +1,15 @@
+gang
+Copyright (c) 2026 Lachlan Jacobs
+
+This product vendors and modifies source from pi-intercom, used under the MIT License:
+
+  pi-intercom
+  Copyright (c) 2026 Nico Bailon
+  https://github.com/nicobailon/pi-intercom
+
+The vendored source lives under src/intercom/. It has been modified: peer-dependency
+imports retargeted from @mariozechner/* to @earendil-works/*, a broker message tap and
+an embedded mission-control HTTP/SSE server added.
+
+gang targets the Pi coding agent (@earendil-works/pi-coding-agent, originally authored by
+Mario Zechner as @mariozechner/pi-coding-agent).

package/README.md

@@ -0,0 +1,159 @@
+# gang
+
+<p align="center">
+  <img src="assets/gang-logo.png" alt="gang mission-control crew logo" width="260">
+</p>
+
+A minimal, **observable** subagent primitive for [Pi](https://github.com/earendil-works). Fire up
+subagents as **visible tmux panes** you watch live, let them talk over a **cross-agent message
+bus**, and observe everything three ways: live panes, a durable log, and a mission-control view —
+in your terminal (a Pi overlay) **and** in the browser.
+
+Built on a vendored, fully-owned copy of [pi-intercom](https://github.com/nicobailon/pi-intercom)
+(MIT). No external `pi-intercom` runtime dependency; npm deps install with the package.
+Targets `@earendil-works` Pi **0.80.x** (supported range: `>=0.80.2 <0.81.0`).
+
+```
+┌─ tmux panes ──────────────┐   raw per-agent view — watch each member's pi session
+│  superintendent │ worker        │
+│           │ reviewer      │
+└───────────┴───────────────┘
+        │ intercom (unix socket: ~/.pi/agent/intercom/broker.sock)
+        ▼
+┌─ owned broker (vendored) ────────────────────┐
+│  • routes messages                            │
+│  • TAP  → ~/.pi/agent/intercom/intercom.jsonl │  durable, greppable, replayable
+│  • HTTP + SSE :7717  ─────────────────────────┼─► mission control:  /gang watch  (in Pi)
+└───────────────────────────────────────────────┘                     127.0.0.1:7717 (browser)
+```
+
+## Requirements
+
+- **Pi** (`@earendil-works/pi-coding-agent`) 0.80.x, ≥ 0.80.2 — `pi --version`
+- **tmux** — members run as visible panes (`brew install tmux`)
+- **Node** ≥ 22
+
+## Install
+
+### Option A — from npm (recommended)
+
+```sh
+pi install pi-gang
+pi list                                           # verify: should list  gang
+```
+
+### Option B — from GitHub
+
+Pi packages run local extension code with your user permissions, so review the source before
+installing. Pi installs the package's runtime dependencies for you on a git install:
+
+```sh
+pi install https://github.com/Jeecabs/gang.git
+pi list                                           # verify: should list  gang
+```
+
+SSH also works if your GitHub account is configured for it:
+`pi install ssh://git@github.com/Jeecabs/gang.git`
+
+### Option C — local clone (to hack on it)
+
+```sh
+git clone git@github.com:Jeecabs/gang.git
+cd gang
+npm install                                       # REQUIRED — the broker + GUI run from node_modules
+pi install .                                       # persistent: registers it in your Pi settings
+# …or load it for a single session without touching settings:
+pi -e ./src/intercom/index.ts -e ./src/gang/index.ts
+```
+
+> ⚠️ A **local** install (`pi install .`) references the folder **in place** and does **not** run
+> `npm install` for you — so run it yourself, and don't move or delete the folder (the broker
+> launches from its `node_modules`). A git/npm install handles deps automatically.
+
+Unsure about Pi extensions in general? Pi documents itself — just ask it:
+`pi -p "how do I write and install a Pi extension?"`
+
+## Use
+
+In any Pi session, ask for a member — or call the tool yourself. The session adopts the **`superintendent`**
+identity the first time you spawn (not before), so sessions where you never use gang keep their
+natural title in `pi -r`:
+
+```
+/gang spawn list the repo's largest files
+/gang spawn @reviewer -t high review the diff carefully
+```
+
+`gang spawn` returns immediately and opens a tmux pane. The member does the task in its own Pi
+session and sends the result **back to superintendent as an intercom message** (it does not return inline).
+Keep working; handle the result when it arrives.
+
+Watch the gang three ways:
+
+```sh
+# 1. in Pi — live mission-control overlay (members + status + feed)
+/gang watch            # or press  alt+g
+
+# 2. in the browser — the same feed, richer
+/gang url              # prints computed loopback URL from GANG_GUI_PORT
+open http://127.0.0.1:7717
+
+# 3. durable, greppable log of every cross-agent message
+tail -f ~/.pi/agent/intercom/intercom.jsonl
+```
+
+## Commands & tools
+
+| Surface | What |
+|---|---|
+| `gang` tool | `{action:"spawn", task, role?, thinking?}` · `{action:"list"}` · `{action:"clean", force?, all?}` · `{action:"stop", role? finished?}` · `{action:"name", name}` — model-callable |
+| `/gang` | show the roster |
+| `/gang spawn [@name] [-t <level>] <task>` | spawn a member by hand; name optional (auto `m1`, `m2`, …). Levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `/gang clean` · `/gang clean --force` · `/gang clean all` | `clean` reaps dead/missing panes and prunes stale roster entries; `clean --force` also kills members that already reported back; `clean all` stops this superintendent's members (detached mode kills the `gang` session; in-tmux mode kills direct member panes only) |
+| `/gang stop <member>` · `/gang stop --all-finished` | stop one member immediately, or bulk-stop any member already reapable (`reported_done`, `pane_dead`, `pane_missing`) |
+| `/gang url` | show the browser mission-control URL (`http://127.0.0.1:<GANG_GUI_PORT>`) |
+| `/gang name [name]` | show or set this agent/session's own name |
+| `/gang watch` · `alt+g` | open mission control (in-Pi overlay) |
+| `intercom` tool | message any session: `list` / `send` / `ask` / `reply` |
+
+Env knobs: `GANG_GUI_PORT` (default `7717`), `GANG_TMUX_BIN` (default Homebrew tmux), `GANG_FEED_HOURS` (mission-control feed recency window, default `6`).
+
+Finished members linger on purpose — their panes stay (`remain-on-exit on`) so you can read the final state. Reap them when you're done with `/gang clean` (or `gang({ action: "clean" })`). If a member has already reported back but its pane is still hanging around, use `/gang clean --force` or `/gang stop --all-finished`. `/gang stop <member>` is the first-class escape hatch when you know a specific pane should die. `/gang clean all` tears down the detached `gang` session outside tmux; inside tmux it kills this superintendent's direct member panes only.
+
+Agent naming: an unnamed orchestrator session claims `superintendent of <current-folder>` (e.g. `superintendent of private-evals`) **on its first spawn**, not at startup — so plain Pi sessions stay unnamed in the `pi -r` resume list. Use `/gang name <name>` before spawning to pick a custom target; spawned members get that exact supervisor name. Member task prompts also tell agents to name themselves with `gang({ action: "name", name: "<clear role/name>" })` before spinning up their own teammate.
+
+## How it's wired
+
+`package.json` → `pi.extensions` points Pi at two TypeScript entry files it loads on startup:
+
+- `src/intercom/` — vendored pi-intercom: the broker, client, and the `intercom` /
+  `contact_supervisor` tools. **Owned** — imports retargeted to `@earendil-works/*`, plus a broker
+  message **tap** (durable log) and an embedded **HTTP/SSE** mission-control server.
+- `src/gang/` — the `gang` tool (spawn members in tmux, list the roster), the `/gang watch`
+  overlay, and superintendent auto-naming.
+
+`gang spawn <task>` (optionally `@name`) launches `pi --name <name> … @<taskfile>` in a tmux pane with five
+`PI_SUBAGENT_*` env vars. Pass `--thinking <level>` to add Pi's `--thinking` flag for that member.
+The vendored intercom extension reads the env vars at child startup to register
+the member on the bus and unlock its `contact_supervisor` tool — that's the whole contract:
+
+| Env var | Set to | Effect |
+|---|---|---|
+| `PI_SUBAGENT_INTERCOM_SESSION_NAME` | `<role>` | member's intercom identity |
+| `PI_SUBAGENT_ORCHESTRATOR_TARGET` | current supervisor name (`superintendent of <folder>` or custom `/gang name`) | who it reports to |
+| `PI_SUBAGENT_RUN_ID` / `_CHILD_AGENT` / `_CHILD_INDEX` | run metadata | unlocks `contact_supervisor` |
+
+(The member's addressable **name** comes from Pi's `--name` flag; the supervisor self-names
+lazily to the computed or custom `orchestratorName`.)
+
+## Develop
+
+```sh
+npm test             # vendored intercom suite + gang/tmux/tap/GUI/overlay tests
+npm run typecheck    # strict TypeScript check
+```
+
+## Credits
+
+Vendors [pi-intercom](https://github.com/nicobailon/pi-intercom) by Nico Bailon (MIT). See `NOTICE`.
+Built on Pi by the [earendil-works](https://github.com/earendil-works) team.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "pi-gang",
+  "version": "0.1.0",
+  "description": "Minimal, observable subagent primitive for Pi — visible tmux members, cross-agent intercom, and a mission-control GUI.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "assets",
+    "src/**/*.ts",
+    "src/**/*.html",
+    "src/**/SKILL.md",
+    "!src/**/*.test.ts",
+    "!src/**/test/**",
+    "NOTICE"
+  ],
+  "scripts": {
+    "test": "tsx --test \"src/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "pi": {
+    "extensions": [
+      "./src/intercom/index.ts",
+      "./src/gang/index.ts"
+    ],
+    "skills": [
+      "./src/intercom/skills"
+    ]
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.2 <0.81.0",
+    "@earendil-works/pi-tui": ">=0.80.2 <0.81.0",
+    "typebox": ">=1.1.38 <2"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@earendil-works/pi-tui": "^0.80.6",
+    "@types/node": "^22.20.1",
+    "typebox": "^1.3.6",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "tsx": "^4.23.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jeecabs/gang.git"
+  },
+  "author": "Lachlan Jacobs",
+  "bugs": {
+    "url": "https://github.com/Jeecabs/gang/issues"
+  },
+  "homepage": "https://github.com/Jeecabs/gang#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/gang/events.ts

@@ -0,0 +1,11 @@
+export const SUPERINTENDENT_NAMED_EVENT = "gang:superintendent-named";
+export const GANG_MEMBER_REPORT_EVENT = "gang:member-report";
+
+export interface GangMemberReportEvent {
+  fromId: string;
+  fromName?: string;
+  text: string;
+  timestamp: number;
+  expectsReply: boolean;
+  replyTo?: string;
+}

package/src/gang/feed-client.ts

@@ -0,0 +1,88 @@
+import http from "http";
+import { EventEmitter } from "events";
+import { GUI_PORT } from "../intercom/gui/server.js";
+
+/** A parsed event from the broker's SSE feed (same stream the browser dashboard consumes). */
+export interface FeedEvent {
+  type: "snapshot" | "session_joined" | "session_left" | "presence_update" | "message";
+  [key: string]: unknown;
+}
+
+/**
+ * Consumes the broker's `/events` SSE stream in-process so the in-pi overlay renders the exact
+ * same feed as the browser GUI. Reconnects if the broker restarts. Emits:
+ *   "event"  (FeedEvent)        — each parsed feed event
+ *   "status" ("up" | "down")    — connection state for the overlay's live indicator
+ */
+export class FeedClient extends EventEmitter {
+  private req?: http.ClientRequest;
+  private reconnectTimer?: NodeJS.Timeout;
+  private buf = "";
+  private stopped = false;
+
+  constructor(private readonly port: number = GUI_PORT) {
+    super();
+  }
+
+  start(): this {
+    this.connect();
+    return this;
+  }
+
+  private connect(): void {
+    if (this.stopped) return;
+    this.req = http.get({ host: "127.0.0.1", port: this.port, path: "/events" }, (res) => {
+      if (res.statusCode !== 200) {
+        res.destroy();
+        this.scheduleReconnect();
+        return;
+      }
+      this.clearReconnectTimer();
+      this.emit("status", "up");
+      res.setEncoding("utf8");
+      res.on("data", (chunk: string) => this.onData(chunk));
+      res.on("close", () => this.scheduleReconnect());
+    });
+    this.req.on("error", () => this.scheduleReconnect());
+  }
+
+  /** Parse SSE frames (separated by blank lines); ignore comment/keepalive lines. */
+  private onData(chunk: string): void {
+    this.buf += chunk;
+    let idx: number;
+    while ((idx = this.buf.indexOf("\n\n")) !== -1) {
+      const frame = this.buf.slice(0, idx);
+      this.buf = this.buf.slice(idx + 2);
+      const dataLine = frame.split("\n").find((l) => l.startsWith("data: "));
+      if (!dataLine) continue;
+      try {
+        this.emit("event", JSON.parse(dataLine.slice(6)) as FeedEvent);
+      } catch {
+        // ignore malformed frame
+      }
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.stopped || this.reconnectTimer) return;
+    this.emit("status", "down");
+    this.buf = "";
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      this.connect();
+    }, 1000);
+  }
+
+  private clearReconnectTimer(): void {
+    if (!this.reconnectTimer) return;
+    clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = undefined;
+  }
+
+  stop(): void {
+    this.stopped = true;
+    this.clearReconnectTimer();
+    this.req?.destroy();
+    this.removeAllListeners();
+  }
+}