pi-subagents 0.69.0 → 0.70.0

package/src/runs/background/chain-root-attachment.ts

@@ -1,259 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { resultFilePath, resultPayloadPathForSessionRun } from "./result-files.ts";
-import type { AcceptanceLedger, ArtifactPaths, AsyncStatus, CostSummary, EffectsProjection, ExecutionProjection, Usage } from "../../shared/types.ts";
-import { readStatus } from "../../shared/utils.ts";
-
-export interface ImportedAsyncRoot {
-	runId: string;
-	asyncDir: string;
-	resultPath: string;
-	index: number;
-}
-
-export interface ImportedAsyncRootResult {
-	agent: string;
-	importedPublication?: { sessionId?: string; toolCallId?: string };
-	/** Human-readable display name for the child session, when derived at launch. */
-	sessionName?: string;
-	output: string;
-	success: boolean;
-	exitCode: number;
-	error?: string;
-	sessionFile?: string;
-	intercomTarget?: string;
-	model?: string;
-	requestedModel?: string;
-	contextOverflow?: boolean;
-	totalCost?: CostSummary;
-	usage?: Usage;
-	structuredOutput?: unknown;
-	structuredOutputPath?: string;
-	structuredOutputSchemaPath?: string;
-	acceptance?: AcceptanceLedger;
-	artifactPaths?: ArtifactPaths;
-	savedOutputPath?: string;
-	outputSaveError?: string;
-	transcriptPath?: string;
-	transcriptError?: string;
-	timedOut?: boolean;
-	stopped?: boolean;
-	execution?: ExecutionProjection;
-	effects?: EffectsProjection;
-}
-
-interface AsyncResultFile {
-	sessionId?: string;
-	toolCallId?: string;
-	state?: string;
-	success?: boolean;
-	summary?: string;
-	error?: string;
-	timedOut?: boolean;
-	stopped?: boolean;
-	results?: Array<{
-		agent?: string;
-		sessionName?: string;
-		output?: string;
-		error?: string;
-		success?: boolean;
-		timedOut?: boolean;
-		stopped?: boolean;
-		execution?: ExecutionProjection;
-		effects?: EffectsProjection;
-		sessionFile?: string;
-		intercomTarget?: string;
-		model?: string;
-		requestedModel?: string;
-		contextOverflow?: boolean;
-		totalCost?: CostSummary;
-		usage?: Usage;
-		structuredOutput?: unknown;
-		structuredOutputPath?: string;
-		structuredOutputSchemaPath?: string;
-		acceptance?: AcceptanceLedger;
-		artifactPaths?: ArtifactPaths;
-		savedOutputPath?: string;
-		outputSaveError?: string;
-		transcriptPath?: string;
-		transcriptError?: string;
-	}>;
-}
-
-const TERMINAL_STATES = new Set(["complete", "failed", "partial", "paused", "stopped"]);
-const TERMINAL_STEP_STATUSES = new Set(["complete", "completed", "failed", "partial", "paused", "stopped"]);
-
-function readResultFile(resultPath: string): AsyncResultFile | undefined {
-	try {
-		return JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultFile;
-	} catch (error) {
-		if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
-			return undefined;
-		}
-		throw error;
-	}
-}
-
-function readImportedResultFile(root: ImportedAsyncRoot, status: AsyncStatus | null): AsyncResultFile | undefined {
-	const direct = readResultFile(root.resultPath);
-	if (direct || !status?.sessionId) return direct;
-	const indexedPath = resultPayloadPathForSessionRun(path.dirname(root.resultPath), status.sessionId, root.runId);
-	return indexedPath ? readResultFile(indexedPath) : undefined;
-}
-
-function selectedStatusStep(status: AsyncStatus | null, index: number): NonNullable<AsyncStatus["steps"]>[number] | undefined {
-	return status?.steps?.[index];
-}
-
-function isTerminalStatus(status: AsyncStatus | null, index: number): boolean {
-	if (!status) return false;
-	// A workflow-owned single runner publishes its result after completing its
-	// step. Keep that window open while root process proof is absent or pending;
-	// explicit terminal/unavailable proof retains the existing step fallback.
-	if (status.mode === "single" && status.parentWorkflowRunId
-		&& (!status.processTerminal || status.processTerminal.state === "pending")) return TERMINAL_STATES.has(status.state);
-	const step = selectedStatusStep(status, index);
-	if (step && TERMINAL_STEP_STATUSES.has(step.status)) return true;
-	return TERMINAL_STATES.has(status.state);
-}
-
-function resultState(result: AsyncResultFile | undefined, child: NonNullable<AsyncResultFile["results"]>[number] | undefined): "complete" | "failed" | "partial" | "paused" | "stopped" | undefined {
-	if (!result) return undefined;
-	if (child?.stopped === true) return "stopped";
-	if (child?.success === true) return "complete";
-	if (child?.success === false) return result.state === "stopped" ? "stopped" : result.state === "paused" ? "paused" : result.state === "partial" ? "partial" : "failed";
-	if (result.state === "complete" || result.state === "failed" || result.state === "partial" || result.state === "paused" || result.state === "stopped") return result.state;
-	if (result.success === true) return "complete";
-	if (result.success === false) return "failed";
-	return undefined;
-}
-
-function outputFromTerminalStatus(root: ImportedAsyncRoot, status: AsyncStatus, step: NonNullable<AsyncStatus["steps"]>[number] | undefined): ImportedAsyncRootResult {
-	const agent = step?.agent ?? status.steps?.[root.index]?.agent ?? "subagent";
-	const timedOut = step?.timedOut === true || status.timedOut === true;
-	const stopped = step?.stopped === true || status.stopped === true || status.state === "stopped";
-	const message = step?.error ?? status.error ?? (stopped ? "Subagent stopped by user." : `Attached async root ${root.runId} ended without a result file at ${root.resultPath}.`);
-	const partialStatus = status.state === "partial" || step?.status === "partial";
-	const execution = step?.execution ?? (partialStatus
-		? { status: "partial" as const, success: false, exitCode: 1, error: message }
-		: undefined);
-	return {
-		agent,
-		output: message,
-		success: false,
-		exitCode: 1,
-		error: message,
-		...(timedOut ? { timedOut: true } : {}),
-		...(stopped ? { stopped: true } : {}),
-		...(step?.sessionName ? { sessionName: step.sessionName } : {}),
-		...(step?.sessionFile ?? status.sessionFile ? { sessionFile: step?.sessionFile ?? status.sessionFile } : {}),
-		...(step?.model ? { model: step.model } : {}),
-		...(step?.requestedModel ? { requestedModel: step.requestedModel } : {}),
-		...(step?.contextOverflow ? { contextOverflow: true } : {}),
-		...(step?.totalCost ? { totalCost: step.totalCost } : {}),
-		...(step?.structuredOutput !== undefined ? { structuredOutput: step.structuredOutput } : {}),
-		...(step?.structuredOutputPath ? { structuredOutputPath: step.structuredOutputPath } : {}),
-		...(step?.structuredOutputSchemaPath ? { structuredOutputSchemaPath: step.structuredOutputSchemaPath } : {}),
-		...(step?.acceptance ? { acceptance: step.acceptance } : {}),
-		...(execution ? { execution } : {}),
-		...(step?.effects ? { effects: step.effects } : {}),
-		...(step?.transcriptPath ? { transcriptPath: step.transcriptPath } : {}),
-	};
-}
-
-function outputFromTimeout(root: ImportedAsyncRoot, status: AsyncStatus | null, message: string): ImportedAsyncRootResult {
-	const step = selectedStatusStep(status, root.index);
-	return {
-		agent: step?.agent ?? status?.steps?.[root.index]?.agent ?? "subagent",
-		output: message,
-		success: false,
-		exitCode: 1,
-		error: message,
-		timedOut: true,
-		...(step?.sessionName ? { sessionName: step.sessionName } : {}),
-		...(step?.sessionFile ?? status?.sessionFile ? { sessionFile: step?.sessionFile ?? status?.sessionFile } : {}),
-		...(step?.model ? { model: step.model } : {}),
-		...(step?.requestedModel ? { requestedModel: step.requestedModel } : {}),
-		...(step?.contextOverflow ? { contextOverflow: true } : {}),
-		...(step?.totalCost ? { totalCost: step.totalCost } : {}),
-		...(step?.transcriptPath ? { transcriptPath: step.transcriptPath } : {}),
-	};
-}
-
-function buildImportedResult(root: ImportedAsyncRoot, status: AsyncStatus | null, result: AsyncResultFile): ImportedAsyncRootResult {
-	const child = result.results?.[root.index];
-	const step = selectedStatusStep(status, root.index);
-	const state = resultState(result, child);
-	const agent = child?.agent ?? step?.agent ?? status?.steps?.[root.index]?.agent ?? "subagent";
-	const output = child?.output ?? result.summary ?? "";
-	const timedOut = child?.timedOut === true || step?.timedOut === true || result.timedOut === true || status?.timedOut === true;
-	const stopped = child?.stopped === true || step?.stopped === true || result.stopped === true || status?.stopped === true || state === "stopped";
-	const success = state === "complete" && !timedOut && !stopped;
-	const error = child?.error ?? (success ? undefined : stopped ? "Subagent stopped by user." : result.error ?? result.summary ?? status?.error ?? `Attached async root ${root.runId} did not complete successfully.`);
-	const execution = state ? { status: state === "complete" ? "completed" as const : state, success, exitCode: success ? 0 : 1, ...(error ? { error } : {}) } : undefined;
-	const usage = child?.usage;
-	return {
-		agent,
-		importedPublication: {
-			...(typeof result.sessionId === "string" ? { sessionId: result.sessionId } : {}),
-			...(typeof result.toolCallId === "string" ? { toolCallId: result.toolCallId } : {}),
-		},
-		output: success ? output : (output || error || ""),
-		success,
-		exitCode: success ? 0 : 1,
-		...(error ? { error } : {}),
-		...(timedOut ? { timedOut: true } : {}),
-		...(stopped ? { stopped: true } : {}),
-		...(child?.sessionName ?? step?.sessionName ? { sessionName: child?.sessionName ?? step?.sessionName } : {}),
-		...(child?.sessionFile ?? step?.sessionFile ?? status?.sessionFile ? { sessionFile: child?.sessionFile ?? step?.sessionFile ?? status?.sessionFile } : {}),
-		...(child?.intercomTarget ? { intercomTarget: child.intercomTarget } : {}),
-		...(child?.model ?? step?.model ? { model: child?.model ?? step?.model } : {}),
-		...(child?.requestedModel ?? step?.requestedModel ? { requestedModel: child?.requestedModel ?? step?.requestedModel } : {}),
-		...(child?.contextOverflow || step?.contextOverflow ? { contextOverflow: true } : {}),
-		...(child?.totalCost ?? step?.totalCost ? { totalCost: child?.totalCost ?? step?.totalCost } : {}),
-		...(usage ? { usage } : {}),
-		...(child?.structuredOutput !== undefined ? { structuredOutput: child.structuredOutput } : step?.structuredOutput !== undefined ? { structuredOutput: step.structuredOutput } : {}),
-		...(child?.structuredOutputPath ?? step?.structuredOutputPath ? { structuredOutputPath: child?.structuredOutputPath ?? step?.structuredOutputPath } : {}),
-		...(child?.structuredOutputSchemaPath ?? step?.structuredOutputSchemaPath ? { structuredOutputSchemaPath: child?.structuredOutputSchemaPath ?? step?.structuredOutputSchemaPath } : {}),
-		...(child?.acceptance ?? step?.acceptance ? { acceptance: child?.acceptance ?? step?.acceptance } : {}),
-		...(child?.artifactPaths ? { artifactPaths: child.artifactPaths } : {}),
-		...(child?.savedOutputPath ? { savedOutputPath: child.savedOutputPath } : {}),
-		...(child?.outputSaveError ? { outputSaveError: child.outputSaveError } : {}),
-		...(child?.transcriptPath ?? step?.transcriptPath ? { transcriptPath: child?.transcriptPath ?? step?.transcriptPath } : {}),
-		...(child?.transcriptError ? { transcriptError: child.transcriptError } : {}),
-		...(execution ? { execution } : {}),
-		...(child?.effects ?? step?.effects ? { effects: child?.effects ?? step?.effects } : {}),
-	};
-}
-
-export async function waitForImportedAsyncRoot(
-	root: ImportedAsyncRoot,
-	options: { pollIntervalMs?: number; terminalResultGraceMs?: number; now?: () => number; shouldAbort?: () => boolean; timeoutMessage?: string } = {},
-): Promise<ImportedAsyncRootResult> {
-	const pollIntervalMs = options.pollIntervalMs ?? 500;
-	const terminalResultGraceMs = options.terminalResultGraceMs ?? 1_000;
-	const now = options.now ?? Date.now;
-	let terminalSince: number | undefined;
-	for (;;) {
-		const status = readStatus(root.asyncDir);
-		if (options.shouldAbort?.()) return outputFromTimeout(root, status, options.timeoutMessage ?? "Subagent timed out.");
-		const result = readImportedResultFile(root, status);
-		if (result) return buildImportedResult(root, status, result);
-		if (isTerminalStatus(status, root.index)) {
-			terminalSince ??= now();
-			if (now() - terminalSince >= terminalResultGraceMs) {
-				return outputFromTerminalStatus(root, status!, selectedStatusStep(status, root.index));
-			}
-		} else {
-			terminalSince = undefined;
-		}
-		if (!status && !fs.existsSync(root.asyncDir)) {
-			throw new Error(`Attached async root '${root.runId}' directory does not exist: ${root.asyncDir}`);
-		}
-		await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
-	}
-}
-
-export function resolveAsyncRootResultPath(resultsDir: string, runId: string): string {
-	return resultFilePath(resultsDir, runId);
-}

package/src/runs/background/completion-batcher.ts

@@ -1,168 +0,0 @@
-/**
- * Smart completion batching with straggler handling.
- *
- * Holds successful async-completion notifications briefly so sibling jobs that
- * finish within a short window arrive as a single grouped message. A hard
- * max-wait cap (measured from the first item in a group) prevents holding
- * notifications indefinitely. After a group is emitted, late-finishing
- * siblings that arrive within the straggler window join a shorter "straggler"
- * group with reduced debounce and max-wait timers.
- *
- * Failure and attention signals bypass this batcher entirely. Callers must
- * flush() held items and emit those signals immediately so failures and
- * needs-attention notices are never delayed.
- */
-
-import type { CompletionBatchConfig } from "../../shared/types.ts";
-
-export type { CompletionBatchConfig };
-
-export interface ResolvedCompletionBatchConfig {
-	enabled: boolean;
-	debounceMs: number;
-	maxWaitMs: number;
-	stragglerDebounceMs: number;
-	stragglerMaxWaitMs: number;
-	stragglerWindowMs: number;
-}
-
-export const DEFAULT_COMPLETION_BATCH_CONFIG: ResolvedCompletionBatchConfig = {
-	enabled: true,
-	debounceMs: 150,
-	maxWaitMs: 1000,
-	stragglerDebounceMs: 75,
-	stragglerMaxWaitMs: 400,
-	stragglerWindowMs: 2000,
-};
-
-function parsePositiveInt(value: unknown): number | undefined {
-	if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 1) return undefined;
-	return value;
-}
-
-export function resolveCompletionBatchConfig(
-	globalConfig?: CompletionBatchConfig,
-	override?: CompletionBatchConfig,
-): ResolvedCompletionBatchConfig {
-	const enabled = typeof override?.enabled === "boolean"
-		? override.enabled
-		: typeof globalConfig?.enabled === "boolean"
-			? globalConfig.enabled
-			: DEFAULT_COMPLETION_BATCH_CONFIG.enabled;
-	return {
-		enabled,
-		debounceMs: parsePositiveInt(override?.debounceMs) ?? parsePositiveInt(globalConfig?.debounceMs) ?? DEFAULT_COMPLETION_BATCH_CONFIG.debounceMs,
-		maxWaitMs: parsePositiveInt(override?.maxWaitMs) ?? parsePositiveInt(globalConfig?.maxWaitMs) ?? DEFAULT_COMPLETION_BATCH_CONFIG.maxWaitMs,
-		stragglerDebounceMs: parsePositiveInt(override?.stragglerDebounceMs) ?? parsePositiveInt(globalConfig?.stragglerDebounceMs) ?? DEFAULT_COMPLETION_BATCH_CONFIG.stragglerDebounceMs,
-		stragglerMaxWaitMs: parsePositiveInt(override?.stragglerMaxWaitMs) ?? parsePositiveInt(globalConfig?.stragglerMaxWaitMs) ?? DEFAULT_COMPLETION_BATCH_CONFIG.stragglerMaxWaitMs,
-		stragglerWindowMs: parsePositiveInt(override?.stragglerWindowMs) ?? parsePositiveInt(globalConfig?.stragglerWindowMs) ?? DEFAULT_COMPLETION_BATCH_CONFIG.stragglerWindowMs,
-	};
-}
-
-type TimerHandle = unknown;
-
-interface TimerApi {
-	setTimeout(handler: () => void, delayMs: number): TimerHandle;
-	clearTimeout(handle: TimerHandle): void;
-}
-
-const defaultTimers: TimerApi = {
-	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
-	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
-};
-
-function unrefHandle(handle: TimerHandle): void {
-	if (handle && typeof handle === "object" && "unref" in handle && typeof (handle as { unref: unknown }).unref === "function") {
-		(handle as { unref: () => void }).unref();
-	}
-}
-
-export interface CompletionBatcherOptions<T> {
-	config: ResolvedCompletionBatchConfig;
-	emit: (items: T[]) => void;
-	timers?: TimerApi;
-	now?: () => number;
-}
-
-export interface CompletionBatcher<T> {
-	/** Add a batchable item. Emits immediately when batching is disabled. */
-	push(item: T): void;
-	/** Emit any held items immediately as a single group. */
-	flush(): void;
-	/** Clear timers and return items that were never emitted. */
-	dispose(): T[];
-}
-
-/**
- * Create a completion batcher. The batcher is single-use per registration: it
- * holds at most one open group. `flush` forces emission; `dispose` tears down
- * timers for reload/shutdown without emitting.
- */
-export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>): CompletionBatcher<T> {
-	const timers = options.timers ?? defaultTimers;
-	const now = options.now ?? Date.now;
-	const config = options.config;
-
-	if (!config.enabled) {
-		return {
-			push(item: T) {
-				options.emit([item]);
-			},
-			flush() {},
-			dispose() { return []; },
-		};
-	}
-
-	let pending: T[] = [];
-	let debounceTimer: TimerHandle | null = null;
-	let maxWaitTimer: TimerHandle | null = null;
-	let straggler = false;
-	let lastEmitAt: number | null = null;
-
-	const clearTimers = () => {
-		if (debounceTimer) {
-			timers.clearTimeout(debounceTimer);
-			debounceTimer = null;
-		}
-		if (maxWaitTimer) {
-			timers.clearTimeout(maxWaitTimer);
-			maxWaitTimer = null;
-		}
-	};
-
-	const emitGroup = () => {
-		clearTimers();
-		if (pending.length === 0) return;
-		const items = pending;
-		pending = [];
-		lastEmitAt = now();
-		options.emit(items);
-	};
-
-	return {
-		push(item: T) {
-			if (pending.length === 0) {
-				straggler = lastEmitAt !== null && (now() - lastEmitAt) < config.stragglerWindowMs;
-			}
-			pending.push(item);
-
-			if (debounceTimer) timers.clearTimeout(debounceTimer);
-			const debounceDelay = straggler ? config.stragglerDebounceMs : config.debounceMs;
-			debounceTimer = timers.setTimeout(emitGroup, debounceDelay);
-			unrefHandle(debounceTimer);
-
-			if (!maxWaitTimer) {
-				const maxWaitDelay = straggler ? config.stragglerMaxWaitMs : config.maxWaitMs;
-				maxWaitTimer = timers.setTimeout(emitGroup, maxWaitDelay);
-				unrefHandle(maxWaitTimer);
-			}
-		},
-		flush: emitGroup,
-		dispose() {
-			clearTimers();
-			const abandoned = pending;
-			pending = [];
-			return abandoned;
-		}
-	};
-}

package/src/runs/background/completion-dedupe.ts

@@ -1,58 +0,0 @@
-interface CompletionDataLike {
-	id?: unknown;
-	agent?: unknown;
-	timestamp?: unknown;
-	sessionId?: unknown;
-	state?: unknown;
-	taskIndex?: unknown;
-	totalTasks?: unknown;
-	success?: unknown;
-}
-
-function asNonEmptyString(value: unknown): string | undefined {
-	if (typeof value !== "string") return undefined;
-	const trimmed = value.trim();
-	return trimmed.length > 0 ? trimmed : undefined;
-}
-
-function asFiniteNumber(value: unknown): number | undefined {
-	if (typeof value !== "number") return undefined;
-	return Number.isFinite(value) ? value : undefined;
-}
-
-export function buildCompletionKey(data: CompletionDataLike, fallback: string): string {
-	const sessionId = asNonEmptyString(data.sessionId) ?? "no-session";
-	const id = asNonEmptyString(data.id);
-	const state = asNonEmptyString(data.state);
-	if (id) return state
-		? `session:${sessionId}:id:${id}:state:${state}`
-		: `session:${sessionId}:id:${id}`;
-	const agent = asNonEmptyString(data.agent) ?? "unknown";
-	const timestamp = asFiniteNumber(data.timestamp);
-	const taskIndex = asFiniteNumber(data.taskIndex);
-	const totalTasks = asFiniteNumber(data.totalTasks);
-	const success = typeof data.success === "boolean" ? (data.success ? "1" : "0") : "?";
-	return [
-		"meta",
-		sessionId,
-		agent,
-		timestamp !== undefined ? String(timestamp) : "no-ts",
-		taskIndex !== undefined ? String(taskIndex) : "-",
-		totalTasks !== undefined ? String(totalTasks) : "-",
-		success,
-		fallback,
-	].join(":");
-}
-
-function pruneSeenMap(seen: Map<string, number>, now: number, ttlMs: number): void {
-	for (const [key, ts] of seen.entries()) {
-		if (now - ts > ttlMs) seen.delete(key);
-	}
-}
-
-export function markSeenWithTtl(seen: Map<string, number>, key: string, now: number, ttlMs: number): boolean {
-	pruneSeenMap(seen, now, ttlMs);
-	if (seen.has(key)) return true;
-	seen.set(key, now);
-	return false;
-}