@dyyz1993/pi-coding-agent 0.74.24 → 0.74.27

package/dist/extensions/coordinator/INTEGRATION.md

@@ -0,0 +1,376 @@
+# Coordinator Extension - pi-agent-chat Integration Guide
+
+## Overview
+
+The coordinator extension enables cross-session communication and task delegation. It runs inside each pi agent process as an extension, communicating with pi-agent-chat's `AgentProcessManager` via the `"coordinator"` channel.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────┐
+│  pi-agent-chat (AgentProcessManager)             │
+│                                                  │
+│  client.channel("coordinator")                   │
+│    .onReceive(data => {                          │
+│      // Handle incoming __call from extension    │
+│      // Return result to respond                 │
+│    })                                            │
+│                                                  │
+│  client.channel("coordinator")                   │
+│    .send({ type: "message_received", ... })      │
+│    // Emit events to extension                   │
+└───────────────────┬──────────────────────────────┘
+                    │ stdin/stdout JSONL
+└───────────────────┴──────────────────────────────┘
+┌──────────────────────────────────────────────────┐
+│  pi Agent Process (extension)                    │
+│                                                  │
+│  ServerChannel: handles __call from pi-agent-chat│
+│  ClientChannel: sends __call to pi-agent-chat    │
+│                                                  │
+│  Tools: session_delegate, session_delegate_send, │
+│         session_delegate_status, session_delegate_│
+│         stop, session_delegate_fork              │
+└──────────────────────────────────────────────────┘
+```
+
+## Key Communication Pattern
+
+The extension uses `ClientChannel.call()` to send `__call` requests OUTBOUND to pi-agent-chat. pi-agent-chat must respond by returning a value from its `onReceive` handler.
+
+**Critical**: The `RpcClient.handleLine()` does NOT await handler results. It calls handlers synchronously:
+
+```typescript
+for (const handler of handlers) {
+    const result = handler(data.data);
+    if (invokeId && result !== undefined) {
+        this.writeLine({ type: "channel_data", name, data: { ...result, invokeId } });
+    }
+}
+```
+
+This means async handlers that return Promises will NOT work correctly with the auto-response mechanism. You **must** use the manual response pattern for any handler that performs async operations.
+
+## Step-by-Step Integration
+
+### Step 1: Register coordinator channel in `start()`
+
+In `AgentProcessManager.start()`, add `"coordinator"` to the channel registration loop:
+
+```typescript
+for (const name of ["bash", "todo", "subagent", "lsp", "rules-engine", "memory", "coordinator"] as const) {
+    client.channel(name).onReceive((data: unknown) => {
+        this.handleCoordinatorCall(sessionId, data);
+    });
+}
+```
+
+### Step 2: Implement `handleCoordinatorCall()` with manual response
+
+> **Warning**: You MUST use the manual response pattern below. The `RpcClient.handleLine()` does NOT await handlers, so returning a Promise from `onReceive` will send the unresolved Promise object as the response, causing the extension's `ClientChannel.call()` to receive garbage data.
+
+```typescript
+private async handleCoordinatorCall(sessionId: string, data: unknown): Promise<void> {
+    const msg = data as Record<string, unknown>;
+    const method = msg.__call as string;
+    const invokeId = msg.invokeId as string | undefined;
+
+    let result: unknown;
+    try {
+        switch (method) {
+            case "session_delegate":
+                result = await this.handleDelegate(sessionId, msg);
+                break;
+            case "session_delegate_send":
+                result = await this.handleDelegateSend(sessionId, msg);
+                break;
+            case "session_delegate_status":
+                result = await this.handleDelegateStatus(sessionId, msg);
+                break;
+            case "session_delegate_list":
+                result = this.handleDelegateList();
+                break;
+            case "session_delegate_stop":
+                result = await this.handleDelegateStop(sessionId, msg);
+                break;
+            case "session_delegate_fork":
+                result = await this.handleDelegateFork(sessionId, msg);
+                break;
+            default:
+                return;
+        }
+    } catch (err) {
+        result = { error: err instanceof Error ? err.message : String(err) };
+    }
+
+    if (invokeId) {
+        const managed = this.clients.get(sessionId);
+        if (managed) {
+            managed.client.channel("coordinator").send({ ...(result as object), invokeId });
+        }
+    }
+}
+```
+
+### Step 3: Implement each handler
+
+#### `handleDelegate()` — Create new session and send task
+
+```typescript
+private async handleDelegate(
+    parentSessionId: string,
+    msg: Record<string, unknown>,
+): Promise<{ sessionId: string; status: "started" | "already_running" }> {
+    const task = msg.task as string;
+    const parent = this.clients.get(parentSessionId);
+    if (!parent) throw new Error("Parent session not found");
+
+    const projectPath = parent.info.projectPath;
+
+    const newSessionId = `sess_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const sessionDir = path.dirname(parent.info.sessionPath);
+    const sessionPath = path.join(sessionDir, `${newSessionId}.jsonl`);
+
+    const result = await this.start(newSessionId, projectPath, sessionPath);
+
+    this.send(newSessionId, task);
+
+    return { sessionId: newSessionId, status: result.status === "started" ? "started" : "already_running" };
+}
+```
+
+#### `handleDelegateSend()` — Send message to target session
+
+```typescript
+private async handleDelegateSend(
+    fromSessionId: string,
+    msg: Record<string, unknown>,
+): Promise<{ delivered: boolean; targetStatus: "active" | "started" | "not_found" }> {
+    const targetSessionId = msg.targetSessionId as string;
+    const message = msg.message as string;
+
+    const target = this.clients.get(targetSessionId);
+    if (!target) {
+        return { delivered: false, targetStatus: "not_found" };
+    }
+
+    if (target.info.status === "idle") {
+        this.followUp(targetSessionId, message);
+        return { delivered: true, targetStatus: "active" };
+    }
+
+    this.followUp(targetSessionId, message);
+    return { delivered: true, targetStatus: "active" };
+}
+```
+
+#### `handleDelegateStatus()` — Get session status with compact info
+
+```typescript
+private async handleDelegateStatus(
+    _sessionId: string,
+    msg: Record<string, unknown>,
+): Promise<{ status: string; isCompacting: boolean; contextUsage: unknown }> {
+    const targetSessionId = msg.sessionId as string;
+
+    const status = this.getStatus(targetSessionId);
+    if (status.status === "stopped") {
+        return { status: "stopped", isCompacting: false, contextUsage: { tokens: null, contextWindow: 0, percent: null } };
+    }
+
+    const state = await this.getState(targetSessionId);
+    const contextUsage = await this.getContextUsage(targetSessionId);
+
+    return {
+        status: state?.isStreaming ? "streaming" : "idle",
+        isCompacting: state?.isCompacting ?? false,
+        contextUsage,
+    };
+}
+```
+
+#### `handleDelegateList()` — List all managed sessions
+
+```typescript
+private handleDelegateList(): { sessions: Array<{ sessionId: string; status: string; projectPath: string }> } {
+    const sessions: Array<{ sessionId: string; status: string; projectPath: string }> = [];
+    for (const [sessionId, managed] of this.clients) {
+        sessions.push({
+            sessionId,
+            status: managed.info.status,
+            projectPath: managed.info.projectPath,
+        });
+    }
+    return { sessions };
+}
+```
+
+#### `handleDelegateStop()` — Stop a session
+
+```typescript
+private async handleDelegateStop(
+    _sessionId: string,
+    msg: Record<string, unknown>,
+): Promise<{ ok: boolean }> {
+    const targetSessionId = msg.sessionId as string;
+    const ok = this.stop(targetSessionId);
+    return { ok };
+}
+```
+
+#### `handleDelegateFork()` — Fork session without stopping original
+
+```typescript
+private async handleDelegateFork(
+    parentSessionId: string,
+    msg: Record<string, unknown>,
+): Promise<{ sessionId: string; status: "started" | "already_running" }> {
+    const task = msg.task as string;
+    const base = this.clients.get(parentSessionId);
+    if (!base) throw new Error("Base session not found");
+
+    const sessionPath = base.info.sessionPath;
+    const projectPath = base.info.projectPath;
+    const sessionDir = path.dirname(sessionPath);
+
+    // Primary approach: use SessionManager.createBranchedSession() for correct JSONL extraction
+    // This handles tree-structured sessions and avoids half-write corruption
+    import { SessionManager } from "@dyyz1993/pi-coding-agent";
+
+    const sourceManager = SessionManager.open(sessionPath, sessionDir);
+    const leafId = sourceManager.getLeafId();
+    const forkedPath = sourceManager.createBranchedSession(leafId);
+
+    // Fallback: if createBranchedSession is unavailable, use direct file copy
+    // const forkedSessionId = `sess_fork_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    // const forkedPath = path.join(sessionDir, `${forkedSessionId}.jsonl`);
+    // fs.copyFileSync(sessionPath, forkedPath);
+
+    const forkedSessionId = path.basename(forkedPath, ".jsonl");
+    const result = await this.start(forkedSessionId, projectPath, forkedPath);
+
+    this.send(forkedSessionId, task);
+
+    return { sessionId: forkedSessionId, status: result.status === "started" ? "started" : "already_running" };
+}
+```
+
+**Why `SessionManager.createBranchedSession()` is preferred over file copy**:
+
+1. Extracts a single linear path from tree-structured sessions (after navigateTree/branch operations)
+2. Filters and recreates label entries correctly
+3. Generates a new session ID and header
+4. Rebuilds internal index
+5. Avoids reading a partially-written JSONL file (the source session may be actively writing)
+
+File copy (`fs.copyFileSync`) is only safe as a fallback when you can guarantee the source session is idle and the JSONL is not being written to.
+
+### Step 4: Emit events from pi-agent-chat to extension
+
+To send events to the extension (e.g., message_received, task_completed), use:
+
+```typescript
+if (delegatedSessionId) {
+    const managed = this.clients.get(parentSessionId);
+    if (managed) {
+        managed.client.channel("coordinator").send({
+            type: "message_received",
+            fromSessionId: delegatedSessionId,
+            message: "Task completed successfully",
+        });
+    }
+}
+```
+
+Or use `sendChannelData()`:
+
+```typescript
+this.sendChannelData(parentSessionId, "coordinator", {
+    type: "task_completed",
+    sessionId: delegatedSessionId,
+    result: "Done",
+});
+```
+
+### Step 5: Add coordinator extension path to config
+
+In `server-config.ts`, add:
+
+```typescript
+coordinator: process.env.PI_EXT_COORDINATOR,
+```
+
+In `.env`:
+```
+PI_EXT_COORDINATOR=/path/to/pi-momo-fork/packages/coding-agent/extensions/coordinator
+```
+
+And add to the `EXTENSION_ARGS` array in `process-manager.ts`:
+
+```typescript
+const { coordinator, /* ...others */ } = config.piExtensionPaths;
+const EXTENSION_ARGS = [
+    "--no-extensions",
+    ...[subagent, todo, bash, lsp, preview, autoMemory, autoSessionTitle, rules, fileSnapshot, askTools, messageBridge, coordinator]
+        .filter((p): p is string => !!p)
+        .flatMap((p) => ["--extension", p]),
+];
+```
+
+## Channel Contract Reference
+
+### Methods (pi-agent-chat handles these)
+
+| Method | Params | Return |
+|--------|--------|--------|
+| `session_delegate` | `{ task: string, title?: string }` | `{ sessionId: string, status: "started" \| "already_running" }` |
+| `session_delegate_send` | `{ targetSessionId: string, message: string }` | `{ delivered: boolean, targetStatus: "active" \| "started" \| "not_found" }` |
+| `session_delegate_status` | `{ sessionId: string }` | `{ task?: DelegatedTask, isCompacting?: boolean, contextUsage?: ContextUsage }` |
+| `session_delegate_list` | `{}` | `{ tasks: DelegatedTask[] }` |
+| `session_delegate_stop` | `{ sessionId: string }` | `{ ok: boolean }` |
+| `session_delegate_fork` | `{ sessionId: string, task: string, title?: string }` | `{ sessionId: string, status: "started" \| "already_running" }` |
+
+### Events (pi-agent-chat sends these)
+
+| Event | Data | When |
+|-------|------|------|
+| `message_received` | `{ fromSessionId: string, message: string }` | Worker session sends a message |
+| `task_started` | `{ sessionId: string, title: string, task: string }` | Worker starts processing |
+| `task_stopped` | `{ sessionId: string }` | Worker stopped |
+| `task_completed` | `{ sessionId: string, result?: string }` | Worker finished |
+| `task_error` | `{ sessionId: string, error: string }` | Worker errored |
+
+### Types
+
+```typescript
+interface DelegatedTask {
+    sessionId: string;
+    title: string;
+    task: string;
+    projectPath: string;
+    dispatchedAt: number;
+    status: "idle" | "streaming" | "stopped" | "completed";
+    completedAt?: number;
+    result?: string;
+}
+
+interface ContextUsage {
+    tokens: number | null;
+    contextWindow: number;
+    percent: number | null;
+}
+```
+
+## Testing Checklist
+
+- [ ] Register coordinator channel in `start()`
+- [ ] `session_delegate` creates new session and sends task
+- [ ] `session_delegate_send` delivers message via `followUp()`
+- [ ] `session_delegate_status` returns status + isCompacting + contextUsage
+- [ ] `session_delegate_list` lists all managed sessions
+- [ ] `session_delegate_stop` stops target session
+- [ ] `session_delegate_fork` copies session file and starts new process
+- [ ] Events are emitted back to extension on state changes
+- [ ] Async responses are sent manually via `channel.send()` with invokeId
+- [ ] Coordinator extension path is configured in `.env`
+- [ ] `handleEvent()` routes coordinator channel data correctly

package/dist/extensions/coordinator/handler.test.ts

@@ -0,0 +1,277 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import type { DelegatedTask } from "./types.js";
+import { TaskStore } from "./handler.js";
+
+function makeTask(overrides: Partial<DelegatedTask> = {}): DelegatedTask {
+	return {
+		sessionId: `sess-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+		title: "Test task",
+		task: "Do something useful",
+		projectPath: "/tmp/test",
+		dispatchedAt: Date.now(),
+		status: "idle",
+		...overrides,
+	};
+}
+
+describe("TaskStore.buildPrompt()", () => {
+	let tempDir: string;
+
+	afterEach(() => {
+		if (tempDir && fs.existsSync(tempDir)) {
+			fs.rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it("includes stopped tasks in prompt (by design, for re-activation)", () => {
+		tempDir = path.join(os.tmpdir(), `coordinator-test-${Date.now()}`);
+		fs.mkdirSync(tempDir, { recursive: true });
+
+		const store = new TaskStore(tempDir);
+		const task = makeTask({ title: "Re-activatable task", sessionId: "sess-stopped-1" });
+		store.add(task);
+		store.update("sess-stopped-1", { status: "stopped" });
+
+		const prompt = store.buildPrompt();
+
+		expect(prompt).toContain("Re-activatable task");
+		expect(prompt).toContain("STOPPED");
+	});
+
+	it("includes completed tasks in prompt (by design, for re-activation)", () => {
+		tempDir = path.join(os.tmpdir(), `coordinator-test-${Date.now()}`);
+		fs.mkdirSync(tempDir, { recursive: true });
+
+		const store = new TaskStore(tempDir);
+		const task = makeTask({
+			title: "Completed task still visible",
+			sessionId: "sess-completed-1",
+			status: "completed",
+			completedAt: Date.now(),
+			result: "Did the thing",
+		});
+		store.add(task);
+
+		const prompt = store.buildPrompt();
+
+		expect(prompt).toContain("Completed task still visible");
+		expect(prompt).toContain("DONE");
+	});
+
+	it("persists tasks across restarts and buildPrompt includes them all", () => {
+		tempDir = path.join(os.tmpdir(), `coordinator-test-${Date.now()}`);
+		fs.mkdirSync(tempDir, { recursive: true });
+
+		const store1 = new TaskStore(tempDir);
+		store1.add(makeTask({ title: "Task A", sessionId: "sess-a" }));
+		store1.add(makeTask({ title: "Task B", sessionId: "sess-b", status: "completed", completedAt: Date.now() }));
+
+		const store2 = new TaskStore(tempDir);
+		const prompt = store2.buildPrompt();
+
+		expect(prompt).toContain("Task A");
+		expect(prompt).toContain("Task B");
+		expect(prompt).toContain("DONE");
+	});
+
+	it("store.remove() exists and works when called directly", () => {
+		tempDir = path.join(os.tmpdir(), `coordinator-test-${Date.now()}`);
+		fs.mkdirSync(tempDir, { recursive: true });
+
+		const store = new TaskStore(tempDir);
+		store.add(makeTask({ sessionId: "sess-removable", title: "Can be removed" }));
+		expect(store.get("sess-removable")).toBeDefined();
+
+		store.remove("sess-removable");
+
+		expect(store.get("sess-removable")).toBeUndefined();
+		expect(store.buildPrompt()).toBe("");
+	});
+
+	it("BUG: store.remove() is never called by any channel handler or tool", () => {
+		tempDir = path.join(os.tmpdir(), `coordinator-test-${Date.now()}`);
+		fs.mkdirSync(tempDir, { recursive: true });
+
+		const handlerSource = fs.readFileSync(
+			path.join(__dirname, "handler.ts"),
+			"utf-8",
+		);
+
+		const indexSource = fs.readFileSync(
+			path.join(__dirname, "index.ts"),
+			"utf-8",
+		);
+
+		expect(
+			handlerSource.includes("remove("),
+			"TaskStore.remove() method exists in handler.ts",
+		).toBe(true);
+
+		const handlerBodies: string[] = [];
+		const handlePattern = /channel\.handle\("([^"]+)",\s*async\s*\([^)]*\)\s*=>\s*\{/g;
+		let match;
+		while ((match = handlePattern.exec(handlerSource)) !== null) {
+			const startIdx = match.index + match[0].length;
+			let braceCount = 1;
+			let endIdx = startIdx;
+			while (braceCount > 0 && endIdx < handlerSource.length) {
+				if (handlerSource[endIdx] === "{") braceCount++;
+				else if (handlerSource[endIdx] === "}") braceCount--;
+				endIdx++;
+			}
+			handlerBodies.push(handlerSource.slice(startIdx, endIdx));
+		}
+
+		for (const body of handlerBodies) {
+			expect(
+				body.includes("remove("),
+				"No channel.handle() body should call remove()",
+			).toBe(false);
+		}
+
+		expect(
+			indexSource.includes(".remove("),
+			"BUG: index.ts never calls store.remove() - no tool/command exposes removal",
+		).toBe(false);
+	});
+
+	it("session_delegate_stop only sets status=stopped, does not remove task", () => {
+		tempDir = path.join(os.tmpdir(), `coordinator-test-${Date.now()}`);
+		fs.mkdirSync(tempDir, { recursive: true });
+
+		const store = new TaskStore(tempDir);
+		store.add(makeTask({ sessionId: "sess-stop-test", title: "Accumulated task" }));
+		store.update("sess-stop-test", { status: "stopped" });
+
+		const task = store.get("sess-stop-test");
+		expect(task).toBeDefined();
+		expect(task?.status).toBe("stopped");
+
+		const prompt = store.buildPrompt();
+		expect(prompt).toContain("Accumulated task");
+		expect(prompt).toContain("STOPPED");
+	});
+
+	it("BUG: no tool or command exposes remove functionality to LLM or user", () => {
+		const indexSource = fs.readFileSync(
+			path.join(__dirname, "index.ts"),
+			"utf-8",
+		);
+
+		const registeredTools: string[] = [];
+		const toolPattern = /pi\.registerTool\(\{[^}]*name:\s*"([^"]+)"/g;
+		let match;
+		while ((match = toolPattern.exec(indexSource)) !== null) {
+			registeredTools.push(match[1]);
+		}
+
+		const registeredCommands: string[] = [];
+		const cmdPattern = /pi\.registerCommand\(\s*"([^"]+)"/g;
+		while ((match = cmdPattern.exec(indexSource)) !== null) {
+			registeredCommands.push(match[1]);
+		}
+
+		const removalToolNames = [
+			"session_delegate_remove",
+			"session_delegate_cleanup",
+			"session_delegate_forget",
+			"session_delegate_delete",
+		];
+
+		for (const name of removalToolNames) {
+			expect(
+				registeredTools.includes(name),
+				`BUG: No tool named "${name}" is registered`,
+			).toBe(false);
+		}
+
+		const removalCmdPatterns = [
+			"coordinator-cleanup",
+			"coordinator-remove",
+			"coordinator-forget",
+			"coordinator-clear",
+		];
+
+		for (const name of removalCmdPatterns) {
+			expect(
+				registeredCommands.includes(name),
+				`BUG: No command named "${name}" is registered`,
+			).toBe(false);
+		}
+	});
+
+	it("BUG: no automatic cleanup of tasks whose sessions no longer exist", () => {
+		tempDir = path.join(os.tmpdir(), `coordinator-test-${Date.now()}`);
+		fs.mkdirSync(tempDir, { recursive: true });
+
+		const store = new TaskStore(tempDir);
+		store.add(makeTask({
+			sessionId: "ghost-session-999",
+			title: "Ghost task",
+			status: "idle",
+		}));
+
+		const prompt = store.buildPrompt();
+		expect(prompt).toContain("ghost-session-999");
+		expect(prompt).toContain("Ghost task");
+
+		expect(store.list().length).toBe(1);
+	});
+
+	it("BUG: no age-based or context-pressure-based cleanup mechanism", () => {
+		tempDir = path.join(os.tmpdir(), `coordinator-test-${Date.now()}`);
+		fs.mkdirSync(tempDir, { recursive: true });
+
+		const store = new TaskStore(tempDir);
+		const oldTimestamp = Date.now() - 7 * 24 * 60 * 60 * 1000;
+
+		for (let i = 0; i < 20; i++) {
+			store.add(makeTask({
+				sessionId: `sess-old-${i}`,
+				title: `Old task ${i}`,
+				dispatchedAt: oldTimestamp + i * 1000,
+				status: "completed",
+				completedAt: oldTimestamp + i * 1000 + 5000,
+			}));
+		}
+
+		const allTasks = store.list();
+		expect(allTasks.length).toBe(20);
+
+		const prompt = store.buildPrompt();
+		for (let i = 0; i < 20; i++) {
+			expect(prompt).toContain(`Old task ${i}`);
+		}
+
+		const handlerSource = fs.readFileSync(
+			path.join(__dirname, "handler.ts"),
+			"utf-8",
+		);
+
+		const hasMaxAgeLogic = handlerSource.includes("maxAge") ||
+			handlerSource.includes("ttl") ||
+			handlerSource.includes("expiry") ||
+			handlerSource.includes("staleThreshold") ||
+			handlerSource.includes("cleanupInterval");
+		expect(
+			hasMaxAgeLogic,
+			"BUG: No age-based cleanup logic (maxAge/ttl/expiry) in handler.ts",
+		).toBe(false);
+
+		const indexSource = fs.readFileSync(
+			path.join(__dirname, "index.ts"),
+			"utf-8",
+		);
+		const hasContextEviction = indexSource.includes("contextPressure") ||
+			indexSource.includes("evict") ||
+			indexSource.includes("tokenBudget") ||
+			indexSource.includes("maxContextTasks");
+		expect(
+			hasContextEviction,
+			"BUG: No context-pressure-based eviction logic in index.ts",
+		).toBe(false);
+	});
+});