pi-crew 0.9.53 → 0.9.55

package/src/runtime/batch-barrier.ts

@@ -0,0 +1,147 @@
+/**
+ * BatchBarrier — Rule 1 (no-wait batch grouping).
+ *
+ * When a leader launches several background subagents with the SAME `batchId`
+ * and does NOT join them immediately (`get_subagent_result(wait:true)`), the
+ * completion notifications are coalesced: instead of N individual
+ * "changed state" wake-ups, the leader receives ONE consolidated notification
+ * once ALL members of the batch have reached a terminal state.
+ *
+ * Semantics:
+ * - `register(batchId, agentId)` is called at spawn time (synchronous within a
+ *   leader turn). All members of a batch are therefore known by the time the
+ *   first completion fires (completion is observed via the 1000ms poll loop).
+ * - `markTerminal(batchId, agentId)` returns whether THIS completion made every
+ *   registered member terminal ("allDone"). When allDone, the caller emits a
+ *   single consolidated notification and calls `markNotified`.
+ * - If a member reaches terminal after the batch already notified (late spawn
+ *   edge case), `markTerminal` returns allDone=false for the straggler path is
+ *   NOT covered — but `alreadyNotified` lets the caller suppress stray
+ *   individual notifications once the consolidated one fired.
+ *
+ * Thread-safety: single-threaded JS event loop. No locks needed.
+ */
+
+export interface BatchMember {
+	id: string;
+	description?: string;
+	type?: string;
+	status: string;
+}
+
+export interface BatchSnapshot {
+	batchId: string;
+	members: BatchMember[];
+	terminal: BatchMember[];
+	/** true when every registered member has reached a terminal state. */
+	allDone: boolean;
+	/** true once the consolidated notification has been emitted. */
+	notified: boolean;
+}
+
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled", "error", "stopped"]);
+
+export function isTerminalStatus(status: string): boolean {
+	return TERMINAL_STATUSES.has(status);
+}
+
+export class BatchBarrier {
+	private readonly batches = new Map<
+		string,
+		{
+			members: Map<string, BatchMember>;
+			terminal: Map<string, BatchMember>;
+			notified: boolean;
+		}
+	>();
+
+	/** Register a member at spawn time. Idempotent per (batchId, agentId). */
+	register(batchId: string, agentId: string, meta?: { description?: string; type?: string }): void {
+		let batch = this.batches.get(batchId);
+		if (!batch) {
+			batch = {
+				members: new Map(),
+				terminal: new Map(),
+				notified: false,
+			};
+			this.batches.set(batchId, batch);
+		}
+		if (!batch.members.has(agentId)) {
+			batch.members.set(agentId, {
+				id: agentId,
+				description: meta?.description,
+				type: meta?.type,
+				status: "running",
+			});
+		}
+	}
+
+	/**
+	 * Record that a member reached a terminal state. Returns the batch snapshot.
+	 * `snapshot.allDone` is true iff every registered member is now terminal.
+	 * If the batch was never seen (defensive edge case), the member is registered
+	 * on-the-fly as a batch-of-one so its terminal state is not silently lost.
+	 */
+	markTerminal(batchId: string, member: BatchMember): BatchSnapshot {
+		let batch = this.batches.get(batchId);
+		if (!batch) {
+			batch = {
+				members: new Map(),
+				terminal: new Map(),
+				notified: false,
+			};
+			this.batches.set(batchId, batch);
+		}
+		// Ensure the member is known (auto-register for the defensive case).
+		if (!batch.members.has(member.id)) {
+			batch.members.set(member.id, { ...member, status: member.status });
+		}
+		if (isTerminalStatus(member.status)) {
+			batch.terminal.set(member.id, { ...member });
+			const existing = batch.members.get(member.id);
+			if (existing)
+				batch.members.set(member.id, {
+					...existing,
+					status: member.status,
+				});
+		}
+		const allDone = batch.members.size > 0 && [...batch.members.keys()].every((id) => batch.terminal.has(id));
+		return {
+			batchId,
+			members: [...batch.members.values()],
+			terminal: [...batch.terminal.values()],
+			allDone,
+			notified: batch.notified,
+		};
+	}
+
+	/** Has the consolidated notification already been emitted for this batch? */
+	alreadyNotified(batchId: string): boolean {
+		return this.batches.get(batchId)?.notified ?? false;
+	}
+
+	/** Mark the consolidated notification as emitted. No-op if already set. */
+	markNotified(batchId: string): void {
+		const batch = this.batches.get(batchId);
+		if (batch) batch.notified = true;
+	}
+
+	/** Read-only snapshot (for tests / debugging). */
+	snapshot(batchId: string): BatchSnapshot | undefined {
+		const batch = this.batches.get(batchId);
+		if (!batch) return undefined;
+		return {
+			batchId,
+			members: [...batch.members.values()],
+			terminal: [...batch.terminal.values()],
+			allDone: batch.members.size > 0 && [...batch.members.keys()].every((id) => batch.terminal.has(id)),
+			notified: batch.notified,
+		};
+	}
+
+	/** Drop a batch (used on cleanup / test reset). */
+	dispose(batchId?: string): void {
+		if (batchId === undefined) this.batches.clear();
+		else this.batches.delete(batchId);
+	}
+}

package/src/runtime/broker-issuer.ts

@@ -0,0 +1,39 @@
+/**
+ * broker-issuer.ts — Process-local registry for the active broker credential
+ * issuer.
+ *
+ * The broker lifecycle controller (parent/root session) registers its
+ * `issueForChild` function here on start and clears it on stop. `runChildPi`
+ * reads it as the default `brokerIssuer` so the spawn path does not need the
+ * registration context threaded through every runner call site.
+ *
+ * This mirrors the existing module-level singletons in the codebase
+ * (`runEventBus`, the mailbox append observers). It lives ONLY in the parent
+ * process — children never register an issuer (they receive credentials via
+ * env). The value is a function reference, never a token; nothing here is
+ * persisted or logged.
+ */
+
+/** Credentials handed to a child worker so it can authenticate to the broker. */
+export interface BrokerSpawnCredentials {
+	socketPath: string;
+	token: string;
+}
+
+/** Issuer signature: given a runId (+optional taskId for per-task tokens),
+ *  return credentials or undefined when the broker is disabled / this process
+ *  is not the root session. taskId is optional for backward compat — callers
+ *  that still pass only runId receive the legacy per-run token. */
+export type BrokerIssuer = (runId: string, taskId?: string) => Promise<BrokerSpawnCredentials | undefined>;
+
+let activeIssuer: BrokerIssuer | undefined;
+
+/** Register the active issuer (called by the lifecycle controller on start). */
+export function setActiveBrokerIssuer(issuer: BrokerIssuer | undefined): void {
+	activeIssuer = issuer;
+}
+
+/** Read the active issuer, if any. Returns undefined when no broker is wired. */
+export function getActiveBrokerIssuer(): BrokerIssuer | undefined {
+	return activeIssuer;
+}

package/src/runtime/cancellation-token.ts

@@ -0,0 +1,99 @@
+import { type CancellationReason, CrewCancellationError, cancellationReasonFromUnknown } from "./cancellation.ts";
+
+export interface CancellationTokenState {
+	aborted: boolean;
+	reason?: CancellationReason;
+	lastHeartbeatAt?: string;
+	lastHeartbeatStage?: string;
+}
+
+export interface CancellationTokenOptions {
+	signal?: AbortSignal;
+	onHeartbeat?: (state: CancellationTokenState) => void;
+	now?: () => Date;
+}
+
+export class CancellationToken {
+	readonly #controller = new AbortController();
+	readonly #onHeartbeat?: (state: CancellationTokenState) => void;
+	readonly #now: () => Date;
+	#reason?: CancellationReason;
+	#lastHeartbeatAt?: string;
+	#lastHeartbeatStage?: string;
+
+	constructor(options: CancellationTokenOptions = {}) {
+		this.#onHeartbeat = options.onHeartbeat;
+		this.#now = options.now ?? (() => new Date());
+		if (options.signal?.aborted) this.abort(options.signal.reason);
+		else if (options.signal) options.signal.addEventListener("abort", () => this.abort(options.signal?.reason), { once: true });
+	}
+
+	get signal(): AbortSignal {
+		return this.#controller.signal;
+	}
+	get aborted(): boolean {
+		return this.#controller.signal.aborted;
+	}
+	get reason(): CancellationReason | undefined {
+		return this.#reason;
+	}
+	get lastHeartbeatAt(): string | undefined {
+		return this.#lastHeartbeatAt;
+	}
+	get lastHeartbeatStage(): string | undefined {
+		return this.#lastHeartbeatStage;
+	}
+
+	heartbeat(stage?: string): CancellationTokenState {
+		this.throwIfCancelled();
+		this.#lastHeartbeatAt = this.#now().toISOString();
+		this.#lastHeartbeatStage = stage;
+		const state = this.state();
+		this.#onHeartbeat?.(state);
+		return state;
+	}
+
+	throwIfCancelled(): void {
+		if (this.aborted) throw new CrewCancellationError(this.#reason ?? cancellationReasonFromUnknown(this.#controller.signal.reason));
+	}
+
+	abort(reason?: unknown): void {
+		if (this.aborted) return;
+		this.#reason = cancellationReasonFromUnknown(reason);
+		this.#controller.abort(this.#reason);
+	}
+
+	wait(ms: number): Promise<void> {
+		this.throwIfCancelled();
+		if (ms <= 0) return Promise.resolve();
+		return new Promise((resolve, reject) => {
+			let timeout: NodeJS.Timeout | undefined;
+			const cleanup = (): void => {
+				if (timeout) clearTimeout(timeout);
+				this.signal.removeEventListener("abort", onAbort);
+			};
+			const onAbort = (): void => {
+				cleanup();
+				reject(new CrewCancellationError(this.#reason ?? cancellationReasonFromUnknown(this.signal.reason)));
+			};
+			timeout = setTimeout(() => {
+				cleanup();
+				resolve();
+			}, ms);
+			this.signal.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+
+	state(): CancellationTokenState {
+		return {
+			aborted: this.aborted,
+			...(this.#reason ? { reason: this.#reason } : {}),
+			...(this.#lastHeartbeatAt ? { lastHeartbeatAt: this.#lastHeartbeatAt } : {}),
+			...(this.#lastHeartbeatStage ? { lastHeartbeatStage: this.#lastHeartbeatStage } : {}),
+		};
+	}
+}
+
+export function createCancellationToken(options: CancellationTokenOptions = {}): CancellationToken {
+	return new CancellationToken(options);
+}

package/src/runtime/cancellation.ts

@@ -0,0 +1,99 @@
+import type { OperationTerminalEvidence } from "../state/types.ts";
+
+export type CancellationReasonCode =
+	| "caller_cancelled"
+	| "leader_interrupted"
+	| "provider_timeout"
+	| "worker_timeout"
+	| "tool_timeout"
+	| "shutdown"
+	| "unknown";
+
+export interface CancellationReason {
+	code: CancellationReasonCode;
+	message: string;
+	cause?: unknown;
+}
+
+export function buildSyntheticTerminalEvidence(
+	operation: "worker" | "tool" | "model",
+	reason: CancellationReason,
+	startedAt?: string,
+): OperationTerminalEvidence {
+	return {
+		operation,
+		status: "cancelled",
+		startedAt,
+		finishedAt: new Date().toISOString(),
+		reason,
+	};
+}
+
+const KNOWN_CODES: ReadonlySet<string> = new Set([
+	"caller_cancelled",
+	"leader_interrupted",
+	"provider_timeout",
+	"worker_timeout",
+	"tool_timeout",
+	"shutdown",
+	"unknown",
+]);
+
+export class CrewCancellationError extends Error {
+	readonly reason: CancellationReason;
+
+	constructor(reason: CancellationReason) {
+		super(reason.message);
+		this.name = "CrewCancellationError";
+		this.reason = reason;
+	}
+}
+
+function reasonFromString(value: string): CancellationReason {
+	const trimmed = value.trim();
+	if (KNOWN_CODES.has(trimmed))
+		return {
+			code: trimmed as CancellationReasonCode,
+			message: `Cancelled: ${trimmed}`,
+		};
+	return {
+		code: "caller_cancelled",
+		message: trimmed || "Cancelled by caller.",
+	};
+}
+
+export function cancellationReasonFromUnknown(value: unknown): CancellationReason {
+	if (value instanceof CrewCancellationError) return value.reason;
+	if (value instanceof Error)
+		return {
+			code: "caller_cancelled",
+			message: value.message || "Cancelled by caller.",
+			cause: value,
+		};
+	if (typeof value === "string") return reasonFromString(value);
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const record = value as {
+			code?: unknown;
+			reason?: unknown;
+			message?: unknown;
+			cause?: unknown;
+		};
+		const rawCode = typeof record.code === "string" ? record.code : typeof record.reason === "string" ? record.reason : undefined;
+		const code = rawCode && KNOWN_CODES.has(rawCode) ? (rawCode as CancellationReasonCode) : "caller_cancelled";
+		const message = typeof record.message === "string" && record.message.trim() ? record.message.trim() : `Cancelled: ${code}`;
+		return { code, message, cause: record.cause ?? value };
+	}
+	return { code: "caller_cancelled", message: "Cancelled by caller." };
+}
+
+export function cancellationReasonFromSignal(signal: AbortSignal | undefined): CancellationReason {
+	return cancellationReasonFromUnknown(signal?.reason);
+}
+
+export function cancellationErrorFromSignal(signal: AbortSignal | undefined): CrewCancellationError {
+	return new CrewCancellationError(cancellationReasonFromSignal(signal));
+}
+
+export function throwIfCancelled(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw cancellationErrorFromSignal(signal);
+}

package/src/runtime/capability-inventory.ts

@@ -0,0 +1,137 @@
+import type { AgentConfig } from "../agents/agent-config.ts";
+import { discoverAgents } from "../agents/discover-agents.ts";
+import type { PiTeamsConfig } from "../config/config.ts";
+import { discoverSkills, getLastDiscoveryDiagnostics } from "../skills/discover-skills.ts";
+import type { SkillValidationError } from "../skills/validate.ts";
+import { discoverTeams } from "../teams/discover-teams.ts";
+import { discoverWorkflows } from "../workflows/discover-workflows.ts";
+
+export type CapabilityKind = "team" | "workflow" | "agent" | "skill" | "tool" | "runtime";
+export type CapabilitySource = "builtin" | "project" | "user" | "package" | "git";
+export type CapabilityState = "active" | "disabled" | "shadowed" | "missing";
+
+export interface CapabilityItem {
+	id: string;
+	kind: CapabilityKind;
+	name: string;
+	description: string;
+	source: CapabilitySource;
+	path?: string;
+	state: CapabilityState;
+	disabledReason?: string;
+	shadowedBy?: string;
+}
+
+function normalizeAgents(agents: AgentConfig[], source: CapabilitySource, disabledIds: Set<string>): CapabilityItem[] {
+	return agents.map((agent) => {
+		const id = `agent:${agent.name}`;
+		const configDisabled = disabledIds.has(id);
+		const agentDisabled = agent.disabled || configDisabled;
+		return {
+			id,
+			kind: "agent" as const,
+			name: agent.name,
+			description: agent.description,
+			source,
+			path: agent.filePath,
+			state: agentDisabled ? "disabled" : "active",
+			disabledReason: configDisabled ? "disabled by policy" : agent.disabled ? "disabled in config" : undefined,
+		};
+	});
+}
+
+function normalizeSkills(cwd: string, disabledIds: Set<string>): CapabilityItem[] {
+	const skills = discoverSkills(cwd);
+	return skills.map((skill) => {
+		const id = `skill:${skill.name}`;
+		const configDisabled = disabledIds.has(id);
+		return {
+			id,
+			kind: "skill" as const,
+			name: skill.name,
+			description: skill.description,
+			source: skill.source as CapabilitySource,
+			path: skill.path,
+			state: configDisabled ? "disabled" : "active",
+			disabledReason: configDisabled ? "disabled by policy" : undefined,
+		};
+	});
+}
+
+function normalizeTeams(cwd: string, disabledIds: Set<string>): CapabilityItem[] {
+	const result = discoverTeams(cwd);
+	return [...result.builtin, ...result.user, ...result.project].map((team) => {
+		const id = `team:${team.name}`;
+		const configDisabled = disabledIds.has(id);
+		return {
+			id,
+			kind: "team" as const,
+			name: team.name,
+			description: team.description,
+			source: team.source as CapabilitySource,
+			path: team.filePath,
+			state: configDisabled ? "disabled" : "active",
+			disabledReason: configDisabled ? "disabled by policy" : undefined,
+		};
+	});
+}
+
+function normalizeWorkflows(cwd: string, disabledIds: Set<string>): CapabilityItem[] {
+	const result = discoverWorkflows(cwd);
+	return [...result.builtin, ...result.user, ...result.project].map((workflow) => {
+		const id = `workflow:${workflow.name}`;
+		const configDisabled = disabledIds.has(id);
+		return {
+			id,
+			kind: "workflow" as const,
+			name: workflow.name,
+			description: workflow.description,
+			source: workflow.source as CapabilitySource,
+			path: workflow.filePath,
+			state: configDisabled ? "disabled" : "active",
+			disabledReason: configDisabled ? "disabled by policy" : undefined,
+		};
+	});
+}
+
+export function buildCapabilityInventory(cwd: string, config?: PiTeamsConfig): CapabilityItem[] {
+	const disabledIds = new Set<string>(config?.policy?.disabledCapabilities ?? []);
+	const agents = discoverAgents(cwd);
+	const items = [
+		...normalizeTeams(cwd, disabledIds),
+		...normalizeWorkflows(cwd, disabledIds),
+		...normalizeAgents([...agents.builtin, ...agents.user, ...agents.project], "builtin", disabledIds),
+		...normalizeSkills(cwd, disabledIds),
+	];
+
+	// Mark shadowed resources: project/user items with same kind:name as a builtin
+	const builtinNames = new Set(
+		items.filter((item) => item.source === "builtin" || item.source === "package").map((item) => `${item.kind}:${item.name}`),
+	);
+	for (const item of items) {
+		if (item.source !== "builtin" && item.source !== "package" && builtinNames.has(`${item.kind}:${item.name}`)) {
+			item.state = "shadowed";
+			item.shadowedBy = `builtin:${item.kind}:${item.name}`;
+		}
+	}
+
+	return items.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * L3: surface skill-validation diagnostics from the most recent
+ * `discoverSkills()` call. Skills that fail HARD validation are silently
+ * excluded from `buildCapabilityInventory()`; this function exposes the
+ * underlying errors so users see WHY a skill is missing instead of just
+ * noticing the absence.
+ *
+ * Soft warnings (unknown props, derived-name fallback) are also returned so
+ * skill authors can clean up their frontmatter over time.
+ *
+ * IMPORTANT: `discoverSkills()` is internally cached for 30s, so this
+ * function returns diagnostics from whichever call last populated the cache.
+ * Call `buildCapabilityInventory(cwd)` first to ensure a fresh pass.
+ */
+export function buildSkillValidationDiagnostics(): SkillValidationError[] {
+	return getLastDiscoveryDiagnostics();
+}