@oai404iao/pi-subagent 0.2.0

package/src/providers.ts

@@ -0,0 +1,139 @@
+import { rm } from "node:fs/promises";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { SubagentMode, SubagentProviderName } from "./types.ts";
+
+export interface SessionView {
+	getBranch(): SessionEntry[];
+	getCwd(): string;
+	getSessionDir(): string;
+	getSessionFile(): string | undefined;
+	getSessionId(): string;
+}
+
+export interface ProviderParent {
+	sessionManager: SessionView;
+}
+
+export interface PreparedChildSession {
+	sessionManager: SessionManager;
+	seedMessageCount: number;
+	rollback(): Promise<void>;
+}
+
+export interface ChildProvider {
+	name: SubagentProviderName;
+	inheritsParentContext: boolean;
+	supportsContinuable: boolean;
+	prepare(parent: ProviderParent, mode: SubagentMode): Promise<PreparedChildSession>;
+}
+
+async function removeOwnedSession(path: string | undefined): Promise<void> {
+	if (!path) return;
+	await rm(path, { force: true });
+}
+
+function freshSession(parent: ProviderParent): PreparedChildSession {
+	const parentFile = parent.sessionManager.getSessionFile();
+	const options = parentFile ? { parentSession: parentFile } : undefined;
+	const sessionManager = parentFile
+		? SessionManager.create(
+				parent.sessionManager.getCwd(),
+				parent.sessionManager.getSessionDir(),
+				options,
+			)
+		: SessionManager.inMemory(parent.sessionManager.getCwd(), options);
+	const childFile = sessionManager.getSessionFile();
+	return {
+		sessionManager,
+		seedMessageCount: 0,
+		rollback: () => removeOwnedSession(childFile),
+	};
+}
+
+/**
+ * Return the latest assistant entry that closed a completed turn.
+ *
+ * A tool-calling assistant message has stopReason "toolUse" and is not a safe
+ * fork boundary. The current parent turn is therefore excluded.
+ */
+export function completedTurnBoundaryId(entries: readonly SessionEntry[]): string | undefined {
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index];
+		if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+		if (entry.message.stopReason !== "toolUse") return entry.id;
+	}
+	return undefined;
+}
+
+function forkedSession(parent: ProviderParent): PreparedChildSession {
+	const parentFile = parent.sessionManager.getSessionFile();
+	const boundaryId = completedTurnBoundaryId(parent.sessionManager.getBranch());
+	if (!boundaryId) return freshSession(parent);
+	if (!parentFile) {
+		throw new Error(
+			"fork provider cannot copy completed history from an ephemeral parent session; use spawn instead",
+		);
+	}
+
+	const clone = SessionManager.open(
+		parentFile,
+		parent.sessionManager.getSessionDir(),
+		parent.sessionManager.getCwd(),
+	);
+	if (!clone.getEntry(boundaryId)) return freshSession(parent);
+	const childFile = clone.createBranchedSession(boundaryId);
+	if (!childFile) return freshSession(parent);
+	const sessionManager = SessionManager.open(
+		childFile,
+		parent.sessionManager.getSessionDir(),
+		parent.sessionManager.getCwd(),
+	);
+	return {
+		sessionManager,
+		seedMessageCount: sessionManager.buildSessionContext().messages.length,
+		rollback: () => removeOwnedSession(childFile),
+	};
+}
+
+export class SpawnProvider implements ChildProvider {
+	readonly name = "spawn";
+	readonly inheritsParentContext = false;
+	readonly supportsContinuable = true;
+
+	prepare(parent: ProviderParent, _mode: SubagentMode): Promise<PreparedChildSession> {
+		return Promise.resolve(freshSession(parent));
+	}
+}
+
+export class ForkProvider implements ChildProvider {
+	readonly name = "fork";
+	readonly inheritsParentContext = true;
+	readonly supportsContinuable = false;
+
+	async prepare(parent: ProviderParent, mode: SubagentMode): Promise<PreparedChildSession> {
+		if (mode === "continuable") {
+			throw new Error("fork provider is one-shot only; use spawn for continuable background work");
+		}
+		return forkedSession(parent);
+	}
+}
+
+export class ProviderRegistry {
+	private readonly providers = new Map<SubagentProviderName, ChildProvider>();
+
+	register(provider: ChildProvider): void {
+		if (this.providers.has(provider.name)) throw new Error(`duplicate subagent provider: ${provider.name}`);
+		this.providers.set(provider.name, provider);
+	}
+
+	get(name: SubagentProviderName): ChildProvider {
+		const provider = this.providers.get(name);
+		if (!provider) throw new Error(`subagent provider is not registered: ${name}`);
+		return provider;
+	}
+
+	list(): ChildProvider[] {
+		return [...this.providers.values()];
+	}
+}

package/src/render.ts

@@ -0,0 +1,109 @@
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type { DelegationDetails, ParentMessageDetails } from "./types.ts";
+import { formatUsage } from "./result.ts";
+
+export function renderDelegationCall(
+	args: { agent?: string; description?: string; prompt?: string; run_in_background?: boolean },
+	theme: {
+		fg(color: any, text: string): string;
+		bold(text: string): string;
+	},
+	provider: "spawn" | "fork",
+): Text {
+	const mode =
+		provider === "fork"
+			? "fork · foreground"
+			: args.run_in_background === false
+				? "spawn · foreground"
+				: args.run_in_background === true
+					? "spawn · background"
+					: "spawn · configured default";
+	let text =
+		theme.fg("toolTitle", theme.bold(provider === "fork" ? "subagent_fork " : "subagent ")) +
+		theme.fg("accent", args.agent ?? "…") +
+		theme.fg("muted", ` [${mode}]`);
+	if (args.description) text += `\n  ${theme.fg("dim", args.description)}`;
+	return new Text(text, 0, 0);
+}
+
+export function renderDelegationResult(
+	details: DelegationDetails | undefined,
+	content: string,
+	options: { expanded: boolean; isPartial: boolean },
+	theme: {
+		fg(color: any, text: string): string;
+		bold(text: string): string;
+	},
+): Text | Container {
+	if (!details) return new Text(content || "(no output)", 0, 0);
+	const running = options.isPartial || details.status === "starting" || details.status === "running";
+	const icon = running
+		? theme.fg("warning", "◌")
+		: details.status === "failed"
+			? theme.fg("error", "✗")
+			: theme.fg("success", "✓");
+	const header = `${icon} ${theme.fg("toolTitle", theme.bold(details.agent))} ${theme.fg(
+		"muted",
+		`[${details.provider}/${details.mode}]`,
+	)} ${theme.fg("dim", details.id)}`;
+
+	if (!options.expanded) {
+		const lines = [header, theme.fg("muted", details.label)];
+		const trace = details.trace.slice(-5);
+		for (const item of trace) {
+			const prefix = item.type === "tool" ? "→ " : "";
+			const preview = item.text.split("\n").slice(0, 2).join("\n");
+			lines.push(theme.fg(item.type === "tool" ? "muted" : "toolOutput", `${prefix}${preview}`));
+		}
+		if (details.usage) lines.push(theme.fg("dim", formatUsage(details.usage)));
+		if (details.sessionFile) lines.push(theme.fg("dim", `session: ${details.sessionFile}`));
+		return new Text(lines.join("\n"), 0, 0);
+	}
+
+	const container = new Container();
+	container.addChild(new Text(header, 0, 0));
+	container.addChild(new Text(theme.fg("muted", `Task: ${details.label}`), 0, 0));
+	if (details.trace.length > 0) {
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(theme.fg("muted", "─── Activity ───"), 0, 0));
+		for (const item of details.trace) {
+			if (item.type === "tool") container.addChild(new Text(theme.fg("muted", `→ ${item.text}`), 0, 0));
+		}
+	}
+	if (details.output) {
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(theme.fg("muted", "─── Output ───"), 0, 0));
+		container.addChild(new Markdown(details.output, 0, 0, getMarkdownTheme()));
+	}
+	if (details.usage) {
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(theme.fg("dim", formatUsage(details.usage)), 0, 0));
+	}
+	if (details.sessionFile) container.addChild(new Text(theme.fg("dim", `session: ${details.sessionFile}`), 0, 0));
+	return container;
+}
+
+export function renderParentMessage(
+	content: string,
+	details: ParentMessageDetails | undefined,
+	expanded: boolean,
+	outputPad: number,
+	theme: {
+		fg(color: any, text: string): string;
+		bold(text: string): string;
+	},
+): Text | Markdown {
+	if (expanded) return new Markdown(content, outputPad, 0, getMarkdownTheme());
+	const kind = details?.kind === "report" ? "report" : "settled";
+	const icon = details?.stopReason && details.stopReason !== "completed" ? "◐" : "●";
+	const label = details?.label ? ` — ${details.label}` : "";
+	return new Text(
+		theme.fg("accent", icon) +
+			" " +
+			theme.fg("toolTitle", theme.bold(`subagent ${kind}`)) +
+			theme.fg("muted", ` ${details?.childId ?? "unknown"}${label}`),
+		outputPad,
+		0,
+	);
+}

package/src/result.ts

@@ -0,0 +1,131 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { Usage } from "@earendil-works/pi-ai";
+import type { SubagentStopReason, SubagentUsage } from "./types.ts";
+
+export interface TruncatedText {
+	text: string;
+	truncated: boolean;
+	omittedBytes: number;
+}
+
+export function truncateUtf8(input: string, maxBytes: number): TruncatedText {
+	const totalBytes = Buffer.byteLength(input, "utf8");
+	if (totalBytes <= maxBytes) return { text: input, truncated: false, omittedBytes: 0 };
+	const buffer = Buffer.from(input, "utf8");
+	let end = Math.min(maxBytes, buffer.length);
+	while (end > 0 && (buffer[end] & 0xc0) === 0x80) end--;
+	const text = buffer.subarray(0, end).toString("utf8");
+	return { text, truncated: true, omittedBytes: totalBytes - Buffer.byteLength(text, "utf8") };
+}
+
+export function emptyUsage(): SubagentUsage {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			total: 0,
+		},
+		turns: 0,
+	};
+}
+
+export function addUsage(target: SubagentUsage, usage: Usage, countTurn = true): void {
+	target.input += usage.input;
+	target.output += usage.output;
+	target.cacheRead += usage.cacheRead;
+	target.cacheWrite += usage.cacheWrite;
+	target.totalTokens += usage.totalTokens;
+	target.cost.input += usage.cost.input;
+	target.cost.output += usage.cost.output;
+	target.cost.cacheRead += usage.cost.cacheRead;
+	target.cost.cacheWrite += usage.cost.cacheWrite;
+	target.cost.total += usage.cost.total;
+	if (countTurn) target.turns++;
+}
+
+function assistantText(message: AgentMessage): string {
+	if (message.role !== "assistant") return "";
+	return message.content
+		.filter((part): part is Extract<(typeof message.content)[number], { type: "text" }> => part.type === "text")
+		.map((part) => part.text)
+		.join("");
+}
+
+export function finalAssistantText(messages: readonly AgentMessage[], startIndex: number, streamedFallback = ""): string {
+	for (let index = messages.length - 1; index >= startIndex; index--) {
+		const text = assistantText(messages[index]);
+		if (text.trim().length > 0) return text;
+	}
+	return streamedFallback;
+}
+
+export function finalStopReason(
+	messages: readonly AgentMessage[],
+	startIndex: number,
+	fallback: SubagentStopReason = "error",
+): SubagentStopReason {
+	for (let index = messages.length - 1; index >= startIndex; index--) {
+		const message = messages[index];
+		if (message.role !== "assistant") continue;
+		switch (message.stopReason) {
+			case "stop":
+				return "completed";
+			case "length":
+				return "max-tokens";
+			case "aborted":
+				return "aborted";
+			case "error":
+				return "error";
+			case "toolUse":
+			case "pending":
+				return fallback;
+			default:
+				return fallback;
+		}
+	}
+	return fallback;
+}
+
+export function formatUsage(usage: SubagentUsage): string {
+	const parts = [`${usage.turns} turn${usage.turns === 1 ? "" : "s"}`];
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+	if (usage.cost.total) parts.push(`$${usage.cost.total.toFixed(4)}`);
+	return parts.join(" ");
+}
+
+function formatTokens(count: number): string {
+	if (count < 1000) return String(count);
+	if (count < 10_000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1_000_000) return `${Math.round(count / 1000)}k`;
+	return `${(count / 1_000_000).toFixed(1)}M`;
+}
+
+export function formatToolArguments(name: string, args: Record<string, unknown>): string {
+	if (name === "bash" && typeof args.command === "string") {
+		return `$ ${singleLine(args.command, 100)}`;
+	}
+	const path = args.path ?? args.file_path;
+	if (typeof path === "string" && ["read", "write", "edit", "ls"].includes(name)) {
+		return `${name} ${singleLine(path, 100)}`;
+	}
+	if (name === "grep" && typeof args.pattern === "string") {
+		return `grep /${singleLine(args.pattern, 60)}/`;
+	}
+	const encoded = JSON.stringify(args);
+	return `${name} ${singleLine(encoded, 100)}`;
+}
+
+function singleLine(value: string, limit: number): string {
+	const line = value.replace(/\s+/g, " ").trim();
+	return line.length > limit ? `${line.slice(0, limit)}…` : line;
+}

package/src/schemas.ts

@@ -0,0 +1,130 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+function agentNameParameter(agentNames?: readonly string[]) {
+	if (agentNames === undefined) {
+		return Type.String({
+			description: "Agent definition name",
+			minLength: 1,
+			maxLength: 64,
+		});
+	}
+	return StringEnum([...new Set(agentNames)], {
+		description: "Available agent definition name",
+	});
+}
+
+function delegationFields(agentNames?: readonly string[]) {
+	return {
+		agent: agentNameParameter(agentNames),
+		description: Type.String({
+			description: "Short 3-5 word display label for the delegated task",
+			minLength: 1,
+			maxLength: 200,
+		}),
+		prompt: Type.String({
+			description: "Complete task for the child agent",
+			minLength: 1,
+		}),
+	};
+}
+
+function forkDelegationFields(agentNames?: readonly string[]) {
+	return {
+		...delegationFields(agentNames),
+		prompt: Type.String({
+			description:
+				"Task for a child that already sees all completed parent turns; state only the new work",
+			minLength: 1,
+		}),
+	};
+}
+
+function createDelegationParameters(
+	enableRunInBackground: boolean,
+	agentNames?: readonly string[],
+) {
+	const fields = delegationFields(agentNames);
+	return Type.Object(
+		enableRunInBackground
+			? {
+					...fields,
+					run_in_background: Type.Optional(
+						Type.Boolean({
+							description:
+								"Run as a continuable background child. The spawn provider defaults this from configuration.",
+						}),
+					),
+				}
+			: fields,
+		{ additionalProperties: false },
+	);
+}
+
+export const ForegroundDelegationParameters = createDelegationParameters(false);
+
+export const DelegationParameters = createDelegationParameters(true);
+
+export function delegationParameters(
+	enableRunInBackground: boolean,
+	agentNames?: readonly string[],
+) {
+	if (agentNames === undefined) {
+		return enableRunInBackground ? DelegationParameters : ForegroundDelegationParameters;
+	}
+	return createDelegationParameters(enableRunInBackground, agentNames);
+}
+
+export const ForkDelegationParameters = Type.Object(
+	forkDelegationFields(),
+	{ additionalProperties: false },
+);
+
+export function forkDelegationParameters(agentNames?: readonly string[]) {
+	if (agentNames === undefined) return ForkDelegationParameters;
+	return Type.Object(forkDelegationFields(agentNames), { additionalProperties: false });
+}
+
+export const SendMessageParameters = Type.Object(
+	{
+		subagent_id: Type.String({ description: "Durable id of a direct continuable child", minLength: 1 }),
+		message: Type.String({
+			description: "Message to enqueue as the child's next FIFO turn",
+			minLength: 1,
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+export const InterruptParameters = Type.Object(
+	{
+		agent_id: Type.String({
+			description: "Id of a live child or deeper descendant whose current turn should stop",
+			minLength: 1,
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+export const ListAgentsParameters = Type.Object(
+	{
+		scope: Type.Optional(
+			StringEnum(["children", "descendants"] as const, {
+				description: "List direct continuable children (default) or the complete descendant tree",
+				default: "children",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+export const ReportParameters = Type.Object(
+	{
+		output: Type.String({
+			description:
+				"Self-contained update for the agent that started you. Reporting does not end your turn.",
+			minLength: 1,
+		}),
+	},
+	{ additionalProperties: false },
+);

package/src/tool-policy.ts

@@ -0,0 +1,131 @@
+export const MUTATION_TOOL_GROUP = "$mutation";
+
+const TOOL_GROUP_PREFIX = "$";
+const MUTATION_TOOL_CANDIDATES = ["apply_patch", "edit", "write"] as const;
+
+export interface ToolPolicyOptions {
+	requested: readonly string[] | undefined;
+	mandatory?: readonly string[];
+	denied?: readonly string[];
+}
+
+export interface ResolvedToolPolicy {
+	activeTools: string[];
+	resolvedRequestedTools?: string[];
+}
+
+function unique(values: Iterable<string>): string[] {
+	return [...new Set(values)];
+}
+
+export function assertSupportedToolReferences(tools: readonly string[], field = "tools"): void {
+	const unsupported = tools.find(
+		(tool) => tool.startsWith(TOOL_GROUP_PREFIX) && tool !== MUTATION_TOOL_GROUP,
+	);
+	if (unsupported) {
+		throw new Error(
+			`${field} contains unsupported logical tool "${unsupported}"; supported logical tools: ${MUTATION_TOOL_GROUP}`,
+		);
+	}
+}
+
+/**
+ * Build Pi's hard tool registry ceiling before child extensions initialize.
+ *
+ * Logical groups expand to every implementation that an extension may choose.
+ * The post-initialization resolver narrows this ceiling to the implementation
+ * that the selected model and its extensions actually left active.
+ */
+export function buildToolCeiling(options: ToolPolicyOptions): string[] | undefined {
+	if (options.requested === undefined) return undefined;
+	assertSupportedToolReferences(options.requested);
+
+	const denied = new Set(options.denied ?? []);
+	const requestedDenied = options.requested.find((tool) => denied.has(tool));
+	if (requestedDenied) {
+		throw new Error(`tool "${requestedDenied}" is unavailable in this subagent mode`);
+	}
+
+	const ceiling: string[] = [];
+	for (const tool of options.requested) {
+		if (tool === MUTATION_TOOL_GROUP) {
+			ceiling.push(...MUTATION_TOOL_CANDIDATES.filter((candidate) => !denied.has(candidate)));
+		} else if (!denied.has(tool)) {
+			ceiling.push(tool);
+		}
+	}
+	for (const tool of options.mandatory ?? []) {
+		if (!denied.has(tool)) ceiling.push(tool);
+	}
+	return unique(ceiling);
+}
+
+function resolveMutationTools(registered: Set<string>, active: Set<string>): string[] {
+	if (registered.has("apply_patch") && active.has("apply_patch")) return ["apply_patch"];
+	const native = MUTATION_TOOL_CANDIDATES
+		.filter((tool) => tool !== "apply_patch")
+		.filter((tool) => registered.has(tool) && active.has(tool));
+	if (native.length > 0) return native;
+	throw new Error(
+		`${MUTATION_TOOL_GROUP} has no active implementation; apply_patch, edit, and write are unavailable for the selected model and child extensions`,
+	);
+}
+
+/**
+ * Apply the agent policy after extension `session_start` handlers have selected
+ * model-specific tools. Explicit names may narrow that selection but never
+ * reactivate a tool that an extension left inactive.
+ */
+export function resolveToolPolicy(
+	options: ToolPolicyOptions & {
+		registered: readonly string[];
+		active: readonly string[];
+	},
+): ResolvedToolPolicy {
+	assertSupportedToolReferences(options.requested ?? []);
+	const registered = new Set(options.registered);
+	const active = new Set(options.active);
+	const mandatory = unique(options.mandatory ?? []);
+	const mandatorySet = new Set(mandatory);
+	const denied = new Set(options.denied ?? []);
+
+	for (const tool of mandatory) {
+		if (denied.has(tool)) throw new Error(`mandatory tool "${tool}" is denied by the runtime`);
+		if (!registered.has(tool)) throw new Error(`mandatory tool "${tool}" is not registered`);
+	}
+
+	if (options.requested === undefined) {
+		const selected = options.active.filter((tool) => !denied.has(tool));
+		for (const tool of mandatory) {
+			if (!selected.includes(tool)) selected.push(tool);
+		}
+		return { activeTools: unique(selected) };
+	}
+
+	const resolvedRequestedTools: string[] = [];
+	for (const tool of options.requested) {
+		if (denied.has(tool)) throw new Error(`tool "${tool}" is unavailable in this subagent mode`);
+		if (tool === MUTATION_TOOL_GROUP) {
+			resolvedRequestedTools.push(...resolveMutationTools(registered, active));
+			continue;
+		}
+		if (!registered.has(tool)) {
+			throw new Error(`requested tool "${tool}" is not registered by Pi or a loaded child extension`);
+		}
+		if (!active.has(tool) && !mandatorySet.has(tool)) {
+			throw new Error(
+				`requested tool "${tool}" is inactive for the selected model or child extension policy`,
+			);
+		}
+		resolvedRequestedTools.push(tool);
+	}
+
+	const selected = unique(resolvedRequestedTools.filter((tool) => !denied.has(tool)));
+	for (const tool of mandatory) {
+		if (!selected.includes(tool)) selected.push(tool);
+	}
+	return {
+		activeTools: selected,
+		resolvedRequestedTools: unique(resolvedRequestedTools),
+	};
+}