@maxiaochao/pi-toolkit 0.9.2 → 0.9.4

package/packages/tiny-subagent/README.md

@@ -0,0 +1,128 @@
+# @maxiaochao/pi-tiny-subagent
+
+A small Pi extension that runs one fresh Pi child process for one focused prompt. It does not use the `pi-subagents` package and does not inherit the parent conversation or extensions.
+
+![Tiny Subagent production runner screenshot](docs/screenshot.png)
+
+## Why this package exists
+
+This is the toolkit's deliberately small subagent model: one persona, one focused prompt, one isolated child context. It avoids a general orchestration framework and keeps child transcript noise out of the parent context while preserving process and protocol diagnostics.
+
+## Demo
+
+![Tiny Subagent demo](docs/demo.gif)
+
+```text
+tiny_subagents({ action: "list" })
+tiny_subagents({
+  agent: "worker",
+  prompt: "Inspect the authentication flow and summarize the risks"
+})
+```
+
+The child receives package-local persona instructions, selected built-in tools, and a fresh context; the parent receives the focused result or structured failure details.
+
+## Install
+
+```bash
+pi install npm:@maxiaochao/pi-tiny-subagent
+```
+
+The full `@maxiaochao/pi-toolkit` package also bundles this extension. Install the full toolkit or this standalone child package, not both.
+
+Update the distribution you installed:
+
+```bash
+pi update npm:@maxiaochao/pi-toolkit       # bundled copy
+pi update npm:@maxiaochao/pi-tiny-subagent # standalone child
+```
+
+The versions are independent. Publishing the child does not update an already published toolkit version.
+
+The package registers one tool: `tiny_subagents`.
+
+## Personas
+
+The default `agents/worker.md` has this shape:
+
+```md
+---
+name: worker
+description: General-purpose worker for one focused task
+tools: read, bash, edit, write, grep, find, ls
+---
+
+You are a focused worker subagent.
+```
+
+The supported frontmatter fields are:
+
+- `name` (required): Persona name passed in the `agent` field.
+- `description` (required): Short description returned by `action: "list"` so the parent model can choose a persona.
+- `model` (optional): Default child model, such as `provider/model:high`. A call-level `model` overrides it; if both are absent, the child inherits the current parent-session model.
+- `tools` (optional): Comma-separated allowlist of Pi built-in tools. Supported values are `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, and `powershell` on Windows. Extension tools such as `contact_supervisor` are not allowed. If omitted, the child uses Pi's default built-in tools.
+
+For example, a read-only reviewer persona can restrict its tools and select a default model:
+
+```md
+---
+name: reviewer
+description: Review code and report correctness risks without modifying files
+model: provider/model:high
+tools: read, grep, find, ls
+---
+
+Review the assigned code. Do not edit files.
+```
+
+Persona files are loaded only from this package's `agents/*.md`; they do not share configuration with `pi-subagents`.
+
+Before execution, the parent model should discover the package-local personas:
+
+```text
+tiny_subagents({ action: "list" })
+```
+
+It can then match the task to a persona by name or description and execute without `action`:
+
+```text
+tiny_subagents({
+  agent: "worker",
+  prompt: "Inspect the authentication flow and summarize the risks"
+})
+```
+
+## Execution
+
+The child is started in the current working directory with a fresh context:
+
+```text
+pi --mode json --print --no-session --no-extensions --no-skills
+```
+
+The selected persona body is passed as an additional system prompt. Only built-in Pi tools can be enabled by `tools` in the persona file.
+
+## Live output
+
+`tiny_subagents` sends a TUI update when the child starts and after each child `message_end` or `tool_result_end` event. While the child is running, the collapsed row shows the latest activity.
+
+Press Pi's `Ctrl+O` tool-output expansion key to inspect the current child execution. The expanded `tiny_subagents` view shows:
+
+- selected persona name and description
+- selected model
+- the task prompt
+- the persona system prompt
+- child assistant tool calls, tool results, and assistant text
+- the final output and errors
+
+This uses Pi's standard tool-output expansion state, so `Ctrl+O` also changes the expanded/collapsed display state of other tool rows. The added content and event tracking are local to `tiny_subagents`; they do not change other tools or the parent model context.
+
+## Errors and large output
+
+Successful calls return the final assistant text. Failures return the Pi error message, stop reason, exit code, signal, stderr, protocol errors, and output produced before failure. Inline output is limited to 16 KiB. If stdout, stderr, or the final answer exceeds that size, the complete files are retained in a private temporary artifact directory and its path, byte counts, and `cleanup: "remove directory when no longer needed"` instruction are returned. Small-result temporary directories are removed automatically.
+
+The child uses the same Pi installation, provider configuration, model catalog, and authentication environment as the parent process. The package only selects the model; it does not define providers or credentials.
+
+## Development and tests
+
+The authoritative implementation is under `extensions/` and `src/`. See [TESTING.md](TESTING.md) for the test strategy, fixture cases, and latest baseline.

package/packages/tiny-subagent/TESTING.md

@@ -0,0 +1,20 @@
+# Tiny Subagent test strategy
+
+## Flow
+
+1. `npm --prefix packages/tiny-subagent test` runs deterministic process and persona tests.
+2. `pi -ne -ns --no-session -e ./packages/tiny-subagent/extensions/tiny-subagent.ts` verifies extension loading.
+3. `npm pack ./packages/tiny-subagent --dry-run` verifies package contents.
+4. Verify the README example and the production-runner media `docs/screenshot.png` and `docs/demo.gif` are present in the tarball.
+
+## Cases
+
+- Resolve package-local personas and validate frontmatter.
+- Start an isolated child Pi process with selected model and tools.
+- Stream child activity while keeping it outside the parent conversation.
+- Preserve detailed process/protocol failures and oversized artifacts.
+- Render collapsed and expanded tool output.
+
+## Latest baseline
+
+All deterministic child-process and persona cases pass. Release validation also requires the extension load check.

package/packages/tiny-subagent/agents/worker.md

@@ -0,0 +1,9 @@
+---
+name: worker
+description: General-purpose worker for one focused task
+tools: read, bash, edit, write, grep, find, ls
+---
+
+You are a focused worker subagent.
+
+Work only on the task in the user prompt. Inspect the current project before making claims. Use the available built-in tools when needed. Do not delegate to another agent. Finish with a concise result, including changes made, validation performed, and any remaining risks.

package/packages/tiny-subagent/extensions/tiny-subagent.ts

@@ -0,0 +1,228 @@
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { discoverPackageAgents } from "../src/personas.ts";
+import { runTinySubagent, type TinySubagentResult } from "../src/runner.ts";
+
+const ACTIONS = ["list"] as const;
+const TinySubagentParams = Type.Union([
+	Type.Object({
+		action: StringEnum(ACTIONS, { description: "Discover package-local personas before execution." }),
+	}),
+	Type.Object({
+		prompt: Type.String({ minLength: 1, description: "One focused prompt for the subagent." }),
+		agent: Type.Optional(Type.String({ minLength: 1, description: "Persona name selected from action=list. Defaults to worker." })),
+		model: Type.Optional(Type.String({ minLength: 1, description: "Optional Pi model, for example provider/model:high." })),
+	}),
+]);
+
+type ToolParams = {
+	action?: "list";
+	prompt?: string;
+	agent?: string;
+	model?: string;
+};
+
+const packageAgentsDir = fileURLToPath(new URL("../agents/", import.meta.url));
+
+function modelId(ctx: { model?: { provider: string; id: string } }): string | undefined {
+	return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+}
+
+function listText(discovery: ReturnType<typeof discoverPackageAgents>): string {
+	const lines = ["Available tiny-subagent personas:"];
+	if (discovery.agents.length === 0) lines.push("- (none)");
+	for (const agent of discovery.agents) {
+		const model = agent.model ?? "inherits current session model";
+		const tools = agent.tools?.join(", ") ?? "Pi default built-in tools";
+		lines.push(`- ${agent.name}: ${agent.description} (model: ${model}; tools: ${tools})`);
+	}
+	if (discovery.diagnostics.length > 0) {
+		lines.push("", "Persona diagnostics:", ...discovery.diagnostics.map((diagnostic) => `- ${diagnostic}`));
+	}
+	return lines.join("\n");
+}
+
+function errorText(result: TinySubagentResult): string {
+	const lines = ["Tiny subagent failed."];
+	if (result.errorMessage) lines.push(`Error: ${result.errorMessage}`);
+	if (result.stopReason) lines.push(`Stop reason: ${result.stopReason}`);
+	if (result.exitCode !== null) lines.push(`Exit code: ${result.exitCode}`);
+	if (result.signal) lines.push(`Signal: ${result.signal}`);
+	if (result.stderr.trim()) lines.push(`stderr:\n${result.stderr.trim()}`);
+	if (result.protocolErrors.length > 0) lines.push(`Protocol errors:\n${result.protocolErrors.join("\n")}`);
+	if (result.output.trim()) lines.push(`Output before failure:\n${result.output.trim()}`);
+	if (result.artifacts) lines.push(`Full output artifacts: ${result.artifacts.directory}`);
+	return lines.join("\n");
+}
+
+function renderSummary(result: TinySubagentResult): string {
+ const text = result.ok ? result.output || "(no output)" : errorText(result);
+ if (!result.ok || !result.artifacts) return text;
+ return `${text}\n\nFull output artifacts: ${result.artifacts.directory}`;
+}
+
+type TinySubagentDetails = TinySubagentResult & {
+ agent: string;
+ description: string;
+ systemPrompt: string;
+ prompt: string;
+ personaPath: string;
+};
+
+function messageText(message: TinySubagentDetails["messages"][number]): string {
+ if (typeof message.content === "string") return message.content;
+ if (!Array.isArray(message.content)) return "";
+ return message.content
+  .filter((part) => part.type === "text" && typeof part.text === "string")
+  .map((part) => part.text as string)
+  .join("");
+}
+
+function messageLines(message: TinySubagentDetails["messages"][number]): string[] {
+ if (message.role === "user") return [];
+ if (message.role === "assistant" && Array.isArray(message.content)) {
+  return message.content.flatMap((part) => {
+   if (part.type === "toolCall") {
+    const args = part.arguments === undefined ? "" : ` ${JSON.stringify(part.arguments)}`;
+    return [`→ ${part.name ?? "tool"}${args}`];
+   }
+   if (part.type === "text" && typeof part.text === "string") return [`assistant: ${part.text}`];
+   return [];
+  });
+ }
+ if (message.role === "toolResult") {
+  const prefix = `← ${message.toolName ?? "tool"}${message.isError ? " [error]" : ""}`;
+  const text = messageText(message);
+  return [prefix, ...(text ? text.split("\n").map((line) => `  ${line}`) : [])];
+ }
+ const text = messageText(message);
+ return text ? [`${message.role ?? "message"}: ${text}`] : [];
+}
+
+function latestActivity(messages: TinySubagentDetails["messages"]): string {
+ const lines = messages.flatMap(messageLines);
+ return lines.length > 0 ? lines[lines.length - 1] : "starting child Pi...";
+}
+
+export default function (pi: ExtensionAPI) {
+	if (process.env.PI_SUBAGENT_CHILD === "1") return;
+
+	pi.registerTool({
+		name: "tiny_subagents",
+		label: "Tiny Subagent",
+		description: "Delegate one focused task to a package-local persona in a fresh Pi context. Supports persona discovery with action=list and execution with agent, prompt, and an optional model override. No parent conversation or extensions are inherited.",
+		promptSnippet: "Run one focused task through a package-local tiny subagent persona",
+		promptGuidelines: ["Before execution, call tiny_subagents with action 'list' once and choose an executable persona by name or description. After receiving the list, do not list again; omit action and run one focused prompt with the selected agent."],
+		parameters: TinySubagentParams,
+
+		async execute(_toolCallId, params: ToolParams, signal, onUpdate, ctx) {
+			const discovery = discoverPackageAgents(packageAgentsDir);
+			if (params.action === "list") {
+				return {
+					content: [{ type: "text" as const, text: listText(discovery) }],
+					details: { action: "list", agents: discovery.agents, diagnostics: discovery.diagnostics },
+				};
+			}
+
+			if (!params.prompt?.trim()) {
+				const text = "prompt is required for execution. Use action: list to inspect available personas.";
+				return { content: [{ type: "text" as const, text }], details: { errorMessage: text }, isError: true };
+			}
+
+			const selectedName = params.agent?.trim() || "worker";
+			const persona = discovery.agents.find((agent) => agent.name === selectedName);
+			if (!persona) {
+				const text = `Unknown persona '${selectedName}'.\n\n${listText(discovery)}`;
+				return { content: [{ type: "text" as const, text }], details: { errorMessage: text, availableAgents: discovery.agents.map((agent) => agent.name) }, isError: true };
+			}
+
+			const explicitModel = params.model?.trim();
+			const selectedModel = explicitModel || persona.model || modelId(ctx);
+			const inheritThinking = !explicitModel && !persona.model ? ctx.thinkingLevel : undefined;
+			const addDisplayDetails = (partial: TinySubagentResult) => ({
+				...partial,
+				agent: persona.name,
+				description: persona.description,
+				systemPrompt: persona.systemPrompt,
+				prompt: params.prompt as string,
+				personaPath: persona.filePath,
+			});
+			const result = await runTinySubagent(params.prompt, {
+				...(selectedModel ? { model: selectedModel } : {}),
+				...(inheritThinking ? { thinking: inheritThinking } : {}),
+				...(persona.tools ? { tools: persona.tools } : {}),
+				systemPrompt: persona.systemPrompt,
+				cwd: ctx.cwd,
+				signal,
+				onUpdate: (partial) => {
+					onUpdate?.({
+						content: [{ type: "text" as const, text: partial.output || "(running...)" }],
+						details: addDisplayDetails(partial),
+					});
+				},
+			});
+			return {
+				content: [{ type: "text" as const, text: renderSummary(result) }],
+				details: addDisplayDetails(result),
+				...(result.ok ? {} : { isError: true }),
+			};
+		},
+
+		renderCall(args, theme) {
+			if (args.action === "list") return new Text(theme.fg("toolTitle", theme.bold("tiny_subagents list")), 0, 0);
+			const agent = args.agent || "worker";
+			const model = args.model ? ` ${theme.fg("accent", String(args.model))}` : "";
+			const prompt = args.prompt ? String(args.prompt).replace(/\s+/g, " ") : "...";
+			const preview = prompt.length > 80 ? `${prompt.slice(0, 80)}...` : prompt;
+			return new Text(`${theme.fg("toolTitle", theme.bold("tiny_subagents"))} ${theme.fg("accent", agent)}${model}\n  ${theme.fg("dim", preview)}`, 0, 0);
+		},
+
+		renderResult(result, { expanded, isPartial }, theme) {
+			const details = result.details as TinySubagentDetails | undefined;
+			if (!details?.agent || !details.messages) {
+				const content = result.content[0];
+				return new Text(content?.type === "text" ? content.text : "(no output)", 0, 0);
+			}
+
+			const model = details.model ?? "parent session model";
+			const status = isPartial ? "running" : details.ok ? "completed" : "failed";
+			const statusColor = isPartial ? "warning" : details.ok ? "success" : "error";
+			const statusText = theme.fg(statusColor, status);
+			const fullOutputPath = details.artifacts?.finalOutput;
+			let finalOutput = details.output || "(no output)";
+			if (expanded && fullOutputPath && existsSync(fullOutputPath)) finalOutput = readFileSync(fullOutputPath, "utf8");
+
+			if (expanded) {
+				const container = new Container();
+				container.addChild(new Text(`${theme.fg("toolTitle", theme.bold(details.agent))} ${statusText}`, 0, 0));
+				container.addChild(new Text(theme.fg("muted", `Model: ${model}`), 0, 0));
+				container.addChild(new Text(theme.fg("muted", `Description: ${details.description}`), 0, 0));
+				container.addChild(new Spacer(1));
+				container.addChild(new Text(theme.fg("muted", "--- Prompt ---"), 0, 0));
+				container.addChild(new Text(details.prompt, 0, 0));
+				container.addChild(new Spacer(1));
+				container.addChild(new Text(theme.fg("muted", "--- Agent identity ---"), 0, 0));
+				container.addChild(new Markdown(details.systemPrompt || "(empty)", 0, 0, getMarkdownTheme()));
+				container.addChild(new Spacer(1));
+				container.addChild(new Text(theme.fg("muted", "--- Child transcript ---"), 0, 0));
+				const transcript = details.messages.flatMap(messageLines);
+				if (transcript.length === 0) container.addChild(new Text(theme.fg("dim", "waiting for child events..."), 0, 0));
+				else for (const line of transcript) container.addChild(new Text(line, 0, 0));
+				container.addChild(new Spacer(1));
+				container.addChild(new Text(theme.fg("muted", "--- Final output ---"), 0, 0));
+				container.addChild(new Markdown(finalOutput, 0, 0, getMarkdownTheme()));
+				if (details.errorMessage) container.addChild(new Text(theme.fg("error", `Error: ${details.errorMessage}`), 0, 0));
+				return container;
+			}
+
+			const preview = latestActivity(details.messages).replace(/\s+/g, " ");
+			const compactPreview = preview.length > 100 ? `${preview.slice(0, 100)}...` : preview;
+			return new Text(`${theme.fg("toolTitle", theme.bold(details.agent))} ${statusText} ${theme.fg("dim", `(${model})`)}\n  ${theme.fg("dim", compactPreview)}\n  ${theme.fg("muted", `(${keyHint("app.tools.expand", "to expand")})`)}`, 0, 0);
+		},
+	});
+}

package/packages/tiny-subagent/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@maxiaochao/pi-tiny-subagent",
+  "version": "0.1.1",
+  "description": "A tiny Pi subagent tool with package-local personas and detailed process errors.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "subagent"
+  ],
+  "files": [
+    "extensions",
+    "src",
+    "agents",
+    "docs",
+    "README.md",
+    "TESTING.md",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
+    "directory": "packages/tiny-subagent"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/tiny-subagent.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types tests/run-tests.mjs",
+    "load-test": "pi -ne -ns --no-session -e ./extensions/tiny-subagent.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/tiny-subagent/src/personas.ts

@@ -0,0 +1,110 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const BUILTIN_TOOLS = new Set([
+	"read",
+	"bash",
+	"edit",
+	"write",
+	"grep",
+	"find",
+	"ls",
+	"powershell",
+]);
+
+export interface AgentDefinition {
+	name: string;
+	description: string;
+	model?: string;
+	tools?: string[];
+	systemPrompt: string;
+	filePath: string;
+}
+
+export interface AgentDiscovery {
+	agents: AgentDefinition[];
+	diagnostics: string[];
+}
+
+function unquote(value: string): string {
+	const trimmed = value.trim();
+	if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+		return trimmed.slice(1, -1);
+	}
+	return trimmed;
+}
+
+function parseList(value: string): string[] | undefined {
+	let source = value.trim();
+	if (!source) return undefined;
+	if (source.startsWith("[") && source.endsWith("]")) source = source.slice(1, -1);
+	const items = source.split(",").map((item) => unquote(item).trim()).filter(Boolean);
+	return items.length > 0 ? items : undefined;
+}
+
+export function parseAgentMarkdown(content: string, filePath = "<memory>"): AgentDefinition {
+	const lines = content.replace(/^\uFEFF/, "").split(/\r?\n/);
+	if (lines[0]?.trim() !== "---") throw new Error("missing YAML frontmatter");
+
+	const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+	if (end < 0) throw new Error("unterminated YAML frontmatter");
+
+	const fields = new Map<string, string>();
+	for (const line of lines.slice(1, end)) {
+		if (!line.trim() || line.trim().startsWith("#")) continue;
+		const match = line.match(/^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+		if (!match) throw new Error(`invalid frontmatter line: ${line}`);
+		fields.set(match[1], unquote(match[2]));
+	}
+
+	const name = fields.get("name")?.trim();
+	const description = fields.get("description")?.trim();
+	if (!name) throw new Error("frontmatter name is required");
+	if (!description) throw new Error("frontmatter description is required");
+
+	const rawTools = fields.get("tools");
+	const tools = rawTools === undefined ? undefined : parseList(rawTools);
+	if (rawTools !== undefined && !tools) throw new Error("frontmatter tools must not be empty");
+	for (const tool of tools ?? []) {
+		if (!BUILTIN_TOOLS.has(tool)) throw new Error(`unsupported non-builtin tool: ${tool}`);
+	}
+
+	const model = fields.get("model")?.trim() || undefined;
+	return {
+		name,
+		description,
+		...(model ? { model } : {}),
+		...(tools ? { tools } : {}),
+		systemPrompt: lines.slice(end + 1).join("\n").trim(),
+		filePath,
+	};
+}
+
+export function discoverPackageAgents(agentsDir: string): AgentDiscovery {
+	const agents: AgentDefinition[] = [];
+	const diagnostics: string[] = [];
+	let entries: string[];
+	try {
+		entries = readdirSync(agentsDir).filter((entry) => entry.endsWith(".md")).sort();
+	} catch (error) {
+		return { agents, diagnostics: [`Cannot read persona directory ${agentsDir}: ${error instanceof Error ? error.message : String(error)}`] };
+	}
+
+	const names = new Set<string>();
+	for (const entry of entries) {
+		const filePath = join(agentsDir, entry);
+		try {
+			if (!statSync(filePath).isFile()) continue;
+			const definition = parseAgentMarkdown(readFileSync(filePath, "utf8"), filePath);
+			if (names.has(definition.name)) {
+				diagnostics.push(`${filePath}: duplicate persona name '${definition.name}'`);
+				continue;
+			}
+			names.add(definition.name);
+			agents.push(definition);
+		} catch (error) {
+			diagnostics.push(`${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return { agents, diagnostics };
+}