@tshu-w/pi-agents 0.1.1 → 0.2.1

package/src/agents/tool.ts

@@ -1,12 +1,15 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { boundBlocks, boundText } from "../output.ts";
+import { boundBlocks, boundText, type Truncation } from "../output.ts";
 import { rejectFields } from "../params.ts";
-import { renderTextResult, renderToolCall, startDuration, type DurationState } from "../render-call.ts";
+import { renderResultList, 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,
@@ -32,11 +35,25 @@ 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 } = outcome;
-	const pendingLine = pending.length > 0 ? `Still pending: ${pending.map((agent) => label(agent, ids)).join(", ")}` : "";
-	if (results.length === 0) return { text: pendingLine || "No results.", read: [], details: { results: [], pending: pending.map((agent) => agent.id) } };
+	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");
@@ -53,10 +70,10 @@ function renderWait(outcome: WaitOutcome, ids: string[]): { text: string; read:
 	});
 	let text = bounded.text;
 	const read = results.slice(0, bounded.shown);
-	const omitted = results.slice(bounded.shown);
-	if (omitted.length > 0) text += `\n\n[Results omitted: ${omitted.map((result) => label(result.agent, ids)).join(", ")}. Use wait with fewer targets.]`;
-	if (pendingLine) text += `\n\n${pendingLine}`;
-	return { text, read, details: { results: details, pending: pending.map((agent) => agent.id), ...bounded.details } };
+	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. */
@@ -85,8 +102,18 @@ 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.
-		renderResult: (result, options, theme, context) => renderTextResult(result, options, theme, context),
+		// `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.`,
 		promptSnippet: "Create, message, and coordinate Agents",
 		promptGuidelines: [
@@ -101,7 +128,7 @@ export function registerAgentTool(
 			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, or xhigh (default: the caller's level)." })),
+			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)." })),
@@ -168,7 +195,8 @@ export function registerAgentTool(
 					const selected = targets?.map((target) => agents.ownedTarget(target));
 					// An empty partial result lets the row show the elapsed time.
 					onUpdate?.({ content: [], details: undefined });
-					const outcome = await agents.wait(selected, params.history ?? 0, params.timeout ?? 30, signal);
+					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 };

package/src/daemon/client.mjs

@@ -42,13 +42,16 @@ export async function ensureDaemon(paths, { sessionDir, signal }) {
       if (code !== 0) launchError = new Error(`Daemon exited (${code}). See ${paths.daemonLog}`);
     });
     child.unref();
+    // The new daemon sets its socket's mode just after binding; a mode that stays wrong is an error.
+    let modeWait = 0;
     for (;;) {
       signal?.throwIfAborted();
       if (launchError) throw launchError;
       try {
         return await request(paths.daemon, { action: 'status' }, { signal, timeoutMs: 1000 });
       } catch (failure) {
-        if (!['ENOENT', 'ECONNREFUSED', ...RETRY].includes(failure.code)) throw failure;
+        if (failure.code === 'SOCKET_MODE' && ++modeWait > 20) throw failure;
+        if (!['ENOENT', 'ECONNREFUSED', 'SOCKET_MODE', ...RETRY].includes(failure.code)) throw failure;
         // Another daemon holds the lock; it answers once its socket is up.
         if (child.exitCode === 0) break;
       }

package/src/host/client.mjs

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { constants } from 'node:fs';
 import { open, readdir, stat, unlink } from 'node:fs/promises';
 import net from 'node:net';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
 import { FRAME, frame, json, readFrames } from './frames.mjs';
@@ -16,7 +16,7 @@ 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;
 
-function hostStatus(path) {
+export function hostStatus(path) {
   return new Promise((resolve, reject) => {
     const socket = net.connect(path);
     socket.setTimeout(1000, () => socket.destroy(Object.assign(new Error('Host status timed out'), { code: 'ETIMEDOUT' })));
@@ -27,6 +27,11 @@ function hostStatus(path) {
   });
 }
 
+/** The file of the Session a host runs; Pi keeps a relative session directory relative, so it resolves against the host's cwd. */
+export function hostSessionFile(host) {
+  return host.session?.file && resolve(host.cwd, host.session.file);
+}
+
 export function alive(pid) {
   try { process.kill(pid, 0); return true; }
   catch (error) { return error.code !== 'ESRCH'; }
@@ -50,6 +55,19 @@ export async function listHosts(paths) {
   return hosts;
 }
 
+/**
+ * Running hosts once `found` matches one or no host `starting` remains, waiting at most `timeoutMs`:
+ * a host whose Pi has not reported its Session yet may be starting the Session a caller looks for.
+ */
+export async function settledHosts(paths, found, { starting = host => !host.session, timeoutMs = START_TIMEOUT_MS } = {}) {
+  const deadline = performance.now() + timeoutMs;
+  for (;;) {
+    const hosts = await listHosts(paths);
+    if (hosts.some(found) || !hosts.some(starting) || performance.now() > deadline) return hosts;
+    await delay(100);
+  }
+}
+
 /**
  * Starts a detached host running `pi args` in `cwd` and resolves to its socket once it accepts connections.
  * With `waitForTerminal`, Pi starts when the first terminal attaches.
@@ -88,9 +106,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.
  * Resolves to { reason: 'detach' | 'takeover' | 'exited' | 'closed', session }.
  */
-export function attach(socketPath, { isDetach, stdin = process.stdin, stdout = process.stdout }) {
+export function attach(socketPath, { isDetach, onAttach, stdin = process.stdin, stdout = process.stdout }) {
   return new Promise((resolve, reject) => {
     const socket = net.connect(socketPath);
     const size = () => ({ cols: stdout.columns, rows: stdout.rows });
@@ -104,7 +123,7 @@ export function attach(socketPath, { isDetach, stdin = process.stdin, stdout = p
       if (at > 0) socket.write(frame(FRAME.data, Buffer.from(keys.slice(0, at).join(''), encoding)));
       socket.write(frame(FRAME.detached));
     };
-    let result, connected = false, altScreen = false;
+    let result, connected = false, altScreen = false, attached = false;
     function finish() {
       stdout.off('resize', onResize);
       stdin.off('data', onInput);
@@ -113,7 +132,8 @@ export function attach(socketPath, { isDetach, stdin = process.stdin, stdout = p
         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.
-        if (result?.reason !== 'exited') stdout.write(altScreen ? `\x1b[?1049l${RESET}` : `${RESET}\r\n`);
+        // 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`);
       }
       resolve(result ?? { reason: 'closed' });
     }
@@ -129,6 +149,11 @@ export function attach(socketPath, { isDetach, stdin = process.stdin, stdout = p
       if (type === FRAME.data) {
         for (const [, mode] of body.toString('latin1').matchAll(ALT_SCREEN)) altScreen = mode === 'h';
         stdout.write(body);
+        // The host sends the screen only after it has told Pi that a terminal is attached.
+        if (!attached) {
+          attached = true;
+          onAttach?.();
+        }
       }
       else if (type === FRAME.detached) result = { ...json(body) };
       else if (type === FRAME.exited) result = { reason: 'exited', ...json(body) };

package/src/host/extension.ts

@@ -3,7 +3,7 @@ import net from "node:net";
 import { treeMetadata } from "../agents/registry.ts";
 import { FRAME, frame, json, readFrames } from "./frames.mjs";
 
-const IDLE_EXIT_MS = 5 * 60_000;
+const IDLE_EXIT_MS = 10 * 60_000;
 
 // Only the host's own child runs in it; children of Pi inherit the variables but have another parent.
 // They stay in the environment so a Pi that replaces itself with execve finds its host again.
@@ -12,20 +12,21 @@ const hostSocket = process.env.PI_AGENTS_HOST && process.env.PI_AGENTS_HOST_PID
 export interface Host {
 	socket: string;
 	attached(): boolean;
-	onChange(listener: () => void): void;
+	onChange(listener: () => void): () => void;
 }
 
 /**
  * Connects Pi to the host it runs in: reports the current Session, detaches on request,
- * disables suspend, and exits after the tree has been idle and detached for a while.
+ * disables suspend, and exits after the tree has been idle and detached, with no RPC client, for a while.
  * Returns the host, if Pi runs in one.
  */
-export function hostExtension(pi: ExtensionAPI, { treeIdle }: { treeIdle: () => boolean }): Host | undefined {
+export function hostExtension(pi: ExtensionAPI, { treeIdle, rpcClients }: { treeIdle: () => boolean; rpcClients: () => number }): Host | undefined {
 	if (!hostSocket) return;
 	const listeners: Array<() => void> = [];
 
 	let ctx: ExtensionContext | undefined;
-	let attached = true;
+	// Whether a terminal was attached when Pi started, until the host reports a change.
+	let attached = process.env.PI_AGENTS_HOST_ATTACHED !== "0";
 	let idleSince: number | undefined;
 	let socket: net.Socket | undefined;
 	const connect = (path: string): net.Socket => {
@@ -43,32 +44,55 @@ export function hostExtension(pi: ExtensionAPI, { treeIdle }: { treeIdle: () =>
 	const report = () => {
 		if (!ctx) return;
 		const file = ctx.sessionManager.getSessionFile();
-		send({ type: "session", session: { id: ctx.sessionManager.getSessionId(), name: pi.getSessionName(), file } });
+		send({ type: "session", session: { id: ctx.sessionManager.getSessionId(), name: pi.getSessionName(), file, cwd: ctx.cwd } });
 	};
 
 	// Pi suspends by stopping its process group; a host has no shell to resume it, so resume at once.
-	process.on("SIGTSTP", () => process.kill(process.pid, "SIGCONT"));
-
-	const timer = setInterval(() => {
-		if (!ctx || attached || !ctx.isIdle() || ctx.hasPendingMessages() || !treeIdle()) {
+	const resume = () => process.kill(process.pid, "SIGCONT");
+	const checkIdle = () => {
+		if (!ctx || attached || !ctx.isIdle() || ctx.hasPendingMessages() || !treeIdle() || rpcClients() > 0) {
 			idleSince = undefined;
 			return;
 		}
 		idleSince ??= Date.now();
 		if (Date.now() - idleSince >= IDLE_EXIT_MS) ctx.shutdown();
-	}, 1000);
-	timer.unref();
+	};
+	let timer: ReturnType<typeof setInterval> | undefined;
 
 	pi.on("session_start", (_event, current) => {
 		// Owned Agents run in the same process; only the root speaks for the host.
 		if (treeMetadata(current)) return;
 		ctx = current;
 		socket ??= connect(hostSocket);
+		if (!timer) {
+			process.on("SIGTSTP", resume);
+			timer = setInterval(checkIdle, 1000);
+			timer.unref();
+		}
 		report();
 	});
 	pi.on("session_info_changed", () => report());
-	pi.on("session_shutdown", () => { ctx = undefined; });
+	// A reload or another Session loads this extension again, which takes over.
+	pi.on("session_shutdown", () => {
+		ctx = undefined;
+		idleSince = undefined;
+		clearInterval(timer);
+		timer = undefined;
+		process.off("SIGTSTP", resume);
+		socket?.destroy();
+		socket = undefined;
+	});
 
 	pi.registerCommand("detach", { description: "Detach this terminal; Pi keeps running", handler: async () => send({ type: "detach" }) });
-	return { socket: hostSocket, attached: () => attached, onChange: (listener) => { listeners.push(listener); } };
+	return {
+		socket: hostSocket,
+		attached: () => attached,
+		onChange: (listener) => {
+			listeners.push(listener);
+			return () => {
+				const at = listeners.indexOf(listener);
+				if (at >= 0) listeners.splice(at, 1);
+			};
+		},
+	};
 }