@trim21/personal-pi-extensions 0.0.202 → 0.0.203

package/README.md

@@ -230,12 +230,12 @@ index.ts     —— pi adapter：把 core 接到 pi 的 sendMessage / 生命周
 
 ### 工具（LLM 可见）
 
-| 工具                 | 作用                                                                                                                       |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `talk-list-sessions` | 列出其他 session，返回 JSON 数组（`status` / `work_dir` / `id` / `name`）；默认只列有心跳的，`includeOffline: true` 列全部 |
-| `talk-ask`           | 向某个 session 提问并阻塞等待回复（默认 30 分钟超时）                                                                      |
-| `talk-send`          | 发送纯文本消息（`to: "*"` 广播所有，`to: "cwd"` 广播同 cwd）                                                               |
-| `talk-reply`         | 回复一个 ask（`replyTo` 为 ask id，显式关联、不推断）                                                                      |
+| 工具                 | 作用                                                                                                                                    |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `talk-list-sessions` | 列出会话，返回 JSON 数组（`status` / `work_dir` / `id` / `name`，自己带 `self: true`）；默认只列有心跳的，`includeOffline: true` 列全部 |
+| `talk-ask`           | 向某个 session 提问并阻塞等待回复（默认 30 分钟超时）                                                                                   |
+| `talk-send`          | 发送纯文本消息（`to: "*"` 广播所有，`to: "cwd"` 广播同 cwd）                                                                            |
+| `talk-reply`         | 回复一个 ask（`replyTo` 为 ask id，显式关联、不推断）                                                                                   |
 
 对端消息自动投递（无需主动拉取）：投递方式由 `talk.deliver` 配置，`steer` 在模型工作过程中打断/唤醒，`queue` 排队到 session 下一轮自然 turn 时注入。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.202",
+  "version": "0.0.203",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -67,6 +67,9 @@
       "src/opencode-todo.ts",
       "src/question.ts",
       "src/talk/index.ts"
+    ],
+    "skills": [
+      "src/talk/skills"
     ]
   },
   "lint-staged": {

package/src/talk/core.ts

@@ -449,17 +449,18 @@ export class TalkCore {
   // ── Tool actions ───────────────────────────────────────────────────────
 
   /**
-   * JSON listing of visible peer sessions. Defaults to sessions whose
-   * heartbeat is fresh (within LIST_ACTIVE_MS); pass includeOffline to show
-   * every visible peer regardless of last contact.
+   * JSON listing of visible sessions, including self (marked `self: true`).
+   * Defaults to sessions whose heartbeat is fresh (within LIST_ACTIVE_MS);
+   * pass includeOffline to show every visible peer regardless of last contact.
    */
   async list(includeOffline = false): Promise<string> {
     const self = this.requireSelf();
     const now = this.now();
     const all = await listRecords(this.storage);
-    const records = all.filter(
-      (r) => this.isPeerVisible(r.cwd) && (includeOffline || now - r.lastSeenAt < LIST_ACTIVE_MS),
-    );
+    const records = all.filter((r) => {
+      if (r.addr === self.addr) return !this.dead;
+      return this.isPeerVisible(r.cwd) && (includeOffline || now - r.lastSeenAt < LIST_ACTIVE_MS);
+    });
     return formatListing(records, self.addr, (r) => presenceOf(r, now));
   }
 
@@ -468,12 +469,11 @@ export class TalkCore {
     const self = this.requireSelf();
     const now = this.now();
     const records = await listRecords(this.storage);
-    const filtered = records.filter(
-      (r) =>
-        r.cwd === cwd &&
-        this.isPeerVisible(r.cwd) &&
-        (includeOffline || now - r.lastSeenAt < LIST_ACTIVE_MS),
-    );
+    const filtered = records.filter((r) => {
+      if (r.cwd !== cwd) return false;
+      if (r.addr === self.addr) return !this.dead;
+      return this.isPeerVisible(r.cwd) && (includeOffline || now - r.lastSeenAt < LIST_ACTIVE_MS);
+    });
     return formatListing(filtered, self.addr, (r) => presenceOf(r, now));
   }
 

package/src/talk/format.ts

@@ -31,27 +31,30 @@ export function formatDelivery(letter: Letter, now: number = Date.now()): string
   return `${BOUNDARY_PREAMBLE}\n\n${header}:\n\n${letter.body}\n\n${meta}${hint}`;
 }
 
-/** One peer session as the model sees it in a listing. `id` is the stable
- * pi session uuid; `name` is the display name when one was set. */
+/** One session as the model sees it in a listing. `id` is the stable pi
+ * session uuid; `name` is the display name when one was set; `self` marks
+ * the calling session itself. */
 export interface SessionListItem {
   status: string;
   work_dir: string;
   id: string;
   name?: string;
+  self?: boolean;
 }
 
-/** Machine-readable JSON listing of peer sessions (what the model sees). */
+/** Machine-readable JSON listing of sessions (what the model sees). */
 export function formatListing(
   records: SessionRecord[],
   selfAddr: string,
   presence: (r: SessionRecord) => Presence,
 ): string {
-  const others = records.filter((r) => r.addr !== selfAddr);
-  if (others.length === 0) return "[]";
-  const items: SessionListItem[] = others.map((r) => {
+  if (records.length === 0) return "[]";
+  const items: SessionListItem[] = records.map((r) => {
     const p = presence(r);
     const status = p === "live" ? r.status : p === "stalled" ? "not responding" : "offline";
-    return { status, work_dir: r.cwd, id: r.sessionId, name: r.name };
+    const item: SessionListItem = { status, work_dir: r.cwd, id: r.sessionId, name: r.name };
+    if (r.addr === selfAddr) item.self = true;
+    return item;
   });
   return JSON.stringify(items, null, 2);
 }

package/src/talk/index.ts

@@ -11,6 +11,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
@@ -31,6 +32,9 @@ const NOTIFY_TYPE = "talk:notify";
 
 const ASK_TIMEOUT_MS = 30 * 60 * 1000;
 
+/** Guide the model to the multi-agent workflow skill shipped with this package. */
+const SKILL_PATH = fileURLToPath(new URL("skills/multi-agent-dev/SKILL.md", import.meta.url));
+
 function toolResult(text: string) {
   return { content: [{ type: "text" as const, text }], details: {} };
 }
@@ -200,6 +204,14 @@ export default function talk(pi: ExtensionAPI) {
   pi.on("agent_start", () => core.setWorking());
   pi.on("agent_end", () => core.setIdle());
   pi.on("agent_settled", () => core.setIdle());
+  pi.on("before_agent_start", (event) => {
+    // One-line nudge: before coordinating with other pi sessions, read the
+    // shipped workflow skill. Skipped when the skill file is absent.
+    if (!fs.existsSync(SKILL_PATH)) return;
+    return {
+      systemPrompt: `${event.systemPrompt}\n\nBefore multi-session collaboration, read ${SKILL_PATH} to understand the talk workflow.`,
+    };
+  });
   pi.on("session_info_changed", () => {
     if (self) core.setSessionName(pi.getSessionName() ?? self.name);
   });

package/src/talk/skills/multi-agent-dev/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: multi-agent-dev
+description: Coordinate multi-agent development across pi sessions using the talk extension. Explains how sessions discover and address each other, when to use talk-send vs talk-ask, and how to split work, exchange information, and review between agents. Use whenever you need to collaborate with other pi sessions or agents on the same machine.
+---
+
+# Multi-Agent Development with Talk
+
+## Concept
+
+Multi-agent development runs several independent pi sessions in parallel and coordinates them over **talk**. Every session is a complete agent workspace — its own cwd, conversation history, and context. Talk lets sessions discover each other, exchange messages, ask questions, and sync progress.
+
+The core rule: **a peer only knows what you tell it.** Messages must be self-contained — background, goal, and constraints — because the receiving session has none of your context.
+
+## Session model
+
+### Discovery and addressing
+
+- `talk-list-sessions` returns sessions as JSON — **your own session is included and marked `self: true`** (also where you learn your own id):
+
+  ```json
+  [
+    {
+      "status": "idle",
+      "work_dir": "/path/to/cwd",
+      "id": "0193a2f5-...",
+      "name": "...",
+      "self": true
+    }
+  ]
+  ```
+
+- Addressing is **by session id only**: `talk-send` / `talk-ask` take the full `id` (pi session uuid). Names, paths, and prefixes are not accepted.
+- An unknown or invisible target is refused with `Unknown session id` — always list before sending.
+
+### Status
+
+- `idle` / `working` (agent actively running) / `waiting-talk-message` (blocked in `talk-ask` waiting for a reply)
+- `not responding` (heartbeat stale, process alive but unresponsive) / `offline` (process exited or marked dead)
+- The default listing shows only sessions with a heartbeat in the last 15 minutes; pass `includeOffline: true` for everything.
+
+### Visibility
+
+- Each workspace controls what it can see via `allowed` in `<cwd>/.pi/talk.json` (path prefixes). Sessions outside the prefixes are neither listed nor addressable.
+- Visibility is one-way: you seeing a session does not mean it sees you.
+
+## Tools
+
+| Tool                 | Purpose                                                                                                                             |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `talk-list-sessions` | List visible sessions (`id` / `status` / `work_dir` / `name`)                                                                       |
+| `talk-send`          | Send a plain message (async — the main collaboration primitive). `to: "*"` broadcasts, `to: "cwd"` broadcasts to the same directory |
+| `talk-ask`           | Ask a question and block for the reply (default 30 min timeout)                                                                     |
+| `talk-reply`         | Reply to a received ask; `replyTo` is the ask id shown in the delivered message                                                     |
+
+In the TUI: `/talk` lists sessions, `/talk-dead` marks a session as dead (removes it from listings and sweeps it).
+
+## Collaboration workflows
+
+### Split work between sessions
+
+1. `talk-list-sessions` first: see which sessions exist, their `work_dir`, and status.
+2. Assign work by module/files with `talk-send` — state the scope, boundaries, and expected output.
+3. Each session completes its slice, then sends the result or a review request.
+4. Sync progress periodically to avoid overlapping edits.
+
+### Synchronous question/answer (need the answer to continue)
+
+- Use `talk-ask` when the next step depends on the peer's information and the peer is reachable.
+- On receiving an ask, reply with `talk-reply` using the `replyTo` id from the delivered message.
+- If two sessions ask each other simultaneously: the later asker yields — answer the peer's ask first, then re-ask.
+
+### Async notifications
+
+- Use `talk-send` for heads-ups that do not block: send and keep working.
+- Messages deliver on the next natural turn by default (`queue`); `steer` interrupts the peer immediately — behavior depends on the `talk.deliver` setting.
+
+### Cross-session review
+
+- Ask another session to review your changes: `talk-send` the file paths plus a diff summary, request a review, and let it reply.
+- Send paths and summaries, not whole file contents — the peer can `read` them itself.
+
+## Message style
+
+- Plain text, ≤32KB. Send a summary and paths, never the full file or large code blocks.
+- Self-contained: background, goal, constraints — the peer has none of your context.
+- Make the ask explicit: "please review", "please implement", or "FYI only".
+- One topic per message so the reply stays focused.
+
+## Pitfalls
+
+- **Avoid message loops**: if the peer sent you something or is asking you, answer it before sending new ones. Two agents pinging each other deadlock.
+- **Address from known ids**: only run `talk-list-sessions` to discover sessions or verify an id. If you already hold a valid id (e.g. from an incoming message or a previous listing), send directly — an unknown or invisible id is refused with `Unknown session id`.
+- **Respect status**: asking an offline/not-responding session blocks up to 30 min. Prefer `talk-send` there — the message queues on disk and the peer receives it when it resumes.
+- **Visibility boundary**: you can only collaborate with sessions you can see; invisible sessions are unreachable by design.