@underactive/pi-topping-moa-fusion 0.1.0

package/src/planning/tools/writePlan.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { getPlanFilePath, writePlan } from "../planFile.ts";
+
+export function registerWritePlanTool(pi: ExtensionAPI, isEnabled: () => boolean): void {
+	pi.registerTool({
+		name: "write_plan",
+		label: "Write Plan",
+		description: "Write or update content in the plan file. This is the ONLY file you can write during plan mode. Use this to build your plan incrementally.",
+		parameters: Type.Object({
+			content: Type.String({ description: "The full content to write to the plan file (replaces existing content)" }),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			if (!isEnabled()) {
+				return {
+					details: undefined,
+					content: [{ type: "text", text: "Error: Not in plan mode. Use /mf-plan to enter plan mode first." }],
+					isError: true,
+				};
+			}
+
+			const filePath = getPlanFilePath();
+			writePlan(params.content);
+
+			return {
+				content: [{ type: "text", text: `Plan written to ${filePath} (${params.content.length} chars)` }],
+				details: { filePath, length: params.content.length },
+			};
+		},
+	});
+}

package/src/runtime/activityTracking.ts

@@ -0,0 +1,141 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { AssistantMessage, Message } from "@earendil-works/pi-ai";
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+import { StreamingWordCounter } from "../activityMeter.ts";
+import { isNonnegativeFiniteNumber, isValidContentIndex, type WireAssistantMessageEvent } from "./wire.ts";
+
+/** Max length of a one-line tool-activity description surfaced for progress UIs. */
+const ACTIVITY_MAX = 80;
+
+/** Collapse all whitespace/newlines to single spaces and trim. */
+function collapseWhitespace(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Pick the most informative string argument for a one-line activity label.
+ * Prefers well-known tool arg names (command, pattern, path, …); falls back to
+ * the first non-empty string value.
+ */
+function summarizeToolArgs(args: unknown): string {
+	if (!args || typeof args !== "object") return "";
+	const record = args as Record<string, unknown>;
+	const preferred = ["command", "pattern", "query", "path", "file", "glob", "dir", "url", "name"];
+	for (const key of preferred) {
+		const value = record[key];
+		if (typeof value === "string" && value.trim()) return collapseWhitespace(value);
+	}
+	for (const value of Object.values(record)) {
+		if (typeof value === "string" && value.trim()) return collapseWhitespace(value);
+	}
+	return "";
+}
+
+/** Format a `tool_execution_start` event into a single-line "toolName  arg" label. */
+export function formatToolActivity(toolName: string, args: unknown): string {
+	const detail = summarizeToolArgs(args);
+	const label = detail ? `${toolName}  ${detail}` : String(toolName);
+	return stripTerminalSequences(collapseWhitespace(label).slice(0, ACTIVITY_MAX));
+}
+
+/** Cumulative generated-output reading for the fan-out activity monitor. */
+export interface OutputActivity {
+	/** Tokens generated so far this run: confirmed turns plus the in-flight turn. */
+	tokens: number;
+	/**
+	 * Bumped whenever exact provider usage replaces a differing estimate.
+	 * Consumers reset their rate tracker on a change so the correction doesn't
+	 * register as a burst of generation that never happened.
+	 */
+	revision: number;
+}
+
+export class OutputActivityTracker {
+	#counter = new StreamingWordCounter();
+	#confirmed = 0;
+	#liveWords = 0;
+	#revision = 0;
+
+	/** Begin a new assistant turn, discarding only the previous turn's live estimate. */
+	messageStart(message: { role?: string } | undefined): void {
+		if (message?.role !== "assistant") return;
+		this.#resetTurn();
+	}
+
+	messageUpdate(assistantEvent: { type?: string; delta?: string } | undefined): void {
+		if (assistantEvent?.type !== "text_delta" && assistantEvent?.type !== "thinking_delta") return;
+		if (typeof assistantEvent.delta !== "string") return;
+		// Counted per stream kind so a word split across deltas isn't double
+		// counted, and interleaved thinking/text streams don't corrupt each other.
+		this.#liveWords += this.#counter.count(assistantEvent.delta, assistantEvent.type);
+	}
+
+	messageEnd(message: { role?: string; usage?: { output?: unknown } } | undefined): void {
+		if (message?.role !== "assistant") return;
+		const exact = message.usage?.output;
+		if (isNonnegativeFiniteNumber(exact)) {
+			this.#confirmed += exact;
+			if (exact !== this.#liveWords) this.#revision++;
+		} else {
+			this.#confirmed += this.#liveWords;
+		}
+		this.#resetTurn();
+	}
+
+	snapshot(): OutputActivity {
+		return { tokens: this.#confirmed + this.#liveWords, revision: this.#revision };
+	}
+
+	#resetTurn(): void {
+		this.#liveWords = 0;
+		this.#counter.reset();
+	}
+}
+
+type AssistantContentPart = AssistantMessage["content"][number];
+
+/**
+ * Rebuilds the in-flight assistant message from streamed deltas.
+ *
+ * `message_update` carries only `contentIndex`-addressed deltas, so a live view
+ * of what an agent is writing has to be reassembled client-side. Tool calls
+ * materialise only at `toolcall_end`, once their arguments have finished
+ * streaming and are parseable.
+ */
+export class PartialAssistantAssembler {
+	#template: AssistantMessage | undefined;
+	#parts: (AssistantContentPart | undefined)[] = [];
+
+	start(message: AgentMessage | undefined): void {
+		this.#template = message?.role === "assistant" ? message : undefined;
+		this.#parts = [];
+	}
+
+	apply(assistantEvent: WireAssistantMessageEvent | undefined): void {
+		if (!assistantEvent) return;
+		if (("contentIndex" in assistantEvent && !isValidContentIndex(assistantEvent.contentIndex))) return;
+		if (assistantEvent.type === "text_delta") {
+			const part = this.#parts[assistantEvent.contentIndex];
+			if (part?.type === "text") part.text += assistantEvent.delta;
+			else this.#parts[assistantEvent.contentIndex] = { type: "text", text: assistantEvent.delta };
+		} else if (assistantEvent.type === "thinking_delta") {
+			const part = this.#parts[assistantEvent.contentIndex];
+			if (part?.type === "thinking") part.thinking += assistantEvent.delta;
+			else this.#parts[assistantEvent.contentIndex] = { type: "thinking", thinking: assistantEvent.delta };
+		} else if (assistantEvent.type === "toolcall_end") {
+			this.#parts[assistantEvent.contentIndex] = assistantEvent.toolCall;
+		}
+	}
+
+	/** The message as it currently stands, or undefined before any content arrives. */
+	snapshot(): Message | undefined {
+		if (!this.#template) return undefined;
+		const content = this.#parts.filter((part) => part !== undefined);
+		return content.length > 0 ? { ...this.#template, content } : undefined;
+	}
+
+	clear(): void {
+		this.#template = undefined;
+		this.#parts = [];
+	}
+}

package/src/runtime/cancelRun.ts

@@ -0,0 +1,134 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isKeyRelease, Key, matchesKey } from "@earendil-works/pi-tui";
+
+/**
+ * Cancellation registry for in-flight subagent processes.
+ *
+ * One CancelRun is created per orchestration phase (MoA fan-out, synthesis
+ * round, tool-call parallel run). Each agent slot gets its own
+ * AbortController; the combined signal handed to runSingleAgent also folds in
+ * a run-wide "cancel all" controller and any upstream signal (e.g. pi's
+ * turn-abort signal in the mf_plan_subagent tool path).
+ *
+ * Slot indices are positional and shared by construction with the arrays the
+ * orchestrators build from the same source list: proposers[i] ↔ widget
+ * statuses[i] ↔ run.agents[i].
+ */
+
+export type AgentCancelState = "running" | "cancelling" | "done" | "error" | "cancelled";
+
+export interface TrackedAgent {
+	/** Display label, e.g. "openai/gpt-5.2" or "explore #1". */
+	label: string;
+	state: AgentCancelState;
+	controller: AbortController;
+}
+
+export class CancelRun {
+	readonly agents: TrackedAgent[] = [];
+	cancelAllRequested = false;
+	private readonly allController = new AbortController();
+	private readonly listeners = new Set<() => void>();
+
+	/** Register one agent slot; returns its index and the combined abort signal. */
+	add(label: string, upstream?: AbortSignal): { index: number; signal: AbortSignal } {
+		const controller = new AbortController();
+		this.agents.push({ label, state: "running", controller });
+		const signals = [controller.signal, this.allController.signal];
+		if (upstream) signals.push(upstream);
+		return { index: this.agents.length - 1, signal: AbortSignal.any(signals) };
+	}
+
+	/** Cancel one agent. No-op unless it is still running (race-safe: an agent may settle while the overlay is open). */
+	cancel(index: number): void {
+		const agent = this.agents[index];
+		if (!agent || agent.state !== "running") return;
+		agent.state = "cancelling";
+		agent.controller.abort();
+		this.notify();
+	}
+
+	/** Cancel every running agent and mark the whole run as user-cancelled. */
+	cancelAll(): void {
+		if (this.cancelAllRequested) return;
+		this.cancelAllRequested = true;
+		for (const agent of this.agents) {
+			if (agent.state === "running") agent.state = "cancelling";
+		}
+		this.allController.abort();
+		this.notify();
+	}
+
+	/** Record an agent's final state once its subprocess result arrives. */
+	settle(index: number, state: "done" | "error" | "cancelled"): void {
+		const agent = this.agents[index];
+		if (!agent) return;
+		agent.state = state;
+		this.notify();
+	}
+
+	/** Subscribe to state changes (for live overlay re-renders). Returns an unsubscribe function. */
+	onChange(listener: () => void): () => void {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+
+	private notify(): void {
+		for (const listener of this.listeners) listener();
+	}
+}
+
+/** Extra per-row display data echoed from the progress widget / tool progress. */
+export interface CancelRowExtras {
+	contextTokens?: number;
+	contextWindow?: number;
+	activity?: string;
+	loopCount?: number;
+}
+
+/**
+ * Published by an orchestrator while agents are in flight so the input
+ * triggers (ESC listener, F4 shortcut) can find the live run and
+ * open the cancel overlay against it.
+ */
+export interface CancelSession {
+	/** Overlay title, e.g. "MoA fan-out — running proposers". */
+	title: string;
+	/** The live run, or undefined when nothing is in flight (ESC passes through). */
+	run: CancelRun | undefined;
+	/** Optional per-row display extras (context bar, tool activity, loop badge). */
+	getExtras?: (index: number) => CancelRowExtras | undefined;
+	/** True while the cancel overlay is mounted; guards double-open races. */
+	overlayOpen: boolean;
+	/** Registered by the overlay while open so orchestrators can force-close it before competing UIs. */
+	closeOverlay?: () => void;
+}
+
+export interface CancelOverlayEscHost {
+	getActiveObserveSession(): { overlayOpen: boolean } | undefined;
+	openCancelOverlayIfActive(ctx: ExtensionContext): boolean;
+}
+
+/**
+ * Subscribes ESC to open the cancel overlay while `session.run` is in
+ * flight, passing ESC through otherwise so the editor, model pickers, and
+ * observe overlay keep their own ESC handling. Terminal input listeners run
+ * ahead of pi's key-release filter, so under the Kitty keyboard protocol the
+ * ESC *release* arrives here a tick after the press closed an overlay and
+ * cleared `overlayOpen` — reopening it instantly. Only a key press may open
+ * the overlay. Returns undefined outside the TUI.
+ */
+export function subscribeCancelOverlayOnEsc(
+	ctx: ExtensionContext,
+	host: CancelOverlayEscHost,
+	session: CancelSession,
+): (() => void) | undefined {
+	if (ctx.mode !== "tui") return undefined;
+	return ctx.ui.onTerminalInput((data) => {
+		if (isKeyRelease(data) || !matchesKey(data, Key.escape)) return undefined;
+		if (host.getActiveObserveSession()?.overlayOpen) return undefined;
+		if (session.overlayOpen) return undefined;
+		if (!session.run) return undefined;
+		return host.openCancelOverlayIfActive(ctx) ? { consume: true } : undefined;
+	});
+}

package/src/runtime/mutationTripwire.ts

@@ -0,0 +1,251 @@
+/**
+ * Working-tree mutation tripwire for plan mode.
+ *
+ * Plan-mode subprocesses are spawned read-only (pi `--tools` allowlist plus
+ * the PI_CURSOR_FORCE_MODE handshake for agentic provider bridges), but that
+ * boundary is ultimately cooperative for providers that run full agents with
+ * their own local tools outside pi's tool loop. This module detects — via
+ * `git status --porcelain` snapshots — any working-tree change that appears
+ * while planning agents run, so the orchestration can warn loudly instead of
+ * silently absorbing rogue edits.
+ */
+
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { mapWithConcurrencyLimit } from "./processPool.ts";
+
+const execFileAsync = promisify(execFile);
+
+/** `git status --porcelain` snapshot, or null when unavailable (not a git repo, no git). */
+export async function captureWorkingTreeState(cwd: string): Promise<string | null> {
+	try {
+		const { stdout } = await execFileAsync("git", ["status", "--porcelain=v1", "-z"], {
+			cwd,
+			maxBuffer: 10 * 1024 * 1024,
+		});
+		const fields = stdout.split("\0");
+		const lines: string[] = [];
+		for (let index = 0; index < fields.length; index++) {
+			const field = fields[index];
+			if (!field) continue;
+			const status = field.slice(0, 2);
+			const destination = field.slice(3);
+			if (status.includes("R") || status.includes("C")) {
+				const source = fields[++index];
+				if (source === undefined) continue;
+				lines.push(`${status} ${JSON.stringify(source)} -> ${JSON.stringify(destination)}`);
+			} else {
+				lines.push(`${status} ${JSON.stringify(destination)}`);
+			}
+		}
+		return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+	} catch {
+		return null;
+	}
+}
+
+interface PorcelainEntry {
+	displayPath: string;
+	relativePath: string;
+}
+
+function parseJsonPathPrefix(value: string): { path: string; end: number } | undefined {
+	if (!value.startsWith('"')) return undefined;
+	let escaped = false;
+	for (let index = 1; index < value.length; index++) {
+		const char = value[index];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (char === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (char !== '"') continue;
+		try {
+			const parsed: unknown = JSON.parse(value.slice(0, index + 1));
+			return typeof parsed === "string" ? { path: parsed, end: index + 1 } : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+	return undefined;
+}
+
+/** Parse canonical JSON-quoted snapshots and legacy human-readable porcelain lines. */
+function parsePorcelainEntry(line: string): PorcelainEntry {
+	const field = line.slice(3).trim();
+	const first = parseJsonPathPrefix(field);
+	if (first) {
+		const remainder = field.slice(first.end);
+		if (remainder.startsWith(" -> ")) {
+			const second = parseJsonPathPrefix(remainder.slice(4));
+			if (second) return { displayPath: `${first.path} -> ${second.path}`, relativePath: second.path };
+		}
+		return { displayPath: first.path, relativePath: first.path };
+	}
+	const renameAt = field.lastIndexOf(" -> ");
+	return renameAt >= 0
+		? { displayPath: field, relativePath: field.slice(renameAt + 4) }
+		: { displayPath: field, relativePath: field };
+}
+
+/** "XY path" / "XY old -> new" porcelain line → displayable path. */
+export function porcelainPath(line: string): string {
+	return parsePorcelainEntry(line).displayPath;
+}
+
+const MAX_HASH_FILE_BYTES = 16 * 1024 * 1024;
+const MAX_HASH_DIRECTORY_BYTES = 16 * 1024 * 1024;
+const MAX_HASH_DIRECTORY_ENTRIES = 2048;
+
+interface DirectoryEntryFingerprint {
+	hash: string;
+	statSignature: string;
+}
+
+async function fingerprintDirectory(
+	directory: string,
+	previous?: WorkingTreeFingerprint,
+): Promise<WorkingTreeFingerprint> {
+	const hash = createHash("sha256");
+	const directoryEntries = new Map<string, DirectoryEntryFingerprint>();
+	let entryCount = 0;
+	let contentBytes = 0;
+	let truncated = false;
+
+	const walk = async (current: string, prefix: string): Promise<void> => {
+		const entries = await readdir(current, { withFileTypes: true });
+		entries.sort((left, right) => left.name.localeCompare(right.name));
+		for (const entry of entries) {
+			if (entryCount >= MAX_HASH_DIRECTORY_ENTRIES) {
+				truncated = true;
+				return;
+			}
+			entryCount++;
+			const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+			const entryPath = path.join(current, entry.name);
+			const metadata = await lstat(entryPath);
+			const kind = entry.isDirectory() ? "d" : entry.isFile() ? "f" : entry.isSymbolicLink() ? "l" : "o";
+			hash.update(`${kind}:${relative}:${metadata.size}:${metadata.mtimeMs}\0`);
+			if (entry.isDirectory()) {
+				await walk(entryPath, relative);
+				if (truncated) return;
+			} else if (entry.isFile()
+				&& metadata.size <= MAX_HASH_FILE_BYTES
+				&& contentBytes + metadata.size <= MAX_HASH_DIRECTORY_BYTES) {
+				const statSignature = `${metadata.size}:${metadata.mtimeMs}`;
+				const prior = previous?.directoryEntries?.get(relative);
+				const contentHash = prior?.statSignature === statSignature
+					? prior.hash
+					: createHash("sha256").update(await readFile(entryPath)).digest("hex");
+				contentBytes += metadata.size;
+				directoryEntries.set(relative, { hash: contentHash, statSignature });
+				hash.update(contentHash);
+			}
+		}
+	};
+
+	await walk(directory, "");
+	return {
+		hash: `directory:${entryCount}:${contentBytes}:${truncated ? "truncated" : "complete"}:${hash.digest("hex")}`,
+		directoryEntries,
+	};
+}
+
+export interface WorkingTreeFingerprint {
+	hash: string;
+	statSignature?: string;
+	directoryEntries?: ReadonlyMap<string, DirectoryEntryFingerprint>;
+}
+
+/** Fingerprint every path currently mentioned by porcelain output. */
+export async function hashWorkingTreeFiles(
+	cwd: string,
+	porcelain: string,
+	previous?: ReadonlyMap<string, WorkingTreeFingerprint>,
+): Promise<Map<string, WorkingTreeFingerprint>> {
+	const fingerprints = new Map<string, WorkingTreeFingerprint>();
+	const root = path.resolve(cwd);
+	await mapWithConcurrencyLimit(porcelain.split("\n").filter(Boolean), 8, async (line) => {
+		const { displayPath, relativePath } = parsePorcelainEntry(line);
+		try {
+			const filePath = path.resolve(root, relativePath);
+			if (filePath !== root && !filePath.startsWith(`${root}${path.sep}`)) throw new Error("Path escapes repository");
+			const metadata = await lstat(filePath);
+			if (metadata.isDirectory()) {
+				fingerprints.set(displayPath, await fingerprintDirectory(filePath, previous?.get(displayPath)));
+				return;
+			}
+			const statSignature = `${metadata.size}:${metadata.mtimeMs}`;
+			if (!metadata.isFile() || metadata.size > MAX_HASH_FILE_BYTES) {
+				fingerprints.set(displayPath, { hash: statSignature, statSignature });
+				return;
+			}
+			const prior = previous?.get(displayPath);
+			if (prior?.statSignature === statSignature) {
+				fingerprints.set(displayPath, prior);
+				return;
+			}
+			const content = await readFile(filePath);
+			fingerprints.set(displayPath, {
+				hash: createHash("sha256").update(content).digest("hex"),
+				statSignature,
+			});
+		} catch {
+			fingerprints.set(displayPath, { hash: "unreadable" });
+		}
+	});
+	return fingerprints;
+}
+
+/** Paths whose porcelain status differs between two snapshots (either direction). */
+export function diffWorkingTreeStates(before: string, after: string): string[] {
+	const beforeLines = new Set(before.split("\n").filter(Boolean));
+	const afterLines = new Set(after.split("\n").filter(Boolean));
+	const changed = new Set<string>();
+	for (const line of afterLines) if (!beforeLines.has(line)) changed.add(porcelainPath(line));
+	for (const line of beforeLines) if (!afterLines.has(line)) changed.add(porcelainPath(line));
+	return [...changed];
+}
+
+export class MutationTripwire {
+	private baseline: string | null = null;
+	private baselineHashes: Map<string, WorkingTreeFingerprint> | null = null;
+
+	/** Snapshot the working tree before spawning planning agents. */
+	async arm(cwd: string): Promise<void> {
+		this.baseline = await captureWorkingTreeState(cwd);
+		this.baselineHashes = this.baseline === null ? null : await hashWorkingTreeFiles(cwd, this.baseline);
+	}
+
+	/**
+	 * Paths changed since the last arm()/check(). Re-baselines on every call so
+	 * subsequent checks only report NEW changes (a fan-out warning is not
+	 * repeated after synthesis). Returns [] when git state is unavailable.
+	 */
+	async check(cwd: string): Promise<string[]> {
+		if (this.baseline === null) return [];
+		const current = await captureWorkingTreeState(cwd);
+		if (current === null) return [];
+		const currentHashes = await hashWorkingTreeFiles(cwd, current, this.baselineHashes ?? undefined);
+		const changed = new Set(diffWorkingTreeStates(this.baseline, current));
+		for (const path of new Set([...(this.baselineHashes?.keys() ?? []), ...currentHashes.keys()])) {
+			if (this.baselineHashes?.get(path)?.hash !== currentHashes.get(path)?.hash) changed.add(path);
+		}
+		this.baseline = current;
+		this.baselineHashes = currentHashes;
+		return [...changed];
+	}
+}
+
+/** One-line warning for a non-empty change set, capped for notify() display. */
+export function formatMutationWarning(phase: string, changed: string[]): string {
+	const shown = changed.slice(0, 6).join(", ");
+	const more = changed.length > 6 ? ` (+${changed.length - 6} more)` : "";
+	return `⚠ Repo files changed during ${phase} — planning agents must never modify the working tree. Review with git status / git diff: ${shown}${more}`;
+}

package/src/runtime/processPool.ts

@@ -0,0 +1,55 @@
+import { type ChildProcess } from "node:child_process";
+
+/** Globally tracked spawned processes so /reload can kill them. */
+export const trackedProcesses: Set<ChildProcess> = new Set();
+
+/** Send SIGTERM, then force a still-live child down after the grace period. */
+export function escalateKill(proc: ChildProcess, termTimeoutMs = 5000): void {
+	if (proc.exitCode !== null || proc.signalCode !== null) return;
+	try { proc.kill("SIGTERM"); } catch { return; }
+	setTimeout(() => {
+		if (proc.exitCode !== null || proc.signalCode !== null) return;
+		try { proc.kill("SIGKILL"); } catch { /* ignore */ }
+	}, termTimeoutMs).unref();
+}
+
+/** Kill every tracked process. Safe to call multiple times. */
+export function cleanupTrackedProcesses(termTimeoutMs = 5000): void {
+	// Snapshot targets before clearing so the delayed SIGKILL pass still
+	// reaches the same processes that were just signalled.
+	const processes = [...trackedProcesses];
+	for (const proc of processes) {
+		if (proc.exitCode !== null || proc.signalCode !== null) continue;
+		try { proc.kill("SIGTERM"); } catch { /* ignore */ }
+	}
+	trackedProcesses.clear();
+
+	// Give SIGTERM a moment, then SIGKILL any process that has not exited.
+	setTimeout(() => {
+		for (const proc of processes) {
+			if (proc.exitCode !== null || proc.signalCode !== null) continue;
+			try { proc.kill("SIGKILL"); } catch { /* ignore */ }
+		}
+	}, termTimeoutMs).unref();
+}
+
+
+export async function mapWithConcurrencyLimit<TIn, TOut>(
+	items: TIn[],
+	concurrency: number,
+	fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+	if (items.length === 0) return [];
+	const limit = Math.max(1, Math.min(concurrency, items.length));
+	const results: TOut[] = new Array(items.length);
+	let nextIndex = 0;
+	const workers = new Array(limit).fill(null).map(async () => {
+		while (true) {
+			const current = nextIndex++;
+			if (current >= items.length) return;
+			results[current] = await fn(items[current], current);
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}