pi-ui-extend 0.1.1

package/external/pi-tools-suite/src/async-subagents/core/types.ts

@@ -0,0 +1,150 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+
+export interface AgentTask {
+	id: string;
+	task: string;
+	scope?: string;
+	/** Logical sub-agent type/profile, resolved from config before spawning. */
+	subagentType?: string;
+	/** Explicit model override for this task. */
+	model?: string;
+	/** Explicit thinking level for this task. */
+	thinking?: string;
+	/** Extra prompt text appended after the generated or overridden prompt. */
+	promptAppend?: string;
+	/** Full prompt replacement for this task. Supports prompt template variables. */
+	promptOverride?: string;
+	/** Optional visual attention instructions for vision-capable sub-agents. */
+	focus?: string;
+	/** Local image files to attach to the sub-agent RPC prompt. */
+	imagePaths?: string[];
+	tools?: string[];
+	extraArgs?: string[];
+	/** Per-agent wall-clock timeout in milliseconds. */
+	timeoutMs?: number;
+	parentObjective?: string;
+}
+
+export interface AgentState {
+	id: string;
+	status: "planned" | "running" | "retrying" | "done" | "failed" | "stopped";
+	exitCode?: number;
+	startedAt?: string;
+	finishedAt?: string;
+	/** ISO-8601 timestamp for the next retry attempt while status is retrying. */
+	nextRetryAt?: string;
+	pid?: number;
+	resultLines?: number;
+	stderrLines?: number;
+	eventLines?: number;
+	/** How many times this agent has been retried (0 = first attempt). */
+	retryCount?: number;
+}
+
+/** Retry configuration for failed agents. */
+export interface RetryConfig {
+	/** Maximum number of retry attempts (default 0 = no retries). */
+	maxRetries: number;
+	/** Base delay in ms before first retry, doubled on each subsequent attempt (default 2000). */
+	backoffMs: number;
+	/** Exit codes eligible for retry. Default: all non-zero. Empty array disables retry. */
+	retryableExitCodes?: number[];
+}
+
+export interface RunState {
+	runDir: string;
+	agents: AgentState[];
+}
+
+export type StructuredSeverity = "low" | "medium" | "high" | "critical";
+
+export interface StructuredFinding {
+	text: string;
+	severity?: StructuredSeverity;
+	file?: string;
+	line?: number;
+}
+
+export interface StructuredFileReference {
+	path: string;
+	line?: number;
+}
+
+export interface StructuredRisk {
+	text: string;
+	severity?: StructuredSeverity;
+}
+
+/** Machine-readable structured result written alongside result.md. */
+export interface StructuredResult {
+	/** Structured result schema version. */
+	schemaVersion?: 2;
+	/** Agent identifier. */
+	agentId: string;
+	/** Final status. */
+	status: AgentState["status"];
+	/** Process exit code. */
+	exitCode?: number;
+	/** ISO-8601 start timestamp. */
+	startedAt?: string;
+	/** ISO-8601 finish timestamp. */
+	finishedAt?: string;
+	/** Wall-clock duration in seconds. */
+	durationSeconds?: number;
+	/** Retry count (0 = first attempt, omitted when never retried). */
+	retryCount?: number;
+	/** Sub-agent type that was used. */
+	subagentType?: string;
+	/** Model used by the sub-agent. */
+	model?: string;
+	/** The full result text (may be truncated by maxResultBytes). */
+	resultText?: string;
+	/** True when resultText was truncated. */
+	resultTruncated?: boolean;
+	/** Original byte length before truncation. */
+	resultOriginalBytes?: number;
+	/** Compact best-effort summary extracted from resultText for parent-agent chaining. */
+	summary?: string;
+	/** Best-effort findings extracted from bullet/checklist style result text. */
+	findings?: StructuredFinding[];
+	/** File references mentioned in result text. */
+	files?: StructuredFileReference[];
+	/** Best-effort risk statements extracted from result text. */
+	risks?: StructuredRisk[];
+	/** Best-effort recommended next actions extracted from result text. */
+	nextActions?: string[];
+	/** Optional confidence if the agent explicitly reports it. */
+	confidence?: "low" | "medium" | "high";
+	/** First line(s) of stderr, if any. */
+	stderrPreview?: string;
+}
+
+export interface AgentResult {
+	result?: string;
+	stderr?: string;
+	exitCode?: number;
+	state: AgentState;
+	/** Structured JSON result, if available. */
+	structured?: StructuredResult;
+}
+
+export interface SpawnedAgent {
+	pid: number;
+	agentDir: string;
+	process: ChildProcessWithoutNullStreams;
+}
+
+export interface RpcEventRecord {
+	type: string;
+	[key: string]: unknown;
+}
+
+export type RpcEventHandler = (event: RpcEventRecord) => void;
+
+export type AgentCompletionHandler = (completion: {
+	runDir: string;
+	agentId: string;
+	agentDir: string;
+	exitCode: number;
+	state: AgentState;
+}) => void;

package/external/pi-tools-suite/src/async-subagents/core/ultrawork-auto.ts

@@ -0,0 +1,184 @@
+import { complete } from "@earendil-works/pi-ai";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { currentModelRef, resolveSubagentRoutingConfig, type SubagentConfig } from "./config.js";
+
+export type UltraworkAutoDecision = "ultrawork" | "hint" | "none";
+
+export interface UltraworkAutoContext {
+	model?: unknown;
+	modelRegistry?: {
+		find(provider: string, modelId: string): Model<Api> | undefined;
+		getApiKeyAndHeaders(model: Model<Api>): Promise<
+			| { ok?: true; apiKey?: string; headers?: Record<string, string> }
+			| { ok: false; error: string }
+		>;
+	};
+	hasUI?: boolean;
+	ui?: { notify?(message: string, level?: string): void };
+}
+
+export const ULTRAWORK_AUTO_HINT = [
+	"Auto-ultrawork hint:",
+	"If this task turns out to be broad, multi-file, high-risk, or benefits from independent parallel tracks, adopt ultrawork mode: spawn focused subagents and keep the parent context lean. Otherwise solve it directly.",
+].join(" ");
+
+const TRUE_ENV_PATTERN = /^(1|true|yes|on|auto)$/i;
+
+const CLASSIFIER_SYSTEM_PROMPT = [
+	"You classify the FIRST user message for Pi ultrawork mode.",
+	"This is a weak-model routing task: be conservative and follow the labels exactly.",
+	"Return exactly one lowercase word: ultrawork, hint, or none.",
+	"ultrawork = clearly broad/complex/parallel work that should spawn subagents immediately.",
+	"hint = not enough detail, but it may become broad/complex; tell the parent agent to switch only if complexity appears.",
+	"none = simple chat, one known file, exact lookup, trivial edit, or narrow question.",
+	"When uncertain between ultrawork and hint, choose hint. When uncertain between hint and none, choose none.",
+].join("\n");
+
+export function isUltraworkAutoEnvEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	return [env.ULTRAWORK_AUTO, env.PI_ULTRAWORK_AUTO, env.ASYNC_SUBAGENTS_ULTRAWORK_AUTO, env.PI_SUBAGENTS_ULTRAWORK_AUTO]
+		.some((value) => typeof value === "string" && TRUE_ENV_PATTERN.test(value.trim()));
+}
+
+export function isGptLikeModel(modelRef: string | undefined): boolean {
+	if (!modelRef) return false;
+	const lower = modelRef.toLowerCase();
+	return lower.includes("openai-codex/") || /\bgpt(?:[-_.\w]*)?\b/i.test(modelRef);
+}
+
+export function appendUltraworkAutoHint(text: string): string {
+	return `${text.trimEnd()}\n\n${ULTRAWORK_AUTO_HINT}`;
+}
+
+export async function decideUltraworkAuto(
+	userText: string,
+	config: SubagentConfig,
+	ctx: UltraworkAutoContext,
+	signal?: AbortSignal,
+): Promise<UltraworkAutoDecision> {
+	const routing = resolveSubagentRoutingConfig(config);
+	if (!routing.enabled) return "none";
+	if (signal?.aborted) throw new Error("Aborted");
+
+	try {
+		const resolved = await resolveClassifierModel(ctx, routing.model);
+		if (!resolved) return "none";
+
+		const response = await complete(
+			resolved.model,
+			{
+				systemPrompt: CLASSIFIER_SYSTEM_PROMPT,
+				messages: [
+					{
+						role: "user" as const,
+						content: [{ type: "text" as const, text: buildClassifierPrompt(userText) }],
+						timestamp: Date.now(),
+					},
+				],
+			},
+			{
+				apiKey: resolved.apiKey,
+				headers: resolved.headers,
+				cacheRetention: "none",
+				maxRetries: routing.maxRetries,
+				maxTokens: Math.min(routing.maxTokens, 32),
+				signal,
+				temperature: 0,
+				timeoutMs: routing.timeoutMs,
+			},
+		);
+
+		return parseUltraworkAutoDecision(responseText(response));
+	} catch (error) {
+		if (signal?.aborted || isAbortError(error)) throw error;
+		return "none";
+	}
+}
+
+export function parseUltraworkAutoDecision(raw: string): UltraworkAutoDecision {
+	const normalized = raw.trim().toLowerCase()
+		.replace(/^```(?:json|text)?\s*/iu, "")
+		.replace(/```$/u, "")
+		.trim();
+
+	if (normalized === "ultrawork" || normalized === "hint" || normalized === "none") return normalized;
+
+	try {
+		const parsed = JSON.parse(normalized) as unknown;
+		const value = isRecord(parsed) ? parsed.decision ?? parsed.mode ?? parsed.result : parsed;
+		if (typeof value === "string") return parseUltraworkAutoDecision(value);
+	} catch {
+		// Fall through to weak-model text extraction.
+	}
+
+	const matches = normalized.match(/\b(ultrawork|hint|none)\b/gi) ?? [];
+	const unique = [...new Set(matches.map((match: string) => match.toLowerCase()))];
+	return unique.length === 1 && isUltraworkDecision(unique[0]) ? unique[0] : "none";
+}
+
+function buildClassifierPrompt(userText: string): string {
+	return [
+		"Choose one label for this first user message.",
+		"Use ultrawork for: explicit parallel/subagents/delegate; broad repo investigation; architecture/root-cause/debugging across modules; code review/audit/security/perf/release/test strategy; multi-file implementation/refactor.",
+		"Use hint for: vague but potentially complex requests like 'fix this bug', 'implement feature', 'improve the project', 'investigate issue' with no scope yet.",
+		"Use none for: simple question, exact string/file lookup, known one-file edit, typo, formatting, command request, or casual chat.",
+		"First user message:",
+		`<<<${truncate(userText, 4000)}>>>`,
+		"Answer with exactly one word: ultrawork, hint, or none.",
+	].join("\n");
+}
+
+async function resolveClassifierModel(ctx: UltraworkAutoContext, modelRef: string): Promise<{
+	model: Model<Api>;
+	apiKey?: string;
+	headers?: Record<string, string>;
+} | undefined> {
+	const configured = await resolveModelRef(ctx, modelRef);
+	if (configured) return configured;
+	const parentModel = currentModelRef(ctx.model);
+	return parentModel && parentModel !== modelRef ? resolveModelRef(ctx, parentModel) : undefined;
+}
+
+async function resolveModelRef(ctx: UltraworkAutoContext, modelRef: string): Promise<{
+	model: Model<Api>;
+	apiKey?: string;
+	headers?: Record<string, string>;
+} | undefined> {
+	const parsed = parseModelRef(modelRef);
+	if (!parsed || !ctx.modelRegistry) return undefined;
+	const model = ctx.modelRegistry.find(parsed.provider, parsed.modelId);
+	if (!model) return undefined;
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (auth.ok === false) return undefined;
+	return { model, apiKey: auth.apiKey, headers: auth.headers };
+}
+
+function parseModelRef(modelRef: string): { provider: string; modelId: string } | undefined {
+	const trimmed = modelRef.trim();
+	const slash = trimmed.indexOf("/");
+	if (slash <= 0 || slash === trimmed.length - 1) return undefined;
+	return { provider: trimmed.slice(0, slash), modelId: trimmed.slice(slash + 1) };
+}
+
+function responseText(response: { content: Array<{ type: string; text?: string }> }): string {
+	return response.content
+		.filter((block): block is { type: "text"; text: string } => block.type === "text" && typeof block.text === "string")
+		.map((block) => block.text)
+		.join("\n");
+}
+
+function truncate(value: string, maxChars: number): string {
+	const trimmed = value.trim();
+	return trimmed.length <= maxChars ? trimmed : `${trimmed.slice(0, maxChars).trimEnd()}…`;
+}
+
+function isUltraworkDecision(value: string): value is UltraworkAutoDecision {
+	return value === "ultrawork" || value === "hint" || value === "none";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isAbortError(error: unknown): boolean {
+	return error instanceof Error && /abort/i.test(error.name || error.message);
+}

package/external/pi-tools-suite/src/async-subagents/core/utils.ts

@@ -0,0 +1,11 @@
+export function isoNow(): string {
+	return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+export function serializeJsonLine(value: unknown): string {
+	return `${JSON.stringify(value)}\n`;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}

package/external/pi-tools-suite/src/async-subagents/format.ts

@@ -0,0 +1,41 @@
+import type { AgentState } from "./lib.js";
+
+export function formatAgentStatus(status: string): string {
+	const icons: Record<string, string> = {
+		planned: "[planned]",
+		running: "[running]",
+		retrying: "[retrying]",
+		done: "[done]",
+		failed: "[failed]",
+		stopped: "[stopped]",
+	};
+	return icons[status] || `[${status}]`;
+}
+
+export function truncate(text: string, maxLen: number): string {
+	if (text.length <= maxLen) return text;
+	return text.slice(0, maxLen - 3) + "...";
+}
+
+export function plural(count: number, one: string, many = `${one}s`): string {
+	return `${count} ${count === 1 ? one : many}`;
+}
+
+export function statusGlyph(status: AgentState["status"]): string {
+	if (status === "done") return "✓";
+	if (status === "failed") return "✕";
+	if (status === "stopped") return "■";
+	if (status === "retrying") return "↻";
+	if (status === "running") return "◐";
+	return "○";
+}
+
+export function statusLabel(status: AgentState["status"]): string {
+	return status === "running" ? "in progress" : status;
+}
+
+export function modelName(model?: string): string {
+	if (!model) return "";
+	const slash = model.lastIndexOf("/");
+	return slash >= 0 ? model.slice(slash + 1) : model;
+}