pi-link 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -2,7 +2,31 @@
 
 All notable changes to pi-link are documented here.
 
-This changelog is based on the git history from `2026-03-21` through `2026-04-02` (current). Versions correspond to npm publishes.
+This changelog is based on the git history from `2026-03-21` through `2026-04-03` (current). Versions correspond to npm publishes.
+
+---
+
+## 0.1.7 — 2026-04-09
+
+### Added
+
+- **Bundled `pi-link-coordination` skill.** The coordination guide is now shipped with the package via `pi.skills` manifest entry. Installing pi-link now auto-loads the skill — no manual copy required. The skill provides on-demand guidance for agents delegating work across terminals: tool selection (`link_prompt` vs `link_send`), the golden rule (no sync-after-async on same target), callback contracts, and coordination modes.
+
+---
+
+## 0.1.6 — 2026-04-03
+
+**Pi 0.65.0 migration.** Pi removed `session_switch` and `session_fork` events. All session transitions (startup, reload, `/new`, `/resume`, `/fork`) now fire `session_start` with `event.reason`. Each transition tears down the old extension runtime via `session_shutdown` before creating a fresh one — so there is no live connection to update in-place across sessions.
+
+### Added
+
+- **Persistent connection intent.** `/link-connect` and `/link-disconnect` now save their state to the session via `pi.appendEntry("link-active", ...)`. On `session_start`, the saved preference is checked before falling back to `--link`. Connect once and it stays connected across session resumes without needing the flag. Explicit user intent (`link-active`) takes precedence over the `--link` flag default.
+
+### Removed
+
+- **`cwd_update` message type.** With the old `session_switch` gone, mid-session cwd changes have no trigger. Working directories are now only reported on connect (via `register`/`welcome`). Protocol returns to 9 message types.
+
+- **`session_switch` handler.** The 77-line in-place mutation matrix (hub rename, cwd diffing, client reconnect) is dead under the new lifecycle. Replaced by a unified `session_start` handler + `shouldConnect()` helper.
 
 ---
 

package/README.md

@@ -191,7 +191,7 @@ Send a prompt to a remote terminal and **wait** for the LLM's response (synchron
 
 Lists all connected terminals with role info, live agent status, working directory, and self-identification. Takes no parameters.
 
-Each terminal reports its current working directory on connect and on session switch. `link_list` shows the full absolute path so agents can choose the right target, use explicit paths when terminals differ, and catch wrong-project mistakes early.
+Each terminal reports its current working directory on connect. `link_list` shows the full absolute path so agents can choose the right target, use explicit paths when terminals differ, and catch wrong-project mistakes early.
 
 Each terminal's status is derived automatically from Pi lifecycle events — agents can't set it manually. Three states:
 
@@ -397,7 +397,7 @@ The `pi.extensions` field tells Pi which files to load as extensions. Here it po
 
 ### Protocol
 
-The wire protocol consists of **10 message types**, all serialized as JSON over WebSocket frames. New cwd-related fields are optional for backward compatibility.
+The wire protocol consists of **9 message types**, all serialized as JSON over WebSocket frames. Cwd-related fields are optional for backward compatibility.
 
 | Type              | Direction       | Purpose                                                                 |
 | ----------------- | --------------- | ----------------------------------------------------------------------- |
@@ -409,7 +409,6 @@ The wire protocol consists of **10 message types**, all serialized as JSON over
 | `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                             |
-| `cwd_update`      | Any → Hub → All | Terminal broadcasts a cwd change                                        |
 | `error`           | Hub → Client    | Error notification                                                      |
 
 ### Message Flow Examples
@@ -429,7 +428,7 @@ Client                         Hub
   |                             |
 ```
 
-Hub then broadcasts `terminal_joined` to the other connected terminals. The `welcome` message includes status and cwd snapshots for all connected terminals (fields omitted above for brevity). `terminal_joined` also includes the new terminal's optional cwd, and mid-session cwd changes are distributed via `cwd_update`.
+Hub then broadcasts `terminal_joined` to the other connected terminals. The `welcome` message includes status and cwd snapshots for all connected terminals (fields omitted above for brevity). `terminal_joined` also includes the new terminal's optional cwd.
 
 **Sending a chat message:**
 
@@ -482,7 +481,7 @@ Default names are random 4-character hex IDs: `t-a1b2`, `t-c3d4`, etc.
 | `agentRunning`           | `boolean`                             | Whether an agent run is active; blocks incoming remote prompts                              |
 | `activeToolName`         | `string \| null`                      | Name of the currently executing tool (drives `tool:<name>` status)                          |
 | `stateSince`             | `number`                              | Timestamp of last status change (used for duration display)                                 |
-| `currentCwd`             | `string`                              | Current working directory reported to peers on connect and session switch                   |
+| `currentCwd`             | `string`                              | Current working directory reported to peers on connect                                      |
 | `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 (includes inactivity + ceiling timers per entry) |

package/index.ts

@@ -49,11 +49,6 @@ interface TerminalJoinedMsg {
   terminals: string[];
   cwd?: string;
 }
-interface CwdUpdateMsg {
-  type: "cwd_update";
-  name: string;
-  cwd: string;
-}
 interface TerminalLeftMsg {
   type: "terminal_left";
   name: string;
@@ -105,7 +100,6 @@ type LinkMessage =
   | PromptRequestMsg
   | PromptResponseMsg
   | StatusUpdateMsg
-  | CwdUpdateMsg
   | ErrorMsg;
 
 // ─── Extension ───────────────────────────────────────────────────────────────
@@ -240,17 +234,18 @@ export default function (pi: ExtensionAPI) {
     return normalized;
   }
 
-  function pushCwdUpdate() {
-    const msg: CwdUpdateMsg = {
-      type: "cwd_update",
-      name: terminalName,
-      cwd: currentCwd,
-    };
-    if (role === "hub") {
-      hubBroadcast(msg, terminalName);
-    } else if (role === "client" && ws?.readyState === WebSocket.OPEN) {
-      ws.send(JSON.stringify(msg));
-    }
+  // ── Connection intent ──────────────────────────────────────────────────
+
+  function shouldConnect(_ctx: ExtensionContext): boolean {
+    const saved = _ctx.sessionManager
+      .getEntries()
+      .filter(
+        (e: { type: string; customType?: string }) =>
+          e.type === "custom" && e.customType === "link-active",
+      )
+      .pop() as { data?: { active?: boolean } } | undefined;
+    if (saved?.data?.active !== undefined) return saved.data.active;
+    return pi.getFlag("link") === true;
   }
 
   // ── Pending prompt helpers ───────────────────────────────────────────────
@@ -452,10 +447,6 @@ export default function (pi: ExtensionAPI) {
         resetInactivityFor(msg.name);
         break;
 
-      case "cwd_update":
-        terminalCwds.set(msg.name, msg.cwd);
-        break;
-
       // ── Chat message ──
       case "chat":
         pi.sendMessage(
@@ -588,21 +579,6 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
-      // Cwd update — store and relay to other clients only
-      if (msg.type === "cwd_update") {
-        hubTerminalCwds.set(clientName, msg.cwd);
-        const normalized: CwdUpdateMsg = {
-          type: "cwd_update",
-          name: clientName,
-          cwd: msg.cwd,
-        };
-        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" ||
@@ -817,90 +793,13 @@ export default function (pi: ExtensionAPI) {
       terminalName = preferredName;
     }
 
-    if (pi.getFlag("link") === true) await initialize();
+    if (shouldConnect(_ctx)) await initialize();
   });
 
   pi.on("session_shutdown", async () => {
     cleanup();
   });
 
-  pi.on("session_switch", async (_event, _ctx) => {
-    ctx = _ctx;
-
-    // 1. Cwd change detection (always, before any name logic)
-    const newCwd = _ctx.cwd;
-    const cwdChanged = newCwd !== currentCwd;
-    if (cwdChanged) currentCwd = newCwd;
-
-    // 2. Restore preferred name from the new session
-    const saved = _ctx.sessionManager
-      .getEntries()
-      .filter(
-        (e: { type: string; customType?: string }) =>
-          e.type === "custom" && e.customType === "link-name",
-      )
-      .pop() as { data?: { name?: string } } | undefined;
-
-    preferredName = saved?.data?.name ?? null;
-    const desiredName = preferredName ?? `t-${crypto.randomUUID().slice(0, 4)}`;
-    const nameChanged = desiredName !== terminalName;
-
-    if (!nameChanged && !cwdChanged) return; // nothing to do
-
-    if (!nameChanged) {
-      // Name stayed the same, but cwd changed — push cwd update
-      pushCwdUpdate();
-      return;
-    }
-
-    // Name changed (cwd may or may not have changed too)
-    if (role === "hub") {
-      // Hub rename in-place — avoid tearing down the server
-      const takenByOther = Array.from(hubClients.values()).includes(
-        desiredName,
-      );
-      if (takenByOther) {
-        // Can't use preferred name — keep current identity
-        ctx?.ui.notify(
-          `Session preferred name "${desiredName}" is taken, keeping "${terminalName}"`,
-          "warning",
-        );
-        // Still push cwd update under current name if cwd changed
-        if (cwdChanged) pushCwdUpdate();
-        return;
-      }
-      const old = terminalName;
-      terminalName = desiredName;
-      const list = terminalList();
-      connectedTerminals = list;
-      updateStatus();
-      // Notify clients only — hub already updated local state
-      hubBroadcast(
-        { type: "terminal_left", name: old, terminals: list },
-        terminalName,
-      );
-      hubBroadcast(
-        {
-          type: "terminal_joined",
-          name: desiredName,
-          terminals: list,
-          cwd: currentCwd,
-        },
-        terminalName,
-      );
-      pushStatus(true);
-    } else if (role === "client") {
-      // Client — disconnect and reconnect with new name (register includes cwd)
-      terminalName = desiredName;
-      disconnect();
-      manuallyDisconnected = false;
-      await initialize();
-    } else {
-      // Disconnected — just update local name
-      terminalName = desiredName;
-    }
-  });
-
   pi.on("agent_start", async () => {
     agentRunning = true;
     activeToolName = null;
@@ -1384,18 +1283,23 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("link-disconnect", {
     description: "Disconnect from the link",
     handler: async (_args, _ctx) => {
+      pi.appendEntry("link-active", { active: false });
+      manuallyDisconnected = true;
       if (role === "disconnected") {
-        _ctx.ui.notify("Already disconnected", "info");
+        if (reconnectTimer) {
+          clearTimeout(reconnectTimer);
+          reconnectTimer = null;
+        }
+        _ctx.ui.notify("Link disconnected", "info");
         return;
       }
-      manuallyDisconnected = true;
       disconnect();
       _ctx.ui.notify("Disconnected from link", "info");
     },
   });
 
   pi.registerCommand("link-connect", {
-    description: "Connect to the link (after manual disconnect)",
+    description: "Connect to the link",
     handler: async (_args, _ctx) => {
       if (role !== "disconnected") {
         _ctx.ui.notify(
@@ -1404,6 +1308,7 @@ export default function (pi: ExtensionAPI) {
         );
         return;
       }
+      pi.appendEntry("link-active", { active: true });
       manuallyDisconnected = false;
       await initialize();
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-link",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
   "author": "alvivar",
   "license": "MIT",
@@ -25,6 +25,9 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   }
 }

package/skills/pi-link-coordination/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: pi-link-coordination
+description: Guidance for coordinating work across Pi terminals using pi-link. Use when delegating tasks, choosing between link_prompt and link_send, planning async vs sync work, batching parallel jobs, or avoiding busy/conflict patterns.
+---
+
+# Pi-Link Coordination
+
+How to coordinate work across Pi terminals via pi-link.
+
+---
+
+## Tool Selection Rule
+
+- Need the answer back now? → `link_prompt`
+- Need autonomous work done? → `link_send(triggerTurn: true)`
+- Need to notify only? → `link_send(triggerTurn: false)`
+
+---
+
+## The Golden Rule
+
+> After `link_send(triggerTurn: true)` to terminal X, do not `link_prompt` X until X sends a completion callback.
+
+Pick one mode per terminal per task. Mixing sync and async on the same terminal is the most common coordination failure.
+
+---
+
+## The Tools
+
+### `link_list`
+
+Returns connected terminals with names, live status (`idle`, `thinking`, `tool:<name>`), and working directory (cwd). Use before delegating when availability or path context is uncertain.
+
+### `link_prompt`
+
+Synchronous RPC. Send a prompt, wait for the response.
+
+- Fails immediately if target is missing, self, disconnects, or busy (local work or another remote prompt)
+- 90s inactivity timeout, 30min hard ceiling
+- Remote agent doesn't share your context — prompts must be self-contained
+- Include: goal, scope, constraints, output format, done condition
+
+### `link_send`
+
+Fire-and-forget. Send to one terminal or `to: "*"` to broadcast (excludes sender).
+
+Set `triggerTurn: true` to activate the receiver's LLM. The sender does **not** get the response back.
+
+**Callback contract for `triggerTurn: true`:** ask the receiver to reply via `link_send` with:
+
+- `DONE` signal
+- Output paths / artifacts created
+- Blockers or open questions
+
+---
+
+## Operating Constraints
+
+- **One remote prompt at a time per target.** Concurrent requests rejected as busy.
+- **No shared context.** Every remote prompt must be self-contained.
+- **Messages are ephemeral.** Offline terminals lose messages.
+- **Localhost only.** Same machine.
+- **Cwd is a hint, not proof.** Same cwd ≠ same workspace/branch/access. Use explicit paths; absolute when cwds differ or shared-root assumptions are unclear.
+- **Naming:** `role@domain` (e.g., `builder@pi-link`). Only talk to your own domain unless told otherwise.
+
+---
+
+## Coordination Modes
+
+### Sync ask — `link_prompt`
+
+For answers, review, analysis you need back now. One terminal at a time. Keep scope focused to avoid timeout.
+
+### Async delegate — `link_send(triggerTurn: true)`
+
+For autonomous work. Require the callback contract (DONE + paths + blockers). Do your own work in parallel. Don't `link_prompt` the target until the callback arrives.
+
+### Parallel batch — async to multiple terminals
+
+Distribute independent tasks. Use explicit paths (absolute if cwds differ). Wait for all callbacks, then synthesize. Don't prompt any dispatched terminal until its callback arrives.
+
+---
+
+## Anti-Patterns
+
+**❌ Mixing async and sync on the same terminal**
+Dispatched with `link_send(triggerTurn: true)` then sent a `link_prompt` → rejected as busy. See Golden Rule.
+
+**❌ Using `link_send` when you need the response**
+Result disappears. Use `link_prompt`.
+
+**❌ Vague prompts**
+"Fix the bug" is useless. Include file, line, root cause, expected fix.
+
+**❌ No completion callback on async work**
+Always require DONE + artifact paths + blockers.
+
+**❌ Circular delegation**
+A → B → C → A = deadlock. Maintain clear hierarchy.
+
+**❌ Skipping `link_list` before retrying a busy target**
+Check status before re-sending.
+
+---
+
+## Quick Reference
+
+| I need to...                     | Tool                            | Mode            |
+| -------------------------------- | ------------------------------- | --------------- |
+| See who's available              | `link_list`                     | —               |
+| Get an answer from another agent | `link_prompt`                   | Synchronous     |
+| Delegate autonomous work         | `link_send(triggerTurn: true)`  | Asynchronous    |
+| Notify without activating        | `link_send(triggerTurn: false)` | Fire-and-forget |
+| Broadcast to all                 | `link_send(to: "*")`            | Broadcast       |