@youngjurry/pi-agents 0.7.1

package/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+## 0.7.1 - 2026-09-01
+
+- Order the `/agents` picker by latest task assignment, newest first, instead of alphabetically.
+- Persist `lastAssignedAt` separately from noisy session activity timestamps.
+- Move reused agents to the top after a successful `followup_task` without reshuffling on streaming, tools, completion, loading, or read-only inspection.
+- Preserve canonical path ordering in `list_agents(view="status")` and FIFO ordering in the execution queue.
+- Add public npm package metadata, reproducible development dependencies, and prepublish checks for `@youngjurry/pi-agents`.
+
+## 0.7.0 - 2026-09-01
+
+- Add validated global `defaultThinkingLevel` configuration with an internal `medium` default.
+- Remove implicit inheritance from the parent Agent's active model and thinking level.
+- Apply task overrides before Role settings and global settings; an explicit model without `reasoning_effort` now selects that model's highest supported level.
+- Clamp requested and configured levels through Pi's model-specific thinking capabilities and persist the effective value.
+- Show effective thinking level alongside the model in the live tree, `/agents` picker/transcript, completion rendering, status output, and non-TUI inspection.
+- Defer forwarded child permission and custom dialogs while `/agents` is open, preserving inspector keyboard focus and showing queued dialogs only after the inspector exits.
+
+## 0.6.0 - 2026-08-31
+
+- Replace the single-task `spawn_agent` action with one non-redundant `spawn_agents` action whose `agents` array accepts either one or many tasks.
+- Start tasks up to the configured execution limit and persist overflow tasks in an explicit FIFO `queued` state.
+- Automatically start queued tasks as slots become available without blocking the parent tool call.
+- Report `queued` status, queue position, and running/queued capacity through `list_agents(view="status")`, action results, the live widget, and `/agents`.
+- Allow queued agents to receive persistent messages and be cancelled without loading an `AgentSession`.
+- Restore waiting work after main-session resume while interrupted running work remains interrupted.
+- Add `maxConcurrentSubagents` and `maxResidentSubagents` settings with validated positive-integer values.
+- Keep exactly five catalog actions and the same two provider-facing gateway schemas.
+
+## 0.5.3 - 2026-08-31
+
+- Align transcript navigation with `/tree`: `↑`/`↓` move by line and `←`/`→` move by page.
+- Add distinct single-key jumps: `t` for the top and `b` for the bottom.
+- Remove duplicate `PageUp`/`PageDown` and `Home`/`End` aliases from the transcript viewer.
+
+## 0.5.2 - 2026-08-30
+
+- Show each active sub-agent's full `provider/model` identifier in the live tree below the editor.
+- Preserve terminal-width truncation for long model names.
+
+## 0.5.1 - 2026-08-30
+
+- Reuse each child session's original custom tool renderers in the read-only transcript viewer.
+- Match the main transcript's compact `web_search`, `fetch`, and other extension-tool presentation instead of dumping raw tool content.
+- Cache renderer definitions across child-session unloading and discover them without waking or loading a child when viewing restored sessions.
+
+## 0.5.0 - 2026-08-30
+
+- Turn `/agents` into an interactive, user-only sub-agent session browser.
+- Add read-only Pi-style transcript viewing for assistant output, thinking, tool calls, tool results, and collaboration messages.
+- Support `/agents <path>` direct opening and agent-path argument completion.
+- Refresh running transcripts without switching, waking, or loading child sessions.
+- Keep the inspector out of all model-facing prompts, messages, and tool schemas.
+
+## 0.4.1 - 2026-08-15
+
+- Remove test-only dependencies from the published package manifest so Pi Git installs stay dependency-free.
+- Keep test tooling isolated in temporary development environments.
+
+## 0.4.0 - 2026-08-15
+
+- Replace vague root guidance with Codex-derived parallel speed/quality criteria while keeping bounded-task guidance in the on-demand action catalog.
+- Move the default child model from source code to `~/.pi/agent/codex-agents/agents-setting.json`.
+- Resolve models by spawn override, role override, global setting, then parent-model inheritance.
+- Decouple model selection from `fork_turns` history inheritance.
+- Re-queue failed notification flushes instead of dropping them.
+- Defer queued mail after aborted or errored turns without automatically restarting the recipient.
+- Add regression tests for prompt separation, settings validation and precedence, notification ordering, abort behavior, and flush recovery.
+
+## 0.3.2 - 2026-08-15
+
+- Queue inter-agent notifications while the recipient's turn is active instead of appending into the live message tree.
+- Fix assistant(tool_calls) → user → tool history corruption that caused gateway 400 errors on strict providers.
+- Deliver queued completion notices inside `wait_agent` results.
+- Flush remaining queued notices at turn end and wake the recipient to process them.
+
+## 0.3.1 - 2026-08-15
+
+- Group child sessions and results under their owning root session ID.
+- Record the root session file in each storage group's `owner.json`.
+- Remove orphaned storage groups only when an existing main session is resumed.
+- Migrate the resumed main session's referenced legacy child files into its group.
+
+## 0.3.0 - 2026-08-15
+
+- Replace session-persistent deferred schemas with a stable `agent_action` dispatcher.
+- Add `list_agents(view="roles" | "tools" | "status" | "results")` and remove boolean view flags.
+- Return the five action descriptions and parameter schemas only from the `tools` catalog view.
+- Keep individual action implementations locally registered without exposing their provider schemas.
+- Use the same compact gateway surface for root and child agents.
+
+## 0.2.1 - 2026-08-15
+
+- Reduce the root prompt to a single delegation capability sentence.
+- Move role discovery, tool activation, and result retrieval guidance into `list_agents` parameter descriptions.
+- Show discovered roles and enabled tools in the `list_agents` TUI result.
+- Label `list_agents` calls as roles, results, or status instead of always showing `all`.
+
+## 0.2.0 - 2026-08-15
+
+- Keep only `list_agents` active before delegation is requested.
+- Add `list_agents(include_roles=true)` for on-demand role discovery.
+- Dynamically enable collaboration tools through Pi deferred tool loading.
+- Remove hard-coded role names from the `spawn_agent` schema.
+- Keep the root prompt limited to capability discovery and result retrieval.
+
+## 0.1.0 - 2026-08-15
+
+- Initial public release.
+- Persistent recursive agent tree backed by in-process Pi `AgentSession`s.
+- Six Codex-style collaboration tools.
+- Context forking, mailbox communication, concurrency and residency limits.
+- Hidden child-session persistence and lazy reload.
+- Root-TUI permission approval forwarding.
+- Pull-based result retrieval with compact completion notices.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smithyyang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# Codex-style Agents for Pi
+
+In-process persistent multi-agent collaboration modeled after OpenAI Codex MultiAgentV2.
+
+## Install
+
+Install the public npm package:
+
+```bash
+pi install npm:@youngjurry/pi-agents
+```
+
+Or install directly from GitHub:
+
+```bash
+pi install git:github.com/YoungJurry/pi-agents
+```
+
+Choose only one source to avoid loading the extension twice. Then start Pi or run `/reload` in an existing session.
+
+> This extension runs child agents with the same OS user and filesystem permissions as the root Pi process. Review [SECURITY.md](./SECURITY.md) before using it on untrusted work.
+
+## Quick start
+
+Ask Pi to delegate work:
+
+```text
+Spawn two agents to research independent parts of this task, wait for completion,
+then pull and summarize their results.
+```
+
+The model queries `list_agents(view="tools")` for the action catalog and, when needed, `list_agents(view="roles")` for role-specific configuration. It executes catalog actions through the compact `agent_action` dispatcher.
+
+Completion notices are intentionally small. Full answers enter the parent context only when explicitly requested with `list_agents(view="results")`.
+
+## Inspect sub-agent sessions
+
+Use the user-only `/agents` command to browse the current root session's sub-agents and open a read-only transcript:
+
+```text
+/agents
+/agents /root/api_research
+```
+
+The picker orders agents by latest task assignment, newest first; a successful `followup_task` moves a reused agent back to the top without letting ordinary streaming or tool activity reshuffle the list. It shows lifecycle status, model, effective thinking level, role, nickname, and residency. Selecting an agent opens its active session branch with normal Pi-style assistant messages, thinking, tool calls, tool results, and collaboration messages. Custom tools reuse their original Pi renderers, so tools such as `web_search` and `fetch` stay as compact as they are in the main transcript. Running sessions refresh while the viewer is open. Child permission dialogs wait behind the inspector and appear only after the user fully exits `/agents`, so they cannot steal focus from or hide behind its overlay.
+
+Viewer controls:
+
+- `↑` / `↓`: move one line
+- `←` / `→`: move one page up or down
+- `t` / `b`: jump to the top or bottom
+- `Ctrl+O`: expand or collapse tool output
+- `Ctrl+T`: show or hide thinking
+- `r`: refresh immediately
+- `Escape`: return to the agent picker
+
+This inspector is implemented only as a slash command and TUI overlay. It does not register an LLM tool, alter tool schemas or system prompts, add messages to the root context, switch sessions, wake agents, or expose child sessions through the normal `/resume` picker.
+
+## Tools
+
+Only two compact collaboration schemas remain active:
+
+- `list_agents`: query one catalog or data view
+  - `roles`: available roles and their tool access
+  - `tools`: action descriptions and parameter schemas
+  - `status`: canonical agent-tree status
+  - `results`: stored final answers
+- `agent_action`: execute a catalog action by name with its matching arguments
+
+`list_agents(view="tools")` returns these actions as ordinary tool-result content instead of activating more provider tool schemas:
+
+- `spawn_agents`: submit one or many persistent child tasks in a single action; overflow waits in the visible FIFO queue
+- `send_message`: non-waking mailbox message
+- `followup_task`: assign more work and trigger processing
+- `wait_agent`: event-driven mailbox wait
+- `interrupt_agent`: abort a run without deleting context
+
+Example dispatcher call:
+
+```json
+{
+  "action": "spawn_agents",
+  "arguments": {
+    "agents": [
+      {
+        "message": "Research the API implementation",
+        "task_name": "api_research",
+        "agent_type": "explorer"
+      },
+      {
+        "message": "Inspect the test strategy",
+        "task_name": "test_research",
+        "agent_type": "explorer"
+      }
+    ]
+  }
+}
+```
+
+The five action implementations stay registered locally, but their individual provider schemas are never added to later requests. `spawn_agents` replaces the old single-task action rather than adding a redundant sixth action; an array with one item performs a single spawn. Root and child agents use the same stable `list_agents` + `agent_action` surface. Agents use canonical paths such as `/root/api_research` and can recursively spawn children.
+
+## Context inheritance
+
+Each item in the `spawn_agents` action accepts a `fork_turns` argument:
+
+- `none`: fresh context
+- `all`: sanitized semantic parent context (default)
+- a positive integer string: the most recent N task/user turns
+
+Tool calls, tool results, thinking, shell transcripts, and previous collaboration mail are removed from inherited context.
+
+## Roles
+
+Built-ins: `default`, `explorer`, `awaiter`.
+
+Additional roles are read from:
+
+- `~/.pi/agent/agents/*.md`
+- nearest trusted `.pi/agents/*.md`
+
+Role format:
+
+```markdown
+---
+name: reviewer
+description: Review code without editing
+tools: read, grep, find, ls, bash
+model: openai/gpt-5.4
+thinking: high
+nickname_candidates: [Ada, Grace]
+---
+
+Review carefully and return findings with exact paths.
+```
+
+## Model configuration
+
+Global sub-agent settings live outside the installed package so updates cannot overwrite them:
+
+`~/.pi/agent/codex-agents/agents-setting.json`
+
+```json
+{
+  "defaultModel": "opencode-go/ox-alpha-free",
+  "defaultThinkingLevel": "medium",
+  "maxConcurrentSubagents": 3,
+  "maxResidentSubagents": 3
+}
+```
+
+Model and thinking configuration uses task fields first, then Role frontmatter, then global settings. Parent Agent model and thinking state are never used as implicit fallbacks.
+
+| Task override | Effective selection |
+|---|---|
+| `model` and `reasoning_effort` | Use both explicit values |
+| `model` only | Use that model and its highest supported thinking level |
+| `reasoning_effort` only | Use the Role/global model with the explicit thinking level |
+| neither | Use Role values where present, then `defaultModel` and `defaultThinkingLevel` |
+
+Unsupported thinking values are clamped through Pi's model-specific `thinkingLevelMap`, and the effective level is persisted and displayed. If `defaultThinkingLevel` is omitted, the plugin-level default is `medium`. Supported configured values are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
+
+The settings file is optional, but spawning requires a model from either the task, selected Role, or `defaultModel`; it no longer inherits the parent model. Limits must be positive integers, and `maxResidentSubagents` cannot be smaller than `maxConcurrentSubagents`. If concurrency is configured while residency is omitted, residency automatically expands to at least the concurrency limit. Setting changes take effect after `/reload`. Invalid JSON, an invalid `defaultThinkingLevel`, an empty `defaultModel`, or an unavailable configured model produces an explicit error. `fork_turns` controls inherited messages independently of model and thinking selection.
+
+## Lifecycle
+
+- Default child execution slots: 3 (4 active agents including root), configurable with `maxConcurrentSubagents`
+- Default resident child sessions: 3, configurable with `maxResidentSubagents`
+- `spawn_agents` starts tasks until all execution slots are occupied and records the remainder as `queued`
+- Queued tasks are lightweight, persistent, FIFO ordered, and do not occupy resident-session capacity
+- `list_agents(view="status")` reports each waiting task's queue position plus current running/queued capacity
+- The live widget shows `Agents active: <running>/<limit> · queued: <waiting>` and labels waiting paths explicitly
+- Completed/interrupted sessions are unloaded by LRU when residency is full
+- Child sessions persist under `~/.pi/agent/codex-agents/roots/<root-session-id>/sessions/` and reload lazily
+- Full final answers persist under `~/.pi/agent/codex-agents/roots/<root-session-id>/results/`
+- Each root storage group records its owning main-session file in `owner.json`
+- Resuming an existing main session removes groups whose owning main-session file has been deleted; new sessions and `/reload` do not trigger cleanup
+- 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
+- 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
+- Child sessions are kept out of Pi's normal `/resume` picker
+- Agent-tree metadata persists in root session custom entries
+- Child extension approval dialogs are serialized and forwarded to the root TUI with the agent path
+- While `/agents` is open, forwarded permission/custom dialogs wait without taking keyboard focus and appear only after the inspector closes
+- In non-interactive modes, permission extensions such as `permission-gate.ts` fail closed
+- All agents share the same cwd and filesystem
+
+Use `/agents` to browse the tree and inspect read-only child transcripts. A compact live tree appears below the editor while child agents exist and shows each active agent's `provider/model` identifier and effective thinking level.

package/SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+This extension runs subagents in the same Pi process and operating-system user account. Agents share the working directory and filesystem permissions.
+
+Tool allowlists and permission extensions are policy controls, not an OS sandbox. For untrusted tasks, run Pi inside a container, VM, or other system-level sandbox.
+
+Child approval dialogs from loaded permission extensions are forwarded to the root TUI. In non-interactive modes, permission extensions such as `permission-gate.ts` can fail closed according to their own policy.

package/context.ts

@@ -0,0 +1,124 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
+import { EXTENSION_ID } from "./types.ts";
+
+export type ForkMode = "none" | "all" | number;
+
+const SHARED_GUIDANCE = `All agents share the same working directory and filesystem. Edits made by one agent are immediately visible to every other agent. Coordinate ownership of files and avoid overwriting another agent's work.`;
+
+export function rootAgentInstructions(): string {
+	return `<multi_agent_role>You can use sub-agents when parallel work would materially improve speed or quality.</multi_agent_role>`;
+}
+
+export function childAgentInstructions(path: string, parentPath: string, rolePrompt?: string): string {
+	const role = rolePrompt?.trim() ? `\n\n<agent_role>\n${rolePrompt.trim()}\n</agent_role>` : "";
+	return `<multi_agent_role>\nYou are ${path}, a sub-agent in a collaborative team. Your direct parent is ${parentPath}. Complete the assigned task independently. You can use the collaboration tools and may spawn child agents. Your full final response is stored as the task result; your parent receives only a brief completion notification. Do not repeatedly poll or send the same result manually.\n\n${SHARED_GUIDANCE}\n</multi_agent_role>${role}`;
+}
+
+export function formatTeamMessage(options: {
+	type: "NEW_TASK" | "MESSAGE" | "AGENT_STATUS";
+	taskName: string;
+	sender: string;
+	payload: string;
+}): string {
+	if (options.type === "AGENT_STATUS") return options.payload;
+	return `Message Type: ${options.type}\nTask name: ${options.taskName}\nSender: ${options.sender}\nPayload:\n${options.payload}`;
+}
+
+export function parseForkMode(value: string | undefined): ForkMode {
+	const normalized = value?.trim().toLowerCase() || "all";
+	if (normalized === "none") return "none";
+	if (normalized === "all") return "all";
+	if (!/^\d+$/.test(normalized) || Number(normalized) <= 0) {
+		throw new Error("fork_turns must be `none`, `all`, or a positive integer string");
+	}
+	return Number(normalized);
+}
+
+function assistantTextOnly(message: AssistantMessage): AssistantMessage | undefined {
+	if (message.stopReason !== "stop") return undefined;
+	const content = message.content
+		.filter((part): part is TextContent => part.type === "text")
+		.map((part) => ({ ...part }));
+	if (content.length === 0) return undefined;
+	return { ...message, content };
+}
+
+function isTaskBoundary(message: AgentMessage): boolean {
+	if (message.role === "user") return true;
+	if (message.role !== "custom") return false;
+	if (message.customType !== EXTENSION_ID) return false;
+	const text = typeof message.content === "string"
+		? message.content
+		: message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+	return text.startsWith("Message Type: NEW_TASK\n");
+}
+
+function cloneMessage(message: AgentMessage): AgentMessage {
+	return structuredClone(message);
+}
+
+/**
+ * Build the semantic history inherited by a child. Tool calls/results, thinking,
+ * bash transcripts, and prior inter-agent mail are intentionally removed.
+ */
+export function sanitizeForkMessages(messages: readonly AgentMessage[], mode: ForkMode): AgentMessage[] {
+	if (mode === "none") return [];
+	let selected = [...messages];
+	if (typeof mode === "number") {
+		let boundaries = 0;
+		let start = 0;
+		for (let index = selected.length - 1; index >= 0; index--) {
+			if (!isTaskBoundary(selected[index]!)) continue;
+			boundaries++;
+			if (boundaries === mode) {
+				start = index;
+				break;
+			}
+		}
+		selected = selected.slice(start);
+	}
+
+	const output: AgentMessage[] = [];
+	for (const message of selected) {
+		switch (message.role) {
+			case "user":
+				output.push(cloneMessage(message));
+				break;
+			case "assistant": {
+				const cleaned = assistantTextOnly(message);
+				if (cleaned) output.push(cloneMessage(cleaned));
+				break;
+			}
+			case "branchSummary":
+			case "compactionSummary":
+				output.push(cloneMessage(message));
+				break;
+			case "custom":
+				if (message.customType !== EXTENSION_ID) output.push(cloneMessage(message));
+				break;
+			default:
+				break;
+		}
+	}
+	return output;
+}
+
+export function lastAssistantAnswer(messages: readonly AgentMessage[]): { text: string; timestamp?: number; error?: string; aborted: boolean } {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index];
+		if (message?.role !== "assistant") continue;
+		const text = message.content
+			.filter((part): part is TextContent => part.type === "text")
+			.map((part) => part.text)
+			.join("\n")
+			.trim();
+		return {
+			text,
+			timestamp: message.timestamp,
+			error: message.stopReason === "error" ? message.errorMessage || "agent error" : undefined,
+			aborted: message.stopReason === "aborted",
+		};
+	}
+	return { text: "", aborted: false };
+}