@oai404iao/pi-subagent 0.2.0

package/src/agents.ts

@@ -0,0 +1,174 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { assertSupportedToolReferences } from "./tool-policy.ts";
+import type { AgentDefinition, AgentScope, AgentSource } from "./types.ts";
+
+const MAX_AGENT_FILE_BYTES = 256 * 1024;
+const AGENT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const THINKING_LEVELS = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+export interface AgentDiscoveryOptions {
+	cwd: string;
+	scope: AgentScope;
+	projectTrusted: boolean;
+	bundledDir: string;
+	agentDir?: string;
+	includeBundled?: boolean;
+	excludeUserAgentNames?: ReadonlySet<string>;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentDefinition[];
+	diagnostics: string[];
+	projectAgentsDir?: string;
+}
+
+function isDirectory(path: string): boolean {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | undefined {
+	let current = resolve(cwd);
+	while (true) {
+		const candidate = join(current, CONFIG_DIR_NAME, "agents");
+		if (isDirectory(candidate)) return candidate;
+		const parent = dirname(current);
+		if (parent === current) return undefined;
+		current = parent;
+	}
+}
+
+function optionalString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function parseTools(value: unknown, filePath: string): string[] | undefined {
+	const raw = optionalString(value);
+	if (!raw || raw === "*" || raw.toLowerCase() === "all") return undefined;
+	if (raw.toLowerCase() === "none") return [];
+	const tools = [...new Set(raw.split(",").map((tool) => tool.trim()).filter(Boolean))];
+	if (tools.length === 0) throw new Error(`${filePath}: tools must name at least one tool, "all", or "none"`);
+	assertSupportedToolReferences(tools, `${filePath}: tools`);
+	return tools;
+}
+
+function parseThinking(value: unknown, filePath: string): ThinkingLevel | undefined {
+	const thinking = optionalString(value);
+	if (!thinking) return undefined;
+	if (!THINKING_LEVELS.has(thinking as ThinkingLevel)) {
+		throw new Error(`${filePath}: unsupported thinking level "${thinking}"`);
+	}
+	return thinking as ThinkingLevel;
+}
+
+function loadAgentFile(filePath: string, source: AgentSource): AgentDefinition {
+	const stats = statSync(filePath);
+	if (stats.size > MAX_AGENT_FILE_BYTES) {
+		throw new Error(`${filePath}: agent definition exceeds ${MAX_AGENT_FILE_BYTES} bytes`);
+	}
+	const content = readFileSync(filePath, "utf8");
+	const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
+	const name = optionalString(frontmatter.name);
+	const description = optionalString(frontmatter.description);
+	if (!name || !AGENT_NAME_PATTERN.test(name)) {
+		throw new Error(`${filePath}: name must match ${AGENT_NAME_PATTERN}`);
+	}
+	if (!description) throw new Error(`${filePath}: description is required`);
+	if (!body.trim()) throw new Error(`${filePath}: agent system prompt is empty`);
+
+	return {
+		name,
+		description,
+		tools: parseTools(frontmatter.tools, filePath),
+		model: optionalString(frontmatter.model),
+		thinking: parseThinking(frontmatter.thinking, filePath),
+		systemPrompt: body.trim(),
+		source,
+		filePath,
+	};
+}
+
+function loadDirectory(
+	dir: string,
+	source: AgentSource,
+	excludeNames?: ReadonlySet<string>,
+): { agents: AgentDefinition[]; diagnostics: string[] } {
+	if (!isDirectory(dir)) return { agents: [], diagnostics: [] };
+	const agents: AgentDefinition[] = [];
+	const diagnostics: string[] = [];
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch (error) {
+		return {
+			agents,
+			diagnostics: [`${dir}: ${error instanceof Error ? error.message : String(error)}`],
+		};
+	}
+
+	for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+		if (!entry.name.endsWith(".md") || (!entry.isFile() && !entry.isSymbolicLink())) continue;
+		if (excludeNames?.has(entry.name)) continue;
+		const filePath = join(dir, entry.name);
+		try {
+			agents.push(loadAgentFile(filePath, source));
+		} catch (error) {
+			diagnostics.push(error instanceof Error ? error.message : String(error));
+		}
+	}
+	return { agents, diagnostics };
+}
+
+export function discoverAgents(options: AgentDiscoveryOptions): AgentDiscoveryResult {
+	const projectAgentsDir =
+		options.scope !== "user" && options.projectTrusted
+			? findNearestProjectAgentsDir(options.cwd)
+			: undefined;
+	const sources: Array<{ dir: string; source: AgentSource }> = [];
+	if (options.includeBundled !== false) {
+		sources.push({ dir: options.bundledDir, source: "bundled" });
+	}
+	if (options.scope !== "project") {
+		sources.push({ dir: join(options.agentDir ?? getAgentDir(), "agents"), source: "user" });
+	}
+	if (options.scope !== "user" && options.projectTrusted && projectAgentsDir) {
+		sources.push({ dir: projectAgentsDir, source: "project" });
+	}
+
+	const diagnostics: string[] = [];
+	if (options.scope !== "user" && !options.projectTrusted) {
+		diagnostics.push("Project-local agents were not loaded because the project is not trusted.");
+	}
+
+	const byName = new Map<string, AgentDefinition>();
+	for (const item of sources) {
+		const loaded = loadDirectory(
+			item.dir,
+			item.source,
+			item.source === "user" ? options.excludeUserAgentNames : undefined,
+		);
+		diagnostics.push(...loaded.diagnostics);
+		for (const agent of loaded.agents) byName.set(agent.name, agent);
+	}
+
+	return {
+		agents: [...byName.values()],
+		diagnostics,
+		...(projectAgentsDir ? { projectAgentsDir } : {}),
+	};
+}
+
+export function formatAgentCatalog(agents: AgentDefinition[]): string {
+	if (agents.length === 0) return "(no agents)";
+	return agents.map((agent) => `${agent.name} (${agent.source}) — ${agent.description}`).join("\n");
+}
+
+export function hasBundledAgents(dir: string): boolean {
+	return existsSync(dir) && isDirectory(dir);
+}

package/src/catalog.ts

@@ -0,0 +1,89 @@
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { foldDescriptor } from "./descriptor.ts";
+import type { SessionView } from "./providers.ts";
+import type { CatalogDiagnostic, SubagentDescriptor } from "./types.ts";
+
+export interface PersistedDescriptor {
+	id: string;
+	sessionFile: string;
+	descriptor: SubagentDescriptor;
+}
+
+export interface PersistedCatalog {
+	descriptors: PersistedDescriptor[];
+	diagnostics: CatalogDiagnostic[];
+}
+
+async function mapWithConcurrency<T>(
+	items: readonly T[],
+	limit: number,
+	visit: (item: T) => Promise<void>,
+): Promise<void> {
+	let next = 0;
+	const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+		while (true) {
+			const index = next++;
+			if (index >= items.length) return;
+			await visit(items[index]);
+		}
+	});
+	await Promise.all(workers);
+}
+
+export async function readPersistedCatalog(session: SessionView): Promise<PersistedCatalog> {
+	const descriptors: PersistedDescriptor[] = [];
+	const diagnostics: CatalogDiagnostic[] = [];
+	const sessions = await SessionManager.list(session.getCwd(), session.getSessionDir());
+
+	await mapWithConcurrency(sessions, 8, async (info) => {
+		try {
+			const manager = SessionManager.open(info.path, session.getSessionDir(), session.getCwd());
+			const folded = foldDescriptor(manager.getEntries());
+			if (folded.kind === "valid") {
+				const headerParent = manager.getHeader()?.parentSession;
+				if (headerParent !== folded.descriptor.parentSessionFile) {
+					diagnostics.push({
+						kind: "diagnostic",
+						id: manager.getSessionId(),
+						reason: "corrupt",
+						sessionFile: info.path,
+						...(headerParent ? { parentSessionFile: headerParent } : {}),
+						message: "descriptor parentSessionFile does not match the child session header",
+					});
+					return;
+				}
+				descriptors.push({
+					id: manager.getSessionId(),
+					sessionFile: info.path,
+					descriptor: folded.descriptor,
+				});
+			} else if (folded.kind === "corrupt") {
+				const headerParent = manager.getHeader()?.parentSession;
+				diagnostics.push({
+					kind: "diagnostic",
+					id: manager.getSessionId(),
+					reason: "corrupt",
+					sessionFile: info.path,
+					...(headerParent ? { parentSessionFile: headerParent } : {}),
+					message: folded.message,
+				});
+			}
+		} catch (error) {
+			diagnostics.push({
+				kind: "diagnostic",
+				id: info.id,
+				reason: "unavailable",
+				sessionFile: info.path,
+				...(info.parentSessionPath ? { parentSessionFile: info.parentSessionPath } : {}),
+				message: error instanceof Error ? error.message : String(error),
+			});
+		}
+	});
+
+	descriptors.sort(
+		(left, right) =>
+			left.descriptor.createdAt.localeCompare(right.descriptor.createdAt) || left.id.localeCompare(right.id),
+	);
+	diagnostics.sort((left, right) => left.id.localeCompare(right.id));
+	return { descriptors, diagnostics };
+}

package/src/config.ts

@@ -0,0 +1,182 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { AgentScope, ReportDelivery, SubagentSettings } from "./types.ts";
+
+export const CONFIG_FILE_NAME = "subagent.json";
+
+export const DEFAULT_SETTINGS: Readonly<SubagentSettings> = {
+	agentScope: "user",
+	syncBundledAgents: false,
+	maxDepth: 3,
+	enableRunInBackground: true,
+	defaultBackground: true,
+	reportDelivery: "wakeup",
+	inheritExtensions: false,
+	maxOutputBytes: 50 * 1024,
+};
+
+const CONFIG_KEYS = new Set([
+	"$schema",
+	"agentScope",
+	"syncBundledAgents",
+	"maxDepth",
+	"enableRunInBackground",
+	"defaultBackground",
+	"reportDelivery",
+	"inheritExtensions",
+	"maxOutputBytes",
+]);
+
+interface LoadSettingsOptions {
+	cwd: string;
+	projectTrusted: boolean;
+	agentDir?: string;
+}
+
+export interface LoadedSettings {
+	settings: SubagentSettings;
+	sources: string[];
+}
+
+type ConfigRecord = Record<string, unknown>;
+
+function asRecord(value: unknown, filePath: string): ConfigRecord {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error(`${filePath}: configuration must be a JSON object`);
+	}
+	return value as ConfigRecord;
+}
+
+function readConfig(filePath: string): ConfigRecord | undefined {
+	if (!existsSync(filePath)) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(readFileSync(filePath, "utf8"));
+	} catch (error) {
+		throw new Error(`${filePath}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const record = asRecord(parsed, filePath);
+	for (const key of Object.keys(record)) {
+		if (!CONFIG_KEYS.has(key)) throw new Error(`${filePath}: unknown setting "${key}"`);
+	}
+	return record;
+}
+
+function findNearestProjectConfig(cwd: string): string | undefined {
+	let current = resolve(cwd);
+	while (true) {
+		const candidate = join(current, CONFIG_DIR_NAME, CONFIG_FILE_NAME);
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(current);
+		if (parent === current) return undefined;
+		current = parent;
+	}
+}
+
+function parseAgentScope(value: unknown, source: string): AgentScope {
+	if (value === "user" || value === "project" || value === "both") return value;
+	throw new Error(`${source}: agentScope must be "user", "project", or "both"`);
+}
+
+function parseReportDelivery(value: unknown, source: string): ReportDelivery {
+	if (value === "wakeup" || value === "quiet") return value;
+	throw new Error(`${source}: reportDelivery must be "wakeup" or "quiet"`);
+}
+
+function parseBoolean(value: unknown, key: string, source: string): boolean {
+	if (typeof value === "boolean") return value;
+	throw new Error(`${source}: ${key} must be a boolean`);
+}
+
+function parseInteger(
+	value: unknown,
+	key: string,
+	source: string,
+	options: { minimum: number; maximum: number },
+): number {
+	if (
+		typeof value !== "number" ||
+		!Number.isSafeInteger(value) ||
+		value < options.minimum ||
+		value > options.maximum
+	) {
+		throw new Error(
+			`${source}: ${key} must be a safe integer between ${options.minimum} and ${options.maximum}`,
+		);
+	}
+	return value;
+}
+
+function applyConfig(
+	settings: SubagentSettings,
+	config: ConfigRecord,
+	source: string,
+	options: { allowSyncBundledAgents: boolean },
+): SubagentSettings {
+	if (config.syncBundledAgents !== undefined && !options.allowSyncBundledAgents) {
+		throw new Error(`${source}: syncBundledAgents may be configured only in the user-level subagent.json`);
+	}
+	return {
+		agentScope:
+			config.agentScope === undefined ? settings.agentScope : parseAgentScope(config.agentScope, source),
+		syncBundledAgents:
+			config.syncBundledAgents === undefined
+				? settings.syncBundledAgents
+				: parseBoolean(config.syncBundledAgents, "syncBundledAgents", source),
+		maxDepth:
+			config.maxDepth === undefined
+				? settings.maxDepth
+				: parseInteger(config.maxDepth, "maxDepth", source, {
+						minimum: 0,
+						maximum: Number.MAX_SAFE_INTEGER,
+					}),
+		enableRunInBackground:
+			config.enableRunInBackground === undefined
+				? settings.enableRunInBackground
+				: parseBoolean(config.enableRunInBackground, "enableRunInBackground", source),
+		defaultBackground:
+			config.defaultBackground === undefined
+				? settings.defaultBackground
+				: parseBoolean(config.defaultBackground, "defaultBackground", source),
+		reportDelivery:
+			config.reportDelivery === undefined
+				? settings.reportDelivery
+				: parseReportDelivery(config.reportDelivery, source),
+		inheritExtensions:
+			config.inheritExtensions === undefined
+				? settings.inheritExtensions
+				: parseBoolean(config.inheritExtensions, "inheritExtensions", source),
+		maxOutputBytes:
+			config.maxOutputBytes === undefined
+				? settings.maxOutputBytes
+				: parseInteger(config.maxOutputBytes, "maxOutputBytes", source, {
+						minimum: 1024,
+						maximum: 1024 * 1024,
+					}),
+	};
+}
+
+export function loadSettings(options: LoadSettingsOptions): LoadedSettings {
+	let settings: SubagentSettings = { ...DEFAULT_SETTINGS };
+	const sources: string[] = [];
+	const userPath = join(options.agentDir ?? getAgentDir(), CONFIG_FILE_NAME);
+	const userConfig = readConfig(userPath);
+	if (userConfig) {
+		settings = applyConfig(settings, userConfig, userPath, { allowSyncBundledAgents: true });
+		sources.push(userPath);
+	}
+
+	if (options.projectTrusted) {
+		const projectPath = findNearestProjectConfig(options.cwd);
+		if (projectPath) {
+			const projectConfig = readConfig(projectPath);
+			if (projectConfig) {
+				settings = applyConfig(settings, projectConfig, projectPath, { allowSyncBundledAgents: false });
+				sources.push(projectPath);
+			}
+		}
+	}
+
+	return { settings, sources };
+}