pi-crew 0.9.53 → 0.9.55

package/src/extension/tool-result.ts

@@ -0,0 +1,16 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { TeamToolDetails } from "./team-tool-types.ts";
+
+export type PiTeamsToolResult<TDetails = TeamToolDetails> = AgentToolResult<TDetails> & { isError?: boolean };
+
+export function toolResult<TDetails>(text: string, details: TDetails, isError = false): PiTeamsToolResult<TDetails> {
+	return { content: [{ type: "text", text }], details, isError };
+}
+
+export function isToolError(result: { isError?: boolean }): boolean {
+	return result.isError === true;
+}
+
+export function textFromToolResult(result: { content?: Array<{ type: string; text?: string }> }): string {
+	return result.content?.map((item) => item.text ?? "").join("\n") ?? "";
+}

package/src/extension/validate-resources.ts

@@ -0,0 +1,108 @@
+import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
+import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
+import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
+import { validateWorkflowForTeam } from "../workflows/validate-workflow.ts";
+
+export interface ValidationIssue {
+	level: "error" | "warning";
+	resource: string;
+	message: string;
+}
+
+export interface ValidationReport {
+	issues: ValidationIssue[];
+	agents: number;
+	teams: number;
+	workflows: number;
+}
+
+export function validateResources(cwd: string): ValidationReport {
+	const agents = allAgents(discoverAgents(cwd));
+	const teams = allTeams(discoverTeams(cwd));
+	const workflows = allWorkflows(discoverWorkflows(cwd));
+	const agentNames = new Set(agents.map((agent) => agent.name));
+	const workflowNames = new Set(workflows.map((workflow) => workflow.name));
+	const issues: ValidationIssue[] = [];
+
+	for (const agent of agents) {
+		const modelValues = [agent.model, ...(agent.fallbackModels ?? [])].filter(
+			(value): value is string => typeof value === "string" && value.length > 0,
+		);
+		for (const model of modelValues) {
+			if (/\s/.test(model)) {
+				issues.push({
+					level: "warning",
+					resource: `agent:${agent.name}`,
+					message: `Model reference '${model}' contains whitespace.`,
+				});
+			}
+			if (model.includes("/") && model.split("/").some((part) => part.trim() === "")) {
+				issues.push({
+					level: "warning",
+					resource: `agent:${agent.name}`,
+					message: `Model reference '${model}' has an empty provider/model segment.`,
+				});
+			}
+		}
+	}
+
+	for (const team of teams) {
+		for (const role of team.roles) {
+			if (!agentNames.has(role.agent)) {
+				issues.push({
+					level: "error",
+					resource: `team:${team.name}`,
+					message: `Role '${role.name}' references unknown agent '${role.agent}'.`,
+				});
+			}
+		}
+		if (team.defaultWorkflow && !workflowNames.has(team.defaultWorkflow)) {
+			issues.push({
+				level: "error",
+				resource: `team:${team.name}`,
+				message: `defaultWorkflow references unknown workflow '${team.defaultWorkflow}'.`,
+			});
+		}
+		const workflow = workflows.find((candidate) => candidate.name === team.defaultWorkflow);
+		if (workflow) {
+			for (const error of validateWorkflowForTeam(workflow, team)) {
+				issues.push({
+					level: "error",
+					resource: `workflow:${workflow.name}`,
+					message: `Team '${team.name}': ${error}`,
+				});
+			}
+		}
+	}
+
+	for (const workflow of workflows) {
+		if (workflow.steps.length === 0) {
+			issues.push({
+				level: "warning",
+				resource: `workflow:${workflow.name}`,
+				message: "Workflow has no steps.",
+			});
+		}
+	}
+
+	return {
+		issues,
+		agents: agents.length,
+		teams: teams.length,
+		workflows: workflows.length,
+	};
+}
+
+export function formatValidationReport(report: ValidationReport): string {
+	const lines = [
+		"pi-crew resource validation:",
+		`Agents: ${report.agents}`,
+		`Teams: ${report.teams}`,
+		`Workflows: ${report.workflows}`,
+		`Issues: ${report.issues.length}`,
+	];
+	if (report.issues.length > 0) {
+		lines.push("", ...report.issues.map((issue) => `- ${issue.level.toUpperCase()} ${issue.resource}: ${issue.message}`));
+	}
+	return lines.join("\n");
+}

package/src/hooks/registry.ts

@@ -0,0 +1,200 @@
+import { appendEvent } from "../state/event-log.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+import { runEventBus } from "../ui/run-event-bus.ts";
+import type { HookContext, HookDefinition, HookExecutionReport, HookName, HookResult } from "./types.ts";
+
+const registry = new Map<HookName, HookDefinition[]>();
+
+// Track hook IDs registered by pi-crew for scope-aware cleanup
+const _piCrewHookIds = new Set<number>();
+let _nextHookId = 1;
+
+// SECURITY: Hooks are currently global (registered once, applied to all workspaces).
+// For multi-workspace environments, consider filtering hooks by workspace scope:
+//   const workspaceHooks = getHooks(name).filter(h => !h.workspaceId || h.workspaceId === ctx.workspaceId);
+// This prevents globally-registered hooks from operating on runs they weren't designed for.
+
+export function registerHook(definition: HookDefinition): number {
+	const hookId = _nextHookId++;
+	_piCrewHookIds.add(hookId);
+	const hooks = registry.get(definition.name) ?? [];
+	hooks.push({ ...definition, _hookId: hookId });
+	registry.set(definition.name, hooks);
+	return hookId;
+}
+
+export function clearHooks(): void {
+	registry.clear();
+	_piCrewHookIds.clear();
+	_nextHookId = 1;
+}
+
+// Scope-aware hook clearing: only removes hooks registered by pi-crew
+export function clearHooksScoped(): void {
+	for (const [name, hooks] of registry) {
+		const remaining = hooks.filter((h) => !("_hookId" in h && _piCrewHookIds.has((h as { _hookId?: number })._hookId ?? -1)));
+		if (remaining.length === 0) {
+			registry.delete(name);
+		} else {
+			registry.set(name, remaining);
+		}
+	}
+	_piCrewHookIds.clear();
+	_nextHookId = 1;
+}
+
+export function getHooks(name: HookName): HookDefinition[] {
+	return registry.get(name) ?? [];
+}
+
+export async function executeHook(name: HookName, ctx: HookContext): Promise<HookExecutionReport> {
+	const hooks = getHooks(name);
+	if (hooks.length === 0) return { hookName: name, outcome: "allow", durationMs: 0 };
+	// SECURITY: Filter hooks by workspace scope.
+	//   - Global hooks (no workspaceId) match all contexts UNLESS ctx explicitly
+	//     opts out via `includeGlobalHooks: false`. This is the documented
+	//     behavior: "Hooks without workspaceId match ALL workspaces".
+	//   - Scoped hooks (workspaceId set) require an exact match with ctx.workspaceId.
+	//   - If ctx has no workspaceId, scoped hooks are excluded (they can't match).
+	//   - `includeGlobalHooks: true` on ctx forces inclusion of global hooks even
+	//     when ctx has a workspaceId.
+	const scopedHooks = hooks.filter((h) => {
+		// Scoped hook: must match ctx.workspaceId exactly
+		if (h.workspaceId !== undefined) {
+			return h.workspaceId === ctx.workspaceId;
+		}
+		// Global hook (no workspaceId): include unless ctx explicitly excludes
+		return ctx.includeGlobalHooks !== false;
+	});
+	if (scopedHooks.length === 0) return { hookName: name, outcome: "allow", durationMs: 0 };
+	const POLLUTED_KEYS = new Set(
+		[
+			"__proto__",
+			"constructor",
+			"prototype",
+			"hasOwnProperty",
+			"toString",
+			"valueOf",
+			"isPrototypeOf",
+			"propertyIsEnumerable",
+			"__defineGetter__",
+			"__defineSetter__",
+			"__lookupGetter__",
+			"__lookupSetter__",
+		].map((k) => k.toLowerCase().normalize("NFKC")),
+	);
+	function sanitizeMergeData(data: Record<string, unknown>): Record<string, unknown> {
+		const clean: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(data)) {
+			if (!POLLUTED_KEYS.has(k.toLowerCase().normalize("NFKC"))) {
+				if (v !== null && typeof v === "object") {
+					if (Array.isArray(v)) {
+						// Sanitize array elements that are objects
+						clean[k] = v.map((item) =>
+							item !== null && typeof item === "object" && !Array.isArray(item)
+								? sanitizeMergeData(item as Record<string, unknown>)
+								: item,
+						);
+					} else {
+						clean[k] = sanitizeMergeData(v as Record<string, unknown>);
+					}
+				} else {
+					clean[k] = v;
+				}
+			}
+		}
+		return clean;
+	}
+	// Sanitize ctx by stripping dangerous property names before passing to handlers.
+	// Hook authors must NOT set these keys directly on ctx: [...POLLUTED_KEYS]
+	// This sanitization runs at the start of executeHook to prevent prototype pollution attacks.
+	function sanitizeContext(ctx: HookContext): HookContext {
+		for (const key of Object.keys(ctx)) {
+			if (POLLUTED_KEYS.has(key.toLowerCase().normalize("NFKC"))) {
+				delete ctx[key];
+			}
+		}
+		return ctx;
+	}
+	function sanitizeErrorMessage(message: string): string {
+		// Remove file paths, environment variable references, and other potentially sensitive data
+		return message
+			.replace(/\/[^:\s]+/g, "[path]")
+			.replace(/\b[A-Z_0-9]+\s*=/g, "[env]")
+			.replace(/\b\d+\.\d+\.\d+\.\d+\b/g, "[ip]");
+	}
+	const start = Date.now();
+	const diagnostics: string[] = [];
+	let capturedModifications: Record<string, unknown> | undefined;
+	for (const hook of scopedHooks) {
+		try {
+			const result: HookResult = await hook.handler(sanitizeContext(ctx));
+			// SECURITY: Sanitize any direct mutations the handler may have made to ctx.
+			// This prevents hooks from injecting dangerous properties via direct ctx assignment.
+			sanitizeContext(ctx);
+			if (hook.mode === "blocking" && result.outcome === "block") {
+				return {
+					hookName: name,
+					outcome: "block",
+					durationMs: Date.now() - start,
+					reason: result.reason,
+				};
+			}
+			if (result.outcome === "modify" && result.data) {
+				// EXT-13 (Round 3): Deep-clone hook result.data so subsequent hooks
+				// (or the same hook if reused) cannot mutate shared ctx via shared
+				// nested-object references. sanitizeMergeData already produces a
+				// fresh top-level object, but nested values would still alias.
+				const clonedData = sanitizeMergeData(result.data);
+				Object.assign(ctx, clonedData);
+				capturedModifications = clonedData;
+			}
+		} catch (error) {
+			const message = sanitizeErrorMessage(error instanceof Error ? error.message : String(error));
+			if (hook.mode === "blocking") {
+				return {
+					hookName: name,
+					outcome: "block",
+					durationMs: Date.now() - start,
+					reason: `Hook error: ${message}`,
+				};
+			}
+			// Non-blocking hook errors are accumulated as diagnostics; continue to next hook
+			diagnostics.push(message);
+		}
+	}
+	if (diagnostics.length > 0) {
+		return {
+			hookName: name,
+			outcome: "diagnostic",
+			durationMs: Date.now() - start,
+			reason: diagnostics.join("; "),
+			modifiedData: capturedModifications,
+		};
+	}
+	return {
+		hookName: name,
+		outcome: "allow",
+		durationMs: Date.now() - start,
+		modifiedData: capturedModifications,
+	};
+}
+
+export function appendHookEvent(manifest: TeamRunManifest, report: HookExecutionReport): void {
+	appendEvent(manifest.eventsPath, {
+		type: "hook.executed",
+		runId: manifest.runId,
+		message: `Hook ${report.hookName} completed with outcome=${report.outcome}${report.reason ? `: ${report.reason}` : ""}`,
+		data: {
+			hookName: report.hookName,
+			outcome: report.outcome,
+			durationMs: report.durationMs,
+			reason: report.reason,
+		},
+	});
+	runEventBus.emit({
+		type: "effectiveness_changed",
+		runId: manifest.runId,
+		data: { hookName: report.hookName, outcome: report.outcome },
+	});
+}

package/src/hooks/types.ts

@@ -0,0 +1,69 @@
+export type HookName =
+	| "before_run_start"
+	| "after_run_complete"
+	| "before_task_start"
+	| "after_task_complete"
+	| "task_result"
+	| "before_cancel"
+	| "before_retry"
+	| "before_forget"
+	| "before_cleanup"
+	| "before_publish"
+	| "session_before_switch"
+	| "session_after_connect"
+	| "session_after_disconnect"
+	| "run_recovery"
+	| "before_goal_step"
+	| "before_goal_abort";
+
+/**
+ * Hook exit codes inspired by claude-mem's lifecycle architecture:
+ * - 0 = allow (success)
+ * - 1 = warn (non-blocking error, continue)
+ * - 2 = block (blocking error, stop)
+ */
+/** @internal */ const HOOK_EXIT_SUCCESS = 0 as const;
+/** @internal */ const HOOK_EXIT_WARN = 1 as const;
+/** @internal */ const HOOK_EXIT_BLOCK = 2 as const;
+
+export type HookMode = "blocking" | "non_blocking";
+export type HookOutcome = "allow" | "block" | "modify" | "diagnostic";
+
+export interface HookContext {
+	runId: string;
+	taskId?: string;
+	cwd: string;
+	// NOTE: Hooks receive a shared mutable context object. A hook may directly set
+	// properties on ctx, but MUST NOT set dangerous names like "__proto__",
+	// "constructor", "prototype", etc. (see registry.ts POLLUTED_KEYS).
+	// Hook authors are trusted but must avoid prototype pollution attacks.
+	// The sanitizeMergeData function prevents dangerous properties from propagating
+	// via result.data merge, and a runtime guard sanitizes ctx before passing to
+	// handlers AND after handler execution to catch direct mutations.
+	[key: string]: unknown;
+}
+
+export interface HookResult {
+	outcome: HookOutcome;
+	reason?: string;
+	data?: Record<string, unknown>;
+}
+
+export interface HookDefinition {
+	name: HookName;
+	mode: HookMode;
+	handler: (ctx: HookContext) => HookResult | Promise<HookResult>;
+	// SECURITY: Optional workspace scoping. When set, the hook only executes for
+	// runs in the specified workspace. When absent, the hook applies to all runs.
+	workspaceId?: string;
+	/** @internal Internal hook ID for scope-aware cleanup. */
+	_hookId?: number;
+}
+
+export interface HookExecutionReport {
+	hookName: HookName;
+	outcome: HookOutcome;
+	durationMs: number;
+	reason?: string;
+	modifiedData?: Record<string, unknown>;
+}

package/src/i18n.ts

@@ -0,0 +1,212 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { logInternalError } from "./utils/internal-error.ts";
+
+type Params = Record<string, string | number>;
+
+const namespace = "pi-crew";
+const TEMPLATE_RE = /\{(\w+)\}/g;
+
+const fallback = {
+	"agent.requiresPrompt": "Agent requires prompt.",
+	"agent.started": "Agent {state}.",
+	"agent.id": "Agent ID: {id}",
+	"agent.type": "Type: {type}",
+	"agent.description": "Description: {description}",
+	"agent.retrieveHint": "Use get_subagent_result to retrieve output. Do not duplicate this agent's work.",
+	"agent.foregroundStatus": "Agent {id} {status}.",
+	"agent.noOutput": "No output.",
+	"result.requiresAgentId": "get_subagent_result requires agent_id.",
+	"result.notFound": "Agent not found: {id}",
+	"result.unrecoverable": "Subagent was interrupted before its durable run id was recorded; it cannot be recovered after restart.",
+	"result.waitAborted": "Waiting for subagent result was aborted.",
+	"result.waitTimeout": "Timed out waiting for subagent result.",
+	"result.stillRunning": "Agent is still running. Use wait=true or check again later.",
+	"steer.noted": "Steering request noted for {id}.",
+	"steer.unavailable": "Current default pi-crew backend is child-process, so mid-turn session.steer is not available yet.",
+	"steer.cancelHint": "Use team cancel runId={runId} if the agent must be interrupted.",
+} as const;
+
+type Key = keyof typeof fallback;
+
+/** Map of locale → partial translations. Keys not present fall back to English. */
+const translations: Record<string, Partial<Record<Key, string>>> = {
+	es: {
+		"agent.requiresPrompt": "Agent requiere prompt.",
+		"agent.started": "Agent {state}.",
+		"agent.id": "ID del agente: {id}",
+		"agent.type": "Tipo: {type}",
+		"agent.description": "Descripción: {description}",
+		"agent.retrieveHint": "Usa get_subagent_result para recuperar la salida. No dupliques el trabajo de este agente.",
+		"agent.foregroundStatus": "Agent {id} {status}.",
+		"agent.noOutput": "Sin salida.",
+		"result.requiresAgentId": "get_subagent_result requiere agent_id.",
+		"result.notFound": "Agente no encontrado: {id}",
+		"result.unrecoverable":
+			"El subagente fue interrumpido antes de registrar su ID de ejecución duradero; no se puede recuperar tras reiniciar.",
+		"result.waitAborted": "Se canceló la espera del resultado del subagente.",
+		"result.waitTimeout": "Se agotó el tiempo de espera del resultado del subagente.",
+		"result.stillRunning": "El agente sigue ejecutándose. Usa wait=true o vuelve a comprobar más tarde.",
+		"steer.noted": "Solicitud de dirección registrada para {id}.",
+		"steer.unavailable":
+			"El backend predeterminado actual de pi-crew es child-process, así que session.steer a mitad de turno aún no está disponible.",
+		"steer.cancelHint": "Usa team cancel runId={runId} si hay que interrumpir el agente.",
+	},
+	fr: {
+		"agent.requiresPrompt": "Agent nécessite un prompt.",
+		"agent.started": "Agent {state}.",
+		"agent.id": "ID de l'agent : {id}",
+		"agent.type": "Type : {type}",
+		"agent.description": "Description : {description}",
+		"agent.retrieveHint": "Utilisez get_subagent_result pour récupérer la sortie. Ne dupliquez pas le travail de cet agent.",
+		"agent.foregroundStatus": "Agent {id} {status}.",
+		"agent.noOutput": "Aucune sortie.",
+		"result.requiresAgentId": "get_subagent_result nécessite agent_id.",
+		"result.notFound": "Agent introuvable : {id}",
+		"result.unrecoverable":
+			"Le sous-agent a été interrompu avant l'enregistrement de son ID d'exécution durable ; il ne peut pas être récupéré après redémarrage.",
+		"result.waitAborted": "L'attente du résultat du sous-agent a été annulée.",
+		"result.waitTimeout": "Délai d'attente du résultat du sous-agent dépassé.",
+		"result.stillRunning": "L'agent est toujours en cours d'exécution. Utilisez wait=true ou réessayez plus tard.",
+		"steer.noted": "Demande de pilotage enregistrée pour {id}.",
+		"steer.unavailable":
+			"Le backend pi-crew par défaut actuel est child-process, donc session.steer en milieu de tour n'est pas encore disponible.",
+		"steer.cancelHint": "Utilisez team cancel runId={runId} si l'agent doit être interrompu.",
+	},
+	"pt-BR": {
+		"agent.requiresPrompt": "Agent requer prompt.",
+		"agent.started": "Agent {state}.",
+		"agent.id": "ID do agente: {id}",
+		"agent.type": "Tipo: {type}",
+		"agent.description": "Descrição: {description}",
+		"agent.retrieveHint": "Use get_subagent_result para recuperar a saída. Não duplique o trabalho deste agente.",
+		"agent.foregroundStatus": "Agent {id} {status}.",
+		"agent.noOutput": "Sem saída.",
+		"result.requiresAgentId": "get_subagent_result requer agent_id.",
+		"result.notFound": "Agente não encontrado: {id}",
+		"result.unrecoverable":
+			"O subagente foi interrompido antes que seu ID de execução durável fosse registrado; ele não pode ser recuperado após reiniciar.",
+		"result.waitAborted": "A espera pelo resultado do subagente foi abortada.",
+		"result.waitTimeout": "Tempo limite de espera pelo resultado do subagente esgotado.",
+		"result.stillRunning": "O agente ainda está em execução. Use wait=true ou verifique novamente mais tarde.",
+		"steer.noted": "Solicitação de orientação registrada para {id}.",
+		"steer.unavailable":
+			"O backend padrão atual do pi-crew é child-process, então session.steer no meio do turno ainda não está disponível.",
+		"steer.cancelHint": "Use team cancel runId={runId} se o agente precisar ser interrompido.",
+	},
+};
+
+// --- Runtime state ---
+
+let currentLocale: string | undefined;
+const warnedMissing = new Set<string>();
+
+// --- Helpers ---
+
+function format(template: string, params: Params = {}): string {
+	return template.replace(TEMPLATE_RE, (_match, key) => String(params[key] ?? `{${key}}`));
+}
+
+function warnOnce(key: string): void {
+	const tag = `${currentLocale}:${key}`;
+	if (warnedMissing.has(tag)) return;
+	warnedMissing.add(tag);
+	logInternalError("i18n.missing", new Error(`Missing translation`), `key="${key}" locale="${currentLocale}"`);
+}
+
+// --- Public API ---
+
+/**
+ * Translate a key for the currently active locale.
+ * Falls back to English, then to the raw key as a last resort.
+ */
+export function t(key: Key, params?: Params): string {
+	if (currentLocale && translations[currentLocale]) {
+		const template = translations[currentLocale]?.[key];
+		if (template) return format(template, params);
+		warnOnce(key);
+	}
+	return format(fallback[key] ?? key, params);
+}
+
+/**
+ * Register or extend translations for a locale at runtime.
+ * Useful for contributors adding new language bundles without modifying i18n.ts.
+ *
+ * @example
+ * addTranslations("vi", { "agent.requiresPrompt": "Agent cần prompt." })
+ */
+const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+function stripDangerousKeys<T extends Record<string, unknown>>(obj: T): T {
+	const safe: Record<string, unknown> = {};
+	for (const key of Object.keys(obj)) {
+		if (!DANGEROUS_KEYS.has(key)) {
+			safe[key] = obj[key];
+		}
+	}
+	return safe as T;
+}
+
+export function addTranslations(locale: string, bundle: Partial<Record<Key, string>>): void {
+	if (!locale) return;
+	const safeBundle = stripDangerousKeys(bundle as Record<string, unknown>) as Partial<Record<Key, string>>;
+	const existing = translations[locale];
+	if (existing) {
+		Object.assign(existing, safeBundle);
+	} else {
+		translations[locale] = { ...safeBundle };
+	}
+}
+
+/**
+ * Returns the list of currently registered locales (excluding English, which is always available).
+ */
+export function listLocales(): string[] {
+	return Object.keys(translations);
+}
+
+// --- Initialization ---
+
+export function initI18n(pi: ExtensionAPI): () => void {
+	try {
+		pi.events?.emit?.("pi-core/i18n/registerBundle", {
+			namespace,
+			defaultLocale: "en",
+			fallback,
+			translations,
+		});
+	} catch {
+		// Non-critical.
+	}
+	const unsubscribe = pi.events?.on?.("pi-core/i18n/localeChanged", (event: unknown) => {
+		if (!event || typeof event !== "object") return;
+		const raw = String((event as { locale?: unknown }).locale ?? "").trim();
+		currentLocale = raw && translations[raw] ? raw : undefined;
+	});
+	try {
+		pi.events?.emit?.("pi-core/i18n/requestApi", {
+			namespace,
+			onApi(api: { getLocale?: () => string | undefined }) {
+				const raw = api.getLocale?.()?.trim();
+				if (raw && translations[raw]) currentLocale = raw;
+			},
+		});
+	} catch {
+		// Non-critical.
+	}
+	return () => {
+		currentLocale = undefined;
+		unsubscribe?.();
+	};
+}
+
+// --- Test helpers ---
+
+export function __test__resetI18n(): void {
+	currentLocale = undefined;
+	warnedMissing.clear();
+	// Clear runtime-added translations but keep built-in ones.
+	for (const key of Object.keys(translations)) {
+		if (!["es", "fr", "pt-BR"].includes(key)) delete translations[key];
+	}
+}

package/src/observability/correlation.ts

@@ -0,0 +1,50 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+
+export interface CorrelationContext {
+	traceId: string;
+	parentSpanId?: string;
+	spanId: string;
+}
+
+const storage = new AsyncLocalStorage<CorrelationContext>();
+
+export function withCorrelation<T>(ctx: CorrelationContext, fn: () => T): T {
+	return storage.run(ctx, fn);
+}
+
+export function getCurrentContext(): CorrelationContext | undefined {
+	return storage.getStore();
+}
+
+export function newSpanId(runId: string, taskId = "main"): string {
+	// OBS-4: random 8-hex-char suffix — bounded length, collision-resistant across
+	// module reloads (the old monotonic counter collided after HMR and grew unboundedly).
+	return `${runId}:${taskId}:${randomBytes(4).toString("hex")}`;
+}
+
+export function childCorrelation(runId: string, taskId: string): CorrelationContext {
+	const parent = getCurrentContext();
+	const spanId = newSpanId(runId, taskId);
+	return {
+		traceId: parent?.traceId ?? spanId,
+		parentSpanId: parent?.spanId,
+		spanId,
+	};
+}
+
+export function correlatedEvent<T extends { runId?: string; data?: Record<string, unknown> }>(
+	event: T,
+): T & { data: Record<string, unknown> } {
+	const ctx = getCurrentContext();
+	if (!ctx) return event as T & { data: Record<string, unknown> };
+	return {
+		...event,
+		data: {
+			...(event.data ?? {}),
+			traceId: ctx.traceId,
+			spanId: ctx.spanId,
+			parentSpanId: ctx.parentSpanId,
+		},
+	};
+}