@youngjurry/pi-agents 0.7.1

package/index.ts

@@ -0,0 +1,300 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { AgentControl } from "./control.ts";
+import { getAgentSettingsPath, loadAgentSettings, resolveAgentLimits } from "./settings.ts";
+import { createCollaborationTools } from "./tools.ts";
+import { EXTENSION_ID, ROOT_PATH, type AgentLifecycleStatus, type AgentView } from "./types.ts";
+import { AgentPickerComponent, AgentTranscriptViewer } from "./viewer.ts";
+
+const SELF_PATH = fileURLToPath(import.meta.url);
+const WIDGET_KEY = "codex-agents-tree";
+const STATUS_KEY = "codex-agents";
+const PROMPT_MARKER = "<multi_agent_role>";
+
+function statusIcon(status: AgentLifecycleStatus): string {
+	switch (status) {
+		case "queued": return "◷";
+		case "running": return "●";
+		case "completed": return "✓";
+		case "errored": return "✗";
+		case "interrupted": return "■";
+		case "pending_init": return "○";
+		case "shutdown": return "×";
+	}
+}
+
+function statusColor(status: AgentLifecycleStatus): "success" | "error" | "warning" | "muted" | "dim" {
+	switch (status) {
+		case "queued": return "dim";
+		case "running": return "warning";
+		case "completed": return "success";
+		case "errored": return "error";
+		case "interrupted": return "muted";
+		case "pending_init": return "dim";
+		case "shutdown": return "muted";
+	}
+}
+
+function treeLine(agent: AgentView, theme: Theme): string {
+	const depth = Math.max(0, agent.path.split("/").filter(Boolean).length - 1);
+	const indent = "  ".repeat(depth);
+	const branch = depth > 0 ? "└─ " : "";
+	const name = agent.path === ROOT_PATH ? ROOT_PATH : agent.path.split("/").at(-1) || agent.path;
+	const icon = theme.fg(statusColor(agent.status), statusIcon(agent.status));
+	const residency = agent.status === "queued"
+		? theme.fg("warning", ` [waiting #${agent.queuePosition ?? "?"}]`)
+		: agent.path === ROOT_PATH || agent.loaded ? "" : theme.fg("dim", " [unloaded]");
+	const nickname = agent.nickname ? theme.fg("muted", ` (${agent.nickname})`) : "";
+	const runtime = agent.path === ROOT_PATH
+		? ""
+		: theme.fg("dim", ` · thinking ${agent.thinkingLevel ?? "unknown"} · ${agent.model}`);
+	return `${indent}${branch}${icon} ${theme.fg("accent", name)}${nickname}${residency}${runtime}`;
+}
+
+class AgentTreeWidget {
+	constructor(
+		private readonly control: AgentControl,
+		private readonly getContext: () => ExtensionContext | undefined,
+		private readonly theme: Theme,
+	) {}
+
+	render(width: number): string[] {
+		const ctx = this.getContext();
+		if (!ctx) return [];
+		let agents: AgentView[];
+		try {
+			agents = this.control.list(ctx);
+		} catch {
+			return [];
+		}
+		const visibleAgents = agents.filter((agent) => agent.path !== ROOT_PATH && (agent.status === "running" || agent.status === "pending_init" || agent.status === "queued"));
+		if (visibleAgents.length === 0) return [];
+		const counts = this.control.getCounts();
+		const queueSummary = counts.queued > 0 ? ` · queued: ${counts.queued}` : "";
+		const lines = [
+			this.theme.fg("muted", `Agents active: ${counts.running}/${counts.slots}${queueSummary}`),
+			...visibleAgents.slice(0, 8).map((agent) => treeLine(agent, this.theme)),
+		];
+		if (visibleAgents.length > 8) lines.push(this.theme.fg("dim", `  … ${visibleAgents.length - 8} more; use /agents`));
+		return lines.map((line) => truncateToWidth(line, Math.max(1, width)));
+	}
+
+	invalidate(): void {}
+}
+
+export default function codexAgentsExtension(pi: ExtensionAPI): void {
+	const limits = resolveAgentLimits(loadAgentSettings(), getAgentSettingsPath());
+	const control = new AgentControl(
+		pi,
+		path.resolve(SELF_PATH),
+		limits.maxConcurrentSubagents,
+		limits.maxResidentSubagents,
+	);
+	const tools = createCollaborationTools(control);
+	control.setTools(tools);
+	for (const tool of tools) pi.registerTool(tool);
+
+	let activeContext: ExtensionContext | undefined;
+	let widgetTui: { requestRender(): void } | undefined;
+
+	const updateUi = () => {
+		const ctx = activeContext;
+		if (!ctx) return;
+		let activeAgentCount = 0;
+		let queuedAgentCount = 0;
+		try {
+			const counts = control.getCounts();
+			activeAgentCount = counts.running;
+			queuedAgentCount = counts.queued;
+		} catch {
+			// Root context can be transiently unavailable during reload/shutdown.
+		}
+		ctx.ui.setStatus(
+			STATUS_KEY,
+			activeAgentCount > 0 || queuedAgentCount > 0
+				? ctx.ui.theme.fg("warning", `agents ${activeAgentCount} active${queuedAgentCount > 0 ? ` · ${queuedAgentCount} waiting` : ""}`)
+				: undefined,
+		);
+		widgetTui?.requestRender();
+	};
+	control.onChange(updateUi);
+
+	pi.on("session_start", (event, ctx) => {
+		activeContext = ctx;
+		control.bindRoot(ctx);
+		const resumedExistingSession = event.reason === "resume"
+			|| (event.reason === "startup" && ctx.sessionManager.getEntries().some((entry) => entry.type === "message"));
+		if (resumedExistingSession) {
+			const removed = control.cleanupOrphanStorage(ctx.sessionManager.getSessionId());
+			if (removed > 0) ctx.ui.notify(`Cleaned ${removed} orphaned agent storage ${removed === 1 ? "group" : "groups"}.`, "info");
+		}
+		control.configureInitialRootTools();
+		if (ctx.mode === "tui") {
+			ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+				widgetTui = tui;
+				return new AgentTreeWidget(control, () => activeContext, theme);
+			}, { placement: "belowEditor" });
+		}
+		updateUi();
+	});
+
+	pi.on("before_agent_start", (event, ctx) => {
+		activeContext = ctx;
+		control.refreshRootContext(ctx);
+		if (event.systemPrompt.includes(PROMPT_MARKER)) return;
+		return { systemPrompt: `${event.systemPrompt}\n\n${control.getRootInstructions()}` };
+	});
+
+	pi.on("agent_start", (_event, ctx) => {
+		activeContext = ctx;
+		control.setRootStatus("running");
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		activeContext = ctx;
+		control.setRootStatus("completed");
+	});
+
+	pi.on("turn_start", (_event, ctx) => {
+		activeContext = ctx;
+		control.noteTurnStart(ROOT_PATH);
+		control.markMailboxConsumed(ROOT_PATH);
+	});
+
+	pi.on("turn_end", (event, ctx) => {
+		activeContext = ctx;
+		control.noteTurnEnd(ROOT_PATH, event.message.role === "assistant" ? event.message.stopReason : undefined);
+	});
+
+	pi.on("model_select", (_event, ctx) => {
+		activeContext = ctx;
+		control.refreshRootContext(ctx);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		activeContext = ctx;
+		await control.shutdown();
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+		ctx.ui.setWidget(WIDGET_KEY, undefined);
+		activeContext = undefined;
+		widgetTui = undefined;
+	});
+
+	pi.registerMessageRenderer(EXTENSION_ID, (message, _options, theme) => {
+		const content = typeof message.content === "string"
+			? message.content
+			: message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+		const messageDetails = message.details as { type?: string } | undefined;
+		if (messageDetails?.type === "AGENT_STATUS") {
+			return new Text(theme.fg("customMessageText", content), 1, 0);
+		}
+		const [typeLine = "Agent message", taskLine = "", senderLine = "", ...payload] = content.split("\n");
+		const title = typeLine.replace("Message Type: ", "");
+		const task = taskLine.replace("Task name: ", "");
+		const sender = senderLine.replace("Sender: ", "");
+		const body = payload[0] === "Payload:" ? payload.slice(1).join("\n") : payload.join("\n");
+		const header = `${theme.fg("customMessageLabel", theme.bold(title))} ${theme.fg("accent", task)} ${theme.fg("muted", `from ${sender}`)}`;
+		return new Text(`${header}\n${theme.fg("customMessageText", body)}`, 1, 0);
+	});
+
+	pi.registerCommand("agents", {
+		description: "Browse sub-agent status and inspect read-only session transcripts",
+		getArgumentCompletions: (prefix) => {
+			const ctx = activeContext;
+			if (!ctx) return null;
+			const query = prefix.trim();
+			let agents: AgentView[];
+			try {
+				agents = control.list(ctx).filter((agent) => agent.path !== ROOT_PATH);
+			} catch {
+				return null;
+			}
+			const matches = agents
+				.filter((agent) => !query || agent.path.startsWith(query))
+				.map((agent) => ({
+					value: agent.path,
+					label: agent.path,
+					description: `${agent.status} · ${agent.model} · thinking ${agent.thinkingLevel ?? "unknown"}`,
+				}));
+			return matches.length > 0 ? matches : null;
+		},
+		handler: async (args, ctx) => {
+			activeContext = ctx;
+			const requestedPath = args.trim();
+			if (ctx.mode !== "tui") {
+				if (requestedPath) {
+					try {
+						const transcript = control.transcript(ctx, requestedPath);
+						ctx.ui.notify(`${transcript.agent.path}: ${transcript.agent.status} · ${transcript.agent.model} · thinking ${transcript.agent.thinkingLevel ?? "unknown"} · ${transcript.messages.length} messages\n${transcript.sessionFile}`, "info");
+					} catch (error) {
+						ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+					}
+					return;
+				}
+				const agents = control.list(ctx).filter((agent) => agent.path !== ROOT_PATH);
+				ctx.ui.notify(agents.length > 0 ? agents.map((agent) => `${agent.path}: ${agent.status} · ${agent.model} · thinking ${agent.thinkingLevel ?? "unknown"}`).join("\n") : "No sub-agents in this root session", "info");
+				return;
+			}
+
+			const releaseUserOverlay = control.beginUserOverlay();
+			try {
+				let targetPath = requestedPath || undefined;
+				while (true) {
+					if (!targetPath) {
+						targetPath = await ctx.ui.custom<string | undefined>(
+							(tui, theme, keybindings, done) => new AgentPickerComponent(
+								tui,
+								theme,
+								keybindings,
+								() => control.list(ctx),
+								(listener) => control.onChange(listener),
+								done,
+							),
+							{
+								overlay: true,
+								overlayOptions: { anchor: "center", width: "68%", maxHeight: "82%", margin: 1 },
+							},
+						);
+						if (!targetPath) return;
+					}
+
+					try {
+						await control.prepareTranscriptToolDefinitions(ctx);
+					} catch (error) {
+						ctx.ui.notify(`Some custom tool renderers could not be loaded: ${error instanceof Error ? error.message : String(error)}`, "warning");
+					}
+
+					try {
+						control.transcript(ctx, targetPath);
+					} catch (error) {
+						ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+						if (requestedPath) return;
+						targetPath = undefined;
+						continue;
+					}
+
+					const selectedPath = targetPath;
+					await ctx.ui.custom<void>(
+						(tui, theme, keybindings, done) => new AgentTranscriptViewer(
+							tui,
+							theme,
+							keybindings,
+							() => control.transcript(ctx, selectedPath),
+							(listener) => control.onChange(listener),
+							done,
+						),
+						{
+							overlay: true,
+							overlayOptions: { anchor: "center", width: "92%", maxHeight: "92%", margin: 1 },
+						},
+					);
+					targetPath = undefined;
+				}
+			} finally {
+				releaseUserOverlay();
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@youngjurry/pi-agents",
+  "version": "0.7.1",
+  "description": "Persistent in-process Codex-style multi-agent collaboration for Pi",
+  "author": "youngjurry",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "multi-agent",
+    "subagent",
+    "codex"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YoungJurry/pi-agents.git"
+  },
+  "homepage": "https://github.com/YoungJurry/pi-agents#readme",
+  "bugs": {
+    "url": "https://github.com/YoungJurry/pi-agents/issues"
+  },
+  "scripts": {
+    "check": "tsc -p tsconfig.json",
+    "test": "tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "files": [
+    "*.ts",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": { "optional": true },
+    "@earendil-works/pi-agent-core": { "optional": true },
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "@earendil-works/pi-tui": { "optional": true },
+    "typebox": { "optional": true }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-agent-core": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
+    "@types/node": "^26.4.0",
+    "tsx": "^4.23.13",
+    "typebox": "^1.3.7",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/roles.ts

@@ -0,0 +1,116 @@
+import * as fs from "node:fs";
+import * as path 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 type { AgentRole } from "./types.ts";
+
+const BUILTIN_ROLES: AgentRole[] = [
+	{
+		name: "default",
+		description: "General-purpose coding agent",
+		systemPrompt: "",
+		source: "builtin",
+	},
+	{
+		name: "explorer",
+		description: "Read-only codebase exploration and focused research",
+		systemPrompt: "Explore the codebase efficiently. Do not modify files. Return concise findings with exact paths and relevant implementation details.",
+		tools: ["read", "bash", "grep", "find", "ls"],
+		source: "builtin",
+	},
+	{
+		name: "awaiter",
+		description: "Wait for long-running commands or tasks and report completion",
+		systemPrompt: "Wait conservatively for the assigned command or task to reach a terminal state. Do not modify or optimize it. Use long waits, do not hallucinate completion, and report the final status only when known.",
+		thinkingLevel: "low",
+		source: "builtin",
+	},
+];
+
+type RoleFrontmatter = {
+	name?: unknown;
+	description?: unknown;
+	tools?: unknown;
+	model?: unknown;
+	thinking?: unknown;
+	nickname_candidates?: unknown;
+};
+
+const THINKING_LEVELS = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+function stringList(value: unknown): string[] | undefined {
+	const values = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+	const result = values.filter((item): item is string => typeof item === "string").map((item) => item.trim()).filter(Boolean);
+	return result.length > 0 ? result : undefined;
+}
+
+function loadDirectory(directory: string, source: "user" | "project"): AgentRole[] {
+	if (!fs.existsSync(directory)) return [];
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(directory, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const roles: AgentRole[] = [];
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md") || (!entry.isFile() && !entry.isSymbolicLink())) continue;
+		try {
+			const content = fs.readFileSync(path.join(directory, entry.name), "utf8");
+			const { frontmatter, body } = parseFrontmatter<RoleFrontmatter>(content);
+			if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") continue;
+			const thinking = typeof frontmatter.thinking === "string" && THINKING_LEVELS.has(frontmatter.thinking as ThinkingLevel)
+				? frontmatter.thinking as ThinkingLevel
+				: undefined;
+			roles.push({
+				name: frontmatter.name.trim(),
+				description: frontmatter.description.trim(),
+				systemPrompt: body.trim(),
+				tools: stringList(frontmatter.tools),
+				model: typeof frontmatter.model === "string" ? frontmatter.model.trim() : undefined,
+				thinkingLevel: thinking,
+				nicknameCandidates: stringList(frontmatter.nickname_candidates),
+				source,
+			});
+		} catch {
+			// A malformed role must not prevent other roles from loading.
+		}
+	}
+	return roles;
+}
+
+function nearestProjectRoles(cwd: string): string | undefined {
+	let current = path.resolve(cwd);
+	while (true) {
+		const candidate = path.join(current, CONFIG_DIR_NAME, "agents");
+		try {
+			if (fs.statSync(candidate).isDirectory()) return candidate;
+		} catch {
+			// Continue walking.
+		}
+		const parent = path.dirname(current);
+		if (parent === current) return undefined;
+		current = parent;
+	}
+}
+
+export function discoverRoles(cwd: string, projectTrusted: boolean): AgentRole[] {
+	const roles = new Map<string, AgentRole>();
+	for (const role of BUILTIN_ROLES) roles.set(role.name, role);
+	for (const role of loadDirectory(path.join(getAgentDir(), "agents"), "user")) roles.set(role.name, role);
+	const projectDirectory = nearestProjectRoles(cwd);
+	if (projectTrusted && projectDirectory) {
+		for (const role of loadDirectory(projectDirectory, "project")) roles.set(role.name, role);
+	}
+	return [...roles.values()];
+}
+
+export function resolveRole(cwd: string, projectTrusted: boolean, name?: string): AgentRole {
+	const roleName = name?.trim() || "default";
+	const role = discoverRoles(cwd, projectTrusted).find((candidate) => candidate.name === roleName);
+	if (!role) {
+		const names = discoverRoles(cwd, projectTrusted).map((candidate) => candidate.name).join(", ");
+		throw new Error(`unknown agent_type '${roleName}'. Available roles: ${names}`);
+	}
+	return role;
+}

package/settings.ts

@@ -0,0 +1,102 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import {
+	clampThinkingLevel,
+	getSupportedThinkingLevels,
+	type Model,
+} from "@earendil-works/pi-ai";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const DEFAULT_MAX_CONCURRENT_SUBAGENTS = 3;
+export const DEFAULT_MAX_RESIDENT_SUBAGENTS = 3;
+export const DEFAULT_CHILD_THINKING_LEVEL: ThinkingLevel = "medium";
+export const CHILD_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+export interface AgentSettings {
+	defaultModel?: string;
+	defaultThinkingLevel?: ThinkingLevel;
+	maxConcurrentSubagents?: number;
+	maxResidentSubagents?: number;
+}
+
+export interface AgentLimits {
+	maxConcurrentSubagents: number;
+	maxResidentSubagents: number;
+}
+
+export function getAgentSettingsPath(): string {
+	return path.join(getAgentDir(), "codex-agents", "agents-setting.json");
+}
+
+export function selectAgentModel(...candidates: Array<string | undefined>): string | undefined {
+	for (const candidate of candidates) {
+		const model = candidate?.trim();
+		if (model) return model;
+	}
+	return undefined;
+}
+
+export function selectAgentThinkingLevel(
+	model: Model<any>,
+	explicitModel: string | undefined,
+	explicitThinking: ThinkingLevel | undefined,
+	roleThinking: ThinkingLevel | undefined,
+	globalThinking: ThinkingLevel | undefined,
+): ThinkingLevel {
+	if (explicitThinking !== undefined) return clampThinkingLevel(model, explicitThinking) as ThinkingLevel;
+	if (explicitModel?.trim()) {
+		const levels = getSupportedThinkingLevels(model);
+		return (levels.at(-1) ?? "off") as ThinkingLevel;
+	}
+	return clampThinkingLevel(model, roleThinking ?? globalThinking ?? DEFAULT_CHILD_THINKING_LEVEL) as ThinkingLevel;
+}
+
+export function loadAgentSettings(filePath = getAgentSettingsPath()): AgentSettings {
+	if (!fs.existsSync(filePath)) return {};
+
+	let value: unknown;
+	try {
+		value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`failed to read agent settings at ${filePath}: ${message}`);
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error(`agent settings at ${filePath} must contain a JSON object`);
+	}
+
+	const raw = value as Record<string, unknown>;
+	const settings: AgentSettings = {};
+	if (raw.defaultModel !== undefined) {
+		if (typeof raw.defaultModel !== "string" || !raw.defaultModel.trim()) {
+			throw new Error(`defaultModel in ${filePath} must be a non-empty provider/model string`);
+		}
+		settings.defaultModel = raw.defaultModel.trim();
+	}
+	if (raw.defaultThinkingLevel !== undefined) {
+		if (typeof raw.defaultThinkingLevel !== "string" || !CHILD_THINKING_LEVELS.includes(raw.defaultThinkingLevel as ThinkingLevel)) {
+			throw new Error(`defaultThinkingLevel in ${filePath} must be one of: ${CHILD_THINKING_LEVELS.join(", ")}`);
+		}
+		settings.defaultThinkingLevel = raw.defaultThinkingLevel as ThinkingLevel;
+	}
+	for (const key of ["maxConcurrentSubagents", "maxResidentSubagents"] as const) {
+		const limit = raw[key];
+		if (limit === undefined) continue;
+		if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1) {
+			throw new Error(`${key} in ${filePath} must be a positive integer`);
+		}
+		settings[key] = limit;
+	}
+	return settings;
+}
+
+export function resolveAgentLimits(settings: AgentSettings, filePath = getAgentSettingsPath()): AgentLimits {
+	const maxConcurrentSubagents = settings.maxConcurrentSubagents ?? DEFAULT_MAX_CONCURRENT_SUBAGENTS;
+	const maxResidentSubagents = settings.maxResidentSubagents
+		?? Math.max(DEFAULT_MAX_RESIDENT_SUBAGENTS, maxConcurrentSubagents);
+	if (maxResidentSubagents < maxConcurrentSubagents) {
+		throw new Error(`maxResidentSubagents in ${filePath} must be greater than or equal to maxConcurrentSubagents`);
+	}
+	return { maxConcurrentSubagents, maxResidentSubagents };
+}