@pi-agents/orchid 0.1.0-beta.0

package/src/subagents/shared/file-coalescer.ts

@@ -0,0 +1,40 @@
+interface TimerApi {
+	setTimeout(handler: () => void, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+}
+
+interface FileCoalescer {
+	schedule(file: string, delayMs?: number): boolean;
+	clear(): void;
+}
+
+const defaultTimerApi: TimerApi = {
+	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+export function createFileCoalescer(
+	handler: (file: string) => void,
+	defaultDelayMs: number,
+	timerApi: TimerApi = defaultTimerApi,
+): FileCoalescer {
+	const pending = new Map<string, unknown>();
+
+	return {
+		schedule(file: string, delayMs = defaultDelayMs): boolean {
+			if (pending.has(file)) return false;
+			const timer = timerApi.setTimeout(() => {
+				pending.delete(file);
+				handler(file);
+			}, delayMs);
+			pending.set(file, timer);
+			return true;
+		},
+		clear(): void {
+			for (const timer of pending.values()) {
+				timerApi.clearTimeout(timer);
+			}
+			pending.clear();
+		},
+	};
+}

package/src/subagents/shared/fork-context.ts

@@ -0,0 +1,76 @@
+import * as fs from "node:fs";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+
+type SubagentExecutionContext = "fresh" | "fork";
+
+interface ForkableSessionManager {
+	getSessionFile(): string | undefined;
+	getLeafId(): string | null;
+	getSessionDir?(): string;
+	openSession?: (path: string, sessionDir?: string) => { createBranchedSession(leafId: string): string | undefined };
+}
+
+interface ForkContextResolverOptions {
+	openSession?: (path: string, sessionDir?: string) => { createBranchedSession(leafId: string): string | undefined };
+}
+
+interface ForkContextResolver {
+	sessionFileForIndex(index?: number): string | undefined;
+}
+
+export function resolveSubagentContext(value: unknown): SubagentExecutionContext {
+	return value === "fork" ? "fork" : "fresh";
+}
+
+export function createForkContextResolver(
+	sessionManager: ForkableSessionManager,
+	requestedContext: unknown,
+	options: ForkContextResolverOptions = {},
+): ForkContextResolver {
+	if (resolveSubagentContext(requestedContext) !== "fork") {
+		return {
+			sessionFileForIndex: () => undefined,
+		};
+	}
+
+	const parentSessionFile = sessionManager.getSessionFile();
+	if (!parentSessionFile) {
+		throw new Error("Forked subagent context requires a persisted parent session.");
+	}
+
+	const leafId = sessionManager.getLeafId();
+	if (!leafId) {
+		throw new Error("Forked subagent context requires a current leaf to fork from.");
+	}
+
+	const openSession = options.openSession
+		?? sessionManager.openSession
+		?? ((file: string, dir?: string) => SessionManager.open(file, dir));
+	const sessionDir = sessionManager.getSessionDir?.();
+	const cachedSessionFiles = new Map<number, string>();
+
+	return {
+		sessionFileForIndex(index = 0): string | undefined {
+			const cached = cachedSessionFiles.get(index);
+			if (cached) return cached;
+			try {
+				if (!fs.existsSync(parentSessionFile)) {
+					throw new Error(`Parent session file does not exist: ${parentSessionFile}. Pi has not persisted enough history to fork yet.`);
+				}
+				const sourceManager = openSession(parentSessionFile, sessionDir);
+				const sessionFile = sourceManager.createBranchedSession(leafId);
+				if (!sessionFile) {
+					throw new Error("Session manager did not return a forked session file.");
+				}
+				if (!fs.existsSync(sessionFile)) {
+					throw new Error(`Session manager returned a forked session file that does not exist: ${sessionFile}`);
+				}
+				cachedSessionFiles.set(index, sessionFile);
+				return sessionFile;
+			} catch (error) {
+				const cause = error instanceof Error ? error : new Error(String(error));
+				throw new Error(`Failed to create forked subagent session: ${cause.message}`, { cause });
+			}
+		},
+	};
+}

package/src/subagents/shared/formatters.ts

@@ -0,0 +1,133 @@
+/**
+ * Formatting utilities for display output
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Usage, SingleResult } from "./types.ts";
+import type { ChainStep } from "./settings.ts";
+import { isParallelStep } from "./settings.ts";
+import { splitKnownThinkingSuffix, THINKING_LEVELS } from "./model-info.ts";
+
+/**
+ * Format token count with k suffix for large numbers
+ */
+export function formatTokens(n: number): string {
+	return n < 1000 ? String(n) : n < 10000 ? `${(n / 1000).toFixed(1)}k` : `${Math.round(n / 1000)}k`;
+}
+
+export function formatModelThinking(model?: string, thinking?: string): string {
+	const parsed = model ? splitKnownThinkingSuffix(model) : undefined;
+	let displayModel = parsed?.baseModel ?? model;
+	const explicitThinking = THINKING_LEVELS.find((level) => level === thinking?.trim());
+	const displayThinking = parsed?.thinkingSuffix ? parsed.thinkingSuffix.slice(1) : explicitThinking;
+	if (displayModel) {
+		const slashIdx = displayModel.lastIndexOf("/");
+		if (slashIdx !== -1) displayModel = displayModel.slice(slashIdx + 1);
+	}
+	return [displayModel, displayThinking ? `thinking ${displayThinking}` : undefined].filter(Boolean).join(" · ");
+}
+
+/**
+ * Format usage statistics into a compact string
+ */
+export function formatUsage(u: Usage, model?: string): string {
+	const parts: string[] = [];
+	if (u.turns) parts.push(`${u.turns} turn${u.turns > 1 ? "s" : ""}`);
+	if (u.input) parts.push(`in:${formatTokens(u.input)}`);
+	if (u.output) parts.push(`out:${formatTokens(u.output)}`);
+	if (u.cacheRead) parts.push(`R${formatTokens(u.cacheRead)}`);
+	if (u.cacheWrite) parts.push(`W${formatTokens(u.cacheWrite)}`);
+	if (u.cost) parts.push(`$${u.cost.toFixed(4)}`);
+	if (model) parts.push(model);
+	return parts.join(" ");
+}
+
+/**
+ * Format duration in human-readable form
+ */
+export function formatDuration(ms: number): string {
+	if (ms < 1000) return `${ms}ms`;
+	if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+	return `${Math.floor(ms / 60000)}m${Math.floor((ms % 60000) / 1000)}s`;
+}
+
+/**
+ * Build a summary string for a completed/failed chain
+ */
+export function buildChainSummary(
+	steps: ChainStep[],
+	results: SingleResult[],
+	chainDir: string,
+	status: "completed" | "failed",
+	failedStep?: { index: number; error: string },
+): string {
+	const stepNames = steps
+		.map((step) => (isParallelStep(step) ? `parallel[${step.parallel.length}]` : step.agent))
+		.join(" → ");
+
+	const totalDuration = results.reduce((sum, r) => sum + (r.progress?.durationMs || 0), 0);
+	const durationStr = formatDuration(totalDuration);
+
+	const progressPath = path.join(chainDir, "progress.md");
+	const hasProgress = fs.existsSync(progressPath);
+	const allSkills = new Set<string>();
+	for (const r of results) {
+		if (r.skills) r.skills.forEach((s) => allSkills.add(s));
+	}
+	const skillsLine = allSkills.size > 0 ? `🔧 Skills: ${[...allSkills].join(", ")}` : "";
+
+	if (status === "completed") {
+		const stepWord = results.length === 1 ? "step" : "steps";
+		return `✅ Chain completed: ${stepNames} (${results.length} ${stepWord}, ${durationStr})${skillsLine ? `\n${skillsLine}` : ""}
+
+📋 Progress: ${hasProgress ? progressPath : "(none)"}
+📁 Artifacts: ${chainDir}`;
+	} else {
+		const stepInfo = failedStep ? ` at step ${failedStep.index + 1}` : "";
+		const errorInfo = failedStep?.error ? `: ${failedStep.error}` : "";
+		return `❌ Chain failed${stepInfo}${errorInfo}${skillsLine ? `\n${skillsLine}` : ""}
+
+📋 Progress: ${hasProgress ? progressPath : "(none)"}
+📁 Artifacts: ${chainDir}`;
+	}
+}
+
+/**
+ * Format a tool call for display
+ */
+export function formatToolCall(name: string, args: Record<string, unknown>, expanded = false): string {
+	switch (name) {
+		case "bash": {
+			const command = typeof args.command === "string" ? args.command : "";
+			const maxLength = expanded ? 240 : 60;
+			return `$ ${command.slice(0, maxLength)}${command.length > maxLength ? "..." : ""}`;
+		}
+		case "read":
+		case "write":
+		case "edit": {
+			const target = typeof args.path === "string"
+				? args.path
+				: typeof args.file_path === "string"
+					? args.file_path
+					: "";
+			return `${name} ${shortenPath(target)}`;
+		}
+		default: {
+			const s = JSON.stringify(args);
+			const maxLength = expanded ? 160 : 40;
+			return `${name} ${s.slice(0, maxLength)}${s.length > maxLength ? "..." : ""}`;
+		}
+	}
+}
+
+/**
+ * Shorten a path by replacing home directory with ~
+ */
+export function shortenPath(p: string): string {
+	const home = process.env.HOME;
+	if (home && p.startsWith(home)) {
+		return `~${p.slice(home.length)}`;
+	}
+	return p;
+}

package/src/subagents/shared/jsonl-writer.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs";
+
+export interface DrainableSource {
+	pause(): void;
+	resume(): void;
+}
+
+export interface JsonlWriteStream {
+	write(chunk: string): boolean;
+	once(event: "drain", listener: () => void): JsonlWriteStream;
+	end(callback?: () => void): void;
+}
+
+const DEFAULT_MAX_JSONL_BYTES = 50 * 1024 * 1024;
+
+interface JsonlWriterDeps {
+	createWriteStream?: (filePath: string) => JsonlWriteStream;
+	maxBytes?: number;
+}
+
+interface JsonlWriter {
+	writeLine(line: string): void;
+	close(): Promise<void>;
+}
+
+export function createJsonlWriter(
+	filePath: string | undefined,
+	source: DrainableSource,
+	deps: JsonlWriterDeps = {},
+): JsonlWriter {
+	if (!filePath) {
+		return {
+			writeLine() {},
+			async close() {},
+		};
+	}
+
+	const createWriteStream = deps.createWriteStream ?? ((targetPath: string) => fs.createWriteStream(targetPath, { flags: "a" }));
+	let stream: JsonlWriteStream | undefined;
+	try {
+		stream = createWriteStream(filePath);
+	} catch {
+		return {
+			writeLine() {},
+			async close() {},
+		};
+	}
+
+	let backpressured = false;
+	let closed = false;
+	let bytesWritten = 0;
+	const maxBytes = deps.maxBytes ?? DEFAULT_MAX_JSONL_BYTES;
+
+	return {
+		writeLine(line: string) {
+			if (!stream || closed || !line.trim()) return;
+			const chunk = `${line}\n`;
+			const chunkBytes = Buffer.byteLength(chunk, "utf-8");
+			if (bytesWritten + chunkBytes > maxBytes) return;
+			try {
+				const ok = stream.write(chunk);
+				bytesWritten += chunkBytes;
+				if (!ok && !backpressured) {
+					backpressured = true;
+					source.pause();
+					stream.once("drain", () => {
+						backpressured = false;
+						if (!closed) source.resume();
+					});
+				}
+			} catch {}
+		},
+		async close() {
+			if (!stream || closed) return;
+			closed = true;
+			const current = stream;
+			stream = undefined;
+			await new Promise<void>((resolve) => current.end(() => resolve()));
+		},
+	};
+}

package/src/subagents/shared/model-info.ts

@@ -0,0 +1,78 @@
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+export type ThinkingLevel = typeof THINKING_LEVELS[number];
+export type ThinkingLevelMap = Partial<Record<ThinkingLevel, string | null>>;
+
+export interface ModelInfo {
+	provider: string;
+	id: string;
+	fullId: string;
+	reasoning?: boolean;
+	thinkingLevelMap?: ThinkingLevelMap;
+}
+
+interface RegistryModelLike {
+	provider: string;
+	id: string;
+	reasoning?: boolean;
+	thinkingLevelMap?: ThinkingLevelMap;
+}
+
+export function toModelInfo(model: RegistryModelLike): ModelInfo {
+	return {
+		provider: model.provider,
+		id: model.id,
+		fullId: `${model.provider}/${model.id}`,
+		reasoning: model.reasoning,
+		thinkingLevelMap: model.thinkingLevelMap,
+	};
+}
+
+/** Resolve the effective thinking level from a model string (which may contain a known suffix like `:high`)
+ * and an explicit thinking config value. Returns `undefined` when no thinking is applicable
+ * (e.g. no model was specified, or the model has no suffix and no config was provided). */
+export function resolveEffectiveThinking(model: string | undefined, configThinking: string | undefined): string | undefined {
+	if (!model) return undefined;
+	const { thinkingSuffix } = splitKnownThinkingSuffix(model);
+	if (thinkingSuffix) return thinkingSuffix.slice(1);
+	return THINKING_LEVELS.find((level) => level === configThinking);
+}
+
+export function splitKnownThinkingSuffix(model: string): { baseModel: string; thinkingSuffix: string } {
+	const colonIdx = model.lastIndexOf(":");
+	if (colonIdx === -1) return { baseModel: model, thinkingSuffix: "" };
+	const suffix = THINKING_LEVELS.find((level) => level === model.substring(colonIdx + 1));
+	if (!suffix) return { baseModel: model, thinkingSuffix: "" };
+	return {
+		baseModel: model.substring(0, colonIdx),
+		thinkingSuffix: `:${suffix}`,
+	};
+}
+
+export function findModelInfo(model: string | undefined, availableModels: ModelInfo[] | undefined, preferredProvider?: string): ModelInfo | undefined {
+	if (!model || !availableModels || availableModels.length === 0) return undefined;
+	const { baseModel } = splitKnownThinkingSuffix(model);
+	const exact = availableModels.find((entry) => entry.fullId === baseModel);
+	if (exact) return exact;
+
+	const matches = availableModels.filter((entry) => entry.id === baseModel);
+	if (preferredProvider) {
+		const preferred = matches.find((entry) => entry.provider === preferredProvider);
+		if (preferred) return preferred;
+	}
+	return matches.length === 1 ? matches[0] : undefined;
+}
+
+export function getSupportedThinkingLevels(model: ModelInfo | undefined): ThinkingLevel[] {
+	if (!model) return [...THINKING_LEVELS];
+	if (model.reasoning === false) return ["off"];
+
+	if (!model.thinkingLevelMap) return [...THINKING_LEVELS];
+
+	const levels = THINKING_LEVELS.filter((level) => {
+		const mapped = model.thinkingLevelMap?.[level];
+		if (mapped === null) return false;
+		if (level === "xhigh") return mapped !== undefined;
+		return true;
+	});
+	return levels;
+}

package/src/subagents/shared/post-exit-stdio-guard.ts

@@ -0,0 +1,85 @@
+import type { ChildProcess } from "node:child_process";
+
+interface PostExitStdioGuardOptions {
+	idleMs: number;
+	hardMs: number;
+}
+
+interface ChildWithPipedStdio {
+	stdout: ChildProcess["stdout"];
+	stderr: ChildProcess["stderr"];
+	on: ChildProcess["on"];
+}
+
+interface ChildWithKill {
+	kill(signal?: NodeJS.Signals | number): boolean;
+}
+
+export function trySignalChild(child: ChildWithKill, signal: NodeJS.Signals): boolean {
+	try {
+		return child.kill(signal);
+	} catch {
+		return false;
+	}
+}
+
+export function attachPostExitStdioGuard(
+	child: ChildWithPipedStdio,
+	options: PostExitStdioGuardOptions,
+): () => void {
+	const { idleMs, hardMs } = options;
+	let exited = false;
+	let stdoutEnded = false;
+	let stderrEnded = false;
+	let idleTimer: NodeJS.Timeout | undefined;
+	let hardTimer: NodeJS.Timeout | undefined;
+
+	const destroyUnendedStdio = () => {
+		if (!stdoutEnded) {
+			try { child.stdout?.destroy(); } catch {}
+		}
+		if (!stderrEnded) {
+			try { child.stderr?.destroy(); } catch {}
+		}
+	};
+
+	const clearTimers = () => {
+		if (idleTimer) {
+			clearTimeout(idleTimer);
+			idleTimer = undefined;
+		}
+		if (hardTimer) {
+			clearTimeout(hardTimer);
+			hardTimer = undefined;
+		}
+	};
+
+	const armIdleTimer = () => {
+		if (!exited) return;
+		if (idleTimer) clearTimeout(idleTimer);
+		idleTimer = setTimeout(destroyUnendedStdio, idleMs);
+		idleTimer.unref?.();
+	};
+
+	child.stdout?.on("data", armIdleTimer);
+	child.stderr?.on("data", armIdleTimer);
+	child.stdout?.on("end", () => {
+		stdoutEnded = true;
+		if (stdoutEnded && stderrEnded) clearTimers();
+	});
+	child.stderr?.on("end", () => {
+		stderrEnded = true;
+		if (stdoutEnded && stderrEnded) clearTimers();
+	});
+	child.on("exit", () => {
+		exited = true;
+		armIdleTimer();
+		if (hardTimer) return;
+		hardTimer = setTimeout(destroyUnendedStdio, hardMs);
+		hardTimer.unref?.();
+	});
+	child.on("close", clearTimers);
+	child.on("error", clearTimers);
+
+	return clearTimers;
+}

package/src/subagents/shared/session-identity.ts

@@ -0,0 +1,10 @@
+interface SessionIdentityManager {
+	getSessionFile(): string | null | undefined;
+	getSessionId(): string | null | undefined;
+}
+
+export function resolveCurrentSessionId(sessionManager: SessionIdentityManager): string {
+	const sessionId = sessionManager.getSessionFile() ?? sessionManager.getSessionId();
+	if (!sessionId) throw new Error("Current session identity is unavailable.");
+	return sessionId;
+}

package/src/subagents/shared/session-tokens.ts

@@ -0,0 +1,44 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TokenUsage } from "./types.ts";
+
+function findLatestSessionFile(sessionDir: string): string | null {
+	try {
+		const files = fs.readdirSync(sessionDir)
+			.filter((f) => f.endsWith(".jsonl"))
+			.map((f) => path.join(sessionDir, f));
+		if (files.length === 0) return null;
+		files.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+		return files[0] ?? null;
+	} catch {
+		// Session token lookup is optional metadata.
+		return null;
+	}
+}
+
+export function parseSessionTokens(sessionDir: string): TokenUsage | null {
+	const sessionFile = findLatestSessionFile(sessionDir);
+	if (!sessionFile) return null;
+	try {
+		const content = fs.readFileSync(sessionFile, "utf-8");
+		let input = 0;
+		let output = 0;
+		for (const line of content.split("\n")) {
+			if (!line.trim()) continue;
+			try {
+				const entry = JSON.parse(line);
+				const usage = entry.usage ?? entry.message?.usage;
+				if (usage) {
+					input += usage.inputTokens ?? usage.input ?? 0;
+					output += usage.outputTokens ?? usage.output ?? 0;
+				}
+			} catch {
+				// Ignore malformed lines while scanning usage entries.
+			}
+		}
+		return { input, output, total: input + output };
+	} catch {
+		// Usage extraction should not fail the run.
+		return null;
+	}
+}