@youngjurry/pi-agents 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.7.3 - 2026-09-05
+
+- Fold the full `wait_agent` status tree by default and reuse Pi's `Ctrl+O` expansion state to reveal it on demand.
+- Keep provider-facing wait results limited to newly queued mailbox notices while avoiding overwhelming TUI output.
+- Add optional Role `skills` frontmatter that injects selected complete `SKILL.md` instructions into child system prompts.
+- Report configured Role skills through on-demand Role discovery and fail clearly when a selected Skill is unavailable.
+
+## 0.7.2 - 2026-09-02
+
+- Keep execution slots reserved until an `AgentSession` is fully settled and safe to evict.
+- Treat temporary resident saturation as queue backpressure instead of permanently failing waiting agents.
+- Resume blocked FIFO scheduling on settlement without busy-looping or losing wake-up signals.
+- Add regression coverage for the batch overflow race that previously produced `agent residency limit reached` errors.
+
 ## 0.7.1 - 2026-09-01
 
 - Order the `/agents` picker by latest task assignment, newest first, instead of alphabetically.

package/README.md

@@ -125,6 +125,7 @@ Role format:
 name: reviewer
 description: Review code without editing
 tools: read, grep, find, ls, bash
+skills: [document]
 model: openai/gpt-5.4
 thinking: high
 nickname_candidates: [Ada, Grace]
@@ -133,6 +134,8 @@ nickname_candidates: [Ada, Grace]
 Review carefully and return findings with exact paths.
 ```
 
+`skills` is optional. Each named Skill must be discoverable by Pi. Its complete `SKILL.md` is loaded into that Role's child system prompt, including for tightly restricted Roles that do not expose `read` or `bash`. Relative references remain rooted at the Skill's base directory. Unknown Skill names fail explicitly instead of silently weakening the Role. Roles without `skills` retain Pi's normal progressive disclosure: the Skill catalog appears only when `read` or `bash` is active, and the child decides whether to load a matching Skill.
+
 ## Model configuration
 
 Global sub-agent settings live outside the installed package so updates cannot overwrite them:
@@ -177,6 +180,7 @@ The settings file is optional, but spawning requires a model from either the tas
 - Referenced legacy flat child files are migrated when their main session is resumed
 - Parents receive a compact completion notice instead of the full answer; use `list_agents(view="results")` or read the result file on demand
 - Notices to a busy agent are queued safely: `wait_agent` returns them in its own result, and any leftovers are delivered right after a successful recipient turn
+- `wait_agent` sends only newly queued mailbox notices to the model; its full status tree is folded in the TUI by default and can be toggled with `Ctrl+O`
 - Failed notice delivery is re-queued instead of silently discarded
 - Notices pending when a turn is aborted or errors are deferred to the next explicit turn without restarting the interrupted agent
 - The extension never inserts messages between an assistant tool call and its tool result, keeping session history protocol-valid for strict gateways

package/control.ts

@@ -23,7 +23,7 @@ import {
 	rootAgentInstructions,
 	sanitizeForkMessages,
 } from "./context.ts";
-import { discoverRoles, resolveRole } from "./roles.ts";
+import { discoverRoles, formatAssignedSkills, resolveRole } from "./roles.ts";
 import {
 	DEFAULT_CHILD_THINKING_LEVEL,
 	DEFAULT_MAX_CONCURRENT_SUBAGENTS,
@@ -163,6 +163,7 @@ export class AgentControl {
 	private modelRuntimePromise?: Promise<ModelRuntime>;
 	private activeExecutionSlots = 0;
 	private schedulerPromise?: Promise<void>;
+	private schedulerRerunRequested = false;
 	private spawnOperationTail: Promise<void> = Promise.resolve();
 	private disposed = false;
 	private shuttingDown = false;
@@ -586,9 +587,15 @@ export class AgentControl {
 		await this.transcriptToolDefinitionsPromise;
 	}
 
-	private async createLoader(cwd: string, settingsManager: SettingsManager, instructions: string): Promise<DefaultResourceLoader> {
+	private async createLoader(
+		cwd: string,
+		settingsManager: SettingsManager,
+		instructions: string,
+		assignedSkillNames?: readonly string[],
+	): Promise<DefaultResourceLoader> {
 		const selfPath = path.resolve(this.selfExtensionPath);
-		const loader = new DefaultResourceLoader({
+		let loader: DefaultResourceLoader;
+		loader = new DefaultResourceLoader({
 			cwd,
 			agentDir: getAgentDir(),
 			settingsManager,
@@ -596,22 +603,33 @@ export class AgentControl {
 				...base,
 				extensions: base.extensions.filter((extension) => path.resolve(extension.resolvedPath) !== selfPath),
 			}),
-			systemPromptOverride: (base) => `${base || "You are a coding agent."}\n\n${instructions}`,
+			systemPromptOverride: (base) => [
+				base || "You are a coding agent.",
+				instructions,
+				formatAssignedSkills(assignedSkillNames, loader.getSkills().skills),
+			].filter((part) => part.trim()).join("\n\n"),
 		});
 		await loader.reload();
 		this.captureTranscriptToolDefinitions(loader);
 		return loader;
 	}
 
-	private async evictForResidency(protectedPath?: string): Promise<void> {
+	private tryEvictForResidency(protectedPath?: string): boolean {
 		const allResidents = [...this.agentsByPath.values()].filter((record) => record.loaded);
-		if (allResidents.length < this.maxResidentSubagents) return;
+		if (allResidents.length < this.maxResidentSubagents) return true;
 		const candidate = allResidents
 			.filter((record) => record.path !== protectedPath)
 			.filter((record) => record.status !== "running" && !record.holdsExecutionSlot && record.session?.isIdle !== false)
 			.sort((left, right) => left.lastUsedAt - right.lastUsedAt)[0];
-		if (!candidate) throw new Error(`agent residency limit reached (${this.maxResidentSubagents}); all resident agents are busy`);
+		if (!candidate) return false;
 		this.unload(candidate);
+		return true;
+	}
+
+	private async evictForResidency(protectedPath?: string): Promise<void> {
+		if (!this.tryEvictForResidency(protectedPath)) {
+			throw new Error(`agent residency limit reached (${this.maxResidentSubagents}); all resident agents are busy`);
+		}
 	}
 
 	private unload(record: AgentRecord): void {
@@ -656,6 +674,13 @@ export class AgentControl {
 					this.noteTurnEnd(record.path, lastAssistant?.role === "assistant" ? lastAssistant.stopReason : undefined);
 				}
 			}
+			if (event.type === "agent_settled") {
+				this.releaseExecutionSlot(record);
+				this.persistState();
+				// Let AgentSession finish emitting its settled event before an LRU eviction
+				// can dispose this now-idle session.
+				queueMicrotask(() => void this.scheduleQueued());
+			}
 			this.changed();
 		});
 	}
@@ -686,10 +711,8 @@ export class AgentControl {
 		if (answer.aborted) {
 			record.status = "interrupted";
 			record.statusMessage = "interrupted";
-			this.releaseExecutionSlot(record);
 			this.persistState();
 			this.changed();
-			void this.scheduleQueued();
 			return;
 		}
 		if (answer.error) {
@@ -702,10 +725,8 @@ export class AgentControl {
 			record.statusMessage = undefined;
 		}
 		this.writeAgentResult(record);
-		this.releaseExecutionSlot(record);
 		this.persistState();
 		this.changed();
-		void this.scheduleQueued();
 		void this.deliver(record.path, record.parentPath, this.completionNotice(record), false, "AGENT_STATUS").catch(() => {});
 	}
 
@@ -862,8 +883,11 @@ export class AgentControl {
 		return records;
 	}
 
-	private async startQueued(record: AgentRecord): Promise<void> {
-		if (record.status !== "queued") return;
+	private async startQueued(record: AgentRecord): Promise<boolean> {
+		if (record.status !== "queued") return true;
+		// A completed AgentSession emits agent_end just before it becomes idle. Treat a
+		// temporarily full resident set as backpressure, not as a permanent task error.
+		if (!record.session && !this.tryEvictForResidency(record.path)) return false;
 		this.reserveExecutionSlot();
 		record.holdsExecutionSlot = true;
 		record.status = "pending_init";
@@ -877,7 +901,7 @@ export class AgentControl {
 				record.statusMessage = "waiting for an execution slot";
 				this.releaseExecutionSlot(record);
 				this.unload(record);
-				return;
+				return true;
 			}
 			const content = [...(record.queuedMail ?? []), record.queuedMessage].filter((item): item is string => Boolean(item)).join("\n\n");
 			if ((record.queuedMail?.length ?? 0) > 0) this.mailboxPending.set(record.path, 0);
@@ -885,6 +909,7 @@ export class AgentControl {
 			record.queuedMail = undefined;
 			this.launch(record, content);
 			this.persistState();
+			return true;
 		} catch (error) {
 			record.status = "errored";
 			record.statusMessage = error instanceof Error ? error.message : String(error);
@@ -896,6 +921,7 @@ export class AgentControl {
 			this.writeAgentResult(record);
 			this.persistState();
 			void this.deliver(record.path, record.parentPath, this.completionNotice(record), false, "AGENT_STATUS").catch(() => {});
+			return true;
 		}
 	}
 
@@ -903,20 +929,26 @@ export class AgentControl {
 		while (!this.disposed && !this.shuttingDown && this.activeExecutionSlots < this.maxConcurrentSubagents) {
 			const next = this.queuedRecords()[0];
 			if (!next) break;
-			await this.startQueued(next);
+			if (!(await this.startQueued(next))) break;
 		}
 	}
 
 	private async scheduleQueued(): Promise<void> {
 		if (this.disposed || this.shuttingDown) return;
-		if (this.schedulerPromise) return this.schedulerPromise;
+		if (this.schedulerPromise) {
+			this.schedulerRerunRequested = true;
+			return this.schedulerPromise;
+		}
+		this.schedulerRerunRequested = false;
 		const operation = this.runQueuedScheduler();
 		this.schedulerPromise = operation;
 		try {
 			await operation;
 		} finally {
+			const rerun = this.schedulerRerunRequested;
+			this.schedulerRerunRequested = false;
 			if (this.schedulerPromise === operation) this.schedulerPromise = undefined;
-			if (!this.disposed && !this.shuttingDown && this.activeExecutionSlots < this.maxConcurrentSubagents && this.queuedRecords().length > 0) {
+			if (rerun && !this.disposed && !this.shuttingDown) {
 				queueMicrotask(() => void this.scheduleQueued());
 			}
 		}
@@ -1119,6 +1151,7 @@ export class AgentControl {
 			model: role.model || settings.defaultModel,
 			thinkingLevel: role.thinkingLevel ?? settings.defaultThinkingLevel ?? DEFAULT_CHILD_THINKING_LEVEL,
 			tools: role.tools,
+			skills: role.skills,
 			source: role.source,
 		}));
 	}
@@ -1253,7 +1286,12 @@ export class AgentControl {
 		const forkContext = this.forkContextFromSessionManager(sessionManager);
 		const role = resolveRole(this.root.cwd, this.root.ctx.isProjectTrusted(), record.role);
 		const settingsManager = SettingsManager.create(this.root.cwd, getAgentDir());
-		const loader = await this.createLoader(this.root.cwd, settingsManager, this.childInstructions(record, role.systemPrompt));
+		const loader = await this.createLoader(
+			this.root.cwd,
+			settingsManager,
+			this.childInstructions(record, role.systemPrompt),
+			role.skills,
+		);
 		const runtime = await this.getModelRuntime(this.root.ctx);
 		const model = runtime.getModel(record.modelProvider, record.modelId) || this.root.model;
 		if (!model) throw new Error(`model ${record.modelProvider}/${record.modelId} is unavailable`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youngjurry/pi-agents",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Persistent in-process Codex-style multi-agent collaboration for Pi",
   "author": "youngjurry",
   "type": "module",

package/roles.ts

@@ -1,7 +1,7 @@
 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 { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter, type Skill } from "@earendil-works/pi-coding-agent";
 import type { AgentRole } from "./types.ts";
 
 const BUILTIN_ROLES: AgentRole[] = [
@@ -31,6 +31,7 @@ type RoleFrontmatter = {
 	name?: unknown;
 	description?: unknown;
 	tools?: unknown;
+	skills?: unknown;
 	model?: unknown;
 	thinking?: unknown;
 	nickname_candidates?: unknown;
@@ -67,6 +68,7 @@ function loadDirectory(directory: string, source: "user" | "project"): AgentRole
 				description: frontmatter.description.trim(),
 				systemPrompt: body.trim(),
 				tools: stringList(frontmatter.tools),
+				skills: stringList(frontmatter.skills),
 				model: typeof frontmatter.model === "string" ? frontmatter.model.trim() : undefined,
 				thinkingLevel: thinking,
 				nicknameCandidates: stringList(frontmatter.nickname_candidates),
@@ -114,3 +116,19 @@ export function resolveRole(cwd: string, projectTrusted: boolean, name?: string)
 	}
 	return role;
 }
+
+export function formatAssignedSkills(requestedNames: readonly string[] | undefined, discoveredSkills: readonly Skill[]): string {
+	if (!requestedNames?.length) return "";
+	const skillsByName = new Map(discoveredSkills.map((skill) => [skill.name, skill]));
+	const missing = requestedNames.filter((name) => !skillsByName.has(name));
+	if (missing.length > 0) {
+		const available = [...skillsByName.keys()].sort().join(", ") || "none";
+		throw new Error(`Role references unknown skill(s): ${missing.join(", ")}. Available skills: ${available}`);
+	}
+	const sections = requestedNames.map((name) => {
+		const skill = skillsByName.get(name)!;
+		const instructions = fs.readFileSync(skill.filePath, "utf8").trim();
+		return `<skill>\nName: ${skill.name}\nLocation: ${skill.filePath}\nBase directory: ${skill.baseDir}\n\n${instructions}\n</skill>`;
+	});
+	return `<agent_skills>\nThe following Role-selected skills are fully loaded. Follow them when completing the task. Resolve relative paths against each skill's base directory.\n\n${sections.join("\n\n")}\n</agent_skills>`;
+}

package/tools.ts

@@ -71,7 +71,14 @@ function renderCollaborationResult(
 	}
 	const icon = data.timedOut ? theme.fg("warning", "◷") : theme.fg("success", "✓");
 	const lines = [`${icon} ${theme.fg("toolTitle", data.tool)}`];
-	for (const agent of data.targets) lines.push(`  ${theme.fg("accent", compactStatus(agent))}`);
+	if (data.tool === "wait_agent" && data.targets.length > 0 && !options.expanded) {
+		const counts = new Map<string, number>();
+		for (const agent of data.targets) counts.set(agent.status, (counts.get(agent.status) ?? 0) + 1);
+		const summary = [...counts.entries()].map(([status, count]) => `${count} ${status}`).join(" · ");
+		lines.push(`  ${theme.fg("muted", `${data.targets.length} agents hidden · ${summary} · Ctrl+O to expand`)}`);
+	} else {
+		for (const agent of data.targets) lines.push(`  ${theme.fg("accent", compactStatus(agent))}`);
+	}
 	if (data.roles?.length) {
 		lines.push(`  ${theme.fg("muted", "Roles:")} ${data.roles.map((role) => role.name).join(", ")}`);
 		if (options.expanded) {
@@ -81,6 +88,7 @@ function renderCollaborationResult(
 					role.model ? `model: ${role.model}` : undefined,
 					role.thinkingLevel ? `thinking: ${role.thinkingLevel}` : undefined,
 					`tools: ${role.tools?.join(", ") || "default set"}`,
+					role.skills?.length ? `skills: ${role.skills.join(", ")}` : undefined,
 				].filter(Boolean).join(" · ");
 				lines.push(`    ${theme.fg("accent", role.name)} — ${role.description}`);
 				lines.push(`      ${theme.fg("dim", configuration)}`);

package/types.ts

@@ -146,6 +146,7 @@ export interface AgentRoleView {
 	model?: string;
 	thinkingLevel?: ThinkingLevel;
 	tools?: string[];
+	skills?: string[];
 	source: "builtin" | "user" | "project";
 }
 
@@ -154,6 +155,7 @@ export interface AgentRole {
 	description: string;
 	systemPrompt: string;
 	tools?: string[];
+	skills?: string[];
 	model?: string;
 	thinkingLevel?: ThinkingLevel;
 	nicknameCandidates?: string[];