pi-crew 0.1.51 → 0.2.0

package/src/runtime/agent-observability.ts

@@ -1,114 +1,114 @@
-import * as fs from "node:fs";
-import type { TeamRunManifest } from "../state/types.ts";
-import { agentOutputPath, readCrewAgents } from "./crew-agent-records.ts";
-import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
-
-const TOOL_LABELS: Record<string, string> = {
-	read: "reading",
-	bash: "running command",
-	edit: "editing",
-	write: "writing",
-	grep: "searching",
-	find: "finding files",
-	ls: "listing",
-};
-
-export interface TextTailResult {
-	path: string;
-	text: string;
-	bytes: number;
-	truncated: boolean;
-}
-
-export function readTextTail(filePath: string, maxBytes = 64_000): TextTailResult {
-	if (!fs.existsSync(filePath)) return { path: filePath, text: "", bytes: 0, truncated: false };
-	const stat = fs.statSync(filePath);
-	const bytesToRead = Math.min(stat.size, Math.max(0, maxBytes));
-	const fd = fs.openSync(filePath, "r");
-	try {
-		const buffer = Buffer.alloc(bytesToRead);
-		fs.readSync(fd, buffer, 0, bytesToRead, stat.size - bytesToRead);
-		return { path: filePath, text: buffer.toString("utf-8"), bytes: stat.size, truncated: stat.size > bytesToRead };
-	} finally {
-		fs.closeSync(fd);
-	}
-}
-
-function compactDuration(ms: number | undefined): string | undefined {
-	if (ms === undefined || !Number.isFinite(ms)) return undefined;
-	if (ms < 1000) return `${Math.round(ms)}ms`;
-	if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
-	return `${Math.floor(ms / 60_000)}m${Math.floor((ms % 60_000) / 1000)}s`;
-}
-
-function ageBetween(start: string | undefined, end: string | undefined): string | undefined {
-	if (!start) return undefined;
-	const stop = end ? new Date(end).getTime() : Date.now();
-	const ms = Math.max(0, stop - new Date(start).getTime());
-	return compactDuration(ms);
-}
-
-function activityText(agent: CrewAgentRecord): string {
-	const parts: string[] = [];
-	if (agent.progress?.activityState) parts.push(agent.progress.activityState);
-	if (agent.progress?.currentTool) parts.push(TOOL_LABELS[agent.progress.currentTool] ?? `tool=${agent.progress.currentTool}`);
-	if (agent.toolUses !== undefined) parts.push(`tools=${agent.toolUses}`);
-	if (agent.progress?.tokens !== undefined) parts.push(`tokens=${agent.progress.tokens}`);
-	if (agent.progress?.turns !== undefined) parts.push(`turns=${agent.progress.turns}`);
-	const duration = compactDuration(agent.progress?.durationMs) ?? ageBetween(agent.startedAt, agent.completedAt);
-	if (duration) parts.push(duration);
-	if (agent.progress?.failedTool) parts.push(`failedTool=${agent.progress.failedTool}`);
-	if (agent.progress?.recentOutput?.length) parts.push(`last=${agent.progress.recentOutput.at(-1)}`);
-	return parts.join(" ") || "idle";
-}
-
-function statusGlyph(status: CrewAgentRecord["status"]): string {
-	if (status === "completed") return "✓";
-	if (status === "failed") return "✗";
-	if (status === "running") return "▶";
-	if (status === "cancelled" || status === "stopped") return "■";
-	return "·";
-}
-
-function outputWarning(manifest: TeamRunManifest, agent: CrewAgentRecord): string {
-	if (agent.status !== "completed") return "";
-	try {
-		const outputPath = agentOutputPath(manifest, agent.taskId);
-		if (!fs.existsSync(outputPath)) return " no-output";
-		return fs.statSync(outputPath).size === 0 ? " no-output" : "";
-	} catch {
-		return " no-output";
-	}
-}
-
-function agentLine(manifest: TeamRunManifest, agent: CrewAgentRecord): string {
-	return `- ${statusGlyph(agent.status)} ${agent.taskId} ${agent.role} → ${agent.agent} · ${agent.status} · ${agent.runtime} · ${activityText(agent)}${outputWarning(manifest, agent)}${agent.error ? ` · error=${agent.error}` : ""}`;
-}
-
-export function buildAgentDashboard(manifest: TeamRunManifest): { text: string; groups: Record<string, CrewAgentRecord[]> } {
-	const agents = readCrewAgents(manifest);
-	const groups: Record<string, CrewAgentRecord[]> = {
-		running: agents.filter((agent) => agent.status === "running"),
-		queued: agents.filter((agent) => agent.status === "queued"),
-		recent: agents.filter((agent) => agent.status !== "running" && agent.status !== "queued"),
-	};
-	const lines = [
-		`Crew agents for ${manifest.runId}`,
-		`Run: ${manifest.status} · ${manifest.team}/${manifest.workflow ?? "none"} · agents=${agents.length}`,
-		`Counts: running=${groups.running.length}, queued=${groups.queued.length}, recent=${groups.recent.length}`,
-		"",
-		"## Running",
-		...(groups.running.length ? groups.running.map((agent) => agentLine(manifest, agent)) : ["- (none)"]),
-		"",
-		"## Queued",
-		...(groups.queued.length ? groups.queued.map((agent) => agentLine(manifest, agent)) : ["- (none)"]),
-		"",
-		"## Recent",
-		...(groups.recent.length ? groups.recent.slice(-10).map((agent) => agentLine(manifest, agent)) : ["- (none)"]),
-	];
-	return { text: lines.join("\n"), groups };
-}
-
-export function readAgentOutput(manifest: TeamRunManifest, taskId: string, maxBytes?: number): TextTailResult {
-	return readTextTail(agentOutputPath(manifest, taskId), maxBytes);
-}
+import * as fs from "node:fs";
+import type { TeamRunManifest } from "../state/types.ts";
+import { agentOutputPath, readCrewAgents } from "./crew-agent-records.ts";
+import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
+
+const TOOL_LABELS: Record<string, string> = {
+	read: "reading",
+	bash: "running command",
+	edit: "editing",
+	write: "writing",
+	grep: "searching",
+	find: "finding files",
+	ls: "listing",
+};
+
+export interface TextTailResult {
+	path: string;
+	text: string;
+	bytes: number;
+	truncated: boolean;
+}
+
+export function readTextTail(filePath: string, maxBytes = 64_000): TextTailResult {
+	if (!fs.existsSync(filePath)) return { path: filePath, text: "", bytes: 0, truncated: false };
+	const stat = fs.statSync(filePath);
+	const bytesToRead = Math.min(stat.size, Math.max(0, maxBytes));
+	const fd = fs.openSync(filePath, "r");
+	try {
+		const buffer = Buffer.alloc(bytesToRead);
+		fs.readSync(fd, buffer, 0, bytesToRead, stat.size - bytesToRead);
+		return { path: filePath, text: buffer.toString("utf-8"), bytes: stat.size, truncated: stat.size > bytesToRead };
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+
+function compactDuration(ms: number | undefined): string | undefined {
+	if (ms === undefined || !Number.isFinite(ms)) return undefined;
+	if (ms < 1000) return `${Math.round(ms)}ms`;
+	if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+	return `${Math.floor(ms / 60_000)}m${Math.floor((ms % 60_000) / 1000)}s`;
+}
+
+function ageBetween(start: string | undefined, end: string | undefined): string | undefined {
+	if (!start) return undefined;
+	const stop = end ? new Date(end).getTime() : Date.now();
+	const ms = Math.max(0, stop - new Date(start).getTime());
+	return compactDuration(ms);
+}
+
+function activityText(agent: CrewAgentRecord): string {
+	const parts: string[] = [];
+	if (agent.progress?.activityState) parts.push(agent.progress.activityState);
+	if (agent.progress?.currentTool) parts.push(TOOL_LABELS[agent.progress.currentTool] ?? `tool=${agent.progress.currentTool}`);
+	if (agent.toolUses !== undefined) parts.push(`tools=${agent.toolUses}`);
+	if (agent.progress?.tokens !== undefined) parts.push(`tokens=${agent.progress.tokens}`);
+	if (agent.progress?.turns !== undefined) parts.push(`turns=${agent.progress.turns}`);
+	const duration = compactDuration(agent.progress?.durationMs) ?? ageBetween(agent.startedAt, agent.completedAt);
+	if (duration) parts.push(duration);
+	if (agent.progress?.failedTool) parts.push(`failedTool=${agent.progress.failedTool}`);
+	if (agent.progress?.recentOutput?.length) parts.push(`last=${agent.progress.recentOutput.at(-1)}`);
+	return parts.join(" ") || "idle";
+}
+
+function statusGlyph(status: CrewAgentRecord["status"]): string {
+	if (status === "completed") return "✓";
+	if (status === "failed") return "✗";
+	if (status === "running") return "▶";
+	if (status === "cancelled" || status === "stopped") return "■";
+	return "·";
+}
+
+function outputWarning(manifest: TeamRunManifest, agent: CrewAgentRecord): string {
+	if (agent.status !== "completed") return "";
+	try {
+		const outputPath = agentOutputPath(manifest, agent.taskId);
+		if (!fs.existsSync(outputPath)) return " no-output";
+		return fs.statSync(outputPath).size === 0 ? " no-output" : "";
+	} catch {
+		return " no-output";
+	}
+}
+
+function agentLine(manifest: TeamRunManifest, agent: CrewAgentRecord): string {
+	return `- ${statusGlyph(agent.status)} ${agent.taskId} ${agent.role} → ${agent.agent} · ${agent.status} · ${agent.runtime} · ${activityText(agent)}${outputWarning(manifest, agent)}${agent.error ? ` · error=${agent.error}` : ""}`;
+}
+
+export function buildAgentDashboard(manifest: TeamRunManifest): { text: string; groups: Record<string, CrewAgentRecord[]> } {
+	const agents = readCrewAgents(manifest);
+	const groups: Record<string, CrewAgentRecord[]> = {
+		running: agents.filter((agent) => agent.status === "running"),
+		queued: agents.filter((agent) => agent.status === "queued"),
+		recent: agents.filter((agent) => agent.status !== "running" && agent.status !== "queued"),
+	};
+	const lines = [
+		`Crew agents for ${manifest.runId}`,
+		`Run: ${manifest.status} · ${manifest.team}/${manifest.workflow ?? "none"} · agents=${agents.length}`,
+		`Counts: running=${groups.running.length}, queued=${groups.queued.length}, recent=${groups.recent.length}`,
+		"",
+		"## Running",
+		...(groups.running.length ? groups.running.map((agent) => agentLine(manifest, agent)) : ["- (none)"]),
+		"",
+		"## Queued",
+		...(groups.queued.length ? groups.queued.map((agent) => agentLine(manifest, agent)) : ["- (none)"]),
+		"",
+		"## Recent",
+		...(groups.recent.length ? groups.recent.slice(-10).map((agent) => agentLine(manifest, agent)) : ["- (none)"]),
+	];
+	return { text: lines.join("\n"), groups };
+}
+
+export function readAgentOutput(manifest: TeamRunManifest, taskId: string, maxBytes?: number): TextTailResult {
+	return readTextTail(agentOutputPath(manifest, taskId), maxBytes);
+}

package/src/runtime/async-marker.ts

@@ -1,26 +1,26 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { atomicWriteJson } from "../state/atomic-write.ts";
-import type { TeamRunManifest } from "../state/types.ts";
-
-export interface AsyncStartMarker {
-	pid: number;
-	startedAt: string;
-}
-
-export function asyncStartMarkerPath(manifest: Pick<TeamRunManifest, "stateRoot">): string {
-	return path.join(manifest.stateRoot, "async.pid");
-}
-
-export function writeAsyncStartMarker(manifest: Pick<TeamRunManifest, "stateRoot">, marker: AsyncStartMarker): void {
-	atomicWriteJson(asyncStartMarkerPath(manifest), marker);
-}
-
-export function hasAsyncStartMarker(manifest: Pick<TeamRunManifest, "stateRoot">): boolean {
-	try {
-		const raw = JSON.parse(fs.readFileSync(asyncStartMarkerPath(manifest), "utf-8")) as Partial<AsyncStartMarker>;
-		return typeof raw.pid === "number" && Number.isInteger(raw.pid) && raw.pid > 0 && typeof raw.startedAt === "string" && raw.startedAt.length > 0;
-	} catch {
-		return false;
-	}
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteJson } from "../state/atomic-write.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+
+export interface AsyncStartMarker {
+	pid: number;
+	startedAt: string;
+}
+
+export function asyncStartMarkerPath(manifest: Pick<TeamRunManifest, "stateRoot">): string {
+	return path.join(manifest.stateRoot, "async.pid");
+}
+
+export function writeAsyncStartMarker(manifest: Pick<TeamRunManifest, "stateRoot">, marker: AsyncStartMarker): void {
+	atomicWriteJson(asyncStartMarkerPath(manifest), marker);
+}
+
+export function hasAsyncStartMarker(manifest: Pick<TeamRunManifest, "stateRoot">): boolean {
+	try {
+		const raw = JSON.parse(fs.readFileSync(asyncStartMarkerPath(manifest), "utf-8")) as Partial<AsyncStartMarker>;
+		return typeof raw.pid === "number" && Number.isInteger(raw.pid) && raw.pid > 0 && typeof raw.startedAt === "string" && raw.startedAt.length > 0;
+	} catch {
+		return false;
+	}
+}

package/src/runtime/attention-events.ts

@@ -1,28 +1,28 @@
-import { appendEvent, readEvents } from "../state/event-log.ts";
-import type { CrewAttentionEventData, TeamRunManifest } from "../state/types.ts";
-
-export interface AppendTaskAttentionInput {
-	manifest: TeamRunManifest;
-	taskId?: string;
-	message: string;
-	data: CrewAttentionEventData;
-}
-
-export function appendTaskAttentionEvent(input: AppendTaskAttentionInput): boolean {
-	const recent = readEvents(input.manifest.eventsPath).slice(-200);
-	const dedupKey = `${input.taskId ?? ""}:${input.data.reason}:${input.data.activityState}`;
-	const duplicate = recent.some(
-		(event) =>
-			event.type === "task.attention" &&
-			`${event.taskId ?? ""}:${event.data?.reason ?? ""}:${event.data?.activityState ?? ""}` === dedupKey,
-	);
-	if (duplicate) return false;
-	appendEvent(input.manifest.eventsPath, {
-		type: "task.attention",
-		runId: input.manifest.runId,
-		taskId: input.taskId,
-		message: input.message,
-		data: { ...input.data },
-	});
-	return true;
-}
+import { appendEvent, readEvents } from "../state/event-log.ts";
+import type { CrewAttentionEventData, TeamRunManifest } from "../state/types.ts";
+
+export interface AppendTaskAttentionInput {
+	manifest: TeamRunManifest;
+	taskId?: string;
+	message: string;
+	data: CrewAttentionEventData;
+}
+
+export function appendTaskAttentionEvent(input: AppendTaskAttentionInput): boolean {
+	const recent = readEvents(input.manifest.eventsPath).slice(-200);
+	const dedupKey = `${input.taskId ?? ""}:${input.data.reason}:${input.data.activityState}`;
+	const duplicate = recent.some(
+		(event) =>
+			event.type === "task.attention" &&
+			`${event.taskId ?? ""}:${event.data?.reason ?? ""}:${event.data?.activityState ?? ""}` === dedupKey,
+	);
+	if (duplicate) return false;
+	appendEvent(input.manifest.eventsPath, {
+		type: "task.attention",
+		runId: input.manifest.runId,
+		taskId: input.taskId,
+		message: input.message,
+		data: { ...input.data },
+	});
+	return true;
+}

package/src/runtime/auto-resume.ts

@@ -0,0 +1,100 @@
+/**
+ * Auto-resume controller with settle window — prevents premature context injection
+ * by waiting for Pi's setTimeout(0) + setTimeout(100) to drain before resuming.
+ *
+ * Distilled from pi-autoresearch's auto-resume / settle-window pattern.
+ */
+
+/** Time to wait before auto-resuming (ms). Outlasts Pi's setTimeout(0) + setTimeout(100). */
+export const SETTLE_WINDOW_MS = 800;
+
+/** Maximum number of auto-resume turns before forcing a stop. */
+export const MAX_AUTORESUME_TURNS = 20;
+
+/**
+ * Controller for scheduling auto-resume actions with a settle window.
+ *
+ * The settle window ensures that pending async operations (e.g., Pi's
+ * internal setTimeout(0) and setTimeout(100) callbacks) have completed
+ * before the resume callback fires.
+ */
+export class AutoResumeController {
+	private timerId: ReturnType<typeof setTimeout> | null = null;
+	private turnCount = 0;
+	private cancelled = false;
+
+	/**
+	 * Get the current auto-resume turn count.
+	 */
+	get currentTurnCount(): number {
+		return this.turnCount;
+	}
+
+	/**
+	 * Get the maximum allowed auto-resume turns.
+	 */
+	get maxTurns(): number {
+		return MAX_AUTORESUME_TURNS;
+	}
+
+	/**
+	 * Schedule an auto-resume callback after the settle window elapses.
+	 *
+	 * If a resume is already pending, it is cancelled first (debounce behavior).
+	 * If the turn limit has been reached, the callback is not scheduled.
+	 *
+	 * @param message - Description of why the resume is being scheduled
+	 * @param callback - Function to call after the settle window
+	 */
+	scheduleResume(message: string, callback: () => void): void {
+		// Cancel any existing pending resume
+		this.cancelResume();
+
+		// Enforce turn limit
+		if (this.turnCount >= MAX_AUTORESUME_TURNS) {
+			return;
+		}
+
+		this.cancelled = false;
+		this.turnCount++;
+
+		this.timerId = setTimeout(() => {
+			if (!this.cancelled) {
+				this.timerId = null;
+				callback();
+			}
+		}, SETTLE_WINDOW_MS);
+
+		// Prevent the timer from keeping the process alive
+		if (this.timerId && typeof this.timerId === "object" && "unref" in this.timerId) {
+			this.timerId.unref();
+		}
+	}
+
+	/**
+	 * Cancel any pending auto-resume.
+	 */
+	cancelResume(): void {
+		if (this.timerId !== null) {
+			clearTimeout(this.timerId);
+			this.timerId = null;
+		}
+		this.cancelled = true;
+	}
+
+	/**
+	 * Check whether an auto-resume is currently pending.
+	 */
+	hasPendingResume(): boolean {
+		return this.timerId !== null;
+	}
+
+	/**
+	 * Reset the turn counter. Called when a new agent starts processing
+	 * to allow a fresh set of auto-resume turns.
+	 */
+	resetTurnCount(): void {
+		this.turnCount = 0;
+		this.cancelled = false;
+	}
+}

package/src/runtime/background-runner.ts

@@ -4,7 +4,17 @@ import { appendEvent } from "../state/event-log.ts";
 import { loadRunManifestById, saveRunManifest, updateRunStatus } from "../state/state-store.ts";
 import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
 import { loadConfig } from "../config/config.ts";
-import { executeTeamRun } from "./team-runner.ts";
+// Heavy runtime — lazy-loaded to avoid pulling team-runner into background-runner
+// at module load time. Only needed when a background run actually starts.
+import type { executeTeamRun as ExecuteTeamRunFn } from "./team-runner.ts";
+let _cachedExecuteTeamRun: typeof ExecuteTeamRunFn | undefined;
+async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Promise<Awaited<ReturnType<typeof ExecuteTeamRunFn>>> {
+	if (!_cachedExecuteTeamRun) {
+		const mod = await import("./team-runner.ts");
+		_cachedExecuteTeamRun = mod.executeTeamRun;
+	}
+	return _cachedExecuteTeamRun(...args);
+}
 import { resolveCrewRuntime, runtimeResolutionState } from "./runtime-resolver.ts";
 import { directTeamAndWorkflowFromRun } from "./direct-run.ts";
 import { expandParallelResearchWorkflow } from "./parallel-research.ts";

package/src/runtime/cancellation-token.ts

@@ -1,89 +1,89 @@
-import { CrewCancellationError, type CancellationReason, 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);
-}
+import { CrewCancellationError, type CancellationReason, 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);
+}