@hheei/pi-subagents 0.7.0 → 0.8.0

package/dist/tools.js

@@ -2,48 +2,64 @@ import { textToolResult } from "@hheei/pi-ext-core";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { isOperationError } from "./domain.js";
-import { contactParentRenderers, parentToolRenderers, } from "./tool-presentation.js";
-const spawnSchema = Type.Object({
-    task: Type.String({ minLength: 1 }),
-    agent: Type.String({
+import { contactParentRenderers, parentToolRenderers } from "./tool-presentation.js";
+/**
+ * A failed operation still tells the caller what it may have already done: the identity it was
+ * about, whether retrying is safe, and which side effects to check.
+ */
+function operationErrorText(error) {
+    const details = [
+        ...(error.childId === undefined ? [] : [`id ${error.childId}`]),
+        `safeToRetry ${error.safeToRetry}`,
+        ...(error.sideEffects.length === 0 ? [] : [`sideEffects ${error.sideEffects.join(", ")}`]),
+    ];
+    return `${error.reason} (${details.join("; ")})`;
+}
+const delegateSchema = Type.Object({
+    task: Type.String({
         minLength: 1,
-        description: "Agent name from <available_agents> in this tool description.",
+        description: "Work to perform in the selected agent session.",
     }),
-    cwd: Type.Optional(Type.String()),
-    title: Type.Optional(Type.String({
-        maxLength: 60,
-        description: "Short session title for this child, e.g. 'OVITO properties editor'. It becomes the child's Pi session title, prefixed with a robot marker so delegated sessions stay recognizable; omit it — or leave it blank — to derive one from the agent name and child id.",
+    wait: Type.Optional(Type.Boolean({
+        description: "Wait for the final result (default true). False returns the accepted delegation immediately, and its result is delivered automatically when it finishes.",
     })),
-}, { additionalProperties: false });
-const sendSchema = Type.Object({
-    id: Type.String({ minLength: 1, description: "Subagent id, e.g. agent-1" }),
-    message: Type.String({ minLength: 1 }),
-    mode: Type.Optional(Type.Union([Type.Literal("steer"), Type.Literal("follow_up")], {
-        description: "steer (the default) enters the child's current turn once its tool calls are in, before the next model request, so it redirects work already in flight; an idle child just starts a run. follow_up waits until the child has no tool calls or steering left, then continues as a new turn. Use follow_up for work that must not interrupt what the child is doing now.",
+    id: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Existing agent id, e.g. agent-1. Takes precedence over agent and reuses its session.",
     })),
-});
-const idSchema = Type.Object({
-    id: Type.String({ minLength: 1, description: "Subagent id, e.g. agent-1" }),
-});
+    agent: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Agent name from <available_agents> for a new agent. Ignored with id.",
+    })),
+    cwd: Type.Optional(Type.String({ description: "Working directory for a new agent; ignored with id." })),
+}, { additionalProperties: false });
 const getSchema = Type.Object({
-    id: Type.String({ minLength: 1, description: "Subagent id, e.g. agent-1" }),
-    keys: Type.Optional(Type.String({
-        description: "Comma-separated fields to return. Defaults to 'status,progress'. Allowed: status, progress, diagnostic.",
+    id: Type.String({ minLength: 1, description: "Agent id, e.g. agent-1" }),
+    revision: Type.Optional(Type.Integer({
+        minimum: 1,
+        description: "Delegation revision of this agent. Defaults to the newest one.",
     })),
+    includeOutput: Type.Optional(Type.Boolean({
+        description: "Return the delegation's result body, bounded by the shared output budget. Defaults to false.",
+    })),
+}, { additionalProperties: false });
+const idSchema = Type.Object({
+    id: Type.String({ minLength: 1, description: "Agent id, e.g. agent-1" }),
 });
+const dashboardSchema = Type.Object({}, { additionalProperties: false });
 const contactSchema = Type.Object({
     message: Type.String({
         minLength: 1,
         description: "Explanation of what is blocking progress or the error encountered.",
     }),
     reason: Type.Optional(Type.Union([Type.Literal("blocked"), Type.Literal("error")], {
-        description: "Reason: 'blocked' if waiting for input/guidance (can be resumed via agent_send), or 'error' if the turn failed (you may retry via agent_send or create a new child). Defaults to 'blocked'.",
+        description: "Reason: 'blocked' if waiting for input/guidance (can be resumed via agents_delegate with this id), or 'error' if the turn failed (you may retry or create a new agent). Defaults to 'blocked'.",
     })),
 });
 const SUBAGENTS_NAMESPACE = {
-    name: "agent",
+    name: "agents",
     aliases: ["agent", "agents", "subagent", "subagents"],
-    description: "Subagent orchestration and delegation tools",
+    description: "Agent orchestration and delegation tools",
 };
 export function formatAvailableAgents(agents) {
     const available = agents
@@ -59,124 +75,58 @@ export function formatAvailableAgents(agents) {
         "</available_agents>",
     ].join("\n");
 }
-function getSpawnDescription(agents) {
+function getDelegateDescription(agents) {
     return [
-        "Spawn an independent background subagent task to work on a goal asynchronously. Choose an agent from <available_agents> below.",
-        "Returns JSON { id, path }, where path is the absolute child session file path; the first write may still be pending.",
-        "Results are returned automatically to this parent session when the task finishes. After spawning, do independent work or end your turn; do not poll agent_get.",
-        "Related subagent tools: agent_send, agent_get, agent_stop.",
+        "Delegate work to a new or existing agent. Supply agent to start a new session, or id to continue an existing one; with both, id wins and agent is ignored.",
+        "Returns { id, revision, status, hasOutput }: revision identifies this delegation of that agent, and a finished delegation carries its result when wait is true. Results are delivered automatically when the task finishes, so do independent work or end your turn instead of polling agents_get.",
+        "Related agent tools: agents_get, agents_stop, agents_dashboard.",
         formatAvailableAgents(agents),
     ].join("\n");
 }
-const SEND_DESCRIPTION = "Send input to an existing subagent (e.g. 'agent-1'), resuming its session when it is idle, blocked, done, or errored. A child whose runtime has ended is resumed the same way: send to that id, do not spawn a replacement. Stop it first only when send reports the previous process is still running. Results are returned automatically when the task finishes; do not poll agent_get. Related subagent tools: agent_spawn, agent_get, agent_stop.";
-const GET_DESCRIPTION = "Inspect one subagent's status, progress, or diagnostic details by id (e.g. 'agent-1'). Use keys to choose fields; defaults to 'status,progress'. Results are returned automatically; use this for inspection, not completion polling. Related subagent tools: agent_spawn, agent_send, agent_stop.";
-const STOP_DESCRIPTION = "Stop a subagent's runtime by id (e.g. 'agent-1'). The child keeps its session, so a later agent_send can resume it. Related subagent tools: agent_spawn, agent_send, agent_get.";
+const GET_DESCRIPTION = "Read one agent delegation: the newest by default, or one revision, with its result body when includeOutput is true. Use it for inspection, not completion polling. Related agent tools: agents_delegate, agents_stop, agents_dashboard.";
+const STOP_DESCRIPTION = "Stop an agent runtime by id (e.g. 'agent-1'). Open delegations end as failed; finished results and the session are kept, so a later agents_delegate with this id resumes it. Related agent tools: agents_delegate, agents_get, agents_dashboard.";
+const DASHBOARD_DESCRIPTION = "List this session's agents with their runtime state and latest delegation. Related agent tools: agents_delegate, agents_get, agents_stop.";
 const CONTACT_DESCRIPTION = "Notify the parent session when you are BLOCKED and cannot continue without parent decision or intervention. Do NOT call this on success or task completion: simply output your final answer directly as normal text in your response, and the harness will automatically capture and report your result to the parent.";
 const CONTACT_SNIPPET = "Report a blocker to the parent. Do NOT call on success: write normal text to finish.";
 const CONTACT_GUIDELINES = [
     "Use contact_parent ONLY if you are blocked or urgently require a parent decision midway.",
     "Do NOT use contact_parent to deliver final findings or report success: output normal text instead.",
-    "After reporting a blocker, wait for a parent agent_send instruction.",
+    "After reporting a blocker, wait for a parent agents_delegate instruction.",
 ];
-const GET_KEYS = ["status", "progress", "diagnostic"];
-/** Parses the comma-separated `keys` argument; empty means the default view. */
-function parseAgentGetKeys(raw) {
-    if (raw === undefined)
-        return ["status", "progress"];
-    const keys = [];
-    for (const part of raw.split(",")) {
-        const key = part.trim();
-        if (key === "")
-            continue;
-        if (!GET_KEYS.includes(key)) {
-            throw new Error(`Unknown agent_get key "${key}". Allowed keys: ${GET_KEYS.join(", ")}.`);
-        }
-        if (!keys.includes(key))
-            keys.push(key);
-    }
-    return keys.length > 0 ? keys : ["status", "progress"];
-}
-function childAgentDetails(child, keys) {
-    const view = {};
-    if (keys.includes("status"))
-        view.status = child.state;
-    if (keys.includes("progress")) {
-        view.progress = {
-            agent: child.agent,
-            ...(child.path === undefined ? {} : { path: child.path }),
-            presentation: child.presentation,
-            freshness: child.freshness,
-            ...(child.activeTool === undefined ? {} : { activeTool: child.activeTool.slice(0, 200) }),
-            ...(child.state !== "running" || child.summary === undefined
-                ? {}
-                : { summary: child.summary.slice(0, 2000) }),
-            ...(child.usage === undefined
-                ? {}
-                : { turns: child.usage.turns, tokens: child.usage.inputTokens + child.usage.outputTokens }),
-        };
-    }
-    if (keys.includes("diagnostic")) {
-        const diagnostic = child.interrupted ??
-            (child.state === "blocked" || child.state === "error" ? child.summary : undefined) ??
-            (child.freshness === "last_known" ? "Runtime disconnected; state is last known" : undefined);
-        if (diagnostic !== undefined)
-            view.diagnostic = diagnostic.slice(0, 2000);
-    }
-    return view;
-}
 export function registerParentTools(pi, manager, agents) {
     const renderers = parentToolRenderers(pi);
-    const inspectedTasks = new Set();
+    const inspected = new Set();
+    /** The same inspection twice in a row is polling, and polling never gets the answer faster. */
     function inspectionResult(id, text, details) {
-        const repeated = inspectedTasks.has(id);
-        inspectedTasks.add(id);
-        return textToolResult(repeated ? `${text}\nResults are returned automatically; do not poll agent_get.` : text, details);
+        const repeated = inspected.has(id);
+        inspected.add(id);
+        return textToolResult(repeated ? `${text}\nResults are delivered automatically; do not poll agents_get.` : text, details);
     }
-    const spawn = {
-        name: "agent_spawn",
+    const delegate = {
+        name: "agents_delegate",
         namespace: SUBAGENTS_NAMESPACE,
-        label: "Spawn agent",
-        description: getSpawnDescription(agents),
-        parameters: spawnSchema,
+        label: "Delegate to agent",
+        description: getDelegateDescription(agents),
+        parameters: delegateSchema,
         exposure: "deferred",
         defaultActive: false,
         annotations: {
             openWorldHint: true,
         },
-        async execute(_id, params) {
-            if (!Value.Check(spawnSchema, params))
-                throw new Error("Invalid agent_spawn parameters");
-            const spawned = await manager.spawn(params);
-            if (isOperationError(spawned))
-                throw new Error(spawned.reason);
-            const { id } = spawned.child;
-            const { path } = spawned;
-            const details = { id, path };
-            return textToolResult(JSON.stringify(details), details);
+        async execute(_id, params, signal, onUpdate) {
+            if (!Value.Check(delegateSchema, params))
+                throw new Error("Invalid agents_delegate parameters");
+            const view = await manager.delegate(params, signal, (accepted) => {
+                onUpdate?.(textToolResult(JSON.stringify(accepted), accepted));
+            });
+            if (isOperationError(view))
+                throw new Error(operationErrorText(view));
+            return textToolResult(JSON.stringify(view), view);
         },
-        ...renderers.spawn,
-    };
-    const send = {
-        name: "agent_send",
-        namespace: SUBAGENTS_NAMESPACE,
-        label: "Send to agent",
-        description: SEND_DESCRIPTION,
-        parameters: sendSchema,
-        exposure: "deferred",
-        defaultActive: false,
-        annotations: {
-            openWorldHint: true,
-        },
-        async execute(_id, params, signal) {
-            const sent = await manager.send(params.id, params.message, params.mode, signal);
-            if (isOperationError(sent))
-                throw new Error(sent.reason);
-            return textToolResult("Message sent.", undefined);
-        },
-        ...renderers.send,
+        ...renderers.delegate,
     };
     const get = {
-        name: "agent_get",
+        name: "agents_get",
         namespace: SUBAGENTS_NAMESPACE,
         label: "Get agent",
         description: GET_DESCRIPTION,
@@ -188,17 +138,21 @@ export function registerParentTools(pi, manager, agents) {
             idempotentHint: true,
         },
         async execute(_id, params) {
-            const keys = parseAgentGetKeys(params.keys);
-            const child = await manager.get(params.id);
-            if (isOperationError(child))
-                throw new Error(child.reason);
-            const view = childAgentDetails(child, keys);
+            if (!Value.Check(getSchema, params))
+                throw new Error("Invalid agents_get parameters");
+            const view = await manager.inspect({
+                id: params.id,
+                ...(params.revision === undefined ? {} : { revision: params.revision }),
+                includeOutput: params.includeOutput === true,
+            });
+            if (isOperationError(view))
+                throw new Error(operationErrorText(view));
             return inspectionResult(params.id, JSON.stringify(view), view);
         },
         ...renderers.get,
     };
     const stop = {
-        name: "agent_stop",
+        name: "agents_stop",
         namespace: SUBAGENTS_NAMESPACE,
         label: "Stop agent",
         description: STOP_DESCRIPTION,
@@ -209,17 +163,35 @@ export function registerParentTools(pi, manager, agents) {
             destructiveHint: true,
         },
         async execute(_id, params) {
-            const stopped = await manager.stop(params.id);
-            if (isOperationError(stopped))
-                throw new Error(stopped.reason);
-            return textToolResult("Agent stopped.", undefined);
+            const view = await manager.stopAgent(params.id);
+            if (isOperationError(view))
+                throw new Error(operationErrorText(view));
+            return textToolResult(`Agent ${view.id} stopped; revision ${view.revision} is ${view.status}.`, view);
         },
         ...renderers.stop,
     };
-    pi.registerTool(spawn);
-    pi.registerTool(send);
+    const dashboard = {
+        name: "agents_dashboard",
+        namespace: SUBAGENTS_NAMESPACE,
+        label: "Agent dashboard",
+        description: DASHBOARD_DESCRIPTION,
+        parameters: dashboardSchema,
+        exposure: "deferred",
+        defaultActive: false,
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+        async execute() {
+            const view = await manager.dashboard();
+            return textToolResult(`${view.total} agents · running ${view.running} · blocked ${view.blocked} · completed ${view.completed} · failed ${view.failed}`, view);
+        },
+        ...renderers.dashboard,
+    };
+    pi.registerTool(delegate);
     pi.registerTool(get);
     pi.registerTool(stop);
+    pi.registerTool(dashboard);
 }
 export function registerChildTools(pi, identity, options) {
     const tool = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hheei/pi-subagents",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Independent background Pi subagent sessions with durable identity and RPC control.",
   "type": "module",
   "main": "dist/index.js",
@@ -11,8 +11,13 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE",
+    "LICENSES"
   ],
+  "bin": {
+    "pi-subagents-mcp": "./dist/mcp-stdio.js"
+  },
   "pi": {
     "extensions": [
       "dist/extension.js"
@@ -35,7 +40,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@hheei/pi-ext-core": "^0.6.4"
+    "@hheei/pi-ext-core": "^0.7.0",
+    "@modelcontextprotocol/server": "2.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=1.3.0",
@@ -44,9 +50,10 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "1.3.0",
-    "@earendil-works/pi-tui": "1.3.0"
+    "@earendil-works/pi-tui": "1.3.0",
+    "linkedom": "^0.18.14"
   },
   "scripts": {
-    "build": "node -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json"
+    "build": "node -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && node -e \"import { chmodSync, copyFileSync, mkdirSync } from 'node:fs'; mkdirSync('dist/mcp', { recursive: true }); copyFileSync('src/mcp/app.html', 'dist/mcp/app.html'); chmodSync('dist/mcp-stdio.js', 0o755)\""
   }
 }

package/dist/json-lines.d.ts

@@ -1,14 +0,0 @@
-import type { Readable, Writable } from "node:stream";
-export type JsonLineErrorCode = "frame_too_large" | "malformed_json" | "stream_error";
-export declare class JsonLineError extends Error {
-    readonly code: JsonLineErrorCode;
-    constructor(code: JsonLineErrorCode, message: string);
-}
-export interface JsonLineReaderOptions {
-    readonly maxFrameBytes: number;
-    readonly onValue: (value: unknown) => void;
-    readonly onError: (error: JsonLineError) => void;
-}
-export declare function attachJsonLineReader(stream: Readable, options: JsonLineReaderOptions): () => void;
-export declare function serializeJsonLine(value: unknown, maxFrameBytes: number): Buffer;
-export declare function writeJsonLine(stream: Writable, value: unknown, maxFrameBytes: number): Promise<void>;

package/dist/json-lines.js

@@ -1,95 +0,0 @@
-import { errorMessage } from "@hheei/pi-ext-core";
-export class JsonLineError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.name = "JsonLineError";
-        this.code = code;
-    }
-}
-export function attachJsonLineReader(stream, options) {
-    if (!Number.isSafeInteger(options.maxFrameBytes) || options.maxFrameBytes < 1) {
-        throw new Error("maxFrameBytes must be a positive safe integer");
-    }
-    let buffer = Buffer.alloc(0);
-    let stopped = false;
-    const fail = (error) => {
-        if (stopped)
-            return;
-        stopped = true;
-        cleanup();
-        options.onError(error);
-    };
-    const onData = (chunk) => {
-        if (stopped)
-            return;
-        const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        buffer = buffer.length === 0 ? incoming : Buffer.concat([buffer, incoming]);
-        while (!stopped) {
-            const newline = buffer.indexOf(0x0a);
-            if (newline < 0) {
-                if (buffer.length > options.maxFrameBytes) {
-                    fail(new JsonLineError("frame_too_large", "JSON line exceeds frame limit"));
-                }
-                return;
-            }
-            if (newline > options.maxFrameBytes) {
-                fail(new JsonLineError("frame_too_large", "JSON line exceeds frame limit"));
-                return;
-            }
-            let frame = buffer.subarray(0, newline);
-            buffer = buffer.subarray(newline + 1);
-            if (frame.length > 0 && frame[frame.length - 1] === 0x0d) {
-                frame = frame.subarray(0, frame.length - 1);
-            }
-            if (frame.length === 0)
-                continue;
-            try {
-                options.onValue(JSON.parse(frame.toString("utf8")));
-            }
-            catch (error) {
-                fail(new JsonLineError("malformed_json", `Malformed JSON line: ${errorMessage(error)}`));
-            }
-        }
-    };
-    const onStreamError = (error) => {
-        fail(new JsonLineError("stream_error", error.message));
-    };
-    const cleanup = () => {
-        stream.off("data", onData);
-        stream.off("error", onStreamError);
-        buffer = Buffer.alloc(0);
-    };
-    stream.on("data", onData);
-    stream.on("error", onStreamError);
-    return () => {
-        if (stopped)
-            return;
-        stopped = true;
-        cleanup();
-    };
-}
-export function serializeJsonLine(value, maxFrameBytes) {
-    const encoded = Buffer.from(`${JSON.stringify(value)}\n`, "utf8");
-    if (encoded.length - 1 > maxFrameBytes) {
-        throw new JsonLineError("frame_too_large", "Serialized JSON line exceeds frame limit");
-    }
-    return encoded;
-}
-export function writeJsonLine(stream, value, maxFrameBytes) {
-    let encoded;
-    try {
-        encoded = serializeJsonLine(value, maxFrameBytes);
-    }
-    catch (error) {
-        return Promise.reject(error);
-    }
-    return new Promise((resolve, reject) => {
-        stream.write(encoded, (error) => {
-            if (error)
-                reject(error);
-            else
-                resolve();
-        });
-    });
-}