@arhen/pi-core-subagent 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 minimalist-subagents contributors
+Forked from @ghoulm370/pi-subagent-ui (MIT, Copyright (c) 2026 ghoulm370)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# @arhen/pi-subagent
+
+[![npm version](https://img.shields.io/npm/v/%40arhen%2Fpi-subagent?color=cb3837&logo=npm)](https://www.npmjs.com/package/@arhen/pi-subagent)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://github.com/earendil-works/pi)
+
+Minimalist pi extension: **fast in-process subagents** with single / parallel / chain modes, background runs, cancellation, intercom (child↔leader) and an agent↔agent mailbox.
+
+Built for one job: delegate work to isolated subagents **without bloating the parent context**.
+
+## Design principles
+
+- **No agent files required, no discovery overhead.** The leader defines every subagent inline per call — name, system prompt, toolset. Existing files (`.agents/`, `.pi/agents/`, `~/.pi/agent/agents/`) are *looked up by name only when no inline prompt is given*; nothing is ever created or scanned per request.
+- **Two toolsets only.** Read-only (`read, grep, find, ls` — default) or write (`read, grep, find, ls, bash, edit, write` — `write: true`). No per-agent tool config surface.
+- **In-process** — children are `AgentSession`s in the same runtime. No process spawn, no context bleed.
+- **Zero parent-context injection.** No catalog, no context hook. 6 slim tools total.
+- **Throttled updates** — widget/stream updates coalesce to ~6/s; no per-event deep clones.
+- **No silent hangs** — watchdog aborts children that produce no events for 90s; per-task timeout 10min.
+
+## Install
+
+```sh
+pi install npm:@arhen/pi-subagent
+# or locally: pi install /path/to/pi-subagents
+```
+
+## Usage — the leader invents the agents
+
+Define agents inline (never creates files). If a task has **no inline `prompt`**, the extension looks up an existing file by agent name — `.agents/<name>.md` or `.pi/agents/<name>.md` (nearest project dir), then `~/.pi/agent/agents/<name>.md` — and inherits its prompt + tools. Inline params always win over the file. Model resolution: explicit `provider/model-id` (or bare id) via the pi model registry → agent-file `model` → the parent's current model → settings default.
+
+```json
+{
+  "agent": "api-reviewer",
+  "prompt": "You are a strict API reviewer. Check auth, rate limiting, and error handling. Cite file:line.",
+  "task": "Review src/api/upload.ts"
+}
+```
+
+Parallel — mixed toolsets, siblings can talk via mailbox:
+
+```json
+{
+  "allowIntercom": true,
+  "tasks": [
+    { "agent": "researcher", "prompt": "You find facts. Cite paths.", "task": "Map the auth flow", "write": false },
+    { "agent": "implementer", "prompt": "You make minimal changes.", "task": "Implement POST /api/upload", "write": true }
+  ]
+}
+```
+
+Chain — `{previous}` is replaced with the prior agent's output:
+
+```json
+{
+  "chain": [
+    { "agent": "planner", "prompt": "You write a step list.", "task": "Plan the change", "write": false },
+    { "agent": "doer", "prompt": "You follow the plan exactly.", "task": "Execute: {previous}", "write": true }
+  ]
+}
+```
+
+Background + intercom:
+
+```json
+{
+  "agent": "auditor",
+  "prompt": "You audit dependencies.",
+  "task": "Audit package.json for outdated deps",
+  "background": true,
+  "allowIntercom": true
+}
+```
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `subagent` | single / `tasks` (parallel) / `chain` (`{previous}`); `background:true` fire-and-forget; `allowIntercom:true` enables child talk tools; `notifyPerTask: true` wakes you as each task completes (default off) |
+| `subagent_status` | live per-task snapshot (non-blocking) |
+| `subagent_result` | full output of a run or one task |
+| `await_subagent` | block until a run finishes (optional `timeoutMs`) |
+| `reply_subagent` | answer a child's `ask_parent` question |
+| `subagent_cancel` | abort a running/queued run |
+
+### Per-task fields
+
+`agent` (name you invent, or an existing file's name — required), `task` (required), `prompt` (system prompt, optional — falls back to file lookup, then a minimal default), `write` (toolset, default read-only), plus optional `model` (`provider/model-id`), `thinking` (validated enum: `off|minimal|low|medium|high|xhigh|max`), `tools` (explicit allowlist, overrides everything), `maxRuntimeMs`, `id`. Top-level only: `background`, `notifyPerTask`, `allowIntercom`, `concurrency`.
+
+### Child talk tools (when `allowIntercom: true`)
+
+| Tool | Meaning |
+|---|---|
+| `ask_parent` | blocking question to the leader; parent answers via `reply_subagent` |
+| `notify_parent` | one-way message to the leader |
+| `send_agent_message` | message to a sibling subagent's mailbox (`to` = its task id, or `"leader"`) |
+| `poll_agent_messages` | drain this subagent's mailbox |
+
+## Context budget
+
+- Parent tools: 6 schemas with short descriptions. **No catalog, no context hook** — nothing injected per request.
+- Background completion: 3-line notice. Full text only via `subagent_result`.
+- Children: isolated sessions; talk tools injected only when `allowIntercom`; each child's prompt states its own task id and its siblings' so mailbox addressing works.
+
+## Development
+
+```sh
+bun install        # dev deps (typecheck/test only; runtime uses pi's bundled SDK)
+npx tsc --noEmit
+bun test           # pure-logic smoke tests (mailbox, failure classification, watchdog)
+```
+
+Runtime state: runs persist to `<parent-session>.subagents.json` sidecar; restored (non-terminal → aborted) on session start.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@arhen/pi-core-subagent",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "pi extension: fast in-process subagents with single/parallel/chain, background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package",
+    "subagent",
+    "agent-orchestration"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-agent-core": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
+    "typebox": "^1.3.14"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arhen/pi-subagent.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/agents.ts

@@ -0,0 +1,70 @@
+/**
+ * Optional agent-file lookup — fallback for inline definitions.
+ *
+ * The leader defines agents inline (prompt + toolset). If a task has no inline
+ * prompt, we LOOK UP a file by agent name — never create one:
+ *   <cwd>/.agents/<name>.md        (nearest project dir first)
+ *   <cwd>/.pi/agents/<name>.md
+ *   ~/.pi/agent/agents/<name>.md   (user)
+ * First match wins; explicit inline params always override file contents.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export interface FileAgent {
+	prompt: string;
+	tools?: string[];
+	model?: string;
+	thinking?: string;
+}
+
+function projectAgentDirs(cwd: string): string[] {
+	const out: string[] = [];
+	let dir = cwd;
+	for (;;) {
+		for (const sub of [".agents", path.join(".pi", "agents")]) {
+			const candidate = path.join(dir, sub);
+			try {
+				if (fs.statSync(candidate).isDirectory()) out.push(candidate);
+			} catch {
+				/* missing dir is fine */
+			}
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return out;
+}
+
+export function lookupAgent(name: string, cwd: string): FileAgent | undefined {
+	const dirs = [...projectAgentDirs(cwd), path.join(getAgentDir(), "agents")];
+	for (const dir of dirs) {
+		const filePath = path.join(dir, `${name}.md`);
+		let content: string;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+		try {
+			const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+			if (!frontmatter.name || frontmatter.name !== name) continue;
+			const tools = frontmatter.tools
+				?.split(",")
+				.map((t) => t.trim())
+				.filter(Boolean);
+			return {
+				prompt: body,
+				tools: tools && tools.length > 0 ? tools : undefined,
+				model: frontmatter.model,
+				thinking: frontmatter.thinking,
+			};
+		} catch {
+			continue;
+		}
+	}
+	return undefined;
+}

package/src/child.ts

@@ -0,0 +1,153 @@
+/**
+ * Child-session tools + watchdog.
+ *
+ * When `allowIntercom: true`, children get four talk tools:
+ *   - ask_parent            blocking Q&A with the leader (parent)
+ *   - notify_parent         one-way message to the leader
+ *   - send_agent_message    one-way message to another subagent's mailbox
+ *                           (`to` = target task id in this run, or "leader")
+ *   - poll_agent_messages   drain this subagent's mailbox
+ *
+ * Mailbox is a plain map in the manager; agents talk by polling, not push.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export interface MailboxMessage {
+	from: string;
+	text: string;
+	at: number;
+}
+
+/** Child talk tools injected when allowIntercom: true. */
+export const CHILD_TALK_TOOLS = ["ask_parent", "notify_parent", "send_agent_message", "poll_agent_messages"] as const;
+
+export interface ChildHandlers {
+	onAskParent(taskId: string, question: string): Promise<string>;
+	onNotifyParent(taskId: string, message: string, level: "info" | "warning" | "error"): void;
+	/** Route a child→child message. Returns false when the target is unknown. */
+	onSendMessage(taskId: string, to: string, text: string): boolean;
+	/** Drain the mailbox (returns and clears pending messages). */
+	onPollMailbox(taskId: string): MailboxMessage[];
+}
+
+export function createChildTools(taskId: string, handlers: ChildHandlers): ToolDefinition[] {
+	return [
+		{
+			name: "ask_parent",
+			label: "Ask Parent",
+			description:
+				"Ask the parent agent a clarifying question and BLOCK until it replies. Use sparingly — only when you truly cannot proceed without information only the parent has. Prefer figuring it out yourself.",
+			promptSnippet: "Ask the parent agent a question when truly blocked.",
+			promptGuidelines: [
+				"Use ask_parent only as a last resort when blocked on information only the parent has.",
+				"Ask one focused question at a time. The parent's reply resumes your work.",
+			],
+			parameters: Type.Object({
+				question: Type.String({ description: "A single, focused question for the parent agent" }),
+			}),
+			async execute(_toolCallId, params) {
+				const { question } = params as { question: string };
+				const answer = await handlers.onAskParent(taskId, question);
+				return { content: [{ type: "text" as const, text: answer || "(parent gave no answer)" }], details: {} };
+			},
+		},
+		{
+			name: "notify_parent",
+			label: "Notify Parent",
+			description: "Send a non-blocking message to the parent agent (a finding, a risk, a heads-up). Your run continues immediately; the parent sees it on its next turn.",
+			promptSnippet: "Send the parent a non-blocking update or finding.",
+			parameters: Type.Object({
+				message: Type.String({ description: "The message content for the parent" }),
+				level: Type.Optional(StringEnum(["info", "warning", "error"] as const, { default: "info" })),
+			}),
+			async execute(_toolCallId, params) {
+				const { message, level } = params as { message: string; level?: "info" | "warning" | "error" };
+				handlers.onNotifyParent(taskId, message, level ?? "info");
+				return { content: [{ type: "text" as const, text: "Sent." }], details: {} };
+			},
+		},
+		{
+			name: "send_agent_message",
+			label: "Send Agent Message",
+			description:
+				"Send a non-blocking message to another subagent in this run (delivered to its mailbox; it will see it via poll_agent_messages). Use 'leader' to message the parent instead. Messages are small and bounded — no long transcripts.",
+			promptSnippet: "Send a short message to a sibling subagent or the leader.",
+			parameters: Type.Object({
+				to: Type.String({ description: "Target task id of another subagent in this run (e.g. task_2), or 'leader' for the parent agent" }),
+				message: Type.String({ description: "Short message content (keep under ~500 chars)" }),
+			}),
+			async execute(_toolCallId, params) {
+				const { to, message } = params as { to: string; message: string };
+				if (!handlers.onSendMessage(taskId, to, message)) {
+					return { content: [{ type: "text" as const, text: `Unknown target '${to}'. Use a sibling task id in this run or 'leader'.` }], isError: true, details: {} };
+				}
+				return { content: [{ type: "text" as const, text: "Sent." }], details: {} };
+			},
+		},
+		{
+			name: "poll_agent_messages",
+			label: "Poll Agent Messages",
+			description: "Check your mailbox for messages from sibling subagents. Returns and clears all pending messages. Call it before acting on assumptions about other agents' results.",
+			promptSnippet: "Check for messages from other subagents.",
+			parameters: Type.Object({}),
+			async execute() {
+				const messages = handlers.onPollMailbox(taskId);
+				if (messages.length === 0) return { content: [{ type: "text" as const, text: "No messages." }], details: {} };
+				const body = messages
+					.map((m) => `from ${m.from}: ${m.text}`)
+					.join("\n")
+					.slice(0, 4000);
+				return { content: [{ type: "text" as const, text: body }], details: { messages } };
+			},
+		},
+	];
+}
+
+/**
+ * Watchdog — a subagent is "stalled" when it produces no events for stallMs.
+ * In-process AgentSessions have no process-exit signal, so we synthesize one
+ * via event-heartbeat. Every relevant child event must call touch().
+ */
+export interface Watchdog {
+	touch(): void;
+	readonly promise: Promise<never>;
+	dispose(): void;
+}
+
+export function createWatchdog(stallMs: number, label: string): Watchdog {
+	let lastEventAt = Date.now();
+	let disposed = false;
+	let timer: ReturnType<typeof setInterval> | undefined;
+
+	const promise = new Promise<never>((_, reject) => {
+		const interval = Math.max(1000, Math.min(5000, Math.floor(stallMs / 4)));
+		timer = setInterval(() => {
+			if (disposed) return;
+			if (Date.now() - lastEventAt > stallMs) {
+				disposed = true;
+				if (timer) clearInterval(timer);
+				timer = undefined;
+				reject(new Error(`${label} stalled: no activity for ${Math.round(stallMs / 1000)}s`));
+			}
+		}, interval);
+		timer.unref?.();
+	});
+
+	return {
+		touch() {
+			lastEventAt = Date.now();
+		},
+		promise,
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			if (timer) {
+				clearInterval(timer);
+				timer = undefined;
+			}
+		},
+	};
+}