@narumitw/pi-subagents 0.13.0 → 0.14.0

package/src/orchestration.ts

@@ -0,0 +1,164 @@
+import { randomUUID } from "node:crypto";
+
+export type OrchestrationRecoveryTicket = {
+	generation: number;
+	revision: number;
+	nonce: string;
+	prompt: string;
+};
+
+type DelegatedAgent = {
+	live: boolean;
+	resultAvailable: boolean;
+	observedInTurn: boolean;
+};
+
+export const ORCHESTRATION_MARKER_PREFIX = "pi-subagent-orchestration:";
+
+const RECOVERY_PROMPT = [
+	"Delegated subagents still need root coordination.",
+	"Do not yield permanently while current delegated work is unresolved.",
+	"Continue useful non-overlapping local work, or call subagent_wait when no useful local continuation remains.",
+	"Consume available subagent results and synthesize them before finishing.",
+	"Interrupt or close agents that are no longer needed; do not wait forever or spawn more agents unnecessarily.",
+].join(" ");
+
+/** Ephemeral root-turn coordination state. Never persisted across sessions. */
+export class RootOrchestrationState {
+	private generation = 0;
+	private revision = 0;
+	private turnOpen = false;
+	private agents = new Map<string, DelegatedAgent>();
+	private pending: OrchestrationRecoveryTicket | undefined;
+	private deliveredRevision: number | undefined;
+
+	reset(): void {
+		this.generation += 1;
+		this.revision = 0;
+		this.turnOpen = false;
+		this.agents.clear();
+		this.pending = undefined;
+		this.deliveredRevision = undefined;
+	}
+
+	beginTurn(): void {
+		this.turnOpen = true;
+		if (this.pending) this.deliveredRevision = this.pending.revision;
+		this.observeAvailable();
+		// New root work supersedes an intent that has not been delivered yet. The
+		// turn gets a chance to coordinate before agent_end evaluates it again.
+		this.pending = undefined;
+	}
+
+	spawn(agentId: string): void {
+		this.agents.set(agentId, {
+			live: true,
+			resultAvailable: false,
+			observedInTurn: false,
+		});
+		this.bumpRevision();
+	}
+
+	complete(agentId: string): void {
+		const existing = this.agents.get(agentId);
+		if (!existing) return;
+		this.agents.set(agentId, {
+			live: false,
+			resultAvailable: true,
+			observedInTurn: false,
+		});
+		this.bumpRevision();
+		if (!this.turnOpen) this.ensureRecovery();
+	}
+
+	resolve(agentId: string): void {
+		if (!this.agents.delete(agentId)) return;
+		this.bumpRevision();
+	}
+
+	observe(agentId: string): void {
+		const agent = this.agents.get(agentId);
+		if (agent && !agent.live && agent.resultAvailable) agent.observedInTurn = true;
+	}
+
+	observeAvailable(): void {
+		for (const agent of this.agents.values()) {
+			if (!agent.live && agent.resultAvailable) agent.observedInTurn = true;
+		}
+	}
+
+	endTurn(): OrchestrationRecoveryTicket | undefined {
+		if (this.turnOpen) {
+			for (const [id, agent] of this.agents) {
+				if (!agent.live && agent.resultAvailable && agent.observedInTurn) {
+					this.agents.delete(id);
+				}
+			}
+			this.turnOpen = false;
+		}
+		return this.ensureRecovery();
+	}
+
+	pendingTicket(): OrchestrationRecoveryTicket | undefined {
+		return this.pending;
+	}
+
+	isCurrent(ticket: OrchestrationRecoveryTicket): boolean {
+		return (
+			ticket.generation === this.generation &&
+			ticket.revision === this.revision &&
+			ticket.nonce === this.pending?.nonce &&
+			this.hasUnresolved()
+		);
+	}
+
+	markDelivered(ticket: OrchestrationRecoveryTicket): void {
+		if (!this.isCurrent(ticket)) return;
+		this.pending = undefined;
+		this.deliveredRevision = ticket.revision;
+	}
+
+	supersedePending(): OrchestrationRecoveryTicket | undefined {
+		const ticket = this.pending;
+		if (!ticket) return undefined;
+		this.pending = undefined;
+		this.deliveredRevision = ticket.revision;
+		return ticket;
+	}
+
+	hasUnresolved(): boolean {
+		return this.agents.size > 0;
+	}
+
+	liveAgentIds(): string[] {
+		return [...this.agents]
+			.filter(([, agent]) => agent.live)
+			.map(([id]) => id)
+			.sort();
+	}
+
+	private ensureRecovery(): OrchestrationRecoveryTicket | undefined {
+		if (!this.hasUnresolved()) {
+			this.pending = undefined;
+			return undefined;
+		}
+		if (this.deliveredRevision === this.revision) return undefined;
+		if (this.pending?.revision === this.revision && this.pending.generation === this.generation) {
+			return this.pending;
+		}
+		const nonce = randomUUID();
+		this.pending = {
+			generation: this.generation,
+			revision: this.revision,
+			nonce,
+			prompt: `${RECOVERY_PROMPT}\n<!-- ${ORCHESTRATION_MARKER_PREFIX}${nonce} -->`,
+		};
+		return this.pending;
+	}
+
+	private bumpRevision(): void {
+		this.revision += 1;
+		this.pending = undefined;
+		this.deliveredRevision = undefined;
+	}
+}

package/src/params.ts

@@ -0,0 +1,59 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import { THINKING_LEVELS } from "./agents.js";
+
+const TimeoutMs = Type.Number({
+	description:
+		"Hard timeout in milliseconds for each subagent subprocess. Defaults to PI_SUBAGENT_TIMEOUT_MS or 600000.",
+	minimum: 1,
+});
+
+const ThinkingLevelSchema = StringEnum(THINKING_LEVELS, {
+	description: "Pi thinking level for the subagent process: off, minimal, low, medium, high, or xhigh.",
+});
+
+const TaskItem = Type.Object({
+	agent: Type.String({ description: "Name of the agent to invoke" }),
+	task: Type.String({ description: "Task to delegate to the agent" }),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+	timeoutMs: Type.Optional(TimeoutMs),
+	thinkingLevel: Type.Optional(ThinkingLevelSchema),
+});
+
+const ChainItem = Type.Object({
+	agent: Type.String({ description: "Name of the agent to invoke" }),
+	task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+	timeoutMs: Type.Optional(TimeoutMs),
+	thinkingLevel: Type.Optional(ThinkingLevelSchema),
+});
+
+const AggregatorItem = Type.Object({
+	agent: Type.String({ description: "Name of the fan-in agent to invoke after parallel tasks complete" }),
+	task: Type.String({ description: "Fan-in task. Use {previous} to include all parallel outputs." }),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the aggregator process" })),
+	timeoutMs: Type.Optional(TimeoutMs),
+	thinkingLevel: Type.Optional(ThinkingLevelSchema),
+});
+
+const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
+	description: 'Which agent directories to use. Default: "user". Use "both" to include project-local agents.',
+	default: "user",
+});
+
+export const SubagentParams = Type.Object({
+	agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (for single mode)" })),
+	task: Type.Optional(Type.String({ description: "Task to delegate (for single mode)" })),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
+	chain: Type.Optional(Type.Array(ChainItem, { description: "Array of {agent, task} for sequential execution" })),
+	aggregator: Type.Optional(AggregatorItem),
+	agentScope: Type.Optional(AgentScopeSchema),
+	confirmProjectAgents: Type.Optional(
+		Type.Boolean({ description: "Prompt before running project-local agents. Default: true.", default: true }),
+	),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
+	timeoutMs: Type.Optional(TimeoutMs),
+	thinkingLevel: Type.Optional(ThinkingLevelSchema),
+});
+
+export type SubagentParams = Static<typeof SubagentParams>;

package/src/persistence.ts

@@ -0,0 +1,207 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { redactPrivateText } from "./context.js";
+import type { ManagedAgent } from "./registry.js";
+
+const STATE_VERSION = 2;
+const MAX_STATE_BYTES = 1024 * 1024;
+
+interface StoredState {
+	version: 2;
+	updatedAt: number;
+	agents: ManagedAgent[];
+}
+
+export interface PersistenceOptions {
+	retentionDays?: number;
+	maxStoredAgents?: number;
+	stateDir?: string;
+}
+
+export class AgentPersistence {
+	readonly filePath: string;
+	private readonly retentionMs: number;
+	private readonly maxStoredAgents: number;
+
+	constructor(owner: string, options: PersistenceOptions = {}) {
+		const retentionDays = options.retentionDays ?? 30;
+		if (!Number.isFinite(retentionDays) || retentionDays <= 0) {
+			throw new Error("Subagent retentionDays must be a positive finite number");
+		}
+		const retentionMs = retentionDays * 24 * 60 * 60 * 1000;
+		if (!Number.isFinite(retentionMs)) {
+			throw new Error("Subagent retentionDays is too large");
+		}
+		const maxStoredAgents = options.maxStoredAgents ?? 50;
+		if (!Number.isSafeInteger(maxStoredAgents) || maxStoredAgents < 1) {
+			throw new Error("Subagent maxStoredAgents must be a positive safe integer");
+		}
+		const safeOwner = createHash("sha256").update(owner).digest("hex").slice(0, 24);
+		const stateDir = options.stateDir ?? path.join(getAgentDir(), "pi-subagents-state");
+		this.filePath = path.join(stateDir, `${safeOwner}.json`);
+		this.retentionMs = retentionMs;
+		this.maxStoredAgents = maxStoredAgents;
+	}
+
+	load(): ManagedAgent[] {
+		if (!fs.existsSync(this.filePath)) return [];
+		try {
+			const stat = fs.statSync(this.filePath);
+			if (stat.size > MAX_STATE_BYTES) throw new Error("state exceeds size limit");
+			const parsed = JSON.parse(fs.readFileSync(this.filePath, "utf8")) as unknown;
+			if (!isStoredState(parsed)) throw new Error("unsupported or malformed state");
+			const cutoff = Date.now() - this.retentionMs;
+			return parsed.agents
+				.filter((agent) => agent.updatedAt >= cutoff && agent.state !== "closed")
+				.slice(-this.maxStoredAgents)
+				.map(sanitizeAgent);
+		} catch {
+			this.quarantine();
+			return [];
+		}
+	}
+
+	async save(agents: readonly ManagedAgent[]): Promise<void> {
+		const cutoff = Date.now() - this.retentionMs;
+		const eligible = agents.filter(
+			(agent) => agent.state !== "closed" && agent.updatedAt >= cutoff,
+		);
+		const records = selectAgentsForPersistence(eligible, this.maxStoredAgents).map(sanitizeAgent);
+		const state: StoredState = { version: STATE_VERSION, updatedAt: Date.now(), agents: records };
+		let content = `${JSON.stringify(state, null, "\t")}\n`;
+		while (Buffer.byteLength(content, "utf8") > MAX_STATE_BYTES && state.agents.length > 0) {
+			const oldestRootId = state.agents[0].rootId;
+			state.agents = state.agents.filter((agent) => agent.rootId !== oldestRootId);
+			content = `${JSON.stringify(state, null, "\t")}\n`;
+		}
+		await fs.promises.mkdir(path.dirname(this.filePath), { recursive: true });
+		await withFileMutationQueue(this.filePath, async () => {
+			const tempPath = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+			await fs.promises.writeFile(tempPath, content, { encoding: "utf8", mode: 0o600 });
+			await fs.promises.rename(tempPath, this.filePath);
+		});
+	}
+
+	async delete(): Promise<void> {
+		await withFileMutationQueue(this.filePath, async () => {
+			await fs.promises.rm(this.filePath, { force: true });
+		});
+	}
+
+	private quarantine(): void {
+		try {
+			fs.renameSync(this.filePath, `${this.filePath}.invalid-${Date.now()}`);
+		} catch {
+			// A concurrent process may already have moved or removed it.
+		}
+	}
+}
+
+function selectAgentsForPersistence(
+	agents: readonly ManagedAgent[],
+	maxAgents: number,
+): ManagedAgent[] {
+	const byId = new Map(agents.map((agent) => [agent.id, agent]));
+	const selected = new Map<string, ManagedAgent>();
+	const newestFirst = [...agents].sort((left, right) => right.updatedAt - left.updatedAt);
+	for (const agent of newestFirst) {
+		const chain: ManagedAgent[] = [];
+		let current: ManagedAgent | undefined = agent;
+		const seen = new Set<string>();
+		while (current && !seen.has(current.id)) {
+			seen.add(current.id);
+			chain.unshift(current);
+			current = current.parentId ? byId.get(current.parentId) : undefined;
+		}
+		if (current || (agent.parentId && chain[0].parentId)) continue;
+		const missing = chain.filter((candidate) => !selected.has(candidate.id));
+		if (selected.size + missing.length > maxAgents) continue;
+		for (const candidate of missing) selected.set(candidate.id, candidate);
+	}
+	return agents.filter((agent) => selected.has(agent.id));
+}
+
+function sanitizeAgent(agent: ManagedAgent): ManagedAgent {
+	return {
+		...agent,
+		rootId: agent.rootId ?? agent.id,
+		depth: agent.depth ?? 0,
+		children: [...(agent.children ?? [])],
+		mailbox: (agent.mailbox ?? []).map((message) => ({
+			...message,
+			recipientId: agent.id,
+			content: redactPrivateText(message.content),
+		})),
+		state: "idle",
+		currentTask: undefined,
+		currentMailboxMessageIds: undefined,
+		context: agent.context ? redactPrivateText(agent.context) : undefined,
+		error: agent.error ? redactPrivateText(agent.error) : undefined,
+		history: agent.history.map((turn) => ({
+			...turn,
+			task: redactPrivateText(turn.task),
+			output: redactPrivateText(turn.output),
+		})),
+	};
+}
+
+function isStoredState(value: unknown): value is StoredState {
+	if (!value || typeof value !== "object") return false;
+	const state = value as { version?: unknown; agents?: unknown };
+	if ((state.version !== 1 && state.version !== STATE_VERSION) || !Array.isArray(state.agents)) {
+		return false;
+	}
+	return state.agents.every((agent) => {
+		if (!agent || typeof agent !== "object") return false;
+		const record = agent as Partial<ManagedAgent>;
+		return (
+			typeof record.id === "string" &&
+			typeof record.agent === "string" &&
+			typeof record.cwd === "string" &&
+			typeof record.createdAt === "number" &&
+			Number.isFinite(record.createdAt) &&
+			typeof record.updatedAt === "number" &&
+			Number.isFinite(record.updatedAt) &&
+			(record.parentId === undefined || typeof record.parentId === "string") &&
+			(record.children === undefined ||
+				(Array.isArray(record.children) && record.children.every((id) => typeof id === "string"))) &&
+			Array.isArray(record.history) &&
+			record.history.every(isAgentTurn) &&
+			(record.mailbox === undefined ||
+				(Array.isArray(record.mailbox) && record.mailbox.every(isMailboxMessage)))
+		);
+	});
+}
+
+function isAgentTurn(value: unknown): boolean {
+	if (!value || typeof value !== "object") return false;
+	const turn = value as Record<string, unknown>;
+	return (
+		typeof turn.task === "string" &&
+		typeof turn.output === "string" &&
+		typeof turn.startedAt === "number" &&
+		Number.isFinite(turn.startedAt) &&
+		typeof turn.completedAt === "number" &&
+		Number.isFinite(turn.completedAt) &&
+		typeof turn.exitCode === "number" &&
+		Number.isFinite(turn.exitCode)
+	);
+}
+
+function isMailboxMessage(value: unknown): boolean {
+	if (!value || typeof value !== "object") return false;
+	const message = value as Record<string, unknown>;
+	return (
+		typeof message.id === "string" &&
+		typeof message.senderId === "string" &&
+		typeof message.recipientId === "string" &&
+		typeof message.content === "string" &&
+		typeof message.createdAt === "number" &&
+		Number.isFinite(message.createdAt) &&
+		(message.readAt === undefined ||
+			(typeof message.readAt === "number" && Number.isFinite(message.readAt))) &&
+		(message.deduplicationKey === undefined || typeof message.deduplicationKey === "string")
+	);
+}

package/src/protocol.ts

@@ -0,0 +1,76 @@
+import { StringDecoder } from "node:string_decoder";
+
+const DEFAULT_MAX_LINE_BYTES = 256 * 1024;
+
+export interface JsonLineDecoderOptions {
+	maxLineBytes?: number;
+	onValue: (value: unknown) => void;
+	onMalformed?: (line: string) => void;
+	onOversized?: (bytes: number) => void;
+}
+
+/** Bounded newline-delimited JSON decoder for child Pi event streams. */
+export class JsonLineDecoder {
+	private buffer = "";
+	private droppingOversizedLine = false;
+	private readonly maxLineBytes: number;
+	private readonly decoder = new StringDecoder("utf8");
+
+	constructor(private readonly options: JsonLineDecoderOptions) {
+		const maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+		if (!Number.isSafeInteger(maxLineBytes) || maxLineBytes < 1) {
+			throw new Error("JSON line limit must be a positive safe integer");
+		}
+		this.maxLineBytes = maxLineBytes;
+	}
+
+	push(chunk: string | Buffer): void {
+		this.buffer += typeof chunk === "string" ? chunk : this.decoder.write(chunk);
+		this.drain(false);
+	}
+
+	finish(): void {
+		this.buffer += this.decoder.end();
+		this.drain(true);
+		this.buffer = "";
+		this.droppingOversizedLine = false;
+	}
+
+	private drain(flush: boolean): void {
+		while (true) {
+			const newline = this.buffer.indexOf("\n");
+			if (newline < 0) break;
+			const line = this.buffer.slice(0, newline).replace(/\r$/, "");
+			this.buffer = this.buffer.slice(newline + 1);
+			if (this.droppingOversizedLine) {
+				this.droppingOversizedLine = false;
+				continue;
+			}
+			this.processLine(line);
+		}
+
+		if (!flush && Buffer.byteLength(this.buffer, "utf8") > this.maxLineBytes) {
+			this.options.onOversized?.(Buffer.byteLength(this.buffer, "utf8"));
+			this.buffer = "";
+			this.droppingOversizedLine = true;
+		}
+
+		if (flush && this.buffer.length > 0 && !this.droppingOversizedLine) {
+			this.processLine(this.buffer.replace(/\r$/, ""));
+		}
+	}
+
+	private processLine(line: string): void {
+		if (!line.trim()) return;
+		const bytes = Buffer.byteLength(line, "utf8");
+		if (bytes > this.maxLineBytes) {
+			this.options.onOversized?.(bytes);
+			return;
+		}
+		try {
+			this.options.onValue(JSON.parse(line));
+		} catch {
+			this.options.onMalformed?.(line);
+		}
+	}
+}