pi-link 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-link",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
   "author": "alvivar",
   "license": "MIT",

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

@@ -1,12 +1,14 @@
 ---
 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.
+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, managing a remote terminal's context with link_compact, or avoiding busy/conflict patterns.
 ---
 
 # Pi-Link Coordination
 
 How to coordinate work across Pi terminals via pi-link.
 
+Each terminal is an independent agent: they share no memory or conversation history — link only passes messages and prompts between them. Anything a remote terminal needs — file paths, task state, expected output, where to send its callback — must be in the message itself.
+
 ---
 
 ## Tool Selection Rule
@@ -14,6 +16,7 @@ How to coordinate work across Pi terminals via pi-link.
 - Need the answer back now? → `link_prompt`
 - Need autonomous work done? → `link_send(triggerTurn: true)`
 - Need to notify only? → `link_send(triggerTurn: false)`
+- Need to free a terminal's context? → `link_compact`
 
 ---
 
@@ -21,7 +24,9 @@ How to coordinate work across Pi terminals via pi-link.
 
 > 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 `DONE` / `BLOCKED` callback arrives as a normal later user message; treat that callback as the signal that it is safe to send a follow-up `link_prompt`.
+
+Pick one mode per terminal per task. Mixing sync and async on the same terminal is a common coordination failure.
 
 ---
 
@@ -29,7 +34,7 @@ Pick one mode per terminal per task. Mixing sync and async on the same terminal
 
 ### `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. Your own entry is marked `(you)` — use this to discover your link name when replying to broadcast tasks.
+Returns connected terminals with names, live status (`idle`, `thinking`, `tool:<name>`), and working directory (cwd). Some terminals also report context usage as `45K/272K (17%)` — how full that window is: high usage means less room remaining, though a loaded terminal may also be the one already holding the relevant task state. Your own entry is marked `(you)` — use this to discover your link name when replying to broadcast tasks.
 
 Only currently connected terminals are visible. If a target is missing, it is offline; messages to offline terminals are not queued.
 
@@ -37,53 +42,50 @@ Only currently connected terminals are visible. If a target is missing, it is of
 
 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)
+- Fails fast if the target is yourself, not connected, or busy (local work, another remote prompt, or compaction); a mid-wait disconnect resolves as an error
 - 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
+- Remote agent doesn't share your context — include enough detail to complete the task
 
 ### `link_send`
 
-Fire-and-forget. Send to one terminal or `to: "*"` to broadcast (excludes sender).
+Fire-and-forget. Send to one terminal or `to: "*"` to broadcast to every other connected terminal; there is no exclusion filter. Sending to yourself is rejected. A send to a name that isn't connected fails with an error listing who _is_ connected — delivery failure is visible to the sender, not silent.
 
-Set `triggerTurn: true` to queue async work on the receiver. Delivery happens at turn boundaries: pending messages are batched and surface together when the receiver next becomes idle. The sender does **not** get the response back.
+Set `triggerTurn: true` to queue async work on the receiver. The sender does **not** get an automatic response back.
 
-Batched callback shape: `[Link: N message(s) received]` then one or more `From "name":` / `content` blocks.
+Delivery shape depends on the message's `triggerTurn`:
 
-**Callback contract for `triggerTurn: true`:** ask the receiver to reply via `link_send` with:
+- **`triggerTurn: true`** messages go through the receiver's idle-gated inbox and surface at a turn boundary wrapped as `[Link: N message(s) received]` followed by one `From "name":` block per message. Multiple pending messages are batched into one turn.
+- **`triggerTurn: false`** messages bypass the inbox and surface directly as raw content — no wrapper, no `From` block. The receiver sees only the message text, so the sender must include their own identity, task tag, or artifact paths in the body.
+
+**Callback convention for `triggerTurn: true`:** the sender gets no automatic response, so ask the receiver to report back via `link_send(..., triggerTurn: true)` (which lands at a proper turn boundary with the wrapper intact). A useful convention:
 
 - `DONE` / `BLOCKED`
 - Output paths / artifacts created
-- Short result summary or next question
+- Result summary or next question
+
+Use `triggerTurn: false` for fire-and-forget status notifications only — when you don't need to act on the reply.
 
-Keep callbacks concise. Put long details in files and return the paths.
+**Receiver rule:** If your turn opens with `[Link: N message(s) received]`, treat each `From "name":` block as assigned work. When done, send the sender a `DONE` / `BLOCKED` callback via `link_send(..., triggerTurn: true)` — unless the task says otherwise.
+
+### `link_compact`
+
+Blocks until the target finishes compacting, then returns (3 min ceiling — the call then errors for you, though the target may still finish compacting on its own; check it before assuming failure). Ask another terminal to compact its context window into a summary, freeing space. `link_list` exposes context usage; `link_compact` is the lever when you decide a terminal should free context — and because the call only returns once compaction is done, you can immediately hand it more work with `link_send`/`link_prompt` (no sleep, no busy-bounce). Busy targets (mid-turn or already compacting) decline; retry when `link_list` shows them idle. You decide the threshold; pi-link just runs the compaction you ask for. Its optional `instructions` add an extra focus to that summary.
 
 ---
 
 ## 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.
+- **Naming:** Link names are user-defined identities (often `role@domain`, e.g. `builder@pi-link`); the hub keeps them unique, suffixing collisions (`builder@pi-link-2`). Use `link_list` to confirm a target's exact name, and its cwd to tell similar-named terminals apart.
 
 ---
 
-## 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.
+## Parallel batch
 
-### Async delegate — `link_send(triggerTurn: true)`
-
-For autonomous work. Require the callback contract (DONE/BLOCKED + paths + short summary). Do your own work in parallel. Expect the callback at a turn boundary, possibly batched with others. Don't `link_prompt` the target until the callback arrives.
-
-### Parallel batch — async to multiple terminals
-
-Distribute independent tasks. Worker callbacks may return together in one batched turn when you become idle. Use explicit paths (absolute if cwds differ), require short callbacks + artifact paths, wait for all callbacks, then synthesize. Don't prompt any dispatched terminal until its callback arrives.
+`link_send(triggerTurn: true)` can dispatch independent tasks to several terminals at once. Their callbacks may arrive separately or batched into one turn when you next become idle — track which workers are still outstanding. Each task must be self-contained (explicit paths, absolute if cwds differ). Don't `link_prompt` a dispatched terminal until its callback arrives (Golden Rule).
 
 ---
 
@@ -92,32 +94,21 @@ Distribute independent tasks. Worker callbacks may return together in one batche
 **❌ 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 now**
-No direct response comes back to the sender. Use `link_prompt` when you need the answer in the same turn.
-
-**❌ Vague prompts**
-"Fix the bug" is useless. Include file, line, root cause, expected fix.
-
 **❌ No completion callback on async work**
-Always require DONE/BLOCKED + artifact paths + short summary.
+`triggerTurn: true` returns no result to the sender — without an agreed callback you never learn the outcome.
 
 **❌ Circular delegation**
-A → B → C → A = deadlock. Maintain clear hierarchy.
-
-**❌ Skipping `link_list` before retrying a busy target**
-Check status before re-sending.
-
-**❌ Long async callbacks**
-Long callbacks crowd a whole batched turn. Ask workers to write detailed output to files and return paths + short summaries.
+A → B → C → A won't complete — the cycle-closing `link_prompt` hits a busy target (rejected), and an async `link_send` cycle just loops. Keep delegation acyclic.
 
 ---
 
 ## 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       |
+| 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        |
+| Free a loaded worker's context   | `link_compact`                  | Await-completion |