@narumitw/pi-subagents 2.1.3 → 3.0.0

package/src/pi-invocation.ts

@@ -1,168 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { getPackageDir } from "@earendil-works/pi-coding-agent";
-
-const CORE_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
-const MAX_DISPLAY_PATH_LENGTH = 500;
-
-export interface PiInvocation {
-	command: string;
-	args: string[];
-}
-
-export interface PiInvocationRuntime {
-	execPath: string;
-	packageDir: string;
-	runtimeKind: "node" | "bun" | "unsupported";
-}
-
-export class PiInvocationError extends Error {
-	constructor(message: string) {
-		super(message);
-		this.name = "PiInvocationError";
-	}
-}
-
-function displayPath(value: string): string {
-	const suffix = value.length > MAX_DISPLAY_PATH_LENGTH ? "…" : "";
-	return JSON.stringify(`${value.slice(0, MAX_DISPLAY_PATH_LENGTH)}${suffix}`);
-}
-
-function resolutionError(packageDir: string, reason: string): PiInvocationError {
-	return new PiInvocationError(
-		`Unable to resolve the Pi CLI from the loaded ${CORE_PACKAGE_NAME} package at ${displayPath(packageDir)}: ${reason}. Reinstall the matching Pi core package before using the subprocess transport.`,
-	);
-}
-
-function currentRuntime(): PiInvocationRuntime {
-	let packageDir: string;
-	try {
-		packageDir = getPackageDir();
-	} catch {
-		throw resolutionError("<unavailable>", "Pi core did not provide its package directory");
-	}
-	const runtimeKind = process.versions.bun
-		? "bun"
-		: process.release.name === "node" && !process.versions.electron
-			? "node"
-			: "unsupported";
-	return {
-		execPath: process.execPath,
-		packageDir,
-		runtimeKind,
-	};
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isWithinDirectory(parent: string, candidate: string): boolean {
-	const relative = path.relative(parent, candidate);
-	return (
-		relative === "" ||
-		(!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))
-	);
-}
-
-function readCoreManifest(packageDir: string): Record<string, unknown> {
-	const manifestPath = path.join(packageDir, "package.json");
-	let source: string;
-	try {
-		source = fs.readFileSync(manifestPath, "utf8");
-	} catch {
-		throw resolutionError(packageDir, "the package manifest is unavailable");
-	}
-	let manifest: unknown;
-	try {
-		manifest = JSON.parse(source);
-	} catch {
-		throw resolutionError(packageDir, "the package manifest is invalid JSON");
-	}
-	if (!isRecord(manifest)) {
-		throw resolutionError(packageDir, "the package manifest is invalid");
-	}
-	if (manifest.name !== CORE_PACKAGE_NAME) {
-		throw resolutionError(packageDir, "the package manifest has an unexpected package name");
-	}
-	return manifest;
-}
-
-function resolveDeclaredBin(packageDir: string, manifest: Record<string, unknown>): string {
-	const bin = manifest.bin;
-	const piBin = isRecord(bin) ? bin.pi : undefined;
-	if (typeof piBin !== "string" || !piBin.trim()) {
-		throw resolutionError(packageDir, "package.json bin.pi must be a non-empty string");
-	}
-	const candidate = path.resolve(packageDir, piBin);
-	if (path.isAbsolute(piBin) || !isWithinDirectory(packageDir, candidate)) {
-		throw resolutionError(packageDir, "the declared bin.pi target escapes the package directory");
-	}
-	return candidate;
-}
-
-function resolveExistingFile(packageDir: string, candidate: string, reason: string): string {
-	let resolved: string;
-	try {
-		resolved = fs.realpathSync(candidate);
-		if (!fs.statSync(resolved).isFile()) throw new Error("not a file");
-	} catch {
-		throw resolutionError(packageDir, reason);
-	}
-	if (!isWithinDirectory(packageDir, resolved)) {
-		throw resolutionError(packageDir, "the declared bin.pi target escapes the package directory");
-	}
-	return resolved;
-}
-
-function resolveStandaloneExecutable(
-	packageDir: string,
-	runtime: PiInvocationRuntime,
-): string | undefined {
-	if (runtime.runtimeKind !== "bun") return undefined;
-	const { execPath } = runtime;
-	if (!/^pi(?:\.exe)?$/i.test(path.basename(execPath))) return undefined;
-	let resolved: string;
-	let mode: number;
-	try {
-		resolved = fs.realpathSync(execPath);
-		const stat = fs.statSync(resolved);
-		if (!stat.isFile()) throw new Error("not a file");
-		mode = stat.mode;
-	} catch {
-		throw resolutionError(packageDir, "the standalone Pi executable is unavailable");
-	}
-	if (path.dirname(resolved) !== packageDir) return undefined;
-	if (process.platform !== "win32" && (mode & 0o111) === 0) {
-		throw resolutionError(packageDir, "the standalone Pi executable is not executable");
-	}
-	return resolved;
-}
-
-export function resolvePiInvocation(
-	args: string[],
-	runtime: PiInvocationRuntime = currentRuntime(),
-): PiInvocation {
-	let packageDir: string;
-	try {
-		packageDir = fs.realpathSync(runtime.packageDir);
-		if (!fs.statSync(packageDir).isDirectory()) throw new Error("not a directory");
-	} catch {
-		throw resolutionError(runtime.packageDir, "the package directory is unavailable");
-	}
-
-	const manifest = readCoreManifest(packageDir);
-	const declaredBin = resolveDeclaredBin(packageDir, manifest);
-	const standalone = resolveStandaloneExecutable(packageDir, runtime);
-	if (standalone) return { command: standalone, args: [...args] };
-
-	if (runtime.runtimeKind !== "node" && runtime.runtimeKind !== "bun") {
-		throw resolutionError(packageDir, "the host does not provide a supported Node or Bun runtime");
-	}
-	const cliPath = resolveExistingFile(
-		packageDir,
-		declaredBin,
-		"the declared bin.pi target is unavailable",
-	);
-	return { command: runtime.execPath, args: [cliPath, ...args] };
-}

package/src/process-control.ts

@@ -1,43 +0,0 @@
-import type { spawn } from "node:child_process";
-
-export const KILL_GRACE_MS = 5000;
-
-function signalProcess(proc: ReturnType<typeof spawn>, signal: NodeJS.Signals): void {
-	if (process.platform !== "win32" && proc.pid) {
-		try {
-			process.kill(-proc.pid, signal);
-			return;
-		} catch {
-			// Fall back to signaling the immediate child when process-group signaling is unavailable.
-		}
-	}
-	try {
-		proc.kill(signal);
-	} catch {
-		// The process may already have exited.
-	}
-}
-
-export function terminateProcess(
-	proc: ReturnType<typeof spawn>,
-	graceMs = KILL_GRACE_MS,
-): () => void {
-	const leaderExited = proc.exitCode !== null || proc.signalCode !== null;
-	const capturedOutputClosed = [proc.stdout, proc.stderr].every(
-		(stream) => !stream || stream.readableEnded || stream.destroyed,
-	);
-	let closed = leaderExited && capturedOutputClosed;
-	const onClose = () => {
-		closed = true;
-	};
-	proc.once("close", onClose);
-	if (!closed) signalProcess(proc, "SIGTERM");
-	const escalation = setTimeout(() => {
-		if (!closed) signalProcess(proc, "SIGKILL");
-	}, graceMs);
-	escalation.unref();
-	return () => {
-		clearTimeout(escalation);
-		proc.off("close", onClose);
-	};
-}

package/src/prompt-resources.ts

@@ -1,38 +0,0 @@
-import {
-	DefaultResourceLoader,
-	getAgentDir,
-	SettingsManager,
-} from "@earendil-works/pi-coding-agent";
-import { assertPiPromptSourcesAreReadableFiles } from "./prompt-source-safety.js";
-
-export interface PiPromptResources {
-	systemPrompt?: string;
-	appendSystemPromptPaths: string[];
-}
-
-/** Resolve Pi-owned prompt files without loading target packages, extensions, or settings. */
-export async function resolvePiPromptResources(
-	cwd: string,
-	projectTrusted: boolean,
-	agentDir = getAgentDir(),
-): Promise<PiPromptResources> {
-	assertPiPromptSourcesAreReadableFiles(cwd, agentDir, projectTrusted, [
-		"SYSTEM.md",
-		"APPEND_SYSTEM.md",
-	]);
-	const loader = new DefaultResourceLoader({
-		cwd,
-		agentDir,
-		settingsManager: SettingsManager.inMemory({}, { projectTrusted }),
-		noExtensions: true,
-		noSkills: true,
-		noPromptTemplates: true,
-		noThemes: true,
-		noContextFiles: true,
-	});
-	await loader.reload();
-	return {
-		systemPrompt: loader.getSystemPrompt(),
-		appendSystemPromptPaths: loader.getAppendSystemPromptSources().map((source) => source.path),
-	};
-}

package/src/prompt-source-safety.ts

@@ -1,48 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
-
-export type PiPromptFileName = "SYSTEM.md" | "APPEND_SYSTEM.md";
-
-/**
- * Prevent Pi's synchronous prompt loader from opening a selected directory, FIFO, socket, device,
- * or unreadable source. Candidate order mirrors core only as a preflight guard; core still resolves
- * and loads the prompt after this check.
- */
-export function assertPiPromptSourcesAreReadableFiles(
-	cwd: string,
-	agentDir: string,
-	projectTrusted: boolean,
-	fileNames: readonly PiPromptFileName[],
-): void {
-	for (const fileName of fileNames) {
-		const candidates = [
-			...(projectTrusted ? [path.join(cwd, CONFIG_DIR_NAME, fileName)] : []),
-			path.join(agentDir, fileName),
-		];
-		for (const candidate of candidates) {
-			const status = promptSourceStatus(candidate);
-			if (status === "missing") continue;
-			if (status === "invalid") {
-				throw new Error(`Pi ${fileName} prompt source must be a readable regular file`);
-			}
-			break;
-		}
-	}
-}
-
-function promptSourceStatus(filePath: string): "missing" | "regular" | "invalid" {
-	let descriptor: number | undefined;
-	try {
-		descriptor = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
-		return fs.fstatSync(descriptor).isFile() ? "regular" : "invalid";
-	} catch (error) {
-		const code =
-			error && typeof error === "object" && "code" in error
-				? (error as { code?: unknown }).code
-				: undefined;
-		return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "invalid";
-	} finally {
-		if (descriptor !== undefined) fs.closeSync(descriptor);
-	}
-}

package/src/protocol.ts

@@ -1,76 +0,0 @@
-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);
-		}
-	}
-}

package/src/registry-types.ts

@@ -1,204 +0,0 @@
-import type { SubagentThinkingLevel } from "./agents/types.js";
-import type { CapabilityGrant } from "./capability-grant.js";
-import type { CompletionRequirementRecord } from "./completion-requirement.js";
-import type { TargetPolicyAudit } from "./cwd-policy.js";
-import type { DelegationContract } from "./delegation-contract.js";
-import type { ExecutionPlan } from "./execution-plan.js";
-import type { ClassifiedSubagentOutcome } from "./outcome.js";
-import type { AnyStructuredSubagentResult, SubagentResultFormat } from "./result-contract.js";
-import type { SemanticCompatibility, SemanticSnapshot } from "./semantic-snapshot.js";
-import type { TurnTerminationReport } from "./timeout-checkpoint.js";
-import type { TransportTelemetry } from "./transport-types.js";
-
-export type AgentLifecycleState =
-	| "starting"
-	| "running"
-	| "idle"
-	| "completed"
-	| "partial"
-	| "blocked"
-	| "needs-input"
-	| "abstained"
-	| "stale"
-	| "interrupted"
-	| "failed"
-	| "closed";
-
-export interface AgentTurn {
-	runId?: string;
-	generation?: number;
-	task: string;
-	output: string;
-	startedAt: number;
-	completedAt: number;
-	exitCode: number;
-	truncated?: boolean;
-	termination?: TurnTerminationReport;
-}
-
-export interface PersistedAgentCompletion {
-	completionId: string;
-	recipientId?: string;
-	recipientPath?: string;
-	runId: string;
-	generation: number;
-	task: string;
-	output: string;
-	error?: string;
-	createdAt: number;
-}
-
-export interface AgentMailboxMessage {
-	id: string;
-	senderId: string;
-	recipientId: string;
-	content: string;
-	createdAt: number;
-	readAt?: number;
-	deduplicationKey?: string;
-	completionId?: string;
-}
-
-export interface ManagedAgent {
-	id: string;
-	taskName?: string;
-	taskPath?: string;
-	agent: string;
-	parentId?: string;
-	rootId: string;
-	depth: number;
-	children: string[];
-	state: AgentLifecycleState;
-	createdAt: number;
-	updatedAt: number;
-	cwd: string;
-	agentScope?: "user" | "project" | "both";
-	thinkingLevel?: SubagentThinkingLevel;
-	timeoutMs?: number;
-	currentTimeoutMs?: number;
-	idleTimeoutMs?: number;
-	currentIdleTimeoutMs?: number;
-	maxTurns?: number;
-	currentMaxTurns?: number;
-	maxToolCalls?: number;
-	currentMaxToolCalls?: number;
-	currentTask?: string;
-	turnGeneration?: number;
-	currentRunId?: string;
-	currentTurnGeneration?: number;
-	pendingCompletions?: PersistedAgentCompletion[];
-	completionRequirements?: CompletionRequirementRecord[];
-	history: AgentTurn[];
-	error?: string;
-	context?: string;
-	contextSourceIds?: string[];
-	contextTruncated?: boolean;
-	contextTurns?: number;
-	contextBytes?: number;
-	workspaceMode?: "worktree";
-	spawnIdempotencyKey?: string;
-	spawnRequestHash?: string;
-	contract?: DelegationContract;
-	resultFormat?: SubagentResultFormat;
-	structuredResult?: AnyStructuredSubagentResult;
-	outcome?: ClassifiedSubagentOutcome;
-	executionPlan?: ExecutionPlan;
-	capabilityGrant?: CapabilityGrant;
-	semanticSnapshot?: SemanticSnapshot;
-	semanticCompatibility?: SemanticCompatibility;
-	termination?: TurnTerminationReport;
-	telemetry?: TransportTelemetry;
-	target?: TargetPolicyAudit;
-	policy?: { inherited: string[]; overridden: string[]; unsupported: string[] };
-	mailbox: AgentMailboxMessage[];
-	currentMailboxMessageIds?: string[];
-}
-
-export interface AgentRunInspectionSummary {
-	id: string;
-	taskName?: string;
-	taskPath?: string;
-	agent: string;
-	state: AgentLifecycleState;
-	createdAt: number;
-	updatedAt: number;
-	historyCount: number;
-	unreadMessages: number;
-	turnGeneration: number;
-	pendingCompletionCount: number;
-	pendingRequiredCompletionCount?: number;
-}
-
-export interface AgentRunInspectionDetail extends AgentRunInspectionSummary {
-	cwd: string;
-	thinkingLevel?: SubagentThinkingLevel;
-	timeoutMs?: number;
-	currentTimeoutMs?: number;
-	idleTimeoutMs?: number;
-	currentIdleTimeoutMs?: number;
-	maxTurns?: number;
-	currentMaxTurns?: number;
-	maxToolCalls?: number;
-	currentMaxToolCalls?: number;
-	currentTask?: string;
-	currentRunId?: string;
-	currentTurnGeneration?: number;
-	error?: string;
-	workspaceMode?: "worktree";
-	contextTurns?: number;
-	contextBytes?: number;
-	contextSources?: number;
-	contextTruncated?: boolean;
-	contract?: DelegationContract;
-	resultFormat?: SubagentResultFormat;
-	target?: TargetPolicyAudit;
-	policy?: { inherited: string[]; overridden: string[]; unsupported: string[] };
-	structuredResult?: AnyStructuredSubagentResult;
-	outcome?: ClassifiedSubagentOutcome;
-	executionPlan?: ExecutionPlan;
-	capabilityGrant?: CapabilityGrant;
-	semanticSnapshot?: SemanticSnapshot;
-	semanticCompatibility?: SemanticCompatibility;
-	termination?: TurnTerminationReport;
-	completionRequirements?: CompletionRequirementRecord[];
-	telemetry?: TransportTelemetry;
-}
-
-export interface AgentInspectionCounts {
-	activeAgents: number;
-	retainedAgents: number;
-}
-
-export interface TurnOutcome {
-	output: string;
-	exitCode: number;
-	aborted?: boolean;
-	truncated?: boolean;
-	error?: string;
-	policy?: ManagedAgent["policy"];
-	structuredResult?: AnyStructuredSubagentResult;
-	outcome?: ClassifiedSubagentOutcome;
-	executionPlan?: ExecutionPlan;
-	termination?: TurnTerminationReport;
-	telemetry?: TransportTelemetry;
-}
-
-export interface AgentTurnCompletion extends PersistedAgentCompletion {
-	agent: ManagedAgent;
-}
-
-export interface AgentRegistryOptions {
-	maxAgents?: number;
-	maxActiveTurns?: number;
-	maxHistoryTurns?: number;
-	maxDepth?: number;
-	maxChildrenPerAgent?: number;
-	maxMailboxMessages?: number;
-	maxMailboxMessageBytes?: number;
-	maxTaskBytes?: number;
-	maxTurnOutputBytes?: number;
-	idleTtlMs?: number;
-	now?: () => number;
-	onChange?: (agents: ManagedAgent[]) => void | Promise<void>;
-	onTurnComplete?: (completion: AgentTurnCompletion) => void | Promise<void>;
-}