pi-agent-squad 0.8.4 → 0.9.0

package/task-state.ts

@@ -0,0 +1,286 @@
+export const TASK_STATE_ENTRY = "agent-squad-task-state";
+export const TASK_STATE_VERSION = 1 as const;
+export const TASK_RESULT_DELIVERY_PREFIX = "agent-squad-result:";
+
+export const TASK_STATE_LIMITS = {
+	runId: 128,
+	address: 256,
+	agent: 128,
+	task: 64 * 1024,
+	cwd: 4096,
+	ownerRuntimeId: 128,
+	childSessionFile: 4096,
+	resultSummary: 32 * 1024,
+	error: 8 * 1024,
+	retryOf: 128,
+	deliveryId: 256,
+} as const;
+
+export type PersistedTaskMode = "sync" | "async" | "message";
+export type PersistedTaskStatus =
+	| "starting"
+	| "running"
+	| "completed"
+	| "failed"
+	| "cancelled"
+	| "interrupted";
+
+export interface PersistedTaskState {
+	version: 1;
+	runId: string;
+	address: string;
+	agent: string;
+	task: string;
+	cwd: string;
+	readOnly: boolean;
+	mode: PersistedTaskMode;
+	status: PersistedTaskStatus;
+	startedAt: number;
+	updatedAt: number;
+	endedAt?: number;
+	timeoutAt?: number;
+	childSessionFile?: string;
+	resultSummary?: string;
+	error?: string;
+	retryOf?: string;
+	deliveryId?: string;
+	resultInjected?: boolean;
+	ownerRuntimeId: string;
+}
+
+export interface TaskStateEntryLike {
+	type?: unknown;
+	customType?: unknown;
+	data?: unknown;
+}
+
+const MODES = new Set<PersistedTaskMode>(["sync", "async", "message"]);
+const STATUSES = new Set<PersistedTaskStatus>([
+	"starting",
+	"running",
+	"completed",
+	"failed",
+	"cancelled",
+	"interrupted",
+]);
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	try {
+		const prototype = Object.getPrototypeOf(value);
+		return prototype === Object.prototype || prototype === null;
+	} catch {
+		return false;
+	}
+}
+
+function requiredString(
+	value: unknown,
+	maxLength: number,
+	options: { allowEmpty?: boolean } = {},
+): value is string {
+	return (
+		typeof value === "string" &&
+		(options.allowEmpty === true || value.length > 0) &&
+		value.length <= maxLength
+	);
+}
+
+function optionalString(value: unknown, maxLength: number): value is string | undefined {
+	return value === undefined || requiredString(value, maxLength);
+}
+
+function safeTimestamp(value: unknown): value is number {
+	return (
+		typeof value === "number" &&
+		Number.isSafeInteger(value) &&
+		Number.isFinite(value) &&
+		value >= 0
+	);
+}
+
+function optionalTimestamp(value: unknown): value is number | undefined {
+	return value === undefined || safeTimestamp(value);
+}
+
+function hasNull(value: string): boolean {
+	return value.includes("\0");
+}
+
+function isSingleLineIdentity(value: string): boolean {
+	return !/[\u0000-\u0020\u007f]/.test(value);
+}
+
+function isSafeRunIdentity(value: string): boolean {
+	return isSingleLineIdentity(value) && /^[A-Za-z0-9_.-]+$/.test(value);
+}
+
+function isSafeAgentIdentity(value: string): boolean {
+	return (
+		isSafeRunIdentity(value) &&
+		value !== "." &&
+		value !== ".." &&
+		value !== "main"
+	);
+}
+
+function isSafeAddress(value: string): boolean {
+	return (
+		isSingleLineIdentity(value) &&
+		/^[A-Za-z0-9_.#-]+$/.test(value) &&
+		value !== "." &&
+		value !== ".." &&
+		value !== "main"
+	);
+}
+
+/**
+ * Session custom-entry data is untrusted. This validator intentionally rejects
+ * unknown versions, non-plain objects, oversized strings, unknown enums, and
+ * non-integer timestamps. A rejected snapshot is ignored without affecting
+ * other snapshots for the same or another run.
+ */
+export function parsePersistedTaskState(data: unknown): PersistedTaskState | undefined {
+	if (!isPlainObject(data)) return undefined;
+	if (data.version !== TASK_STATE_VERSION || !Number.isInteger(data.version)) return undefined;
+	if (!requiredString(data.runId, TASK_STATE_LIMITS.runId)) return undefined;
+	if (!requiredString(data.address, TASK_STATE_LIMITS.address)) return undefined;
+	if (!requiredString(data.agent, TASK_STATE_LIMITS.agent)) return undefined;
+	if (!requiredString(data.task, TASK_STATE_LIMITS.task, { allowEmpty: true })) return undefined;
+	if (!requiredString(data.cwd, TASK_STATE_LIMITS.cwd)) return undefined;
+	if (typeof data.readOnly !== "boolean") return undefined;
+	if (typeof data.mode !== "string" || !MODES.has(data.mode as PersistedTaskMode)) return undefined;
+	if (typeof data.status !== "string" || !STATUSES.has(data.status as PersistedTaskStatus)) return undefined;
+	if (!safeTimestamp(data.startedAt) || !safeTimestamp(data.updatedAt)) return undefined;
+	if (!optionalTimestamp(data.endedAt) || !optionalTimestamp(data.timeoutAt)) return undefined;
+	if (!optionalString(data.childSessionFile, TASK_STATE_LIMITS.childSessionFile)) return undefined;
+	if (!optionalString(data.resultSummary, TASK_STATE_LIMITS.resultSummary)) return undefined;
+	if (!optionalString(data.error, TASK_STATE_LIMITS.error)) return undefined;
+	if (!optionalString(data.retryOf, TASK_STATE_LIMITS.retryOf)) return undefined;
+	if (!optionalString(data.deliveryId, TASK_STATE_LIMITS.deliveryId)) return undefined;
+	if (data.resultInjected !== undefined && typeof data.resultInjected !== "boolean") return undefined;
+	if (!requiredString(data.ownerRuntimeId, TASK_STATE_LIMITS.ownerRuntimeId)) return undefined;
+	if (
+		!isSafeRunIdentity(data.runId) ||
+		!isSafeAddress(data.address) ||
+		!isSafeAgentIdentity(data.agent) ||
+		!isSafeRunIdentity(data.ownerRuntimeId) ||
+		hasNull(data.task) ||
+		hasNull(data.cwd) ||
+		(data.childSessionFile !== undefined && hasNull(data.childSessionFile)) ||
+		(data.resultSummary !== undefined && hasNull(data.resultSummary)) ||
+		(data.error !== undefined && hasNull(data.error)) ||
+		(data.retryOf !== undefined && !isSafeRunIdentity(data.retryOf)) ||
+		(data.deliveryId !== undefined && !isSingleLineIdentity(data.deliveryId))
+	) {
+		return undefined;
+	}
+	if (
+		data.updatedAt < data.startedAt ||
+		(data.endedAt !== undefined && data.endedAt < data.startedAt) ||
+		(data.timeoutAt !== undefined && data.timeoutAt < data.startedAt)
+	) {
+		return undefined;
+	}
+	if (
+		(data.status === "completed" ||
+			data.status === "failed" ||
+			data.status === "cancelled" ||
+			data.status === "interrupted") &&
+		data.endedAt === undefined
+	) {
+		return undefined;
+	}
+	if (
+		data.status === "completed" &&
+		(!requiredString(data.deliveryId, TASK_STATE_LIMITS.deliveryId) ||
+			typeof data.resultInjected !== "boolean" ||
+			data.deliveryId !== `${TASK_RESULT_DELIVERY_PREFIX}${data.runId}`)
+	) {
+		return undefined;
+	}
+
+	return {
+		version: TASK_STATE_VERSION,
+		runId: data.runId,
+		address: data.address,
+		agent: data.agent,
+		task: data.task,
+		cwd: data.cwd,
+		readOnly: data.readOnly,
+		mode: data.mode as PersistedTaskMode,
+		status: data.status as PersistedTaskStatus,
+		startedAt: data.startedAt,
+		updatedAt: data.updatedAt,
+		...(data.endedAt !== undefined ? { endedAt: data.endedAt } : {}),
+		...(data.timeoutAt !== undefined ? { timeoutAt: data.timeoutAt } : {}),
+		...(data.childSessionFile !== undefined ? { childSessionFile: data.childSessionFile } : {}),
+		...(data.resultSummary !== undefined ? { resultSummary: data.resultSummary } : {}),
+		...(data.error !== undefined ? { error: data.error } : {}),
+		...(data.retryOf !== undefined ? { retryOf: data.retryOf } : {}),
+		...(data.deliveryId !== undefined ? { deliveryId: data.deliveryId } : {}),
+		...(data.resultInjected !== undefined ? { resultInjected: data.resultInjected } : {}),
+		ownerRuntimeId: data.ownerRuntimeId,
+	};
+}
+
+/** Reconstruct the authoritative latest valid snapshot for every run. */
+export function reconstructTaskStates(entries: readonly unknown[]): Map<string, PersistedTaskState> {
+	const latest = new Map<string, PersistedTaskState>();
+	for (const rawEntry of entries) {
+		try {
+			if (!isPlainObject(rawEntry)) continue;
+			const entry = rawEntry as TaskStateEntryLike;
+			if (entry.type !== "custom" || entry.customType !== TASK_STATE_ENTRY) continue;
+			const state = parsePersistedTaskState(entry.data);
+			if (state) latest.set(state.runId, state);
+		} catch {
+			// One hostile/malformed entry must not prevent recovery of the rest.
+		}
+	}
+	return latest;
+}
+
+export function isTerminalTaskStatus(status: PersistedTaskStatus): boolean {
+	return (
+		status === "completed" ||
+		status === "failed" ||
+		status === "cancelled" ||
+		status === "interrupted"
+	);
+}
+
+export function isRetryableTaskStatus(status: PersistedTaskStatus): boolean {
+	return status === "failed" || status === "cancelled" || status === "interrupted";
+}
+
+/** Bound diagnostics written by trusted runtime code before persistence. */
+export function boundTaskText(value: unknown, maxLength: number): string {
+	const text = String(value ?? "");
+	if (text.length <= maxLength) return text;
+	if (maxLength <= 1) return text.slice(0, maxLength);
+	return `${text.slice(0, maxLength - 1)}…`;
+}
+
+export function validateLaunchText(
+	field: keyof Pick<typeof TASK_STATE_LIMITS, "agent" | "task" | "cwd" | "address">,
+	value: string,
+	options: { allowEmpty?: boolean } = {},
+): void {
+	const maxLength = TASK_STATE_LIMITS[field];
+	if (value.length > maxLength || (value.length === 0 && options.allowEmpty !== true)) {
+		const empty = value.length === 0 && options.allowEmpty !== true;
+		throw new Error(
+			empty
+				? `${field} must not be empty.`
+			: `${field} exceeds the ${maxLength}-character persistence limit.`,
+		);
+	}
+	if (
+		(field === "agent" && !isSafeAgentIdentity(value)) ||
+		(field === "address" && !isSafeAddress(value)) ||
+		((field === "task" || field === "cwd") && hasNull(value))
+	) {
+		throw new Error(`${field} contains characters that cannot be persisted safely.`);
+	}
+}

package/task-status.ts

@@ -0,0 +1,107 @@
+import type { PersistedTaskState, PersistedTaskStatus } from "./task-state.ts";
+
+export interface LiveTaskView {
+	runId: string;
+	address: string;
+	agent: string;
+	task: string;
+	status: "starting" | "running";
+	startedAt: number;
+	updatedAt: number;
+}
+
+const GROUP_ORDER: PersistedTaskStatus[] = [
+	"running",
+	"starting",
+	"interrupted",
+	"failed",
+	"cancelled",
+	"completed",
+];
+const GROUP_LABEL: Record<PersistedTaskStatus, string> = {
+	starting: "Active",
+	running: "Active",
+	interrupted: "Interrupted",
+	failed: "Failed",
+	cancelled: "Cancelled",
+	completed: "Completed",
+};
+
+function oneLine(value: string, maxLength: number): string {
+	const text = value.replace(/\s+/g, " ").trim();
+	if (text.length <= maxLength) return text;
+	return `${text.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+
+function activeLine(state: PersistedTaskState | LiveTaskView, now: number): string {
+	const elapsed = Math.max(0, Math.floor((now - state.startedAt) / 1000));
+	return `- ${state.address} · ${state.status} · ${elapsed}s · run ${state.runId.slice(0, 8)}`;
+}
+
+function historyLine(state: PersistedTaskState): string {
+	const reason = oneLine(state.error ?? "", 240);
+	if (state.status === "interrupted") {
+		return `- ${state.address} · runtime ended before completion${reason ? ` · ${reason}` : ""}\n  Retry: /subagent-retry ${state.runId}`;
+	}
+	if (state.status === "failed") {
+		return `- ${state.address} · failed${reason ? ` · ${reason}` : ""} · run ${state.runId.slice(0, 8)}`;
+	}
+	if (state.status === "cancelled") {
+		return `- ${state.address} · cancelled${reason ? ` · ${reason}` : ""} · run ${state.runId.slice(0, 8)}`;
+	}
+	if (state.status === "completed") {
+		return `- ${state.address} · ${state.resultInjected ? "result delivered" : "result pending delivery"} · run ${state.runId.slice(0, 8)}`;
+	}
+	return `- ${state.address} · ${state.status} · run ${state.runId.slice(0, 8)}`;
+}
+
+/**
+ * Merge current runtime tasks with current-branch snapshots. Live data wins for
+ * the same runId. Output is deliberately bounded.
+ */
+export function formatTaskStatus(
+	liveTasks: readonly LiveTaskView[],
+	persistedStates: ReadonlyMap<string, PersistedTaskState>,
+	options: { now?: number; maxPerGroup?: number; maxTotal?: number } = {},
+): string {
+	const now = options.now ?? Date.now();
+	const maxPerGroup = Math.max(1, options.maxPerGroup ?? 10);
+	const maxTotal = Math.max(1, options.maxTotal ?? 40);
+	const merged = new Map<string, PersistedTaskState | LiveTaskView>();
+	for (const state of persistedStates.values()) merged.set(state.runId, state);
+	for (const live of liveTasks) merged.set(live.runId, live);
+
+	const orderedStatuses = [...new Set(GROUP_ORDER)];
+	const sections: string[] = [];
+	let shownTotal = 0;
+	let omittedTotal = 0;
+	for (const status of orderedStatuses) {
+		const label = GROUP_LABEL[status];
+		const statuses =
+			label === "Active" ? new Set<PersistedTaskStatus>(["starting", "running"]) : new Set([status]);
+		if (status === "starting") continue;
+		const items = [...merged.values()]
+			.filter((state) => statuses.has(state.status))
+			.sort((a, b) => b.updatedAt - a.updatedAt);
+		if (items.length === 0) continue;
+		const capacity = Math.max(0, Math.min(maxPerGroup, maxTotal - shownTotal));
+		const visible = items.slice(0, capacity);
+		const lines: string[] = [];
+		for (const item of visible) {
+			lines.push(
+				item.status === "starting" || item.status === "running"
+					? activeLine(item, now)
+					: historyLine(item as PersistedTaskState),
+			);
+			lines.push(`  ${oneLine(item.task, 160) || "(empty task)"}`);
+		}
+		const omitted = items.length - visible.length;
+		if (omitted > 0) lines.push(`- … ${omitted} more ${label.toLowerCase()} task(s) omitted`);
+		sections.push(`${label}:\n${lines.join("\n")}`);
+		shownTotal += visible.length;
+		omittedTotal += omitted;
+	}
+	if (sections.length === 0) return "Subagent tasks: none";
+	if (omittedTotal > 0) sections.push(`History truncated: ${omittedTotal} task(s) omitted.`);
+	return sections.join("\n\n");
+}