@wahack/pi-coding-agent 15.11.0

package/src/task/repair-args.ts

@@ -0,0 +1,129 @@
+/**
+ * Repair double-encoded JSON string arguments for the task tool.
+ *
+ * Models occasionally JSON-escape a string value twice when emitting a
+ * `task` tool call, so an `assignment` that should read
+ *
+ *     # Role
+ *     You are a judge … "describe this" … return —
+ *
+ * arrives — after the one JSON decode the provider already applied — as the
+ * literal text
+ *
+ *     # Role\nYou are a judge … \"describe this\" … return \u2014
+ *
+ * i.e. every newline, quote, and unicode character is still backslash-escaped.
+ * The subagent then receives that garbled prompt, and the call preview renders
+ * one long blob with visible `\n` / `\"` / `\uXXXX`.
+ *
+ * The *whole-arguments* form of this quirk (the entire `arguments` blob is a
+ * JSON string) is already auto-corrected by the validator's JSON-string
+ * coercion. This module handles the *per-field* form, where the object parses
+ * fine but an individual string value is double-encoded — the validator never
+ * fires there because a double-encoded string is still a structurally valid
+ * string.
+ *
+ * This is deliberately scoped to the task tool's natural-language fields
+ * (`assignment`, `description`). It is NOT applied to code-bearing
+ * tools (write/edit/bash/search), where a backslash or quote is load-bearing
+ * and a false-positive unescape would silently corrupt a file or command.
+ */
+import type { TaskItem, TaskParams } from "./types";
+
+/** A backslash that escapes a structural char — `\"`, `\\`, `\/`, or `\uXXXX`. */
+const STRUCTURAL_ESCAPE = /\\(?:["\\/]|u[0-9a-fA-F]{4})/;
+
+/**
+ * Whether `value` carries the signature of whole-string double-encoding rather
+ * than an incidental escape mention. A lone `\n`/`\t` in an instruction (e.g.
+ * "split lines on \n") is far more likely a literal mention than a
+ * double-encoded document, so it is left alone; a structural escape (`\"`,
+ * `\\`, `\uXXXX`) or two-plus escape sequences indicates a re-escaped payload.
+ */
+function hasDoubleEncodeSignature(value: string): boolean {
+	if (STRUCTURAL_ESCAPE.test(value)) return true;
+	let count = 0;
+	for (let i = 0; i < value.length; i++) {
+		if (value.charCodeAt(i) === 0x5c /* \ */) {
+			count += 1;
+			if (count >= 2) return true;
+			i += 1; // skip the escaped char so `\\` counts once
+		}
+	}
+	return false;
+}
+
+/**
+ * Return the once-unescaped string when `value` is uniformly double-encoded
+ * JSON (a well-formed JSON string body that decodes to a different string);
+ * otherwise return `value` unchanged.
+ *
+ * The `JSON.parse(\`"${value}"\`)` round-trip is the safety net: it only
+ * succeeds when *every* backslash begins a valid JSON escape and no bare
+ * double-quote exists — exactly the signature of double-encoding. Genuine
+ * prose with a Windows path (`C:\Users`), a regex (`\d+`), an embedded quote,
+ * or a real (already-decoded) newline makes the parse throw, so the value is
+ * returned untouched.
+ */
+export function repairDoubleEncodedJsonString(value: string): string {
+	// Fast path: no backslash → nothing was escaped → the parse can never differ.
+	if (!value.includes("\\")) return value;
+	if (!hasDoubleEncodeSignature(value)) return value;
+	let decoded: unknown;
+	try {
+		decoded = JSON.parse(`"${value}"`);
+	} catch {
+		return value;
+	}
+	return typeof decoded === "string" && decoded !== value ? decoded : value;
+}
+
+/** Repair a single (possibly partial) task item's prose fields. */
+function repairTaskItem(task: TaskItem): TaskItem {
+	if (task === null || typeof task !== "object") return task;
+	const assignment =
+		typeof task.assignment === "string" ? repairDoubleEncodedJsonString(task.assignment) : task.assignment;
+	const description =
+		typeof task.description === "string" ? repairDoubleEncodedJsonString(task.description) : task.description;
+	if (assignment === task.assignment && description === task.description) return task;
+	return { ...task, assignment, description };
+}
+
+/**
+ * Repair double-encoded prose in task-tool params (`assignment`,
+ * `description`, shared `context`, and each batch task item's prose fields).
+ * Returns the same reference when nothing changed so callers can cheaply skip
+ * work. Defensive against partially-streamed args (missing/undefined fields,
+ * partial task arrays) so it is safe on the render path as well as on
+ * execution.
+ */
+export function repairTaskParams(params: TaskParams): TaskParams {
+	if (params === null || typeof params !== "object") return params;
+
+	const assignment =
+		typeof params.assignment === "string" ? repairDoubleEncodedJsonString(params.assignment) : params.assignment;
+	const description =
+		typeof params.description === "string" ? repairDoubleEncodedJsonString(params.description) : params.description;
+	const context = typeof params.context === "string" ? repairDoubleEncodedJsonString(params.context) : params.context;
+
+	let tasks = params.tasks;
+	if (Array.isArray(params.tasks)) {
+		let changed = false;
+		const repaired = params.tasks.map(task => {
+			const next = repairTaskItem(task);
+			if (next !== task) changed = true;
+			return next;
+		});
+		if (changed) tasks = repaired;
+	}
+
+	if (
+		assignment === params.assignment &&
+		description === params.description &&
+		context === params.context &&
+		tasks === params.tasks
+	) {
+		return params;
+	}
+	return { ...params, assignment, description, context, tasks };
+}

package/src/task/subprocess-tool-registry.ts

@@ -0,0 +1,88 @@
+/**
+ * Registry for handling tool events from subprocess agents.
+ *
+ * Tools can register handlers to:
+ * - Extract structured data from their execution results
+ * - Trigger subprocess termination on completion
+ * - Provide custom rendering for realtime/final display
+ */
+import type { Component } from './stubs/tui/index.ts';
+import type { Theme } from "../modes/theme/theme";
+
+/** Event from subprocess tool execution (parsed from JSONL) */
+export interface SubprocessToolEvent {
+	toolName: string;
+	toolCallId: string;
+	args?: Record<string, unknown>;
+	result?: {
+		content: Array<{ type: string; text?: string }>;
+		details?: unknown;
+	};
+	isError?: boolean;
+}
+
+/** Handler for subprocess tool events */
+export interface SubprocessToolHandler<TData = unknown> {
+	/**
+	 * Extract structured data from tool result.
+	 * Extracted data is accumulated in progress.extractedToolData[toolName][].
+	 */
+	extractData?: (event: SubprocessToolEvent) => TData | undefined;
+
+	/**
+	 * Whether this tool's completion should terminate the subprocess.
+	 * Return true to send SIGTERM after the tool completes.
+	 */
+	shouldTerminate?: (event: SubprocessToolEvent) => boolean;
+
+	/**
+	 * Render a single data item inline during streaming progress.
+	 * Called for each tool execution end event.
+	 */
+	renderInline?: (data: TData, theme: Theme) => Component;
+
+	/**
+	 * Render accumulated data in the final result view.
+	 * Called once with all accumulated data for this tool.
+	 */
+	renderFinal?: (allData: TData[], theme: Theme, expanded: boolean) => Component;
+}
+
+/** Registry for subprocess tool handlers */
+class SubprocessToolRegistryImpl {
+	#handlers = new Map<string, SubprocessToolHandler>();
+
+	/**
+	 * Register a handler for a tool's subprocess events.
+	 */
+	register<T>(toolName: string, handler: SubprocessToolHandler<T>): void {
+		this.#handlers.set(toolName, handler as SubprocessToolHandler);
+	}
+
+	/**
+	 * Get the handler for a tool, if registered.
+	 */
+	getHandler(toolName: string): SubprocessToolHandler | undefined {
+		return this.#handlers.get(toolName);
+	}
+
+	/**
+	 * Check if a tool has a registered handler.
+	 */
+	hasHandler(toolName: string): boolean {
+		return this.#handlers.has(toolName);
+	}
+
+	/**
+	 * Get all registered tool names.
+	 */
+	getRegisteredTools(): string[] {
+		return Array.from(this.#handlers.keys());
+	}
+}
+
+/** Singleton registry instance */
+export const subprocessToolRegistry = new SubprocessToolRegistryImpl();
+
+/** Type helper for extracted tool data in progress/result */
+export type ExtractedToolData = Record<string, unknown[]>;

package/src/task/types.ts

@@ -0,0 +1,336 @@
+import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { Usage } from "@oh-my-pi/pi-ai";
+import { $env } from "@oh-my-pi/pi-utils";
+import * as z from "zod/v4";
+import type { AgentSessionEvent } from "../session/agent-session";
+import type { NestedRepoPatch } from "./worktree";
+
+/** Source of an agent definition */
+export type AgentSource = "bundled" | "user" | "project";
+
+const parseNumber = (value: string | undefined, defaultValue: number): number => {
+	if (value) {
+		try {
+			const number = Number.parseInt(value, 10);
+			if (!Number.isNaN(number) && number > 0) {
+				return number;
+			}
+		} catch {}
+	}
+	return defaultValue;
+};
+
+/** Maximum output bytes per agent */
+export const MAX_OUTPUT_BYTES = parseNumber($env.PI_TASK_MAX_OUTPUT_BYTES, 500_000);
+
+/** Maximum output lines per agent */
+export const MAX_OUTPUT_LINES = parseNumber($env.PI_TASK_MAX_OUTPUT_LINES, 5000);
+
+/** EventBus channel for raw subagent events */
+export const TASK_SUBAGENT_EVENT_CHANNEL = "task:subagent:event";
+
+/** EventBus channel for aggregated subagent progress */
+export const TASK_SUBAGENT_PROGRESS_CHANNEL = "task:subagent:progress";
+
+/** EventBus channel for subagent lifecycle (start/end) */
+export const TASK_SUBAGENT_LIFECYCLE_CHANNEL = "task:subagent:lifecycle";
+
+/** Payload emitted on TASK_SUBAGENT_PROGRESS_CHANNEL */
+export interface SubagentProgressPayload {
+	index: number;
+	agent: string;
+	agentSource: AgentSource;
+	task: string;
+	parentToolCallId?: string;
+	assignment?: string;
+	progress: AgentProgress;
+	sessionFile?: string;
+}
+
+/** Payload emitted on TASK_SUBAGENT_EVENT_CHANNEL */
+export interface SubagentEventPayload {
+	id: string;
+	event: AgentSessionEvent;
+}
+
+/** Payload emitted on TASK_SUBAGENT_LIFECYCLE_CHANNEL */
+export interface SubagentLifecyclePayload {
+	id: string;
+	agent: string;
+	agentSource: AgentSource;
+	description?: string;
+	status: "started" | "completed" | "failed" | "aborted";
+	sessionFile?: string;
+	parentToolCallId?: string;
+	index: number;
+}
+
+/**
+ * One unit of work. The single-spawn schema is `{ agent, ...taskItemSchema }`;
+ * the batch schema (`task.batch`) is `{ agent, context, tasks: taskItemSchema[] }`.
+ * When task isolation is enabled, `isolated` joins the item shape (per-item in
+ * batch form, top-level in the flat form via the spread).
+ */
+const taskItemShape = {
+	id: z.string().max(48).optional().describe("stable agent id; default generated"),
+	description: z.string().optional().describe("ui label, not seen by subagent"),
+	assignment: z.string().describe("the work; self-contained instructions"),
+};
+const isolatedShape = {
+	isolated: z.boolean().optional().describe("run in isolated env; returns patches"),
+};
+const agentShape = {
+	agent: z.string().describe("agent type to spawn"),
+};
+const contextShape = {
+	context: z.string().describe("shared background prepended to each assignment"),
+};
+
+export const taskItemSchema = z.object(taskItemShape);
+const taskItemSchemaIsolated = z.object({ ...taskItemShape, ...isolatedShape });
+
+/** Single task item. Fields are optional defensively: args stream in token by token. */
+export interface TaskItem {
+	/** Stable agent id; default = generated AdjectiveNoun. */
+	id?: string;
+	/** UI label, not seen by the subagent. */
+	description?: string;
+	/** The work; required by the schema. */
+	assignment?: string;
+	/** Run this spawn in an isolated worktree (batch form; flat form carries it top-level). */
+	isolated?: boolean;
+}
+
+export const taskSchema = z.object({ ...agentShape, ...taskItemShape, ...isolatedShape });
+const taskSchemaNoIsolation = z.object({ ...agentShape, ...taskItemShape });
+const taskSchemaBatch = z.object({
+	...agentShape,
+	...contextShape,
+	tasks: z.array(taskItemSchemaIsolated).describe("tasks to spawn; one subagent per item"),
+});
+const taskSchemaBatchNoIsolation = z.object({
+	...agentShape,
+	...contextShape,
+	tasks: z.array(taskItemSchema).describe("tasks to spawn; one subagent per item"),
+});
+const ALL_TASK_SCHEMAS = [taskSchema, taskSchemaNoIsolation, taskSchemaBatch, taskSchemaBatchNoIsolation] as const;
+
+type DynamicTaskSchema = (typeof ALL_TASK_SCHEMAS)[number];
+export type TaskSchema = typeof taskSchema;
+/** Active task tool parameter schema for the current isolation / batch flags */
+export type TaskToolSchemaInstance = DynamicTaskSchema;
+
+export function getTaskSchema(options: { isolationEnabled: boolean; batchEnabled: boolean }): DynamicTaskSchema {
+	if (options.batchEnabled) {
+		return options.isolationEnabled ? taskSchemaBatch : taskSchemaBatchNoIsolation;
+	}
+	return options.isolationEnabled ? taskSchema : taskSchemaNoIsolation;
+}
+
+/**
+ * Runtime params union over both wire shapes. The model sees exactly one shape
+ * (`{ agent, context, tasks[] }` when `task.batch` is on, `{ agent, ...item }`
+ * otherwise); runtime stays permissive so internal callers and stale
+ * transcripts using the flat form keep working under either setting.
+ */
+export interface TaskParams {
+	/** Agent type; required. */
+	agent?: string;
+	/** Stable agent id (flat form); default = generated AdjectiveNoun. */
+	id?: string;
+	/** UI label (flat form), not seen by the subagent. */
+	description?: string;
+	/** The work (flat form). */
+	assignment?: string;
+	/** Batch form (`task.batch`): one subagent per item. */
+	tasks?: TaskItem[];
+	/** Batch form: shared background prepended to every assignment; required by the batch schema. */
+	context?: string;
+	/** Run in an isolated worktree (flat form; per-item in batch form). */
+	isolated?: boolean;
+}
+
+/** A code review finding reported by the reviewer agent */
+export interface ReviewFinding {
+	title: string;
+	body: string;
+	priority: number;
+	confidence: number;
+	file_path: string;
+	line_start: number;
+	line_end: number;
+}
+
+/** Review summary submitted by the reviewer agent */
+export interface ReviewSummary {
+	overall_correctness: "correct" | "incorrect";
+	explanation: string;
+	confidence: number;
+}
+
+/** Structured review data extracted from reviewer agent */
+export interface ReviewData {
+	findings: ReviewFinding[];
+	summary?: ReviewSummary;
+}
+
+/** Agent definition (bundled or discovered) */
+export interface AgentDefinition {
+	name: string;
+	description: string;
+	systemPrompt: string;
+	tools?: string[];
+	spawns?: string[] | "*";
+	model?: string[];
+	thinkingLevel?: ThinkingLevel;
+	output?: unknown;
+	blocking?: boolean;
+	autoloadSkills?: string[];
+	/** When `false`, the agent's `read` tool returns verbatim file content instead of structural summaries. */
+	readSummarize?: boolean;
+	source: AgentSource;
+	filePath?: string;
+}
+
+/** Progress tracking for a single agent */
+export interface AgentProgress {
+	index: number;
+	id: string;
+	agent: string;
+	agentSource: AgentSource;
+	status: "pending" | "running" | "completed" | "failed" | "aborted";
+	task: string;
+	assignment?: string;
+	description?: string;
+	lastIntent?: string;
+	currentTool?: string;
+	currentToolArgs?: string;
+	currentToolStartMs?: number;
+	recentTools: Array<{ tool: string; args: string; endMs: number }>;
+	recentOutput: string[];
+	toolCount: number;
+	/** Count of assistant requests (assistant message_end events) across the run. Drives the soft request budget guard. */
+	requests: number;
+	/** Cumulative input + output + cacheWrite tokens across all turns. Excludes cacheRead (re-reads cached context every turn, making cumulative sum misleading). */
+	tokens: number;
+	/**
+	 * Current per-turn context size: latest assistant message's `usage.totalTokens`.
+	 * This is the number to compare against `contextWindow` — what compaction
+	 * decides on, what the user typically reads as "how full is the context".
+	 * Distinct from `tokens`, which is a lifetime billing-volume counter.
+	 */
+	contextTokens?: number;
+	/** Model's context window in tokens, when known. Lets the UI render `<curr>/<window>` gauges. */
+	contextWindow?: number;
+	/** Cumulative billing cost in USD, accumulated incrementally from message_end events. */
+	cost: number;
+	durationMs: number;
+	modelOverride?: string | string[];
+	/** Resolved model display string in the form `<provider>/<id>`, optionally suffixed with `:<thinkingLevel>` when the level was set explicitly. Undefined when the model could not be resolved. */
+	resolvedModel?: string;
+	/** Data extracted by registered subprocess tool handlers (keyed by tool name) */
+	extractedToolData?: Record<string, unknown[]>;
+	/**
+	 * Auto-retry state when the subagent is sleeping between provider retries
+	 * (e.g. 429 rate-limit with retry-after). Cleared when the retry resolves
+	 * or fails. Surfacing this to the parent prevents the task tool from
+	 * looking indefinitely "in progress" when a child is actually blocked on
+	 * provider quota.
+	 */
+	retryState?: {
+		attempt: number;
+		maxAttempts: number;
+		delayMs: number;
+		errorMessage: string;
+		startedAtMs: number;
+	};
+	/**
+	 * Terminal retry failure surfaced once the subagent gave up retrying
+	 * (e.g. retry-after exceeded the cap, or all attempts exhausted). Carries
+	 * the final error so the parent UI can render "blocked: rate-limited"
+	 * instead of waiting for a status that never arrives.
+	 */
+	retryFailure?: {
+		attempt: number;
+		errorMessage: string;
+	};
+	/**
+	 * Snapshot of the most recent `task` tool call's in-flight `TaskToolDetails`,
+	 * captured from `tool_execution_update`. Lets the parent UI surface live
+	 * nested-subagent progress while this agent is still inside its own `task`
+	 * call. Cleared when the call ends — finalized data lives in
+	 * `extractedToolData.task` after that.
+	 */
+	inflightTaskDetails?: TaskToolDetails;
+}
+
+/** Result from a single agent execution */
+export interface SingleResult {
+	index: number;
+	id: string;
+	agent: string;
+	agentSource: AgentSource;
+	task: string;
+	assignment?: string;
+	description?: string;
+	lastIntent?: string;
+	exitCode: number;
+	output: string;
+	stderr: string;
+	truncated: boolean;
+	durationMs: number;
+	/** Cumulative input + output + cacheWrite tokens across all turns. Excludes cacheRead (re-reads cached context every turn, making cumulative sum misleading). */
+	tokens: number;
+	/** Count of assistant requests (assistant message_end events) across the run. */
+	requests: number;
+	/** Latest per-turn context size at task completion. See `AgentProgress.contextTokens`. */
+	contextTokens?: number;
+	/** Model's context window in tokens, when known. */
+	contextWindow?: number;
+	modelOverride?: string | string[];
+	/** Resolved model display string in the form `<provider>/<id>`, optionally suffixed with `:<thinkingLevel>` when the level was set explicitly. Omitted from tool-result JSON when undefined to keep wire payloads small. */
+	resolvedModel?: string;
+	error?: string;
+	aborted?: boolean;
+	abortReason?: string;
+	/** Aggregated usage from the subprocess, accumulated incrementally from message_end events. */
+	usage?: Usage;
+	/** Output path for the task result */
+	outputPath?: string;
+	/** Patch path for isolated worktree output */
+	patchPath?: string;
+	/** Branch name for isolated branch-mode output */
+	branchName?: string;
+	/** Nested repo patches to apply after parent merge */
+	nestedPatches?: NestedRepoPatch[];
+	/** Data extracted by registered subprocess tool handlers (keyed by tool name) */
+	extractedToolData?: Record<string, unknown[]>;
+	/**
+	 * Terminal retry failure, when the subagent exited because the auto-retry
+	 * loop gave up (retry-after exceeded the cap, or all attempts exhausted).
+	 * Lets the parent task tool surface a "blocked: rate-limited" outcome
+	 * instead of a generic failure.
+	 */
+	retryFailure?: {
+		attempt: number;
+		errorMessage: string;
+	};
+	/** Output metadata for agent:// URL integration */
+	outputMeta?: { lineCount: number; charCount: number };
+}
+
+/** Tool details for TUI rendering */
+export interface TaskToolDetails {
+	projectAgentsDir: string | null;
+	results: SingleResult[];
+	totalDurationMs: number;
+	/** Aggregated usage across all subagents. */
+	usage?: Usage;
+	outputPaths?: string[];
+	progress?: AgentProgress[];
+	async?: {
+		state: "running" | "completed" | "failed";
+		jobId: string;
+		type: "task";
+	};
+}