pi-herdr-agents 2.0.4 → 3.0.0

package/maestro/adapters/fake/fake-harness-adapter.ts

@@ -0,0 +1,263 @@
+import type {
+	HarnessAdapter,
+	ResumeOptions,
+	SpawnOptions,
+} from "../../core/harness-adapter.ts";
+import type {
+	AgentHandle,
+	AgentState,
+	CompletionEvidence,
+} from "../../core/types.ts";
+
+const ABORT_MESSAGE = "Aborted while waiting for subagent to finish";
+
+interface FakeHarnessRecord {
+	handle: AgentHandle;
+	request: SpawnOptions | ResumeOptions;
+	state: AgentState;
+	output: string[];
+	inputs: string[];
+	completion?: CompletionEvidence;
+	exitCode?: number;
+	waiters: Set<Waiter>;
+}
+
+interface Waiter {
+	resolve(evidence: CompletionEvidence): void;
+	reject(error: Error): void;
+	signal: AbortSignal;
+	onAbort(): void;
+}
+
+export class FakeHarnessAdapter implements HarnessAdapter {
+	readonly name = "fake";
+
+	#nextHandle = 1;
+	#records = new Map<string, FakeHarnessRecord>();
+	#sessionHandles = new Map<string, Set<string>>();
+
+	isAvailable(): boolean {
+		return true;
+	}
+
+	async spawn(opts: SpawnOptions): Promise<AgentHandle> {
+		const handle: AgentHandle = {
+			id: this.#newHandleId(),
+			name: opts.name,
+			role: opts.role.name,
+			harness: this.name,
+			cwd: opts.cwd,
+			startedAt: Date.now(),
+			sessionId: opts.sessionId,
+			surfaceId: opts.surface?.id,
+			worktree: opts.worktree,
+		};
+		this.#records.set(handle.id, {
+			handle,
+			request: cloneSpawnOptions(opts),
+			state: "working",
+			output: [],
+			inputs: [],
+			waiters: new Set(),
+		});
+		this.#rememberSession(handle);
+		return {
+			...handle,
+			worktree: handle.worktree ? { ...handle.worktree } : undefined,
+		};
+	}
+
+	async resume(opts: ResumeOptions): Promise<AgentHandle> {
+		if (!opts.name) throw new Error("resume requires name");
+		const prior = this.#latestSessionHandle(opts.sessionId);
+		const handle: AgentHandle = {
+			id: this.#newHandleId(),
+			name: opts.name,
+			role: prior?.role ?? "resumed",
+			harness: this.name,
+			cwd: prior?.cwd ?? process.cwd(),
+			startedAt: Date.now(),
+			sessionId: opts.sessionId,
+			surfaceId: opts.surface?.id,
+		};
+		this.#records.set(handle.id, {
+			handle,
+			request: { ...opts },
+			state: "working",
+			output: [],
+			inputs: opts.message ? [opts.message] : [],
+			waiters: new Set(),
+		});
+		this.#rememberSession(handle);
+		return { ...handle };
+	}
+
+	async getState(handle: AgentHandle): Promise<AgentState> {
+		return this.#records.get(handle.id)?.state ?? "unknown";
+	}
+
+	async interrupt(handle: AgentHandle): Promise<void> {
+		const record = this.#record(handle.id);
+		if (record.state !== "done") record.state = "idle";
+	}
+
+	async kill(handle: AgentHandle): Promise<void> {
+		const record = this.#record(handle.id);
+		record.state = "done";
+		this.#settle(handle.id, {
+			reason: "error",
+			exitCode: 143,
+			errorMessage: "terminated by kill",
+		});
+	}
+
+	async sendInput(handle: AgentHandle, text: string): Promise<void> {
+		this.#record(handle.id).inputs.push(text);
+	}
+
+	async readOutput(handle: AgentHandle, lines?: number): Promise<string> {
+		const output = this.#record(handle.id).output;
+		return (lines === undefined ? output : output.slice(-lines)).join("\n");
+	}
+
+	exitCode(handle: AgentHandle): number | undefined {
+		return this.#records.get(handle.id)?.exitCode;
+	}
+
+	awaitCompletion(
+		handle: AgentHandle,
+		signal: AbortSignal,
+	): Promise<CompletionEvidence> {
+		const record = this.#record(handle.id);
+		if (signal.aborted) return Promise.reject(new Error(ABORT_MESSAGE));
+		if (record.completion) return Promise.resolve({ ...record.completion });
+
+		return new Promise((resolve, reject) => {
+			const waiter: Waiter = {
+				resolve: (evidence) => {
+					signal.removeEventListener("abort", waiter.onAbort);
+					resolve({ ...evidence });
+				},
+				reject: (error) => {
+					signal.removeEventListener("abort", waiter.onAbort);
+					reject(error);
+				},
+				signal,
+				onAbort: () => {
+					record.waiters.delete(waiter);
+					waiter.reject(new Error(ABORT_MESSAGE));
+				},
+			};
+			record.waiters.add(waiter);
+			signal.addEventListener("abort", waiter.onAbort, { once: true });
+		});
+	}
+
+	complete(handleId: string, evidence: CompletionEvidence): void {
+		this.#settle(handleId, evidence);
+	}
+
+	fail(handleId: string, error: string): void {
+		this.#settle(handleId, {
+			reason: "error",
+			exitCode: 1,
+			errorMessage: error,
+		});
+	}
+
+	ping(handleId: string, message: string): void {
+		const record = this.#record(handleId);
+		this.#settle(handleId, {
+			reason: "ping",
+			exitCode: 0,
+			ping: { name: record.handle.name, message },
+		});
+	}
+
+	spawned(): AgentHandle[] {
+		return Array.from(this.#records.values(), (record) =>
+			cloneHandle(record.handle),
+		);
+	}
+
+	inputs(handleId: string): string[] {
+		return [...this.#record(handleId).inputs];
+	}
+
+	request(handleId: string): SpawnOptions | ResumeOptions | undefined {
+		const request = this.#records.get(handleId)?.request;
+		return request ? cloneRequest(request) : undefined;
+	}
+
+	appendOutput(handleId: string, text: string): void {
+		this.#record(handleId).output.push(...text.split("\n"));
+	}
+
+	#settle(handleId: string, evidence: CompletionEvidence): void {
+		const record = this.#record(handleId);
+		if (record.completion) return;
+		const completion = {
+			...evidence,
+			sessionRef: evidence.sessionRef ?? record.handle.sessionId,
+		};
+		record.completion = completion;
+		record.exitCode = completion.exitCode;
+		record.state = "done";
+		const waiters = [...record.waiters];
+		record.waiters.clear();
+		for (const waiter of waiters) waiter.resolve(completion);
+	}
+
+	#record(handleId: string): FakeHarnessRecord {
+		const record = this.#records.get(handleId);
+		if (!record) throw new Error(`unknown handle: ${handleId}`);
+		return record;
+	}
+
+	#newHandleId(): string {
+		const id = `fake-agent-${this.#nextHandle}`;
+		this.#nextHandle += 1;
+		return id;
+	}
+
+	#rememberSession(handle: AgentHandle): void {
+		const handles =
+			this.#sessionHandles.get(handle.sessionId) ?? new Set<string>();
+		handles.add(handle.id);
+		this.#sessionHandles.set(handle.sessionId, handles);
+	}
+
+	#latestSessionHandle(sessionId: string): AgentHandle | undefined {
+		const handles = this.#sessionHandles.get(sessionId);
+		if (!handles) return undefined;
+		const handleId = Array.from(handles).at(-1);
+		return handleId ? this.#records.get(handleId)?.handle : undefined;
+	}
+}
+
+function cloneRequest(request: SpawnOptions | ResumeOptions) {
+	if ("task" in request) return cloneSpawnOptions(request);
+	return {
+		...request,
+		env: request.env ? { ...request.env } : undefined,
+	};
+}
+
+function cloneSpawnOptions(options: SpawnOptions): SpawnOptions {
+	return {
+		...options,
+		role: { ...options.role, allowedTools: [...options.role.allowedTools] },
+		worktree: options.worktree ? { ...options.worktree } : undefined,
+		worktreeRequest: options.worktreeRequest
+			? { ...options.worktreeRequest }
+			: undefined,
+		env: options.env ? { ...options.env } : undefined,
+	};
+}
+
+function cloneHandle(handle: AgentHandle): AgentHandle {
+	return {
+		...handle,
+		worktree: handle.worktree ? { ...handle.worktree } : undefined,
+	};
+}

package/{pi-extension/subagents/activity.ts → maestro/adapters/pi/activity-file.ts}

@@ -12,62 +12,18 @@ import {
 	isFiniteNumber,
 	isPlainObject,
 	isString,
-} from "./type-guards.ts";
-
-export type SubagentActivityPhase = "starting" | "active" | "waiting" | "done";
-export type SubagentActivityScope =
-	| "agent"
-	| "turn"
-	| "provider"
-	| "streaming"
-	| "tool";
-
-export type SubagentActivityEvent =
-	| "session_start"
-	| "input"
-	| "before_agent_start"
-	| "agent_start"
-	| "agent_end"
-	| "turn_start"
-	| "turn_end"
-	| "before_provider_request"
-	| "after_provider_response"
-	| "message_update"
-	| "tool_execution_start"
-	| "tool_call"
-	| "tool_execution_update"
-	| "tool_result"
-	| "tool_execution_end"
-	| "caller_ping"
-	| "subagent_done"
-	| "session_shutdown";
-
-export interface SubagentActivityState {
-	version: 1;
-	runningChildId: string;
-	createdAt: number;
-	updatedAt: number;
-	sequence: number;
-	latestEvent: SubagentActivityEvent;
-	phase: SubagentActivityPhase;
-	agentActive: boolean;
-	turnActive: boolean;
-	providerActive: boolean;
-	toolActive: boolean;
-	activeScope?: SubagentActivityScope;
-	activeSince?: number;
-	waitingSince?: number;
-	turnIndex?: number;
-	messageEventType?: string;
-	toolCallId?: string;
-	toolName?: string;
-	toolStartedAt?: number;
-	toolEndedAt?: number;
-}
-
-export type ActivityReadResult =
-	| { ok: true; activity: SubagentActivityState }
-	| { ok: false; reason: "missing" | "invalid" | "wrong-id"; error?: string };
+} from "../../core/config/type-guards.ts";
+import {
+	isSubagentActivityScope,
+	projectActivity,
+} from "../../core/activity.ts";
+import type {
+	ActivityReadResult,
+	SubagentActivityEvent,
+	SubagentActivityPhase,
+	SubagentActivityScope,
+	SubagentActivityState,
+} from "../../core/types.ts";
 
 export type SubagentShutdownReason =
 	| "quit"
@@ -106,13 +62,6 @@ const KNOWN_PHASES = new Set<SubagentActivityPhase>([
 	"waiting",
 	"done",
 ]);
-const KNOWN_SCOPES = new Set<SubagentActivityScope>([
-	"agent",
-	"turn",
-	"provider",
-	"streaming",
-	"tool",
-]);
 const KNOWN_EVENTS = new Set<SubagentActivityEvent>([
 	"session_start",
 	"input",
@@ -142,12 +91,6 @@ export function getSubagentActivityFile(
 	return join(artifactDir, "subagent-activity", `${runningChildId}.json`);
 }
 
-export function isSubagentActivityScope(
-	value: any,
-): value is SubagentActivityScope {
-	return isString(value) && KNOWN_SCOPES.has(value);
-}
-
 function requireObject(value: any) {
 	return isPlainObject(value) ? value : null;
 }
@@ -225,7 +168,7 @@ function validateActivity(
 	}
 	if (
 		object.activeScope != null &&
-		(!isString(object.activeScope) || !KNOWN_SCOPES.has(object.activeScope))
+		!isSubagentActivityScope(object.activeScope)
 	) {
 		return invalidActivity("unknown activeScope");
 	}
@@ -249,14 +192,14 @@ function validateActivity(
 	].find((error) => error != null);
 	if (validationError) return invalidActivity(validationError);
 
-	return { ok: true, activity: object };
+	return projectActivity(object);
 }
 
 export function readSubagentActivityFile(
 	activityFile: string,
 	expectedRunningChildId: string,
 ): ActivityReadResult {
-	if (!existsSync(activityFile)) return { ok: false, reason: "missing" };
+	if (!existsSync(activityFile)) return projectActivity(undefined);
 
 	let parsed: unknown;
 	try {

package/{pi-extension/subagents → maestro/adapters/pi/child}/subagent-done.ts

@@ -12,9 +12,13 @@ import {
 	consumePersistentTaskInbox,
 	readPersistentDeliveryLedger,
 	readPersistentTaskEvents,
-} from "./session.ts";
-import { createSubagentActivityRecorder } from "./activity.ts";
-import { isString } from "./type-guards.ts";
+} from "../session.ts";
+import { createSubagentActivityRecorder } from "../activity-file.ts";
+import {
+	readOwnProcessIdentity,
+	writeProcessIdentityRecord,
+} from "../process-identity.ts";
+import { isString } from "../../../core/config/type-guards.ts";
 
 export function shouldMarkUserTookOver(agentStarted: boolean): boolean {
 	return agentStarted;
@@ -130,6 +134,28 @@ export function parseDeniedTools(rawValue: string | undefined): string[] {
 		.filter(Boolean);
 }
 
+/**
+ * A managed worktree child names its own process at load from immutable
+ * kernel facts, which Pi's process-title rewrite cannot alter.
+ */
+export function recordProcessIdentity(
+	id: string | undefined,
+	sessionFile: string | undefined,
+	file = process.env.PI_SUBAGENT_PROCESS_FILE,
+): void {
+	if (!file || !id || !sessionFile) return;
+	try {
+		writeProcessIdentityRecord(file, {
+			version: 1,
+			id,
+			sessionFile,
+			...readOwnProcessIdentity(),
+		});
+	} catch {
+		// Unrecorded identity leaves a worktree cancel unconfirmed, never guessed.
+	}
+}
+
 export default function (pi: ExtensionAPI) {
 	let toolNames: string[] = [];
 	let denied: string[] = [];
@@ -157,6 +183,7 @@ export default function (pi: ExtensionAPI) {
 		runningChildId: process.env.PI_SUBAGENT_ID,
 		activityFile: process.env.PI_SUBAGENT_ACTIVITY_FILE,
 	});
+	recordProcessIdentity(process.env.PI_SUBAGENT_ID, sessionFile);
 
 	function renderWidget(ctx: { ui: { setWidget: Function } }, _theme: any) {
 		ctx.ui.setWidget(

package/{pi-extension/subagents → maestro/adapters/pi}/completion.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, rmSync } from "node:fs";
 
-import { isNonEmptyString, isString } from "./type-guards.ts";
+import { isNonEmptyString, isString } from "../../core/config/type-guards.ts";
 
 const ABORT_MESSAGE = "Aborted while waiting for subagent to finish";
 const TERMINAL_SENTINEL = /__SUBAGENT_DONE_(\d+)__/;
@@ -15,11 +15,11 @@ export interface CompletionResult {
 export interface CompletionOptions {
 	intervalMs: number;
 	readTerminalTail: () => Promise<string>;
-	inspectPane?: () => Promise<import("./lifecycle.ts").PaneInspection>;
+	inspectPane?: () => Promise<import("../../core/types.ts").PaneInspection>;
 	/** Bounded artifact grace after explicit pane disappearance. Default: 500ms. */
 	paneDisappearanceGraceMs?: number;
 	onPaneInspection?: (
-		inspection: import("./lifecycle.ts").PaneInspection,
+		inspection: import("../../core/types.ts").PaneInspection,
 		observedAt: number,
 	) => void;
 	sessionFile?: string;
@@ -168,7 +168,7 @@ export async function waitForCompletion(
 			}
 
 		if (reconcile && options.inspectPane) {
-			let inspection: import("./lifecycle.ts").PaneInspection;
+			let inspection: import("../../core/types.ts").PaneInspection;
 			try {
 				inspection = await options.inspectPane();
 			} catch {