@gavin-hu/my-pi-agent 0.13.1 → 0.15.0

package/extensions/subagent/index.ts

@@ -15,7 +15,7 @@
  * Load with:  pi --extension ./extensions/subagent
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled, resolveEffectiveCwd } from "../../lib/env.ts";
 import {
 	type AgentConfig,
@@ -25,8 +25,13 @@ import {
 	formatAgentList,
 	formatAgentNames,
 } from "./agents.ts";
+import { createBackgroundRuntime } from "./background.ts";
+import { registerAgentsCommand } from "./commands.ts";
+import { createSubagentUi } from "./ui.ts";
+import { loadSubagentConfig, type SubagentConfig } from "./config.ts";
 import { runChainMode, runParallelMode, runSingleMode, type ModeContext } from "./orchestrate.ts";
 import { renderSubagentCall, renderSubagentResult } from "./render.ts";
+import { pruneTranscripts, transcriptsDirFor } from "./transcripts.ts";
 import { SUBAGENT_FINISHED_CHANNEL } from "../../lib/events.ts";
 import { finishedEvent } from "./accounting.ts";
 import { runSingleAgent, type RunOptions } from "./run.ts";
@@ -46,6 +51,7 @@ const DESCRIPTION = [
 	"Delegate tasks to specialized subagents with isolated context windows.",
 	"Modes: single (`agent` + `task`), parallel (`tasks`), chain (sequential, `{previous}` placeholder).",
 	"Each runs in its own process, inheriting the current model and thinking level.",
+	"A single run can start in the background (`background: true`) and is managed with `/agents`.",
 	`Built-in agents: ${AGENT_NAMES}.`,
 ].join(" ");
 
@@ -53,6 +59,7 @@ const GUIDELINES = [
 	"Use `subagent` for broad codebase exploration, parallel research, or isolated implementation work that would bloat the main context.",
 	"Prefer `explorer` first when another agent would otherwise re-read many files, then pass its output to `planner` or `worker`.",
 	"Run independent tasks with `tasks` (max 8, up to 4 at once); use `chain` only when each step needs the previous step's output.",
+	"Use `background: true` only for one long task you will collect from `/agents`.",
 	"Project-local agents are repository-controlled and load only when `agentScope` includes them; an untrusted project requires confirmation.",
 ];
 
@@ -68,6 +75,20 @@ function requestedAgentNames(args: SubagentArgs): string[] {
 export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): void {
 	if (!isExtensionEnabled("subagent")) return;
 	const runner = deps.run ?? runSingleAgent;
+	// Read once per session; a call that arrives before `session_start` reads the
+	// same files lazily, so the two paths cannot disagree.
+	let settings: SubagentConfig | undefined;
+	let activeCtx: ExtensionContext | undefined;
+
+	const startSession = async (ctx: ExtensionContext): Promise<void> => {
+		settings = loadSubagentConfig(ctx.cwd);
+		if (settings.transcripts === "off") return;
+		try {
+			pruneTranscripts(await transcriptsDirFor(pi, ctx.cwd), settings);
+		} catch {
+			// Retention is housekeeping: an unreadable store must not fail a session.
+		}
+	};
 
 	/**
 	 * Account for each finished child, then hand the result on unchanged.
@@ -89,6 +110,29 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 		return result;
 	};
 
+	const background = createBackgroundRuntime({
+		appendEntry: (customType, data) => pi.appendEntry(customType, data),
+		onFinish: (run) => ui.notifyFinished(run),
+	});
+	const ui = createSubagentUi({
+		runs: () => background.list(activeCtx?.sessionManager.getBranch() ?? []),
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		background.reset();
+		activeCtx = ctx;
+		ui.attach(ctx);
+		background.subscribe(() => ui.paint());
+		ui.paint();
+		await startSession(ctx);
+	});
+	pi.on("session_shutdown", () => {
+		background.shutdown();
+		ui.detach();
+		activeCtx = undefined;
+	});
+	registerAgentsCommand(pi, background);
+
 	pi.registerTool({
 		name: TOOL_NAME,
 		label: "Subagent",
@@ -127,6 +171,13 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 			const discovery = discoverAgents(root, agentScope);
 			const agents = discovery.agents;
 			const requestedTotal = args.chain?.length ?? args.tasks?.length ?? 1;
+			const config = settings ?? loadSubagentConfig(ctx.cwd);
+			// Resolved against the session cwd, not the active root: a run's record outlives
+			// the worktree it ran in, the way the `job` registry does.
+			const transcripts =
+				config.transcripts === "off"
+					? undefined
+					: { dir: await transcriptsDirFor(pi, ctx.cwd), mode: config.transcripts };
 			const makeDetails = (results: SingleResult[]): SubagentDetails => ({
 				mode,
 				results,
@@ -171,6 +222,68 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 				}
 			}
 
+			if (args.background) {
+				if (mode !== "single") {
+					return {
+						content: [{ type: "text" as const, text: "`background` supports single mode only." }],
+						details: makeDetails([]),
+					};
+				}
+				if (!agents.some((candidate) => candidate.name === args.agent)) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Unknown agent: "${args.agent ?? ""}". Available agents: ${formatAgentList(agents)}`,
+							},
+						],
+						details: makeDetails([]),
+					};
+				}
+				const started = background.start(
+					{
+						agent: args.agent ?? "",
+						task: args.task ?? "",
+						cwd: args.cwd,
+						readOnly: args.readOnly,
+					},
+					ctx.sessionManager.getBranch(),
+					{
+						run,
+						agents,
+						defaults,
+						defaultCwd: root,
+						timeoutMs: config.timeoutMs,
+						transcripts,
+						backgroundMax: config.backgroundMax,
+					},
+				);
+				if (!started.ok) {
+					return {
+						content: [{ type: "text" as const, text: started.error }],
+						details: makeDetails([]),
+					};
+				}
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Started ${started.run.agent} as ${started.run.id} in the background. Use /agents to inspect, collect, or cancel it.`,
+						},
+					],
+					details: {
+						...makeDetails([]),
+						background: {
+							runId: started.run.id,
+							agent: started.run.agent,
+							task: started.run.task,
+							cwd: started.run.cwd,
+							startedAt: started.run.startedAt,
+						},
+					} satisfies SubagentDetails,
+				};
+			}
+
 			const context: ModeContext = {
 				run,
 				args,
@@ -180,6 +293,8 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 				onUpdate,
 				makeDetails,
 				agents,
+				timeoutMs: config.timeoutMs,
+				transcripts,
 			};
 
 			if (mode === "chain" && args.chain) return runChainMode(context);

package/extensions/subagent/orchestrate.ts

@@ -6,6 +6,7 @@
 
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { AgentConfig } from "./agents.ts";
+import type { TranscriptMode } from "./config.ts";
 import type { RunOptions } from "./run.ts";
 import { MAX_CONCURRENCY, PER_TASK_OUTPUT_CAP, type SubagentArgs } from "./schema.ts";
 import {
@@ -30,11 +31,15 @@ export interface ModeContext {
 	onUpdate?: OnUpdateCallback;
 	/** Builds the details payload for this mode from the current results. */
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
+	/** Per-run wall-clock limit in ms; `0` or absent disables it. */
+	timeoutMs?: number;
+	/** Where and when a finished run writes a transcript. */
+	transcripts?: { dir: string; mode: Exclude<TranscriptMode, "off"> };
 }
 
 /** Sequential chain: each step's `{previous}` is the prior step's final output. */
 export async function runChainMode(ctx: ModeContext): Promise<AgentToolResult<SubagentDetails>> {
-	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents } = ctx;
+	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents, timeoutMs, transcripts } = ctx;
 	const chain = args.chain ?? [];
 	const results: SingleResult[] = [];
 	let previous = "";
@@ -62,6 +67,8 @@ export async function runChainMode(ctx: ModeContext): Promise<AgentToolResult<Su
 			signal,
 			onUpdate: chainUpdate,
 			makeDetails,
+			timeoutMs,
+			transcripts,
 		});
 		results.push(result);
 
@@ -89,7 +96,7 @@ export async function runChainMode(ctx: ModeContext): Promise<AgentToolResult<Su
 
 /** Independent tasks with bounded concurrency, reporting running/done progress. */
 export async function runParallelMode(ctx: ModeContext): Promise<AgentToolResult<SubagentDetails>> {
-	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents } = ctx;
+	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents, timeoutMs, transcripts } = ctx;
 	const tasks = args.tasks ?? [];
 	const allResults: SingleResult[] = tasks.map((task) => createResult(task.agent, task.task));
 
@@ -113,6 +120,10 @@ export async function runParallelMode(ctx: ModeContext): Promise<AgentToolResult
 			cwd: task.cwd,
 			readOnly: args.readOnly,
 			signal,
+			// Elapsed time is per run, so a deadline is too: one timer around the mode
+			// would bound the batch rather than each child.
+			timeoutMs,
+			transcripts,
 			onUpdate: (partial) => {
 				const current = partial.details?.results[0];
 				if (!current) return;
@@ -148,7 +159,7 @@ export async function runParallelMode(ctx: ModeContext): Promise<AgentToolResult
 
 /** One agent + task. */
 export async function runSingleMode(ctx: ModeContext): Promise<AgentToolResult<SubagentDetails>> {
-	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents } = ctx;
+	const { run, args, defaults, defaultCwd, signal, onUpdate, makeDetails, agents, timeoutMs, transcripts } = ctx;
 	const result = await run({
 		defaultCwd,
 		defaults,
@@ -160,6 +171,8 @@ export async function runSingleMode(ctx: ModeContext): Promise<AgentToolResult<S
 		signal,
 		onUpdate,
 		makeDetails,
+		timeoutMs,
+		transcripts,
 	});
 
 	if (isFailedResult(result)) {

package/extensions/subagent/render.ts

@@ -296,6 +296,16 @@ function callText(args: StreamedSubagentArgs, theme: Theme, context?: { cwd?: st
 	return text;
 }
 
+/** The transcript this run kept, or why it could not be written. */
+function transcriptLine(result: SingleResult, theme: Theme): string | undefined {
+	if (result.artifactError) {
+		return paint(theme, "warn", `transcript failed: ${sanitizeLine(result.artifactError)}`);
+	}
+	if (!result.artifactPath) return undefined;
+	const cut = result.artifactTruncated ? paint(theme, "warn", " (truncated)") : "";
+	return paint(theme, "faint", `transcript: ${sanitizeLine(result.artifactPath)}${cut}`);
+}
+
 /** Append one result's expanded block: header, error, task, output, usage. */
 function addExpandedResult(
 	container: Container,
@@ -353,6 +363,8 @@ function addExpandedResult(
 		container.addChild(new Spacer(1));
 		container.addChild(new Text(paint(theme, "faint", usage), 0, 0));
 	}
+	const transcript = transcriptLine(result, theme);
+	if (transcript) container.addChild(new Text(transcript, 0, 0));
 }
 
 /** The collapsed single result: header, a word, body, expand hint, and usage. */
@@ -476,6 +488,19 @@ export function renderSubagentResult(
 ): Component {
 	const now = options.now ?? Date.now();
 	const details = toolDetails<SubagentDetails>(result.details);
+	if (details?.background) {
+		syncElapsedTimer(false, context);
+		const text = reuseText(context?.lastComponent);
+		const background = details.background;
+		text.setText(
+			paint(
+				theme,
+				"meta",
+				`Started ${sanitizeLine(background.agent)} as ${sanitizeLine(background.runId)} in the background. Use /agents to collect or cancel it.`,
+			),
+		);
+		return text;
+	}
 	if (!details || details.results.length === 0) {
 		syncElapsedTimer(false, context);
 		const text = reuseText(context?.lastComponent);

package/extensions/subagent/run.ts

@@ -2,8 +2,9 @@
  * Running one subagent subprocess.
  *
  * Spawns `pi --mode json`, folds the JSON event stream into a `SingleResult`,
- * streams partial updates, and cleans up the temporary system-prompt file. The
- * process factory is injectable so tests can drive a scripted child.
+ * enforces the run's deadline, optionally records the raw stream, streams partial
+ * updates, and cleans up the temporary system-prompt file. The process factory and
+ * the transcript store are injectable so tests can drive a scripted child.
  */
 
 import { spawn as nodeSpawn } from "node:child_process";
@@ -11,9 +12,13 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { formatDuration } from "../../lib/format.ts";
+import { LineSplitter } from "../../lib/lines.ts";
 import { BUILTIN_AGENTS, formatAgentList, type AgentConfig } from "./agents.ts";
+import type { TranscriptMode } from "./config.ts";
 import { buildAgentArgs, getPiInvocation, READ_ONLY_NOTE } from "./invocation.ts";
-import { applyEvent, createResult, parseJsonLine } from "./stream.ts";
+import { applyEvent, createResult, isFailedResult, parseJsonLine } from "./stream.ts";
+import { createTranscript, type Transcript } from "./transcripts.ts";
 import type { DispatchDefaults, OnUpdateCallback, SingleResult, SpawnFn, SubagentDetails } from "./types.ts";
 
 export interface RunOptions {
@@ -38,6 +43,12 @@ export interface RunOptions {
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
 	/** Process factory; defaults to `node:child_process.spawn`. */
 	spawn?: SpawnFn;
+	/** Per-run wall-clock limit in ms; `0` or absent disables it. */
+	timeoutMs?: number;
+	/** Return an aborted result instead of throwing (used by background runs). */
+	abortAsResult?: boolean;
+	/** Where and when a finished run writes a transcript. */
+	transcripts?: { dir: string; mode: Exclude<TranscriptMode, "off"> };
 }
 
 async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
@@ -53,57 +64,83 @@ async function writePromptToTempFile(agentName: string, prompt: string): Promise
 interface SpawnOutcome {
 	exitCode: number;
 	aborted: boolean;
+	timedOut: boolean;
+}
+
+/** How long a killed child has to exit before it is killed again, hard. */
+const KILL_ESCALATION_MS = 5000;
+
+/** Why a child is being killed; a timeout fails the run, an abort rejects the call. */
+type KillReason = "abort" | "timeout";
+
+interface SpawnContext {
+	command: string;
+	args: string[];
+	cwd: string;
+	/** Per-run wall-clock limit in ms; `0` disables it. */
+	timeoutMs: number;
+	signal?: AbortSignal;
+	result: SingleResult;
+	onEvent: () => void;
+	transcript?: Transcript;
+	spawn: SpawnFn;
 }
 
 /** Spawn the child, parse stdout line-by-line, and resolve when it closes. */
-function spawnAndCollect(
-	command: string,
-	args: string[],
-	cwd: string,
-	signal: AbortSignal | undefined,
-	result: SingleResult,
-	onEvent: () => void,
-	spawn: SpawnFn,
-): Promise<SpawnOutcome> {
+function spawnAndCollect(context: SpawnContext): Promise<SpawnOutcome> {
+	const { command, args, cwd, timeoutMs, signal, result, onEvent, transcript, spawn } = context;
 	return new Promise<SpawnOutcome>((resolve) => {
 		const proc = spawn(command, args, { cwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
-		let buffer = "";
+		const splitter = new LineSplitter();
 		let settled = false;
-		let aborted = false;
+		let abortRequested = false;
+		let timedOut = false;
 
-		let kill: (() => void) | undefined;
 		let killTimer: ReturnType<typeof setTimeout> | undefined;
+		let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+
+		const kill = (reason: KillReason) => {
+			if (settled) return;
+			if (reason === "abort") abortRequested = true;
+			else {
+				timedOut = true;
+				result.timedOut = true;
+			}
+			proc.kill("SIGTERM");
+			killTimer = setTimeout(() => {
+				if (!proc.killed) proc.kill("SIGKILL");
+			}, KILL_ESCALATION_MS);
+			killTimer.unref();
+		};
+		const onAbort = () => kill("abort");
 
 		const finish = (exitCode: number) => {
 			if (settled) return;
 			settled = true;
-			if (kill && signal) signal.removeEventListener("abort", kill);
+			if (signal) signal.removeEventListener("abort", onAbort);
 			if (killTimer) clearTimeout(killTimer);
-			if (buffer.trim()) {
-				const event = parseJsonLine(buffer);
-				if (event && applyEvent(result, event)) onEvent();
+			if (timeoutTimer) clearTimeout(timeoutTimer);
+			for (const line of splitter.flush()) {
+				if (line.trim()) processLine(line);
 			}
-			resolve({ exitCode, aborted });
+			resolve({ exitCode, aborted: abortRequested, timedOut });
 		};
 
 		const processLine = (line: string) => {
+			transcript?.line(line);
 			const event = parseJsonLine(line);
 			if (event && applyEvent(result, event)) onEvent();
 		};
 
 		proc.stdout?.on("data", (chunk) => {
-			buffer += chunk.toString();
-			// Keep the final partial line in the buffer for the close handler.
-			let newline = buffer.indexOf("\n");
-			while (newline !== -1) {
-				processLine(buffer.slice(0, newline));
-				buffer = buffer.slice(newline + 1);
-				newline = buffer.indexOf("\n");
-			}
+			// The splitter holds the final partial line for the close handler.
+			for (const line of splitter.push(chunk)) processLine(line);
 		});
 
 		proc.stderr?.on("data", (chunk) => {
-			result.stderr += chunk.toString();
+			const text = chunk.toString();
+			result.stderr += text;
+			transcript?.stderr(text);
 		});
 
 		proc.on("close", (code, signal) => {
@@ -122,16 +159,12 @@ function spawnAndCollect(
 		});
 
 		if (signal) {
-			kill = () => {
-				aborted = true;
-				proc.kill("SIGTERM");
-				killTimer = setTimeout(() => {
-					if (!proc.killed) proc.kill("SIGKILL");
-				}, 5000);
-				killTimer.unref();
-			};
-			if (signal.aborted) kill();
-			else signal.addEventListener("abort", kill, { once: true });
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
+		if (timeoutMs > 0) {
+			timeoutTimer = setTimeout(() => kill("timeout"), timeoutMs);
+			timeoutTimer.unref();
 		}
 	});
 }
@@ -163,6 +196,12 @@ export async function runSingleAgent(options: RunOptions): Promise<SingleResult>
 
 	const emit = () => options.onUpdate?.({ content: [], details: options.makeDetails([result]) });
 
+	const timeoutMs = options.timeoutMs ?? 0;
+	if (timeoutMs > 0) result.timeoutMs = timeoutMs;
+	const transcripts = options.transcripts;
+	const transcript = transcripts ? createTranscript() : undefined;
+	let runCwd = options.defaultCwd;
+
 	let tempDir: string | null = null;
 	let tempPath: string | null = null;
 
@@ -178,22 +217,47 @@ export async function runSingleAgent(options: RunOptions): Promise<SingleResult>
 
 		const args = buildAgentArgs(agent, options.task, options.defaults, tempPath, options.readOnly === true);
 		const invocation = getPiInvocation(args);
-		const runCwd = options.cwd ? path.resolve(options.defaultCwd, options.cwd) : options.defaultCwd;
-		const outcome = await spawnAndCollect(
-			invocation.command,
-			invocation.args,
-			runCwd,
-			options.signal,
+		runCwd = options.cwd ? path.resolve(options.defaultCwd, options.cwd) : options.defaultCwd;
+		const outcome = await spawnAndCollect({
+			command: invocation.command,
+			args: invocation.args,
+			cwd: runCwd,
+			timeoutMs,
+			signal: options.signal,
 			result,
-			emit,
+			onEvent: emit,
+			transcript,
 			spawn,
-		);
+		});
 
-		result.exitCode = outcome.exitCode;
+		result.exitCode = outcome.timedOut || outcome.aborted ? 1 : outcome.exitCode;
 		result.finishedAt = Date.now();
-		if (outcome.aborted) throw new Error("Subagent was aborted");
+		// A deadline fails the run rather than rejecting it: a chain then stops at
+		// this step and reports why, instead of discarding the steps already done.
+		if (outcome.timedOut) result.errorMessage = `Timed out after ${formatDuration(timeoutMs)}`;
+		if (outcome.aborted) {
+			if (options.abortAsResult) {
+				result.stopReason = "aborted";
+				result.errorMessage = "Aborted";
+				return result;
+			}
+			throw new Error("Subagent was aborted");
+		}
 		return result;
 	} finally {
+		// Flushed here, not after the call: the abort path throws past every caller.
+		if (transcript && transcripts && (transcripts.mode === "all" || isFailedResult(result))) {
+			const written = transcript.write(transcripts.dir, result, {
+				cwd: runCwd,
+				readOnly: options.readOnly === true,
+			});
+			if (written.path) {
+				result.artifactPath = written.path;
+				result.artifactBytes = written.bytes;
+				if (written.truncated) result.artifactTruncated = true;
+			}
+			if (written.error) result.artifactError = written.error;
+		}
 		if (tempPath) {
 			try {
 				fs.unlinkSync(tempPath);

package/extensions/subagent/schema.ts

@@ -66,6 +66,11 @@ export const SubagentParams = Type.Object({
 			description: "Force a read-only tool set (readers only). Plan mode sets this.",
 		}),
 	),
+	background: Type.Optional(
+		Type.Boolean({
+			description: "Start a single run and return immediately; inspect and collect it with /agents.",
+		}),
+	),
 });
 
 export type SubagentArgs = Static<typeof SubagentParams>;
@@ -85,6 +90,13 @@ export function resolveMode(params: SubagentArgs): ModeResolution {
 	const hasTasks = taskCount > 0;
 	const hasSingle = Boolean(params.agent && params.task);
 
+	if (params.background === true && (hasChain || hasTasks)) {
+		return { error: "`background` supports single mode only; provide `agent` and `task`." };
+	}
+	if (params.background === true && !hasSingle) {
+		return { error: "`background` requires `agent` and `task`." };
+	}
+
 	if (hasChain && hasTasks) return { error: "Provide either `chain` or `tasks`, not both." };
 	if (hasChain && hasSingle) return { error: "Provide either `chain` or `agent`+`task`, not both." };
 	if (hasTasks && hasSingle) return { error: "Provide either `tasks` or `agent`+`task`, not both." };