@tshu-w/pi-agents 0.2.2 → 0.4.0

package/src/agents/tool.ts

@@ -1,25 +1,17 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { boundBlocks, boundText, type Truncation } from "../output.ts";
+import { boundText } from "../output.ts";
 import { rejectFields } from "../params.ts";
-import { renderResultList, renderTextResult, renderToolCall, startDuration, type DurationState } from "../render-call.ts";
+import { renderTextResult, renderToolCall, startDuration, type DurationState } from "../render-call.ts";
 import { agentSession } from "../roots/rpc.ts";
 import type { RootRuntime } from "../roots/runtime.ts";
-import {
-	steerQueued,
-	THINKING_LEVELS,
-	WAIT_INTERRUPTED,
-	type Limits,
-	type WaitOutcome,
-	type WaitResult,
-} from "./agents.ts";
+import { steerQueued, THINKING_LEVELS, waitText, type Limits } from "./agents.ts";
 import {
 	deliver,
 	label,
 	nodes,
 	rememberRoots,
-	shortId,
 	resolveIn,
 	treeEntries,
 	type AgentNode,
@@ -27,55 +19,6 @@ import {
 } from "./registry.ts";
 import { listLine, searchEntries } from "./search.ts";
 
-function resultBlock({ agent, input, history }: WaitResult, ids: string[]): string {
-	return `<agent-result name="${agent.name}" id="${shortId(agent.id, ids)}" status="${input.state}"${history ? ' history="true"' : ""}>\n${input.result ?? ""}\n</agent-result>`;
-}
-
-function resultDetails({ agent, input, history }: WaitResult, result?: string) {
-	return { id: agent.id, name: agent.name, state: input.state, history, ...(result === undefined ? {} : { result }) };
-}
-
-type Named = { id: string; name?: string };
-
-/** The line naming the results left out to keep within Pi's output limits. */
-function omittedLine(omitted: Named[], ids: string[]): string {
-	return omitted.length > 0 ? `[Results omitted: ${omitted.map((agent) => label(agent, ids)).join(", ")}. Use wait with fewer targets.]` : "";
-}
-
-/** The line naming the Agents still pending, and that a steer ended the wait if one did. */
-function pendingLine(pending: Named[], interrupted: boolean | undefined, ids: string[]): string {
-	return pending.length > 0 ? `Still pending: ${pending.map((agent) => label(agent, ids)).join(", ")}${interrupted ? `\n${WAIT_INTERRUPTED}` : ""}` : "";
-}
-
-/** Renders wait results; returns the text and the results the caller has now read. */
-function renderWait(outcome: WaitOutcome, ids: string[]): { text: string; read: WaitResult[]; details: Record<string, unknown> } {
-	const { results, pending, interrupted } = outcome;
-	const pendingText = pendingLine(pending, interrupted, ids);
-	const flag = interrupted ? { interrupted } : {};
-	const named = pending.map(({ id, name }) => ({ id, name }));
-	if (results.length === 0) return { text: pendingText || "No results.", read: [], details: { results: [], pending: named, ...flag } };
-	const only = results[0]!;
-	if (results.length === 1 && pending.length === 0 && !only.history && only.input.state === "completed") {
-		const bounded = boundText(only.input.result ?? "", "pi-agents-wait");
-		return { text: bounded.text, read: results, details: { results: [resultDetails(only, bounded.kept)], pending: [], ...bounded.details } };
-	}
-	const blocks = results.map((result) => resultBlock(result, ids));
-	const bounded = boundBlocks(blocks, "agent-result", "pi-agents-wait");
-	let offset = 0;
-	const details = results.map((result, index) => {
-		const block = blocks[index]!;
-		const available = Math.max(0, bounded.kept.length - offset - block.indexOf("\n") - 1);
-		offset += block.length + 2;
-		return resultDetails(result, index < bounded.shown ? (result.input.result ?? "").slice(0, available) : undefined);
-	});
-	let text = bounded.text;
-	const read = results.slice(0, bounded.shown);
-	const omittedText = omittedLine(results.slice(bounded.shown).map((result) => result.agent), ids);
-	if (omittedText) text += `\n\n${omittedText}`;
-	if (pendingText) text += `\n\n${pendingText}`;
-	return { text, read, details: { results: details, pending: named, ...flag, ...bounded.details } };
-}
-
 /** Registers the `agent` tool. */
 export function registerAgentTool(
 	pi: ExtensionAPI,
@@ -102,36 +45,25 @@ export function registerAgentTool(
 			startDuration(context.state as DurationState, args.action === "wait", context.executionStarted);
 			return renderToolCall("agent", args, theme, context.lastComponent);
 		},
-		// `wait` shows how long it has waited, and when collapsed, each result as a line with the first lines of its body.
-		renderResult: (result, options, theme, context) => renderTextResult(result, options, theme, context, (context.args as { action?: string }).action === "wait"
-			? () => {
-				const { results = [], pending = [], interrupted, ...truncated } = (result.details ?? {}) as { results?: ReturnType<typeof resultDetails>[]; pending?: Named[]; interrupted?: boolean } & Partial<Truncation>;
-				const only = results[0];
-				// As `renderWait` returns them, no results, or a single completed result alone, show as they are.
-				if (!only || (results.length === 1 && pending.length === 0 && !only.history && only.state === "completed")) return undefined;
-				const ids = [...results.map((entry) => entry.id), ...pending.map((agent) => agent.id)];
-				const notes = [omittedLine(results.filter((entry) => entry.result === undefined), ids), pendingLine(pending, interrupted, ids)];
-				return renderResultList(results.flatMap((entry) => entry.result === undefined ? [] : [{ line: `${label(entry, ids)}  ${entry.state}`, body: entry.result }]), notes, truncated, theme);
-			}
-			: undefined),
-		description: `Create, message, and coordinate Agents. \`spawn\` creates an owned Agent and sends its first input; \`send\` sends an input or a write to a visible Agent; \`wait\` waits for owned Agents and returns unread results; \`list\` finds visible Agents; \`abort\` stops an owned Agent's current turn and queued inputs while keeping it available. When an owned Agent finishes an input while its owner is not waiting for it, the owner receives a notification naming the Agent and outcome; \`wait\` returns the result. Owned Agents under the same root share \`${maxConcurrent}\` execution slots and a limit of \`${maxOutstanding}\` inputs that have not ended. Inputs that start a new turn queue when all slots are busy; new inputs are rejected at the input limit.`,
+		renderResult: (result, options, theme, context) => renderTextResult(result, options, theme, context),
+		description: `Create, message, and coordinate Agents. \`spawn\` creates an Agent and sends its first input; \`send\` sends an input or a write to a visible Agent; \`wait\` waits for owned Agents to finish; \`list\` finds visible Agents; \`abort\` stops an owned Agent's current turn and queued inputs while keeping it available. When an owned Agent finishes an input, its owner receives a notification with the result. Owned Agents under the same root share \`${maxConcurrent}\` execution slots and a limit of \`${maxOutstanding}\` inputs that have not ended. Inputs that start a new turn queue when all slots are busy; new inputs are rejected at the input limit.`,
 		promptSnippet: "Create, message, and coordinate Agents",
 		promptGuidelines: [
 			"Use `agent(action='spawn', name=..., message=...)` for concrete, bounded work with a clear expected result. Keep the first message self-contained; use `context='fork'` only when the Agent needs the caller's conversation.",
 			"For independent work, start the Agents before waiting and partition tasks into non-overlapping responsibilities.",
-			"Use `agent(action='wait', ...)` when the next step depends on Agent results. Prefer one longer wait over repeated short polling.",
+			"Use `agent(action='wait', ...)` when your next step or answer depends on Agent results. Prefer one longer wait over repeated short polling.",
 		],
 		parameters: Type.Object({
-			action: StringEnum(["spawn", "send", "wait", "list", "abort"] as const, { description: "Operation and applicable parameters: `spawn(name, message, cwd?, context?, model?, thinkingLevel?)`, `send(target, message, deliverAs?)`, `wait(target?, history?, timeout?)`, `list(query?, state?, limit?, offset?)`, or `abort(target)`." }),
+			action: StringEnum(["spawn", "send", "wait", "list", "abort"] as const, { description: "Operation and applicable parameters: `spawn(name, message, cwd?, context?, model?, thinkingLevel?, disown?)`, `send(target, message, deliverAs?)`, `wait(target?, timeout?)`, `list(query?, state?, limit?, offset?)`, or `abort(target)`." }),
 			name: Type.Optional(Type.String({ description: "Name of the new Agent for `spawn`; unique among the caller's Agents." })),
 			message: Type.Optional(Type.String({ description: "Non-empty text for `spawn` or `send`." })),
 			cwd: Type.Optional(Type.String({ description: "Working directory for `spawn` (default: the caller's current working directory)." })),
 			context: Type.Optional(StringEnum(["fresh", "fork"] as const, { description: "Context for `spawn` (default: fresh). fresh starts without the caller's conversation; fork snapshots it." })),
 			model: Type.Optional(Type.String({ description: "Model for `spawn` as provider/modelId (default: the caller's model)." })),
 			thinkingLevel: Type.Optional(StringEnum(THINKING_LEVELS, { description: "Thinking level for `spawn`: off, minimal, low, medium, high, xhigh, or max (default: the caller's level)." })),
-			target: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())], { description: "Agent ID, name, or unique ID prefix for `send`, `wait`, or `abort`. `wait` and `send` with `deliverAs='write'` also accept an array. When omitted for `wait`, selects all owned Agents with pending or unread results." })),
-			deliverAs: Type.Optional(StringEnum(["followUp", "steer", "write"] as const, { description: "Delivery for `send` (default: followUp). followUp waits until the recipient's current turn ends; steer delivers after its current tool calls, before the next model call; write delivers like steer but never starts a turn and has no result." })),
-			history: Type.Optional(Type.Integer({ minimum: 0, description: "Number of most recent read results to return again per selected Agent for `wait` (default: 0)." })),
+			disown: Type.Optional(Type.Boolean({ description: "For `spawn`, start a root Agent the caller does not own; it replies with send instead of returning a result (default: false)." })),
+			target: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())], { description: "Agent ID, name, or unique ID prefix for `send`, `wait`, or `abort`. `wait` and `send` with `deliverAs='write'` also accept an array. When omitted for `wait`, selects all owned Agents with pending inputs." })),
+			deliverAs: Type.Optional(StringEnum(["followUp", "steer", "write"] as const, { description: "Delivery for `send` (default: followUp). followUp waits until the recipient's current turn ends; steer delivers after its current tool calls, before the next model call; write delivers like steer but does not wake an idle recipient and has no result." })),
 			timeout: Type.Optional(Type.Number({ minimum: 10, maximum: 3600, description: "Maximum seconds for `wait` (default: 30, min: 10, max: 3600). Timeout does not abort Agents." })),
 			query: Type.Optional(Type.String({ description: "Search query for `list`, matching ID, name, cwd, summaries, and user messages. Case-insensitive; spaces mean AND; `|` means OR." })),
 			state: Type.Optional(StringEnum(["running", "waiting", "queued", "idle"] as const, { description: "State for `list`: running, waiting, queued, or idle." })),
@@ -146,8 +78,18 @@ export function registerAgentTool(
 			const targets = params.target === undefined ? undefined : Array.isArray(params.target) ? params.target : [params.target];
 			switch (params.action) {
 				case "spawn": {
-					rejectFields(params, "spawn", ["target", "deliverAs", "history", "timeout", "query", "state", "limit", "offset"]);
+					rejectFields(params, "spawn", ["target", "deliverAs", "timeout", "query", "state", "limit", "offset"]);
 					if (!params.name?.trim() || !params.message?.trim()) throw new Error("spawn requires name and message");
+					if (params.disown) {
+						if (params.context === "fork") throw new Error("Only an owned Agent can fork the caller's context.");
+						if (self.ownerId !== undefined) throw new Error("Only a root Agent can disown an Agent.");
+						const root = agents.disown({ name: params.name, cwd: params.cwd, model: params.model, thinkingLevel: params.thinkingLevel });
+						await roots.send({ id: root.id, label: root.name }, "followUp", params.message, signal);
+						return {
+							content: [{ type: "text", text: `Agent ${label(root, ids())} started.` }],
+							details: { id: root.id, name: root.name, queued: false },
+						};
+					}
 					const { record, queued } = agents.spawn({
 						name: params.name,
 						message: params.message,
@@ -162,7 +104,7 @@ export function registerAgentTool(
 					};
 				}
 				case "send": {
-					rejectFields(params, "send", ["name", "cwd", "context", "model", "thinkingLevel", "history", "timeout", "query", "state", "limit", "offset"]);
+					rejectFields(params, "send", ["name", "cwd", "context", "model", "thinkingLevel", "timeout", "query", "state", "limit", "offset", "disown"]);
 					const delivery = params.deliverAs ?? "followUp";
 					if (!targets?.length || !params.message?.trim()) throw new Error("send requires target and message");
 					if (targets.length > 1 && delivery !== "write") throw new Error("Only a write can go to several Agents.");
@@ -191,18 +133,20 @@ export function registerAgentTool(
 					};
 				}
 				case "wait": {
-					rejectFields(params, "wait", ["name", "message", "cwd", "context", "model", "thinkingLevel", "deliverAs", "query", "state", "limit", "offset"]);
+					rejectFields(params, "wait", ["name", "message", "cwd", "context", "model", "thinkingLevel", "deliverAs", "query", "state", "limit", "offset", "disown"]);
 					const selected = targets?.map((target) => agents.ownedTarget(target));
 					// An empty partial result lets the row show the elapsed time.
 					onUpdate?.({ content: [], details: undefined });
 					const session = agentSession(current.sessionManager);
-					const outcome = await agents.wait(selected, params.history ?? 0, params.timeout ?? 30, signal, () => steerQueued(session?.agent));
-					const rendered = renderWait(outcome, ids());
-					agents.markRead(rendered.read);
-					return { content: [{ type: "text", text: rendered.text }], details: rendered.details };
+					const { end, pending } = await agents.wait(selected, params.timeout ?? 30, signal, () => steerQueued(session?.agent));
+					const text = waitText(end, `Still pending: ${pending.map((agent) => label(agent, ids())).join(", ")}`);
+					return {
+						content: [{ type: "text", text }],
+						details: { pending: pending.map(({ id, name }) => ({ id, name })), ...(end === "timedOut" && { timedOut: true }), ...(end === "interrupted" && { interrupted: true }) },
+					};
 				}
 				case "list": {
-					rejectFields(params, "list", ["name", "message", "cwd", "context", "model", "thinkingLevel", "target", "deliverAs", "history", "timeout"]);
+					rejectFields(params, "list", ["name", "message", "cwd", "context", "model", "thinkingLevel", "target", "deliverAs", "timeout", "disown"]);
 					const offset = params.offset ?? 0;
 					const limit = params.limit ?? 20;
 					const all = await visible(self, signal);
@@ -218,7 +162,7 @@ export function registerAgentTool(
 					return { content: [{ type: "text", text: text.text }], details: { total: items.length, agents, ...text.details } };
 				}
 				case "abort": {
-					rejectFields(params, "abort", ["name", "message", "cwd", "context", "model", "thinkingLevel", "deliverAs", "history", "timeout", "query", "state", "limit", "offset"]);
+					rejectFields(params, "abort", ["name", "message", "cwd", "context", "model", "thinkingLevel", "deliverAs", "timeout", "query", "state", "limit", "offset", "disown"]);
 					if (targets?.length !== 1) throw new Error("abort requires one target");
 					const agent = agents.ownedTarget(targets[0]!);
 					const aborted = await agents.abort(agent, { silent: true });

package/src/host/client.mjs

@@ -15,6 +15,35 @@ const RESET = '\x1b[<u\x1b[>4;0m\x1b[?2004l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b
 const ALT_SCREEN = /\x1b\[\?1049([hl])/g;
 // Splits terminal input into key sequences: CSI and SS3 sequences, Alt+key, or a single character.
 const KEYS = /\x1b\[[0-?]*[ -/]*[@-~]|\x1bO[\s\S]|\x1b?[\s\S]/g;
+// The terminal's reply to the device status query (`\x1b[5n`), which pi-tui does not send, unlike `\x1b[c`.
+const STATUS_QUERY = '\x1b[5n';
+const STATUS_OK = /\x1b\[0n/;
+const DRAIN_TIMEOUT_MS = 1000;
+
+/**
+ * Reads and drops the input the terminal sent before it took the output written so far, such as the release of the
+ * detach key in Pi's keyboard mode, so the shell does not get it. Over a slow link, such as SSH, it arrives late; the
+ * terminal answers a query after it, or the wait ends after `DRAIN_TIMEOUT_MS`.
+ */
+export function drain(stdin, stdout) {
+  return new Promise(resolve => {
+    let input = '';
+    const done = () => {
+      clearTimeout(timer);
+      stdin.off('data', onData);
+      resolve();
+    };
+    const onData = data => {
+      input += data.toString('latin1');
+      if (STATUS_OK.test(input)) done();
+      // A reply split across chunks starts in the kept tail.
+      else input = input.slice(-64);
+    };
+    const timer = setTimeout(done, DRAIN_TIMEOUT_MS);
+    stdin.on('data', onData);
+    stdout.write(STATUS_QUERY);
+  });
+}
 
 export function hostStatus(path) {
   return new Promise((resolve, reject) => {
@@ -107,9 +136,10 @@ export async function startHost(paths, { pi, args, cwd, cols = 120, rows = 40, e
  * Attaches this process's terminal to a host until the host detaches it or Pi exits.
  * The detach key detaches here, before Pi sees it, so it works whatever Pi shows.
  * `onAttach` runs once the host has attached the terminal and told Pi.
+ * With `drainInput`, late input is dropped before returning (see `drain`); a caller that reads the terminal next turns it off.
  * Resolves to { reason: 'detach' | 'takeover' | 'exited' | 'closed', session }.
  */
-export function attach(socketPath, { isDetach, onAttach, stdin = process.stdin, stdout = process.stdout }) {
+export function attach(socketPath, { isDetach, onAttach, drainInput = true, stdin = process.stdin, stdout = process.stdout }) {
   return new Promise((resolve, reject) => {
     const socket = net.connect(socketPath);
     const size = () => ({ cols: stdout.columns, rows: stdout.rows });
@@ -124,16 +154,19 @@ export function attach(socketPath, { isDetach, onAttach, stdin = process.stdin,
       socket.write(frame(FRAME.detached));
     };
     let result, connected = false, altScreen = false, attached = false;
-    function finish() {
+    async function finish() {
       stdout.off('resize', onResize);
       stdin.off('data', onInput);
       if (connected) {
-        stdin.setRawMode(false);
-        stdin.pause();
         // An exiting Pi restores the terminal itself.
         // Leaving the alternate screen returns the cursor to the line below the command; otherwise it ends a line.
         // Terminals keep a keyboard mode stack per screen, so the reset comes before leaving it.
-        if (result?.reason !== 'exited') stdout.write(altScreen ? `${RESET}\x1b[?1049l` : `${RESET}\r\n`);
+        // The drain comes before leaving, so the screen changes once, when it ends.
+        if (result?.reason !== 'exited') stdout.write(RESET);
+        if (drainInput) await drain(stdin, stdout);
+        if (result?.reason !== 'exited') stdout.write(altScreen ? '\x1b[?1049l' : '\r\n');
+        stdin.setRawMode(false);
+        stdin.pause();
       }
       resolve(result ?? { reason: 'closed' });
     }

package/src/index.ts

@@ -41,6 +41,7 @@ import { createReporter } from "./roots/report.ts";
 import { installQueuePatches } from "./roots/queue.ts";
 import { agentSession, installRpcPatches } from "./roots/rpc.ts";
 import { createRootRuntime } from "./roots/runtime.ts";
+import { registerMainAgent } from "./main-agent.ts";
 import { renderAgentMessage } from "./ui/message.ts";
 import { createPanel } from "./ui/panel.ts";
 import { showQueue } from "./ui/queue.ts";
@@ -134,6 +135,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	};
 
 	pi.registerFlag(PROGRAM_ONLY_FLAG, { type: "boolean", description: "Present tools as with codemode.mode \"only\": scripts reach them through program" });
+	registerMainAgent(pi);
 
 	let warnedBothScriptTools = false;
 	pi.on("session_start", (_event, current) => {
@@ -155,9 +157,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			cwd: () => ctx?.cwd ?? current.cwd,
 			busy: () => !(ctx?.isIdle() ?? true),
 			sessionFile: () => ctx?.sessionManager.getSessionFile(),
-			receive: (text, delivery, messageId, from) => {
+			receive: (text, delivery, messageId, from, notice) => {
 				const as = created.stopped ? "write" : delivery;
-				pi.sendMessage(customMessage(text, as, { messageId, sender: from }), as === "write"
+				pi.sendMessage(customMessage(text, as, { messageId, sender: from, notice }), as === "write"
 					? { deliverAs: "steer" }
 					: { deliverAs: as, triggerTurn: true });
 				queue.update();
@@ -167,9 +169,10 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		nodes.set(id, node);
 		programs = new Programs(rootId, {
 			appendEntry: (customType, data) => pi.appendEntry(customType, data),
-			notify: (text) => agents.notify(text),
+			notify: (text, notice) => agents.notify(text, notice),
 			changed: () => panel.update(),
 		});
+		created.programs = programs;
 		programs.restore(current);
 		panel.start(current);
 	});
@@ -227,7 +230,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			if (!node) return;
 			browsing = true;
 			try {
-				await openTaskViewer(current, requireNode(current), programs, pi.getSettings().editorPaddingX ?? 0);
+				await openTaskViewer(current, requireNode(current), pi.getSettings().editorPaddingX ?? 0);
 			} finally {
 				browsing = false;
 			}

package/src/main-agent.md

@@ -0,0 +1,6 @@
+You are the user's main Agent.
+
+- Do quick read-only checks yourself; give other work to Agents.
+- Reuse the Agent already on a topic, or spawn one where the work is (`disown` for lasting topics).
+- Don't wait for Agents; end your turn so the user can talk to you.
+- Pass on their questions as asked and their results briefly.

package/src/main-agent.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { treeMetadata } from "./agents/registry.ts";
+import { statePaths } from "./roots/paths.mjs";
+
+export const MAIN_FLAG = "main";
+const instructions = readFileSync(new URL("./main-agent.md", import.meta.url), "utf8").trim();
+
+/** The main Agent's Session file, as `main.json` names it. */
+function mainSessionFile(): string | undefined {
+	try {
+		return (JSON.parse(readFileSync(statePaths().mainSession, "utf8")) as { sessionFile?: string }).sessionFile;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * The main Agent is the Session `main.json` names: `pd main` starts one with `--main`, and `/new` in it starts the
+ * next. It gets the main Agent's instructions.
+ */
+export function registerMainAgent(pi: ExtensionAPI): void {
+	pi.registerFlag(MAIN_FLAG, { type: "boolean", description: "Start the main Agent (used by pd main)" });
+	let main = false;
+	pi.on("session_start", (event, ctx) => {
+		main = false;
+		if (treeMetadata(ctx)) return;
+		// Absolute, as `pd main` compares it from other directories; a session directory may be relative.
+		const current = ctx.sessionManager.getSessionFile();
+		const file = current && path.resolve(current);
+		const started = event.reason === "startup" && pi.getFlag(MAIN_FLAG) === true;
+		const renewed = event.reason === "new" && event.previousSessionFile !== undefined && path.resolve(event.previousSessionFile) === mainSessionFile();
+		if (file && (started || renewed)) {
+			const record = statePaths().mainSession;
+			mkdirSync(path.dirname(record), { recursive: true, mode: 0o700 });
+			// Replaced at once, so that a reader never sees it half written.
+			const temporary = `${record}.${process.pid}`;
+			writeFileSync(temporary, JSON.stringify({ sessionFile: file }));
+			renameSync(temporary, record);
+		}
+		main = file !== undefined && file === mainSessionFile();
+	});
+	pi.on("before_agent_start", (event) => {
+		if (main) event.systemPromptOptions.sections["main-agent"] = instructions;
+	});
+}

package/src/output.ts

@@ -40,21 +40,3 @@ export function boundText(text: string, prefix: string): BoundedText {
 		details: { truncation, fullOutputPath },
 	};
 }
-
-/**
- * Bounds result blocks joined by blank lines. The block that crosses the limit keeps its closing
- * tag; `shown` counts the blocks that appear, and the caller names the omitted ones.
- */
-export function boundBlocks(blocks: string[], tag: string, prefix: string): BoundedText & { shown: number } {
-	const bounded = boundText(blocks.join("\n\n"), prefix);
-	if (!bounded.details) return { ...bounded, shown: blocks.length };
-	const kept = bounded.kept;
-	let start = 0;
-	const shown = blocks.filter((block) => {
-		const visible = start < kept.length;
-		start += block.length + 2;
-		return visible;
-	}).length;
-	const open = kept.lastIndexOf(`<${tag} `) > kept.lastIndexOf(`</${tag}>`);
-	return { ...bounded, text: `${kept}${open ? `\n</${tag}>` : ""}${bounded.text.slice(kept.length)}`, shown };
-}

package/src/programs/execute.ts

@@ -105,9 +105,9 @@ const sandboxExtras = new AsyncLocalStorage<SandboxExtras>();
 let sandboxPatch: Promise<void> | undefined;
 
 /**
- * Since Pi 1.3.0, its executor admits at most two codemode workers per process, which background
- * Programs waiting on Agents use up. A Program's worker is admitted on its own terms instead: any
- * number may run, and none starts while this many are still exiting after their scripts ended.
+ * Since Pi 1.3.0, its executor admits a limited number of codemode workers per process (two by default),
+ * which background Programs waiting on Agents use up. A Program's worker is admitted on its own terms
+ * instead: any number may run, and none starts while this many are still exiting after their scripts ended.
  */
 const MAX_EXITING_WORKERS = 2;
 const exitingWorkers = new Set<{ exited: boolean }>();
@@ -143,6 +143,26 @@ function programWorker(codemode: Awaited<ReturnType<typeof loadCodemode>>, wasmP
 	};
 }
 
+const WORKER_LIMIT_ENV = "PI_CODEMODE_MAX_WORKERS";
+
+/**
+ * Since Pi 1.4.0, its executor also reserves one of its worker slots before a script starts and holds
+ * it until the script ends, so Programs waiting on Agents make later Programs wait. Its limit is raised
+ * while `start` calls the executor, which reserves before its first `await`, and restored as soon as the
+ * call returns. The Program still holds its slot, which only Programs share unless the host runs scripts
+ * through the same executor, as Pi from source or an SDK host does.
+ */
+function admitAtOnce<T>(start: () => T): T {
+	const limit = process.env[WORKER_LIMIT_ENV];
+	process.env[WORKER_LIMIT_ENV] = String(Number.MAX_SAFE_INTEGER);
+	try {
+		return start();
+	} finally {
+		if (limit === undefined) delete process.env[WORKER_LIMIT_ENV];
+		else process.env[WORKER_LIMIT_ENV] = limit;
+	}
+}
+
 async function patchSandbox(): Promise<void> {
 	const [codemode, source] = await Promise.all([loadCodemode(), loadPiWorkerSource()]);
 	const wasmPath = source.getQuickJSWasmPath();
@@ -269,11 +289,11 @@ export async function executeProgram(
 	};
 	let result: Awaited<ReturnType<typeof executeCodemode>>;
 	try {
-		result = await withSandboxExtras(extras, () => executeCodemode(toolCallId, { code: source }, signal, onUpdate, programCtx, {
+		result = await withSandboxExtras(extras, () => admitAtOnce(() => executeCodemode(toolCallId, { code: source }, signal, onUpdate, programCtx, {
 			models: true,
 			appendEntry: options.appendEntry,
 			getToolNamespace: options.getToolNamespace,
-		}));
+		})));
 	} finally {
 		if (!scriptEnded) extras.ended();
 	}

package/src/programs/loadout.ts

@@ -3,9 +3,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { CODEMODE_TOOL_NAME, type PiCodemode } from "./codemode.ts";
 import { PROGRAM_TOOL_NAME } from "./execute.ts";
 import { shortId } from "../agents/registry.ts";
-import { formatDuration, formatToolCall, moreLines, renderResultList, renderTextResult, startDuration, type DurationState } from "../render-call.ts";
-import type { Truncation } from "../output.ts";
-import { omittedLine, runningLine, type ProgramResultDetails } from "./programs.ts";
+import { formatToolCall, moreLines, renderTextResult, startDuration, type DurationState } from "../render-call.ts";
 
 /** The first line of the `codemode` description, which the `program` intro replaces. */
 const CODEMODE_FIRST_LINE = "Run JavaScript code to orchestrate/compose tool calls\n";
@@ -17,6 +15,11 @@ type Changes = ReturnType<NonNullable<ToolDefinition["prepareLoadout"]>>;
 type Renderers = Pick<ToolDefinition, "renderCall" | "renderResult">;
 
 const CODE_PREVIEW_LINES = 10;
+// The colors Pi highlights JavaScript with; renderers get the same theme object after a theme change, so these tell it apart.
+const SYNTAX_COLORS = ["text", "muted", "syntaxComment", "syntaxKeyword", "syntaxFunction", "syntaxVariable", "syntaxString", "syntaxNumber", "syntaxType", "syntaxOperator", "syntaxPunctuation"] as const;
+
+/** A call row's state: its duration, and its script's highlighting, kept across redraws. */
+type CallState = DurationState & { script?: { code: string; colors: string; lines: string[] } };
 
 export const PROGRAM_ONLY_FLAG = "program-only";
 // Owned Agents run in their owner's process without its CLI flags, so the flag holds for the process.
@@ -82,10 +85,14 @@ export function programRenderers(piCodemode: PiCodemode): Renderers {
 	return {
 		renderCall(args, theme, context) {
 			const { code, ...rest } = (args ?? {}) as Record<string, unknown>;
-			startDuration(context.state as DurationState, rest.action === "wait", context.executionStarted);
+			const state = context.state as CallState;
+			startDuration(state, rest.action === "wait", context.executionStarted);
 			let text = formatToolCall(PROGRAM_TOOL_NAME, rest, theme);
 			if (typeof code === "string" && code) {
-				const lines = highlightCode(code.replace(/\r/g, "").replace(/\t/g, "   ").trimEnd(), "javascript");
+				const source = code.replace(/\r/g, "").replace(/\t/g, "   ").trimEnd();
+				const colors = SYNTAX_COLORS.map((color) => theme.fg(color, "")).join("");
+				if (state.script?.code !== source || state.script.colors !== colors) state.script = { code: source, colors, lines: highlightCode(source, "javascript") };
+				const { lines } = state.script;
 				const shown = context.expanded ? lines : lines.slice(0, CODE_PREVIEW_LINES);
 				text += `\n${shown.join("\n")}`;
 				if (shown.length < lines.length) text += `\n${moreLines(lines.length - shown.length, theme)}`;
@@ -94,21 +101,9 @@ export function programRenderers(piCodemode: PiCodemode): Renderers {
 			component.setText(text);
 			return component;
 		},
-		// `wait` shows how long it has waited, and when collapsed, each result as a line with the first lines of its output;
-		// the other results render like `codemode`.
+		// `wait` shows how long it has waited; the other results render like `codemode`.
 		renderResult: (result, options, theme, context) => (context.args as { action?: string }).action === "wait"
-			? renderTextResult(result, options, theme, context, () => {
-				const { results = [], running = [], interrupted, ...truncated } = (result.details ?? {}) as { results?: ProgramResultDetails[]; running?: string[]; interrupted?: boolean } & Partial<Truncation>;
-				const only = results[0];
-				// As `renderProgramWait` returns them, no results, or a single completed result alone, show as they are.
-				if (!only || (results.length === 1 && running.length === 0 && only.state === "completed")) return undefined;
-				const ids = [...results.map((entry) => entry.id), ...running];
-				const notes = [omittedLine(results.flatMap((entry) => entry.output === undefined ? [entry.id] : []), ids), runningLine(running, interrupted, ids)];
-				return renderResultList(results.flatMap(({ id, state, wallTimeSeconds, output }) => output === undefined ? [] : [{
-					line: [`Program ${shortId(id, ids)}`, state, ...(wallTimeSeconds === undefined ? [] : [formatDuration(wallTimeSeconds * 1000)])].join("  "),
-					body: output,
-				}]), notes, truncated, theme);
-			})
+			? renderTextResult(result, options, theme, context)
 			: piCodemode.renderResult(result, options, theme, context) as Text,
 	};
 }