@tintinweb/pi-subagents 0.4.11 → 0.5.0

package/CHANGELOG.md

@@ -5,22 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.4.11] - 2026-03-18
+## [Unreleased]
 
-### Fixed
-- **Stale dist in published package** — added `prepublishOnly` hook to build fresh `dist/` on every `npm publish`.
-
-## [0.4.10] - 2026-03-18
-
-### Changed
-- **Default max turns is now unlimited** — subagents no longer have a 50-turn default cap. The default is unlimited (no turn limit), matching Claude Code's main loop behavior. Users can still set explicit limits per-agent via `max_turns` frontmatter or the Agent tool parameter, or globally via `/agents` → Settings (`0` = unlimited).
-- **Live turn counter** — all agents now show a live turn count in the widget, inline result, and completion notification. With a turn limit: `⟳5≤30` (5 of 30 turns). Without: `⟳5`. Updates in real time as turns progress.
+## [0.5.0] - 2026-03-22
 
 ### Added
+- **RPC stop handler** — new `subagents:rpc:stop` event bus RPC allows other extensions to stop running subagents by agent ID. Returns structured error ("Agent not found") on failure.
+- **`abort` in `SpawnCapable` interface** — cross-extension RPC consumers can now stop agents, not just spawn them.
+- **Live turn counter** — all agents now show a live turn count in the widget, inline result, and completion notification. With a turn limit: `⟳5≤30` (5 of 30 turns). Without: `⟳5`. Updates in real time as turns progress via `onTurnEnd` callback.
 - **Biome linting** — added [Biome](https://biomejs.dev/) for correctness linting (unused imports, suspicious patterns). Style rules disabled. Run `npm run lint` to check, `npm run lint:fix` to auto-fix.
 - **CI workflow** — GitHub Actions runs lint, typecheck, and tests on push to master and PRs.
+- **Auto-trigger parent turn on background completion** — background agent completion notifications now use `triggerTurn: true`, automatically prompting the parent agent to process results instead of waiting for user input.
+
+### Changed
+- **Standardized RPC envelope** — cross-extension RPC handlers (`ping`, `spawn`, `stop`) now use a `handleRpc` wrapper that emits structured envelopes (`{ success: true, data }` / `{ success: false, error }`), matching pi-mono's `RpcResponse` convention.
+- **Protocol versioning via ping** — ping reply now includes `{ version: PROTOCOL_VERSION }` (currently v2). Callers can detect version mismatches and warn users to update.
+- **Default max turns is now unlimited** — subagents no longer have a 50-turn default cap. The default is unlimited (no turn limit), matching Claude Code's main loop behavior. Users can still set explicit limits per-agent via `max_turns` frontmatter or the Agent tool parameter, or globally via `/agents` → Settings (`0` = unlimited).
+- **Stale dist in published package** — added `prepublishOnly` hook to build fresh `dist/` on every `npm publish`.
 
 ### Fixed
+- **Tool name display** — `getAgentConversation` now reads `ToolCall.name` (the correct property) instead of `toolName`, resolving `[Tool: unknown]` in conversation viewer and verbose output.
 - **Env test CI failure** — `detectEnv` test assumed a branch name exists, but CI checks out detached HEAD. Split into separate tests for repo detection and branch detection with a controlled temp repo.
 
 ## [0.4.9] - 2026-03-18
@@ -325,6 +329,7 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.5.0]: https://github.com/tintinweb/pi-subagents/compare/v0.4.9...v0.5.0
 [0.4.9]: https://github.com/tintinweb/pi-subagents/compare/v0.4.8...v0.4.9
 [0.4.8]: https://github.com/tintinweb/pi-subagents/compare/v0.4.7...v0.4.8
 [0.4.7]: https://github.com/tintinweb/pi-subagents/compare/v0.4.6...v0.4.7

package/README.md

@@ -29,7 +29,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
 - **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show full output. Group completions render each agent individually
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
-- **Cross-extension RPC** — other pi extensions can spawn subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`). Emits `subagents:ready` on load
+- **Cross-extension RPC** — other pi extensions can spawn and stop subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`). Standardized reply envelopes with protocol versioning. Emits `subagents:ready` on load
 
 ## Install
 
@@ -289,7 +289,9 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 
 ## Cross-Extension RPC
 
-Other pi extensions can spawn subagents programmatically via the `pi.events` event bus, without importing this package directly.
+Other pi extensions can spawn and stop subagents programmatically via the `pi.events` event bus, without importing this package directly.
+
+All RPC replies use a standardized envelope: `{ success: true, data?: T }` on success, `{ success: false, error: string }` on failure.
 
 ### Discovery
 
@@ -297,19 +299,19 @@ Listen for `subagents:ready` to know when RPC handlers are available:
 
 ```typescript
 pi.events.on("subagents:ready", () => {
-  // RPC handlers are registered — safe to call ping/spawn
+  // RPC handlers are registered — safe to call ping/spawn/stop
 });
 ```
 
 ### Ping
 
-Check if the subagents extension is loaded:
+Check if the subagents extension is loaded and get the protocol version:
 
 ```typescript
 const requestId = crypto.randomUUID();
-const unsub = pi.events.on(`subagents:rpc:ping:reply:${requestId}`, () => {
+const unsub = pi.events.on(`subagents:rpc:ping:reply:${requestId}`, (reply) => {
   unsub();
-  // Extension is alive
+  if (reply.success) console.log("Protocol version:", reply.data.version);
 });
 pi.events.emit("subagents:rpc:ping", { requestId });
 ```
@@ -322,10 +324,10 @@ Spawn a subagent and receive its ID:
 const requestId = crypto.randomUUID();
 const unsub = pi.events.on(`subagents:rpc:spawn:reply:${requestId}`, (reply) => {
   unsub();
-  if (reply.error) {
+  if (!reply.success) {
     console.error("Spawn failed:", reply.error);
   } else {
-    console.log("Agent ID:", reply.id);
+    console.log("Agent ID:", reply.data.id);
   }
 });
 pi.events.emit("subagents:rpc:spawn", {
@@ -336,6 +338,19 @@ pi.events.emit("subagents:rpc:spawn", {
 });
 ```
 
+### Stop
+
+Stop a running agent by ID:
+
+```typescript
+const requestId = crypto.randomUUID();
+const unsub = pi.events.on(`subagents:rpc:stop:reply:${requestId}`, (reply) => {
+  unsub();
+  if (!reply.success) console.error("Stop failed:", reply.error);
+});
+pi.events.emit("subagents:rpc:stop", { requestId, agentId: "agent-id-here" });
+```
+
 Reply channels are scoped per `requestId`, so concurrent requests don't interfere.
 
 ## Persistent Agent Memory

package/dist/agent-runner.js

@@ -302,7 +302,7 @@ export function getAgentConversation(session) {
                 if (c.type === "text" && c.text)
                     textParts.push(c.text);
                 else if (c.type === "toolCall")
-                    toolCalls.push(`  Tool: ${c.toolName ?? "unknown"}`);
+                    toolCalls.push(`  Tool: ${c.name ?? c.toolName ?? "unknown"}`);
             }
             if (textParts.length > 0)
                 parts.push(`[Assistant]: ${textParts.join("\n")}`);

package/dist/cross-extension-rpc.d.ts

@@ -1,17 +1,32 @@
 /**
  * Cross-extension RPC handlers for the subagents extension.
  *
- * Exposes ping and spawn RPCs over the pi.events event bus,
+ * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
  * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
  */
 /** Minimal event bus interface needed by the RPC handlers. */
 export interface EventBus {
     on(event: string, handler: (data: unknown) => void): () => void;
     emit(event: string, data: unknown): void;
 }
-/** Minimal AgentManager interface needed by the spawn RPC. */
+/** RPC reply envelope — matches pi-mono's RpcResponse shape. */
+export type RpcReply<T = void> = {
+    success: true;
+    data?: T;
+} | {
+    success: false;
+    error: string;
+};
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export declare const PROTOCOL_VERSION = 2;
+/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
 export interface SpawnCapable {
     spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
+    abort(id: string): boolean;
 }
 export interface RpcDeps {
     events: EventBus;
@@ -22,9 +37,10 @@ export interface RpcDeps {
 export interface RpcHandle {
     unsubPing: () => void;
     unsubSpawn: () => void;
+    unsubStop: () => void;
 }
 /**
- * Register ping and spawn RPC handlers on the event bus.
+ * Register ping, spawn, and stop RPC handlers on the event bus.
  * Returns unsub functions for cleanup.
  */
 export declare function registerRpcHandlers(deps: RpcDeps): RpcHandle;

package/dist/cross-extension-rpc.js

@@ -1,33 +1,54 @@
 /**
  * Cross-extension RPC handlers for the subagents extension.
  *
- * Exposes ping and spawn RPCs over the pi.events event bus,
+ * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
  * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
  */
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export const PROTOCOL_VERSION = 2;
 /**
- * Register ping and spawn RPC handlers on the event bus.
+ * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
+ * emit the reply envelope on `channel:reply:${requestId}`.
+ */
+function handleRpc(events, channel, fn) {
+    return events.on(channel, async (raw) => {
+        const params = raw;
+        try {
+            const data = await fn(params);
+            const reply = { success: true };
+            if (data !== undefined)
+                reply.data = data;
+            events.emit(`${channel}:reply:${params.requestId}`, reply);
+        }
+        catch (err) {
+            events.emit(`${channel}:reply:${params.requestId}`, {
+                success: false, error: err?.message ?? String(err),
+            });
+        }
+    });
+}
+/**
+ * Register ping, spawn, and stop RPC handlers on the event bus.
  * Returns unsub functions for cleanup.
  */
 export function registerRpcHandlers(deps) {
     const { events, pi, getCtx, manager } = deps;
-    const unsubPing = events.on("subagents:rpc:ping", (raw) => {
-        const { requestId } = raw;
-        events.emit(`subagents:rpc:ping:reply:${requestId}`, {});
+    const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
+        return { version: PROTOCOL_VERSION };
     });
-    const unsubSpawn = events.on("subagents:rpc:spawn", async (raw) => {
-        const { requestId, type, prompt, options } = raw;
+    const unsubSpawn = handleRpc(events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
         const ctx = getCtx();
-        if (!ctx) {
-            events.emit(`subagents:rpc:spawn:reply:${requestId}`, { error: "No active session" });
-            return;
-        }
-        try {
-            const id = manager.spawn(pi, ctx, type, prompt, options ?? {});
-            events.emit(`subagents:rpc:spawn:reply:${requestId}`, { id });
-        }
-        catch (err) {
-            events.emit(`subagents:rpc:spawn:reply:${requestId}`, { error: err.message });
-        }
+        if (!ctx)
+            throw new Error("No active session");
+        return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
+    });
+    const unsubStop = handleRpc(events, "subagents:rpc:stop", ({ agentId }) => {
+        if (!manager.abort(agentId))
+            throw new Error("Agent not found");
     });
-    return { unsubPing, unsubSpawn };
+    return { unsubPing, unsubSpawn, unsubStop };
 }

package/dist/index.js

@@ -254,7 +254,7 @@ export default function (pi) {
             content: notification + footer,
             display: true,
             details: buildNotificationDetails(record, 500, agentActivity.get(record.id)),
-        }, { deliverAs: "followUp" });
+        }, { deliverAs: "followUp", triggerTurn: true });
     }
     function sendIndividualNudge(record) {
         agentActivity.delete(record.id);
@@ -290,7 +290,7 @@ export default function (pi) {
                 content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
                 display: true,
                 details,
-            }, { deliverAs: "followUp" });
+            }, { deliverAs: "followUp", triggerTurn: true });
         });
         widget.update();
     }, 30_000);
@@ -383,7 +383,7 @@ export default function (pi) {
         manager.clearCompleted(); // preserve existing behavior
     });
     pi.on("session_switch", () => { manager.clearCompleted(); });
-    const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc } = registerRpcHandlers({
+    const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc, unsubStop: unsubStopRpc } = registerRpcHandlers({
         events: pi.events,
         pi,
         getCtx: () => currentCtx,
@@ -395,6 +395,7 @@ export default function (pi) {
     // If the session is going down, there's nothing left to consume agent results.
     pi.on("session_shutdown", async () => {
         unsubSpawnRpc();
+        unsubStopRpc();
         unsubPingRpc();
         currentCtx = undefined;
         delete globalThis[MANAGER_KEY];

package/dist/ui/conversation-viewer.js

@@ -179,7 +179,7 @@ export class ConversationViewer {
                     if (c.type === "text" && c.text)
                         textParts.push(c.text);
                     else if (c.type === "toolCall") {
-                        toolCalls.push(c.toolName ?? "unknown");
+                        toolCalls.push(c.name ?? c.toolName ?? "unknown");
                     }
                 }
                 if (needsSeparator)

package/dist/ui/conversation-viewer.test.js

@@ -159,7 +159,7 @@ describe("ConversationViewer", () => {
                     role: "assistant",
                     content: [
                         { type: "text", text: "Let me check that." },
-                        { type: "toolCall", toolUseId: "t1", toolName: "very_long_tool_name_" + "x".repeat(200), input: {} },
+                        { type: "toolCall", toolUseId: "t1", name: "very_long_tool_name_" + "x".repeat(200), input: {} },
                     ],
                 },
             ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",
@@ -21,9 +21,9 @@
     "autonomous"
   ],
   "dependencies": {
-    "@mariozechner/pi-ai": "^0.60.0",
-    "@mariozechner/pi-coding-agent": "^0.60.0",
-    "@mariozechner/pi-tui": "^0.60.0",
+    "@mariozechner/pi-ai": "^0.61.1",
+    "@mariozechner/pi-coding-agent": "^0.61.1",
+    "@mariozechner/pi-tui": "^0.61.1",
     "@sinclair/typebox": "latest"
   },
   "scripts": {
@@ -36,9 +36,9 @@
     "lint:fix": "biome check --fix src/ test/"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
     "@biomejs/biome": "^2.3.5",
+    "@types/node": "^25.5.0",
+    "typescript": "^5.0.0",
     "vitest": "^4.0.18"
   },
   "pi": {

package/src/agent-runner.ts

@@ -393,7 +393,7 @@ export function getAgentConversation(session: AgentSession): string {
       const toolCalls: string[] = [];
       for (const c of msg.content) {
         if (c.type === "text" && c.text) textParts.push(c.text);
-        else if (c.type === "toolCall") toolCalls.push(`  Tool: ${(c as any).toolName ?? "unknown"}`);
+        else if (c.type === "toolCall") toolCalls.push(`  Tool: ${(c as any).name ?? (c as any).toolName ?? "unknown"}`);
       }
       if (textParts.length > 0) parts.push(`[Assistant]: ${textParts.join("\n")}`);
       if (toolCalls.length > 0) parts.push(`[Tool Calls]:\n${toolCalls.join("\n")}`);

package/src/cross-extension-rpc.ts

@@ -1,8 +1,12 @@
 /**
  * Cross-extension RPC handlers for the subagents extension.
  *
- * Exposes ping and spawn RPCs over the pi.events event bus,
+ * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
  * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
  */
 
 /** Minimal event bus interface needed by the RPC handlers. */
@@ -11,9 +15,18 @@ export interface EventBus {
   emit(event: string, data: unknown): void;
 }
 
-/** Minimal AgentManager interface needed by the spawn RPC. */
+/** RPC reply envelope — matches pi-mono's RpcResponse shape. */
+export type RpcReply<T = void> =
+  | { success: true; data?: T }
+  | { success: false; error: string };
+
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export const PROTOCOL_VERSION = 2;
+
+/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
 export interface SpawnCapable {
   spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
+  abort(id: string): boolean;
 }
 
 export interface RpcDeps {
@@ -26,36 +39,57 @@ export interface RpcDeps {
 export interface RpcHandle {
   unsubPing: () => void;
   unsubSpawn: () => void;
+  unsubStop: () => void;
 }
 
 /**
- * Register ping and spawn RPC handlers on the event bus.
+ * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
+ * emit the reply envelope on `channel:reply:${requestId}`.
+ */
+function handleRpc<P extends { requestId: string }>(
+  events: EventBus,
+  channel: string,
+  fn: (params: P) => unknown | Promise<unknown>,
+): () => void {
+  return events.on(channel, async (raw: unknown) => {
+    const params = raw as P;
+    try {
+      const data = await fn(params);
+      const reply: { success: true; data?: unknown } = { success: true };
+      if (data !== undefined) reply.data = data;
+      events.emit(`${channel}:reply:${params.requestId}`, reply);
+    } catch (err: any) {
+      events.emit(`${channel}:reply:${params.requestId}`, {
+        success: false, error: err?.message ?? String(err),
+      });
+    }
+  });
+}
+
+/**
+ * Register ping, spawn, and stop RPC handlers on the event bus.
  * Returns unsub functions for cleanup.
  */
 export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
   const { events, pi, getCtx, manager } = deps;
 
-  const unsubPing = events.on("subagents:rpc:ping", (raw: unknown) => {
-    const { requestId } = raw as { requestId: string };
-    events.emit(`subagents:rpc:ping:reply:${requestId}`, {});
+  const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
+    return { version: PROTOCOL_VERSION };
   });
 
-  const unsubSpawn = events.on("subagents:rpc:spawn", async (raw: unknown) => {
-    const { requestId, type, prompt, options } = raw as {
-      requestId: string; type: string; prompt: string; options?: any;
-    };
-    const ctx = getCtx();
-    if (!ctx) {
-      events.emit(`subagents:rpc:spawn:reply:${requestId}`, { error: "No active session" });
-      return;
-    }
-    try {
-      const id = manager.spawn(pi, ctx, type, prompt, options ?? {});
-      events.emit(`subagents:rpc:spawn:reply:${requestId}`, { id });
-    } catch (err: any) {
-      events.emit(`subagents:rpc:spawn:reply:${requestId}`, { error: err.message });
-    }
-  });
+  const unsubSpawn = handleRpc<{ requestId: string; type: string; prompt: string; options?: any }>(
+    events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
+      const ctx = getCtx();
+      if (!ctx) throw new Error("No active session");
+      return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
+    },
+  );
+
+  const unsubStop = handleRpc<{ requestId: string; agentId: string }>(
+    events, "subagents:rpc:stop", ({ agentId }) => {
+      if (!manager.abort(agentId)) throw new Error("Agent not found");
+    },
+  );
 
-  return { unsubPing, unsubSpawn };
+  return { unsubPing, unsubSpawn, unsubStop };
 }

package/src/index.ts

@@ -289,7 +289,7 @@ export default function (pi: ExtensionAPI) {
       content: notification + footer,
       display: true,
       details: buildNotificationDetails(record, 500, agentActivity.get(record.id)),
-    }, { deliverAs: "followUp" });
+    }, { deliverAs: "followUp", triggerTurn: true });
   }
 
   function sendIndividualNudge(record: AgentRecord) {
@@ -326,7 +326,7 @@ export default function (pi: ExtensionAPI) {
           content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
           display: true,
           details,
-        }, { deliverAs: "followUp" });
+        }, { deliverAs: "followUp", triggerTurn: true });
       });
       widget.update();
     },
@@ -431,7 +431,7 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("session_switch", () => { manager.clearCompleted(); });
 
-  const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc } = registerRpcHandlers({
+  const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc, unsubStop: unsubStopRpc } = registerRpcHandlers({
     events: pi.events,
     pi,
     getCtx: () => currentCtx,
@@ -445,6 +445,7 @@ export default function (pi: ExtensionAPI) {
   // If the session is going down, there's nothing left to consume agent results.
   pi.on("session_shutdown", async () => {
     unsubSpawnRpc();
+    unsubStopRpc();
     unsubPingRpc();
     currentCtx = undefined;
     delete (globalThis as any)[MANAGER_KEY];

package/src/ui/conversation-viewer.ts

@@ -191,7 +191,7 @@ export class ConversationViewer implements Component {
         for (const c of msg.content) {
           if (c.type === "text" && c.text) textParts.push(c.text);
           else if (c.type === "toolCall") {
-            toolCalls.push((c as any).toolName ?? "unknown");
+            toolCalls.push((c as any).name ?? (c as any).toolName ?? "unknown");
           }
         }
         if (needsSeparator) lines.push(th.fg("dim", "───"));