pi-link 0.1.0 → 0.1.2

package/README.md

@@ -49,12 +49,6 @@ A single Pi terminal is powerful. Multiple terminals working together unlock new
 pi install npm:pi-link
 ```
 
-or from source:
-
-```bash
-pi install https://github.com/alvivar/pi-link
-```
-
 ### Uninstall
 
 ```bash
@@ -89,7 +83,9 @@ Here's a concrete example of two terminals collaborating. Open two separate `pi
 ✓ Renamed to "builder"
 
 > /link
-⚡ Link: "builder" (hub) · 2 terminals online: builder, researcher
+⚡ Link: builder (hub) · 2 online
+  builder: idle (5s)
+  researcher: idle (12s)
 ```
 
 **Terminal 2** — rename it too:
@@ -128,11 +124,11 @@ Every other terminal sees:
 
 Link is **off by default**. Without `--link`, the extension is completely silent — no status bar, no connections, no warnings.
 
-| Method              | When                                | Auto-reconnect? |
-| ------------------- | ----------------------------------- | --- |
-| `pi --link`         | Auto-connect on startup             | Yes |
-| `/link-connect`     | Opt-in mid-session (no flag needed) | Yes |
-| `/link-disconnect`  | Opt-out mid-session                 | Suppressed until `/link-connect` |
+| Method             | When                                | Auto-reconnect?                  |
+| ------------------ | ----------------------------------- | -------------------------------- |
+| `pi --link`        | Auto-connect on startup             | Yes                              |
+| `/link-connect`    | Opt-in mid-session (no flag needed) | Yes                              |
+| `/link-disconnect` | Opt-out mid-session                 | Suppressed until `/link-connect` |
 
 `/link-connect` enables full participation in Pi Link regardless of whether `--link` was passed. `/link-disconnect` always wins — even over `--link` — until you explicitly `/link-connect` again.
 
@@ -146,11 +142,11 @@ The extension registers three tools that the LLM can invoke during agent runs.
 
 ### Which tool should I use?
 
-| Tool           | Behavior                                             | Returns                                  |
-| -------------- | ---------------------------------------------------- | ---------------------------------------- |
-| `link_send`    | Send a message; optionally trigger the remote LLM    | Send/delivery status only                |
-| `link_prompt`  | Run a prompt on a remote terminal and wait for reply | The remote terminal's assistant response |
-| `link_list`    | List currently connected terminals                   | Terminal directory with roles            |
+| Tool          | Behavior                                             | Returns                                  |
+| ------------- | ---------------------------------------------------- | ---------------------------------------- |
+| `link_send`   | Send a message; optionally trigger the remote LLM    | Send/delivery status only                |
+| `link_prompt` | Run a prompt on a remote terminal and wait for reply | The remote terminal's assistant response |
+| `link_list`   | List currently connected terminals                   | Terminal directory with roles and status |
 
 **If you need the other terminal's answer back, use `link_prompt`.** Use `link_send` to notify or steer without waiting.
 
@@ -188,34 +184,47 @@ Send a prompt to a remote terminal and **wait** for the LLM's response (synchron
 
 ### `link_list`
 
-Lists all connected terminals with role info and self-identification. Takes no parameters.
+Lists all connected terminals with role info, live agent status, and self-identification. Takes no parameters.
+
+Each terminal's status is derived automatically from Pi lifecycle events — agents can't set it manually. Three states:
+
+| Status            | Meaning                 |
+| ----------------- | ----------------------- |
+| `idle (2m)`       | Waiting for user input  |
+| `thinking (3s)`   | LLM is generating       |
+| `tool:bash (12s)` | Running a specific tool |
+
+Durations are computed at render time from a `since` timestamp — no timer traffic over the wire. Terminals that just joined with no status data yet render as blank, not fake idle.
 
 **Example output:**
 
 ```
-Connected terminals:
-  • pi-1 (you)
-  • pi-2
-  • pi-3
+link (hub) 3 terminal(s)
+  • builder@pi-link (you)  thinking (3s)
+  • reviewer@pi-link       idle (45s)
+  • docs@pi-link           tool:read (2s)
 ```
 
 ---
 
 ## Slash Commands
 
-| Command                  | Purpose                                                                                                   |
-| ------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `/link`                  | Show link status (name, role, online count)                                                               |
-| `/link-name [name]`      | Rename this terminal. With no argument, adopts the current Pi session name if available. Collision-safe.  |
-| `/link-broadcast <msg>`  | Broadcast a chat message to all other terminals                                                           |
-| `/link-connect`          | Connect to Pi Link (works anytime, with or without `--link`)                                              |
-| `/link-disconnect`       | Disconnect from Pi Link and suppress auto-reconnect (overrides `--link`)                                  |
+| Command                 | Purpose                                                                                                  |
+| ----------------------- | -------------------------------------------------------------------------------------------------------- |
+| `/link`                 | Show link status (name, role, online count, agent status per terminal)                                   |
+| `/link-name [name]`     | Rename this terminal. With no argument, adopts the current Pi session name if available. Collision-safe. |
+| `/link-broadcast <msg>` | Broadcast a chat message to all other terminals                                                          |
+| `/link-connect`         | Connect to Pi Link (works anytime, with or without `--link`)                                             |
+| `/link-disconnect`      | Disconnect from Pi Link and suppress auto-reconnect (overrides `--link`)                                 |
 
 ### Examples
 
 ```
 > /link
-⚡ Link: "builder" (hub) · 3 online: builder, worker-1, worker-2
+⚡ Link: builder (hub) · 3 online
+  builder: idle (12s)
+  worker-1: thinking (3s)
+  worker-2: tool:bash (5s)
 
 > /link-name orchestrator
 ✓ Renamed to "orchestrator"
@@ -339,7 +348,7 @@ When the hub goes down and a client promotes itself, terminal names and in-fligh
 
 | Package                         | Purpose                                          |
 | ------------------------------- | ------------------------------------------------ |
-| `@mariozechner/pi-coding-agent` | Pi SDK types (ExtensionAPI, ExtensionContext)     |
+| `@mariozechner/pi-coding-agent` | Pi SDK types (ExtensionAPI, ExtensionContext)    |
 | `@mariozechner/pi-tui`          | TUI Text widget for custom message rendering     |
 | `@sinclair/typebox`             | JSON Schema type definitions for tool parameters |
 
@@ -371,18 +380,19 @@ The `pi.extensions` field tells Pi which files to load as extensions. Here it po
 
 ### Protocol
 
-The wire protocol consists of **8 message types**, all serialized as JSON over WebSocket frames:
+The wire protocol consists of **9 message types**, all serialized as JSON over WebSocket frames:
 
-| Type              | Direction     | Purpose                                               |
-| ----------------- | ------------- | ----------------------------------------------------- |
-| `register`        | Client → Hub  | First message after connecting; requests a name       |
-| `welcome`         | Hub → Client  | Confirms assigned name (deduplicated) + terminal list |
-| `terminal_joined` | Hub → All     | Broadcast when a terminal joins                       |
-| `terminal_left`   | Hub → All     | Broadcast when a terminal disconnects                 |
-| `chat`            | Any → Any/All | Fire-and-forget message; optionally triggers LLM turn |
-| `prompt_request`  | Any → Any     | Request a remote terminal to execute a prompt         |
-| `prompt_response` | Any → Any     | Response carrying the remote prompt result            |
-| `error`           | Hub → Client  | Error notification                                    |
+| Type              | Direction       | Purpose                                                 |
+| ----------------- | --------------- | ------------------------------------------------------- |
+| `register`        | Client → Hub    | First message after connecting; requests a name         |
+| `welcome`         | Hub → Client    | Confirms assigned name, terminal list + status snapshot |
+| `terminal_joined` | Hub → All       | Broadcast when a terminal joins                         |
+| `terminal_left`   | Hub → All       | Broadcast when a terminal disconnects                   |
+| `chat`            | Any → Any/All   | Fire-and-forget message; optionally triggers LLM turn   |
+| `prompt_request`  | Any → Any       | Request a remote terminal to execute a prompt           |
+| `prompt_response` | Any → Any       | Response carrying the remote prompt result              |
+| `status_update`   | Any → Hub → All | Terminal broadcasts its agent status change             |
+| `error`           | Hub → Client    | Error notification                                      |
 
 ### Message Flow Examples
 
@@ -394,13 +404,13 @@ Client                         Hub
   | register {name:"builder"}   |
   |---------------------------->|
   |                             |
-  | welcome {name:"builder",    |
-  | terminals:["pi-1"]}         |
+  | welcome {name, terminals,   |
+  | statuses}                   |
   |<----------------------------|
   |                             |
 ```
 
-Hub then broadcasts `terminal_joined` to the other connected terminals.
+Hub then broadcasts `terminal_joined` to the other connected terminals. The `welcome` message includes a status snapshot for all connected terminals (fields omitted above for brevity).
 
 **Sending a chat message:**
 
@@ -445,13 +455,13 @@ Default names are random 4-character hex IDs: `t-a1b2`, `t-c3d4`, etc.
 
 ### State Management
 
-| State Field              | Type                                    | Purpose                                               |
-| ------------------------ | --------------------------------------- | ----------------------------------------------------- |
-| `role`                   | `"hub" \| "client" \| "disconnected"`   | Current network role                                  |
-| `isAgentBusy`            | `boolean`                               | Prevents accepting remote prompts during agent runs   |
-| `manuallyDisconnected`   | `boolean`                               | Set by `/link-disconnect`; suppresses auto-reconnect  |
-| `pendingRemotePrompt`    | `object \| null`                        | Tracks the single in-flight remote prompt execution   |
-| `pendingPromptResponses` | `Map`                                   | Outstanding prompt RPCs awaiting responses            |
+| State Field              | Type                                  | Purpose                                              |
+| ------------------------ | ------------------------------------- | ---------------------------------------------------- |
+| `role`                   | `"hub" \| "client" \| "disconnected"` | Current network role                                 |
+| `isAgentBusy`            | `boolean`                             | Prevents accepting remote prompts during agent runs  |
+| `manuallyDisconnected`   | `boolean`                             | Set by `/link-disconnect`; suppresses auto-reconnect |
+| `pendingRemotePrompt`    | `object \| null`                      | Tracks the single in-flight remote prompt execution  |
+| `pendingPromptResponses` | `Map`                                 | Outstanding prompt RPCs awaiting responses           |
 
 ### Message Routing & Error Handling
 
@@ -473,10 +483,14 @@ The `manuallyDisconnected` flag distinguishes user-initiated disconnects (`/link
 
 The extension hooks into Pi's agent lifecycle events:
 
-- **`agent_start`** → Sets `isAgentBusy = true`, blocking incoming remote prompts.
-- **`agent_end`** → Checks if a remote prompt was running. If so, extracts the last assistant response from `event.messages` and sends back a `prompt_response`.
+- **`agent_start`** → Sets `isAgentBusy = true`, blocking incoming remote prompts. Broadcasts `status_update` (`thinking`).
+- **`agent_end`** → Checks if a remote prompt was running. If so, extracts the last assistant response from `event.messages` and sends back a `prompt_response`. Broadcasts `status_update` (`idle`).
+- **`tool_execution_start`** → Broadcasts `status_update` (`tool:<name>`).
+- **`tool_execution_end`** → Clears tool status; broadcasts `status_update` (`thinking`) while the agent run continues.
 - **`session_shutdown`** → Full cleanup via `cleanup()`: closes all sockets, resolves pending promises, and disposes the extension.
 
+Status updates are push-based: each terminal broadcasts changes to the hub, which fans them out. New joiners receive a status snapshot for all terminals in the `welcome` message. Durations are computed at render time from a `since` timestamp — no polling or timer traffic over the wire.
+
 ### Rendering
 
 Incoming link chat messages render with a styled `⚡ [sender]` prefix using the theme's accent color. The link status text in Pi's footer uses `theme.fg("dim", ...)` to match Pi's standard footer styling.

package/index.ts

@@ -45,6 +45,7 @@ interface WelcomeMsg {
   type: "welcome";
   name: string;
   terminals: string[];
+  statuses?: Record<string, LinkStatus>;
 }
 interface TerminalJoinedMsg {
   type: "terminal_joined";
@@ -78,11 +79,21 @@ interface PromptResponseMsg {
   response: string;
   error?: string;
 }
+interface StatusUpdateMsg {
+  type: "status_update";
+  name: string;
+  status: LinkStatus;
+}
 interface ErrorMsg {
   type: "error";
   message: string;
 }
 
+type LinkStatus =
+  | { kind: "idle"; since: number }
+  | { kind: "thinking"; since: number }
+  | { kind: "tool"; toolName: string; since: number };
+
 type LinkMessage =
   | RegisterMsg
   | WelcomeMsg
@@ -91,6 +102,7 @@ type LinkMessage =
   | ChatMsg
   | PromptRequestMsg
   | PromptResponseMsg
+  | StatusUpdateMsg
   | ErrorMsg;
 
 // ─── Extension ───────────────────────────────────────────────────────────────
@@ -108,14 +120,22 @@ export default function (pi: ExtensionAPI) {
   let terminalName = `t-${crypto.randomUUID().slice(0, 4)}`;
   let connectedTerminals: string[] = [];
   let ctx: ExtensionContext | undefined;
-  let isAgentBusy = false;
   let disposed = false;
   let manuallyDisconnected = false;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
 
+  // Status tracking (local truth)
+  let agentRunning = false;
+  let activeToolName: string | null = null;
+  let stateSince = Date.now();
+  let lastPushedKind: string | null = null;
+  let lastPushedTool: string | null = null;
+  const terminalStatuses = new Map<string, LinkStatus>(); // other terminals
+
   // Hub state
   let wss: WebSocketServer | null = null;
   const hubClients = new Map<WebSocket, string>(); // ws → terminal name
+  const hubTerminalStatuses = new Map<string, LinkStatus>(); // hub-authoritative
 
   // Client state
   let ws: WebSocket | null = null;
@@ -148,6 +168,53 @@ export default function (pi: ExtensionAPI) {
     ctx.ui.setStatus("link", theme.fg("dim", info));
   }
 
+  function deriveStatus(): LinkStatus {
+    if (activeToolName)
+      return { kind: "tool", toolName: activeToolName, since: stateSince };
+    if (agentRunning) return { kind: "thinking", since: stateSince };
+    return { kind: "idle", since: stateSince };
+  }
+
+  function pushStatus(force = false) {
+    if (role === "disconnected") return;
+    const status = deriveStatus();
+    const newKind = status.kind;
+    const newTool = status.kind === "tool" ? status.toolName : null;
+    if (!force && newKind === lastPushedKind && newTool === lastPushedTool)
+      return;
+    lastPushedKind = newKind;
+    lastPushedTool = newTool;
+    const msg: StatusUpdateMsg = {
+      type: "status_update",
+      name: terminalName,
+      status,
+    };
+    if (role === "hub") {
+      hubBroadcast(msg, terminalName);
+    } else if (ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  }
+
+  function formatDuration(since: number): string {
+    const sec = Math.floor((Date.now() - since) / 1000);
+    if (sec < 60) return `${sec}s`;
+    if (sec < 3600) return `${Math.floor(sec / 60)}m`;
+    return `${Math.floor(sec / 3600)}h`;
+  }
+
+  function formatStatus(s: LinkStatus): string {
+    const dur = formatDuration(s.since);
+    if (s.kind === "tool") return `tool:${s.toolName} (${dur})`;
+    return `${s.kind} (${dur})`;
+  }
+
+  function getStatusFor(name: string): LinkStatus | null {
+    if (name === terminalName) return deriveStatus();
+    const map = role === "hub" ? hubTerminalStatuses : terminalStatuses;
+    return map.get(name) ?? null;
+  }
+
   function allTerminalNames(): Set<string> {
     const names = new Set<string>();
     names.add(terminalName); // hub's own name
@@ -257,11 +324,18 @@ export default function (pi: ExtensionAPI) {
       case "welcome":
         terminalName = msg.name;
         connectedTerminals = msg.terminals;
+        terminalStatuses.clear();
+        if (msg.statuses) {
+          for (const [name, status] of Object.entries(msg.statuses)) {
+            terminalStatuses.set(name, status);
+          }
+        }
         updateStatus();
         ctx?.ui.notify(
           `Joined link as "${terminalName}" (${connectedTerminals.length} online)`,
           "info",
         );
+        pushStatus(true);
         break;
 
       // ── Directory updates ──
@@ -273,10 +347,16 @@ export default function (pi: ExtensionAPI) {
 
       case "terminal_left":
         connectedTerminals = msg.terminals;
+        terminalStatuses.delete(msg.name);
         updateStatus();
         ctx?.ui.notify(`"${msg.name}" left the link`, "info");
         break;
 
+      // ── Status update from another terminal ──
+      case "status_update":
+        terminalStatuses.set(msg.name, msg.status);
+        break;
+
       // ── Chat message ──
       case "chat":
         pi.sendMessage(
@@ -292,7 +372,7 @@ export default function (pi: ExtensionAPI) {
 
       // ── Another terminal asks us to run a prompt ──
       case "prompt_request":
-        if (isAgentBusy || pendingRemotePrompt) {
+        if (agentRunning || pendingRemotePrompt) {
           routeMessage({
             type: "prompt_response",
             id: msg.id,
@@ -353,12 +433,18 @@ export default function (pi: ExtensionAPI) {
         connectedTerminals = list;
         updateStatus();
 
-        // Confirm to the new client
+        // Confirm to the new client (include status snapshot)
+        const statuses: Record<string, LinkStatus> = {};
+        statuses[terminalName] = deriveStatus(); // hub's own status
+        for (const [name, status] of hubTerminalStatuses) {
+          if (name !== clientName) statuses[name] = status;
+        }
         clientWs.send(
           JSON.stringify({
             type: "welcome",
             name: clientName,
             terminals: list,
+            statuses,
           } satisfies WelcomeMsg),
         );
 
@@ -375,6 +461,21 @@ export default function (pi: ExtensionAPI) {
       // Ignore messages from unregistered clients
       if (!clientName) return;
 
+      // Status update — store and fan out to other clients only (not back to hub)
+      if (msg.type === "status_update") {
+        hubTerminalStatuses.set(clientName, msg.status);
+        const normalized: StatusUpdateMsg = {
+          type: "status_update",
+          name: clientName,
+          status: msg.status,
+        };
+        const json = JSON.stringify(normalized);
+        for (const [otherWs, name] of hubClients) {
+          if (name !== clientName) otherWs.send(json);
+        }
+        return;
+      }
+
       // Route chat / prompt messages
       if (
         msg.type === "chat" ||
@@ -388,6 +489,7 @@ export default function (pi: ExtensionAPI) {
     clientWs.on("close", () => {
       if (clientName) {
         hubClients.delete(clientWs);
+        hubTerminalStatuses.delete(clientName);
         const list = terminalList();
         connectedTerminals = list;
         updateStatus();
@@ -545,6 +647,10 @@ export default function (pi: ExtensionAPI) {
 
     role = "disconnected";
     connectedTerminals = [];
+    terminalStatuses.clear();
+    hubTerminalStatuses.clear();
+    lastPushedKind = null;
+    lastPushedTool = null;
     updateStatus();
   }
 
@@ -565,11 +671,29 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("agent_start", async () => {
-    isAgentBusy = true;
+    agentRunning = true;
+    activeToolName = null;
+    stateSince = Date.now();
+    pushStatus();
+  });
+
+  pi.on("tool_execution_start", async (event) => {
+    activeToolName = event.toolName;
+    stateSince = Date.now();
+    pushStatus();
+  });
+
+  pi.on("tool_execution_end", async () => {
+    activeToolName = null;
+    if (agentRunning) stateSince = Date.now();
+    pushStatus();
   });
 
   pi.on("agent_end", async (event) => {
-    isAgentBusy = false;
+    agentRunning = false;
+    activeToolName = null;
+    stateSince = Date.now();
+    pushStatus();
 
     // If we were running a remote prompt, send the response back
     if (pendingRemotePrompt) {
@@ -806,15 +930,20 @@ export default function (pi: ExtensionAPI) {
     async execute() {
       if (role === "disconnected") return notConnectedResult();
 
+      const statuses: Record<string, string> = {};
       const list = connectedTerminals
         .map((name) => {
+          const status = getStatusFor(name);
+          const statusStr = status ? formatStatus(status) : "";
+          if (statusStr) statuses[name] = statusStr;
           const marker = name === terminalName ? " (you)" : "";
-          return `  • ${name}${marker}`;
+          return `  • ${name}${marker}${statusStr ? "  " + statusStr : ""}`;
         })
         .join("\n");
 
       return textResult(`Connected terminals:\n${list}`, {
         terminals: connectedTerminals,
+        statuses,
         self: terminalName,
         role,
       });
@@ -822,7 +951,12 @@ export default function (pi: ExtensionAPI) {
 
     renderResult(result, _options, theme) {
       const details = result.details as
-        | { terminals?: string[]; self?: string; role?: string }
+        | {
+            terminals?: string[];
+            statuses?: Record<string, string>;
+            self?: string;
+            role?: string;
+          }
         | undefined;
       if (!details?.terminals) {
         const txt = result.content[0];
@@ -834,11 +968,12 @@ export default function (pi: ExtensionAPI) {
       text += theme.fg("accent", `${details.terminals.length} terminal(s)`);
       for (const name of details.terminals) {
         const isSelf = name === details.self;
+        const status = details.statuses?.[name] ?? "";
+        const nameStr = isSelf ? `• ${name} (you)` : `• ${name}`;
         text +=
           "\n  " +
-          (isSelf
-            ? theme.fg("accent", `• ${name} (you)`)
-            : theme.fg("text", `• ${name}`));
+          (isSelf ? theme.fg("accent", nameStr) : theme.fg("text", nameStr)) +
+          (status ? "  " + theme.fg("dim", status) : "");
       }
       return new Text(text, 0, 0);
     },
@@ -853,9 +988,14 @@ export default function (pi: ExtensionAPI) {
         _ctx.ui.notify("Link: not connected", "warning");
         return;
       }
-      const names = connectedTerminals.join(", ");
+      const lines = connectedTerminals.map((name) => {
+        const status = getStatusFor(name);
+        const statusStr = status ? formatStatus(status) : "";
+        const marker = name === terminalName ? " (you)" : "";
+        return `${name}${marker}${statusStr ? ": " + statusStr : ""}`;
+      });
       _ctx.ui.notify(
-        `Link: ${terminalName} (${role}) · ${connectedTerminals.length} online: ${names}`,
+        `Link: ${terminalName} (${role}) · ${connectedTerminals.length} online\n${lines.join("\n")}`,
         "info",
       );
     },
@@ -905,6 +1045,7 @@ export default function (pi: ExtensionAPI) {
           { type: "terminal_joined", name: newName, terminals: list },
           newName,
         );
+        pushStatus(true);
         _ctx.ui.notify(`Renamed to "${newName}"`, "info");
       } else if (role === "client") {
         // Reconnect with new name — hub will enforce uniqueness via register

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-link",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
   "author": "alvivar",
   "license": "MIT",
@@ -23,6 +23,8 @@
     "@types/ws": "^8.18.1"
   },
   "pi": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ]
   }
 }