pi-crew 0.1.34 → 0.1.36

package/src/extension/register.ts

@@ -27,6 +27,13 @@ import { NotificationRouter, type NotificationDescriptor } from "./notification-
 import { createJsonlSink, type NotificationSink } from "./notification-sink.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
 import { summarizeHeartbeats } from "../ui/heartbeat-aggregator.ts";
+import { createMetricRegistry, type MetricRegistry } from "../observability/metric-registry.ts";
+import { wireEventToMetrics, type EventToMetricSubscription } from "../observability/event-to-metric.ts";
+import { createMetricFileSink, type MetricSink } from "../observability/metric-sink.ts";
+import { OTLPExporter } from "../observability/exporters/otlp-exporter.ts";
+import { HeartbeatWatcher } from "../runtime/heartbeat-watcher.ts";
+import { appendDeadletter } from "../runtime/deadletter.ts";
+import { detectInterruptedRuns } from "../runtime/crash-recovery.ts";
 
 export { __test__subagentSpawnParams };
 
@@ -68,6 +75,11 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	const widgetState: CrewWidgetState = { frame: 0 };
 	let notificationSink: NotificationSink | undefined;
 	let notificationRouter: NotificationRouter | undefined;
+	let metricRegistry: MetricRegistry | undefined;
+	let eventMetricSub: EventToMetricSubscription | undefined;
+	let metricSink: MetricSink | undefined;
+	let heartbeatWatcher: HeartbeatWatcher | undefined;
+	let otlpExporter: OTLPExporter | undefined;
 	const configureNotifications = (ctx: ExtensionContext): void => {
 		notificationRouter?.dispose();
 		notificationSink?.dispose();
@@ -92,6 +104,46 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 			}
 		});
 	};
+	const configureObservability = (ctx: ExtensionContext): void => {
+		heartbeatWatcher?.dispose();
+		metricSink?.dispose();
+		eventMetricSub?.dispose();
+		otlpExporter?.dispose();
+		metricRegistry?.dispose();
+		heartbeatWatcher = undefined;
+		metricSink = undefined;
+		eventMetricSub = undefined;
+		otlpExporter = undefined;
+		metricRegistry = undefined;
+		const config = loadConfig(ctx.cwd).config;
+		if (config.observability?.enabled === false) return;
+		metricRegistry = createMetricRegistry();
+		eventMetricSub = wireEventToMetrics(pi.events, metricRegistry);
+		if (config.telemetry?.enabled !== false) metricSink = createMetricFileSink({ crewRoot: projectCrewRoot(ctx.cwd), registry: metricRegistry, retentionDays: config.observability?.metricRetentionDays ?? 7 });
+		if (config.otlp?.enabled === true && config.otlp.endpoint) {
+			otlpExporter = new OTLPExporter({ endpoint: config.otlp.endpoint, headers: config.otlp.headers, intervalMs: config.otlp.intervalMs }, metricRegistry);
+			otlpExporter.start();
+		}
+		heartbeatWatcher = new HeartbeatWatcher({
+			cwd: ctx.cwd,
+			pollIntervalMs: config.observability?.pollIntervalMs ?? 5000,
+			manifestCache: getManifestCache(ctx.cwd),
+			registry: metricRegistry,
+			router: { enqueue: (notification) => { notifyOperator(notification); return true; } },
+			deadletterTickThreshold: config.reliability?.deadletterThreshold ?? 3,
+			onDeadletterTrigger: (manifest, taskId) => {
+				appendDeadletter(manifest, { taskId, runId: manifest.runId, reason: "heartbeat-dead", attempts: 0, timestamp: new Date().toISOString() });
+				metricRegistry?.counter("crew.task.deadletter_total", "Deadletter triggers by reason").inc({ reason: "heartbeat-dead" });
+				pi.events?.emit?.("crew.task.deadletter", { runId: manifest.runId, taskId, reason: "heartbeat-dead" });
+			},
+		});
+		heartbeatWatcher.start();
+		if (config.reliability?.autoRecover === true) {
+			for (const plan of detectInterruptedRuns(ctx.cwd, getManifestCache(ctx.cwd))) {
+				notifyOperator({ id: `recovery_prompt_${plan.runId}`, severity: "warning", source: "crash-recovery", runId: plan.runId, title: `Run ${plan.runId} was interrupted`, body: `${plan.resumableTasks.length} tasks pending recovery. Open dashboard to inspect before resuming.` });
+			}
+		}
+	};
 	const autoRecoveryLast = new Map<string, number>();
 	const notifyOperator = (notification: NotificationDescriptor): void => {
 		try {
@@ -245,6 +297,16 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		stopAsyncRunNotifier(notifierState);
 		stopCrewWidget(currentCtx, widgetState, currentCtx ? loadConfig(currentCtx.cwd).config.ui : undefined);
 		clearPiCrewPowerbar(pi.events, currentCtx);
+		heartbeatWatcher?.dispose();
+		metricSink?.dispose();
+		eventMetricSub?.dispose();
+		otlpExporter?.dispose();
+		metricRegistry?.dispose();
+		heartbeatWatcher = undefined;
+		metricSink = undefined;
+		eventMetricSub = undefined;
+		otlpExporter = undefined;
+		metricRegistry = undefined;
 		manifestCache.dispose();
 		runSnapshotCache.dispose?.();
 		renderScheduler?.dispose();
@@ -272,6 +334,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		const loadedConfig = loadConfig(ctx.cwd);
 		autoRecoveryLast.clear();
 		configureNotifications(ctx);
+		configureObservability(ctx);
 		registerPiCrewPowerbarSegments(pi.events, loadedConfig.config.ui);
 		startAsyncRunNotifier(ctx, notifierState, loadedConfig.config.notifierIntervalMs ?? DEFAULT_UI.notifierIntervalMs);
 		const cache = getManifestCache(ctx.cwd);
@@ -318,7 +381,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 			}
 		};
 		renderScheduler = new RenderScheduler(pi.events, renderTick, {
-			fallbackMs: loadedConfig.config.ui?.dashboardLiveRefreshMs ?? 750,
+			fallbackMs: loadedConfig.config.ui?.dashboardLiveRefreshMs ?? 250,
 			onInvalidate: () => getRunSnapshotCache(ctx.cwd).invalidate(),
 		});
 	});
@@ -343,11 +406,11 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		};
 	});
 
-	registerTeamTool(pi, { foregroundControllers, startForegroundRun, openLiveSidebar, getManifestCache, getRunSnapshotCache, widgetState });
+	registerTeamTool(pi, { foregroundControllers, startForegroundRun, openLiveSidebar, getManifestCache, getRunSnapshotCache, getMetricRegistry: () => metricRegistry, widgetState });
 	registerSubagentTools(pi, subagentManager);
 	time("register.tools");
 
-	registerTeamCommands(pi, { startForegroundRun, openLiveSidebar, getManifestCache, getRunSnapshotCache, dismissNotifications: () => {
+	registerTeamCommands(pi, { startForegroundRun, openLiveSidebar, getManifestCache, getRunSnapshotCache, getMetricRegistry: () => metricRegistry, dismissNotifications: () => {
 		widgetState.notificationCount = 0;
 		if (currentCtx) {
 			const uiConfig = loadConfig(currentCtx.cwd).config.ui;

package/src/extension/registration/commands.ts

@@ -21,12 +21,14 @@ import { openTranscriptViewer, selectAgentTask } from "./viewers.ts";
 import { printTimings, time } from "../../utils/timings.ts";
 import { requestRenderTarget } from "../../ui/pi-ui-compat.ts";
 import type { createRunSnapshotCache } from "../../ui/run-snapshot-cache.ts";
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
 
 export interface RegisterTeamCommandsDeps {
 	startForegroundRun: (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
 	openLiveSidebar: (ctx: ExtensionContext, runId: string) => void;
 	getManifestCache: (cwd: string) => { list(max?: number): TeamRunManifest[] };
 	getRunSnapshotCache?: (cwd: string) => ReturnType<typeof createRunSnapshotCache>;
+	getMetricRegistry?: () => MetricRegistry | undefined;
 	dismissNotifications?: () => void;
 }
 
@@ -106,12 +108,15 @@ async function handleHealthDashboardAction(ctx: ExtensionCommandContext, selecti
 			const confirmed = await openConfirm(ctx, { title: "Recent diagnostic exists", body: `File ${recent} was created <1min ago. Export another diagnostic?`, defaultAction: "cancel" });
 			if (!confirmed) return;
 		}
-		const result = await dispatchDiagnosticExport(ctx as ExtensionContext, selection.runId);
+		const result = await dispatchDiagnosticExport(ctx as ExtensionContext, selection.runId, { registry: depsRef?.getMetricRegistry?.() });
 		depsNotify(ctx, result.message, result.ok ? "info" : "error");
 	}
 }
 
+let depsRef: RegisterTeamCommandsDeps | undefined;
+
 export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommandsDeps): void {
+	depsRef = deps;
 	pi.registerCommand("teams", {
 		description: "List pi-crew teams, workflows, and agents",
 		handler: async (_args: string, ctx: ExtensionCommandContext) => {
@@ -123,7 +128,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 	pi.registerCommand("team-run", {
 		description: "Manually start a pi-crew run (agent may also use the team tool autonomously)",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
-			const result = await handleTeamTool(parseRunArgs(args), { ...ctx, startForegroundRun: (runner, runId) => deps.startForegroundRun(ctx as ExtensionContext, runner, runId), onRunStarted: (runId) => deps.openLiveSidebar(ctx as ExtensionContext, runId) });
+			const result = await handleTeamTool(parseRunArgs(args), { ...ctx, metricRegistry: deps.getMetricRegistry?.(), startForegroundRun: (runner, runId) => deps.startForegroundRun(ctx as ExtensionContext, runner, runId), onRunStarted: (runId) => deps.openLiveSidebar(ctx as ExtensionContext, runId) });
 			await notifyCommandResult(ctx, commandText(result));
 		},
 	});
@@ -161,6 +166,12 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 		},
 	});
 
+	pi.registerCommand("team-metrics", { description: "Show pi-crew metrics snapshot: [filter]", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		const filter = args.trim() || undefined;
+		const result = await handleTeamTool({ action: "api", config: { operation: "metrics-snapshot", filter } }, { ...ctx, metricRegistry: deps.getMetricRegistry?.() });
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
 	pi.registerCommand("team-imports", { description: "List imported pi-crew run bundles", handler: async (_args: string, ctx: ExtensionCommandContext) => {
 		const result = await handleTeamTool({ action: "imports" }, ctx);
 		await notifyCommandResult(ctx, commandText(result));
@@ -225,7 +236,7 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 			const uiConfig = loadConfig(ctx.cwd).config.ui;
 			const rightPanel = uiConfig?.dashboardPlacement !== "center";
 			const width = rightPanel ? Math.min(90, Math.max(40, uiConfig?.dashboardWidth ?? 56)) : "90%";
-			const selection = await ctx.ui.custom<RunDashboardSelection | undefined>((_tui, theme, _keybindings, done) => new RunDashboard(runs, done, theme, { placement: rightPanel ? "right" : "center", showModel: uiConfig?.showModel, showTokens: uiConfig?.showTokens, showTools: uiConfig?.showTools, snapshotCache: deps.getRunSnapshotCache?.(ctx.cwd), runProvider: () => deps.getManifestCache(ctx.cwd).list(50) }), { overlay: true, overlayOptions: rightPanel ? { width, minWidth: 40, maxHeight: "100%", anchor: "top-right", offsetX: 0, offsetY: 0, margin: { top: 0, right: 0, bottom: 0, left: 0 } } : { width, maxHeight: "90%", anchor: "center", margin: 2 } });
+			const selection = await ctx.ui.custom<RunDashboardSelection | undefined>((_tui, theme, _keybindings, done) => new RunDashboard(runs, done, theme, { placement: rightPanel ? "right" : "center", showModel: uiConfig?.showModel, showTokens: uiConfig?.showTokens, showTools: uiConfig?.showTools, snapshotCache: deps.getRunSnapshotCache?.(ctx.cwd), runProvider: () => deps.getManifestCache(ctx.cwd).list(50), registry: deps.getMetricRegistry?.() }), { overlay: true, overlayOptions: rightPanel ? { width, minWidth: 40, maxHeight: "100%", anchor: "top-right", offsetX: 0, offsetY: 0, margin: { top: 0, right: 0, bottom: 0, left: 0 } } : { width, maxHeight: "90%", anchor: "center", margin: 2 } });
 			if (!selection) return;
 			if (selection.action === "reload") continue;
 			if (selection.action === "notifications-dismiss") {

package/src/extension/registration/team-tool.ts

@@ -6,6 +6,7 @@ import { updateCrewWidget } from "../../ui/crew-widget.ts";
 import { updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
 import type { createManifestCache } from "../../runtime/manifest-cache.ts";
 import type { createRunSnapshotCache } from "../../ui/run-snapshot-cache.ts";
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
 import { handleTeamTool } from "../team-tool.ts";
 
 export interface RegisterTeamToolDeps {
@@ -14,6 +15,7 @@ export interface RegisterTeamToolDeps {
 	openLiveSidebar: (ctx: ExtensionContext, runId: string) => void;
 	getManifestCache: (cwd: string) => ReturnType<typeof createManifestCache>;
 	getRunSnapshotCache?: (cwd: string) => ReturnType<typeof createRunSnapshotCache>;
+	getMetricRegistry?: () => MetricRegistry | undefined;
 	widgetState: CrewWidgetState;
 }
 
@@ -36,7 +38,7 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 					const runLabel = resolved.team ?? resolved.agent ?? "direct";
 					pi.setSessionName(`pi-crew: ${runLabel}/${resolved.workflow ?? "default"} — ${resolved.goal.slice(0, 60)}`);
 				}
-				const output = await handleTeamTool(resolved, { ...ctx, signal: controller.signal, startForegroundRun: (runner, runId) => deps.startForegroundRun(ctx, runner, runId), onRunStarted: (runId) => deps.openLiveSidebar(ctx, runId) });
+				const output = await handleTeamTool(resolved, { ...ctx, signal: controller.signal, metricRegistry: deps.getMetricRegistry?.(), startForegroundRun: (runner, runId) => deps.startForegroundRun(ctx, runner, runId), onRunStarted: (runId) => deps.openLiveSidebar(ctx, runId) });
 				if (resolved.action === "run") {
 					pi.appendEntry("crew:run-started", {
 						runId: output.details?.runId,

package/src/extension/team-tool/api.ts

@@ -19,12 +19,37 @@ import { liveControlRealtimeMessage, publishLiveControlRealtime } from "../../su
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
 
+function globMatch(value: string, pattern: string): boolean {
+	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+	return new RegExp(`^${escaped}$`).test(value);
+}
+
+function snapshotHasRunId(snapshot: { values?: unknown }, runId: string): boolean {
+	const values = Array.isArray(snapshot.values) ? snapshot.values : [];
+	return values.some((value) => {
+		if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+		const labels = (value as { labels?: unknown }).labels;
+		return labels && typeof labels === "object" && !Array.isArray(labels) && (labels as Record<string, unknown>).runId === runId;
+	});
+}
+
 export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	const cfg = configRecord(params.config);
+	const operation = typeof cfg.operation === "string" ? cfg.operation : "read-manifest";
+	if (operation === "metrics-snapshot") {
+		const filter = typeof cfg.filter === "string" ? cfg.filter : undefined;
+		const runIdFilter = typeof cfg.runId === "string" ? cfg.runId : params.runId;
+		const snapshots = ctx.metricRegistry?.snapshot() ?? [];
+		const filtered = snapshots.filter((snapshot) => {
+			if (filter && !globMatch(snapshot.name, filter)) return false;
+			if (runIdFilter && !snapshotHasRunId(snapshot, runIdFilter)) return false;
+			return true;
+		});
+		return result(JSON.stringify(filtered, null, 2), { action: "api", status: "ok", ...(runIdFilter ? { runId: runIdFilter } : {}) });
+	}
 	if (!params.runId) return result("API requires runId.", { action: "api", status: "error" }, true);
 	const loaded = loadRunManifestById(ctx.cwd, params.runId);
 	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "api", status: "error" }, true);
-	const cfg = configRecord(params.config);
-	const operation = typeof cfg.operation === "string" ? cfg.operation : "read-manifest";
 	if (operation === "read-manifest") {
 		return result(JSON.stringify(loaded.manifest, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}

package/src/extension/team-tool/context.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
 import type { TeamToolDetails } from "../team-tool-types.ts";
 import { toolResult, type PiTeamsToolResult } from "../tool-result.ts";
 
@@ -6,6 +7,7 @@ export type TeamContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<Extension
 	modelRegistry?: unknown;
 	sessionManager?: { getBranch?: () => unknown[] };
 	events?: { emit?: (event: string, data: unknown) => void };
+	metricRegistry?: MetricRegistry;
 	signal?: AbortSignal;
 	startForegroundRun?: (runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
 	onRunStarted?: (runId: string) => void;

package/src/extension/team-tool/run.ts

@@ -134,7 +134,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	if (executeWorkers && ctx.startForegroundRun) {
 		ctx.onRunStarted?.(updatedManifest.runId);
 		ctx.startForegroundRun(async (signal) => {
-			await executeTeamRun({ manifest: updatedManifest, tasks, team, workflow, agents, executeWorkers, limits: executedConfig.limits, runtime, runtimeConfig: executedConfig.runtime, parentContext: buildParentContext(ctx), parentModel: ctx.model, modelRegistry: ctx.modelRegistry, modelOverride: params.model, signal });
+			await executeTeamRun({ manifest: updatedManifest, tasks, team, workflow, agents, executeWorkers, limits: executedConfig.limits, runtime, runtimeConfig: executedConfig.runtime, parentContext: buildParentContext(ctx), parentModel: ctx.model, modelRegistry: ctx.modelRegistry, modelOverride: params.model, signal, reliability: executedConfig.reliability, metricRegistry: ctx.metricRegistry });
 		}, updatedManifest.runId);
 		const text = [
 			`Started foreground pi-crew run ${updatedManifest.runId}.`,
@@ -150,7 +150,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		].join("\n");
 		return result(text, { action: "run", status: "ok", runId: updatedManifest.runId, artifactsRoot: updatedManifest.artifactsRoot });
 	}
-	const executed = await executeTeamRun({ manifest: updatedManifest, tasks, team, workflow, agents, executeWorkers, limits: executedConfig.limits, runtime, runtimeConfig: executedConfig.runtime, parentContext: buildParentContext(ctx), parentModel: ctx.model, modelRegistry: ctx.modelRegistry, modelOverride: params.model, signal: ctx.signal });
+	const executed = await executeTeamRun({ manifest: updatedManifest, tasks, team, workflow, agents, executeWorkers, limits: executedConfig.limits, runtime, runtimeConfig: executedConfig.runtime, parentContext: buildParentContext(ctx), parentModel: ctx.model, modelRegistry: ctx.modelRegistry, modelOverride: params.model, signal: ctx.signal, reliability: executedConfig.reliability, metricRegistry: ctx.metricRegistry });
 	const text = [
 		`Created pi-crew run ${executed.manifest.runId}.`,
 		`Team: ${team.name}`,

package/src/extension/team-tool.ts

@@ -185,7 +185,7 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 		const loadedConfig = loadConfig(ctx.cwd);
 		const runtime = await resolveCrewRuntime(loadedConfig.config);
 		const executeWorkers = runtime.kind !== "scaffold";
-		const executed = await executeTeamRun({ manifest: resumeManifest, tasks: resetTasks, team, workflow, agents, executeWorkers, limits: loadedConfig.config.limits, runtime, runtimeConfig: loadedConfig.config.runtime, parentContext: buildParentContext(ctx), parentModel: ctx.model, modelRegistry: ctx.modelRegistry, modelOverride: params.model, signal: ctx.signal });
+		const executed = await executeTeamRun({ manifest: resumeManifest, tasks: resetTasks, team, workflow, agents, executeWorkers, limits: loadedConfig.config.limits, runtime, runtimeConfig: loadedConfig.config.runtime, parentContext: buildParentContext(ctx), parentModel: ctx.model, modelRegistry: ctx.modelRegistry, modelOverride: params.model, signal: ctx.signal, reliability: loadedConfig.config.reliability, metricRegistry: ctx.metricRegistry });
 		return result([`Resumed run ${executed.manifest.runId}.`, `Status: ${executed.manifest.status}`, `Tasks: ${executed.tasks.length}`, `Artifacts: ${executed.manifest.artifactsRoot}`].join("\n"), { action: "resume", status: executed.manifest.status === "failed" ? "error" : "ok", runId: executed.manifest.runId, artifactsRoot: executed.manifest.artifactsRoot }, executed.manifest.status === "failed");
 	});
 }

package/src/observability/correlation.ts

@@ -0,0 +1,35 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface CorrelationContext {
+	traceId: string;
+	parentSpanId?: string;
+	spanId: string;
+}
+
+const storage = new AsyncLocalStorage<CorrelationContext>();
+let spanCounter = 0;
+
+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 {
+	spanCounter += 1;
+	return `${runId}:${taskId}:${spanCounter}`;
+}
+
+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 {
+	const ctx = getCurrentContext();
+	if (!ctx) return event;
+	return { ...event, data: { ...(event.data ?? {}), traceId: ctx.traceId, spanId: ctx.spanId, parentSpanId: ctx.parentSpanId } };
+}

package/src/observability/event-to-metric.ts

@@ -0,0 +1,54 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MetricRegistry } from "./metric-registry.ts";
+
+function recordValue(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function stringValue(value: unknown, fallback: string): string {
+	return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function numberValue(value: unknown, fallback = 0): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+export interface EventToMetricSubscription {
+	dispose(): void;
+}
+
+export function wireEventToMetrics(events: ExtensionAPI["events"] | undefined, registry: MetricRegistry): EventToMetricSubscription {
+	const runCount = registry.counter("crew.run.count", "Total runs by status");
+	const taskCount = registry.counter("crew.task.count", "Total tasks by status");
+	const subagentCount = registry.counter("crew.subagent.count", "Total subagent records by status");
+	const mailboxCount = registry.counter("crew.mailbox.count", "Total mailbox messages by direction");
+	registry.counter("crew.task.deadletter_total", "Deadletter triggers by reason");
+	registry.gauge("crew.heartbeat.staleness_ms", "Heartbeat elapsed since last seen, milliseconds");
+	const runDuration = registry.histogram("crew.run.duration_ms", "Run end-to-end duration, milliseconds");
+	const taskDuration = registry.histogram("crew.task.duration_ms", "Task duration, milliseconds");
+	registry.histogram("crew.task.retry_count", "Retries per task", [0, 1, 2, 3, 5, 10]);
+	const tokenUsage = registry.histogram("crew.task.tokens_total", "Token usage per task");
+
+	const handlers: Array<[string, (data: unknown) => void]> = [
+		["crew.run.completed", (data) => { const item = recordValue(data); runCount.inc({ status: "completed" }); runDuration.observe({ team: stringValue(item.team, "unknown") }, numberValue(item.durationMs)); }],
+		["crew.run.failed", () => runCount.inc({ status: "failed" })],
+		["crew.run.cancelled", () => runCount.inc({ status: "cancelled" })],
+		["crew.task.completed", (data) => { const item = recordValue(data); taskCount.inc({ status: "completed" }); taskDuration.observe({ role: stringValue(item.role, "unknown") }, numberValue(item.durationMs)); tokenUsage.observe({ role: stringValue(item.role, "unknown") }, numberValue(item.tokens)); }],
+		["crew.task.failed", () => taskCount.inc({ status: "failed" })],
+		["crew.task.retry_attempt", (data) => { const item = recordValue(data); taskCount.inc({ status: "retry" }); registry.counter("crew.task.retry_attempt_total", "Retry attempts by run and task").inc({ runId: stringValue(item.runId, "unknown"), taskId: stringValue(item.taskId, "unknown") }); }],
+		["crew.task.deadletter", (data) => { const item = recordValue(data); registry.counter("crew.task.deadletter_total", "Deadletter triggers by reason").inc({ reason: stringValue(item.reason, "unknown") }); }],
+		["crew.subagent.completed", (data) => { const item = recordValue(data); subagentCount.inc({ status: stringValue(item.status, "completed") }); }],
+		["crew.subagent.failed", () => subagentCount.inc({ status: "failed" })],
+		["crew.mailbox.message", (data) => { const item = recordValue(data); mailboxCount.inc({ direction: stringValue(item.direction, "unknown") }); }],
+	];
+
+	const unsubscribers: Array<() => void> = [];
+	for (const [event, handler] of handlers) {
+		const unsubscribe = events?.on?.(event, (data: unknown) => {
+			try { handler(data); } catch { /* metric handlers must never break event delivery */ }
+		});
+		if (typeof unsubscribe === "function") unsubscribers.push(unsubscribe);
+	}
+	let disposed = false;
+	return { dispose() { if (disposed) return; disposed = true; for (const unsubscribe of unsubscribers.splice(0)) unsubscribe(); } };
+}

package/src/observability/exporters/adapter.ts

@@ -0,0 +1,24 @@
+import type { MetricSnapshot } from "../metrics-primitives.ts";
+
+export interface MetricExporter {
+	name: string;
+	push(snapshots: MetricSnapshot[]): Promise<void>;
+	dispose(): void;
+}
+
+export class CompositeExporter implements MetricExporter {
+	name = "composite";
+	private readonly exporters: MetricExporter[];
+
+	constructor(exporters: MetricExporter[]) {
+		this.exporters = exporters;
+	}
+
+	async push(snapshots: MetricSnapshot[]): Promise<void> {
+		await Promise.allSettled(this.exporters.map((exporter) => exporter.push(snapshots)));
+	}
+
+	dispose(): void {
+		for (const exporter of this.exporters) exporter.dispose();
+	}
+}

package/src/observability/exporters/otlp-exporter.ts

@@ -0,0 +1,65 @@
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { MetricRegistry } from "../metric-registry.ts";
+import type { MetricSnapshot } from "../metrics-primitives.ts";
+import type { MetricExporter } from "./adapter.ts";
+
+export interface OTLPExporterOptions {
+	endpoint: string;
+	headers?: Record<string, string>;
+	intervalMs?: number;
+	timeoutMs?: number;
+}
+
+function pointValues(snapshot: MetricSnapshot): unknown[] {
+	return snapshot.values.map((value) => ({ attributes: Object.entries(value.labels).map(([key, item]) => ({ key, value: { stringValue: String(item) } })), asDouble: "value" in value ? value.value : undefined, count: "count" in value ? value.count : undefined, sum: "sum" in value ? value.sum : undefined }));
+}
+
+export function convertToOTLP(snapshots: MetricSnapshot[]): unknown {
+	return {
+		resourceMetrics: [{
+			resource: { attributes: [{ key: "service.name", value: { stringValue: "pi-crew" } }] },
+			scopeMetrics: [{
+				scope: { name: "pi-crew" },
+				metrics: snapshots.map((snapshot) => ({ name: snapshot.name, description: snapshot.description, [snapshot.type === "histogram" ? "histogram" : snapshot.type === "gauge" ? "gauge" : "sum"]: { dataPoints: pointValues(snapshot) } })),
+			}],
+		}],
+	};
+}
+
+export class OTLPExporter implements MetricExporter {
+	name = "otlp";
+	private timer?: ReturnType<typeof setInterval>;
+	private readonly opts: OTLPExporterOptions;
+	private readonly registry: MetricRegistry;
+
+	constructor(opts: OTLPExporterOptions, registry: MetricRegistry) {
+		this.opts = opts;
+		this.registry = registry;
+	}
+
+	start(): void {
+		this.dispose();
+		this.timer = setInterval(() => { void this.push(this.registry.snapshot()); }, this.opts.intervalMs ?? 60_000);
+		this.timer.unref?.();
+	}
+
+	async push(snapshots: MetricSnapshot[]): Promise<void> {
+		try {
+			const timeoutMs = this.opts.timeoutMs ?? 10_000;
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), timeoutMs);
+			try {
+				await fetch(this.opts.endpoint, { method: "POST", headers: { "content-type": "application/json", ...(this.opts.headers ?? {}) }, body: JSON.stringify(convertToOTLP(snapshots)), signal: controller.signal });
+			} finally {
+				clearTimeout(timer);
+			}
+		} catch (error) {
+			logInternalError("otlp-export", error);
+		}
+	}
+
+	dispose(): void {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = undefined;
+	}
+}

package/src/observability/exporters/prometheus-exporter.ts

@@ -0,0 +1,47 @@
+import type { HistogramPoint, MetricLabels, MetricPoint, MetricSnapshot } from "../metrics-primitives.ts";
+
+function prometheusName(name: string): string {
+	return name.replace(/\./g, "_");
+}
+
+function escapeLabel(value: string): string {
+	return value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, "\\\"");
+}
+
+function labelsText(labels: MetricLabels): string {
+	const entries = Object.entries(labels);
+	if (!entries.length) return "";
+	return `{${entries.map(([key, value]) => `${key}="${escapeLabel(String(value))}"`).join(",")}}`;
+}
+
+function metricType(type: MetricSnapshot["type"]): string {
+	return type === "histogram" ? "histogram" : type === "gauge" ? "gauge" : "counter";
+}
+
+function isHistogramPoint(value: MetricPoint | HistogramPoint): value is HistogramPoint {
+	return "buckets" in value && "counts" in value;
+}
+
+export function formatPrometheus(snapshots: MetricSnapshot[]): string {
+	const lines: string[] = [];
+	for (const snapshot of snapshots) {
+		const name = prometheusName(snapshot.name);
+		lines.push(`# HELP ${name} ${snapshot.description}`);
+		lines.push(`# TYPE ${name} ${metricType(snapshot.type)}`);
+		for (const value of snapshot.values) {
+			if (isHistogramPoint(value)) {
+				let cumulative = 0;
+				for (let index = 0; index < value.buckets.length; index += 1) {
+					cumulative += value.counts[index] ?? 0;
+					const le = Number.isFinite(value.buckets[index]) ? String(value.buckets[index]) : "+Inf";
+					lines.push(`${name}_bucket${labelsText({ ...value.labels, le })} ${cumulative}`);
+				}
+				lines.push(`${name}_sum${labelsText(value.labels)} ${value.sum}`);
+				lines.push(`${name}_count${labelsText(value.labels)} ${value.count}`);
+			} else {
+				lines.push(`${name}${labelsText(value.labels)} ${value.value}`);
+			}
+		}
+	}
+	return `${lines.join("\n")}\n`;
+}

package/src/observability/metric-registry.ts

@@ -0,0 +1,72 @@
+import { Counter, Gauge, Histogram, type Metric, type MetricSnapshot } from "./metrics-primitives.ts";
+
+const METRIC_NAME_PATTERN = /^crew\.[a-z]+\.[a-z][a-z_]*$/;
+
+function assertMetricName(name: string): void {
+	if (!METRIC_NAME_PATTERN.test(name)) throw new Error(`Invalid metric name '${name}'. Expected crew.<domain>.<measure>.`);
+}
+
+export class MetricRegistry {
+	private metrics = new Map<string, Metric>();
+
+	registerCounter(name: string, description: string): Counter {
+		assertMetricName(name);
+		if (this.metrics.has(name)) throw new Error(`Metric '${name}' is already registered.`);
+		const metric = new Counter(name, description);
+		this.metrics.set(name, metric);
+		return metric;
+	}
+
+	registerGauge(name: string, description: string): Gauge {
+		assertMetricName(name);
+		if (this.metrics.has(name)) throw new Error(`Metric '${name}' is already registered.`);
+		const metric = new Gauge(name, description);
+		this.metrics.set(name, metric);
+		return metric;
+	}
+
+	registerHistogram(name: string, description: string, buckets?: number[]): Histogram {
+		assertMetricName(name);
+		if (this.metrics.has(name)) throw new Error(`Metric '${name}' is already registered.`);
+		const metric = new Histogram(name, description, buckets);
+		this.metrics.set(name, metric);
+		return metric;
+	}
+
+	counter(name: string, description: string): Counter {
+		const existing = this.metrics.get(name);
+		if (existing instanceof Counter) return existing;
+		if (existing) throw new Error(`Metric '${name}' is not a counter.`);
+		return this.registerCounter(name, description);
+	}
+
+	gauge(name: string, description: string): Gauge {
+		const existing = this.metrics.get(name);
+		if (existing instanceof Gauge) return existing;
+		if (existing) throw new Error(`Metric '${name}' is not a gauge.`);
+		return this.registerGauge(name, description);
+	}
+
+	histogram(name: string, description: string, buckets?: number[]): Histogram {
+		const existing = this.metrics.get(name);
+		if (existing instanceof Histogram) return existing;
+		if (existing) throw new Error(`Metric '${name}' is not a histogram.`);
+		return this.registerHistogram(name, description, buckets);
+	}
+
+	get(name: string): Metric | undefined {
+		return this.metrics.get(name);
+	}
+
+	snapshot(): MetricSnapshot[] {
+		return [...this.metrics.values()].map((metric) => metric.snapshot());
+	}
+
+	dispose(): void {
+		this.metrics.clear();
+	}
+}
+
+export function createMetricRegistry(): MetricRegistry {
+	return new MetricRegistry();
+}

package/src/observability/metric-retention.ts

@@ -0,0 +1,46 @@
+import { labelKey, type MetricLabels } from "./metrics-primitives.ts";
+
+interface WindowEvent {
+	timestamp: number;
+	labels: MetricLabels;
+	delta: number;
+}
+
+export class TimeWindowedCounter {
+	private events: WindowEvent[] = [];
+	private readonly windowMs: number;
+	private readonly now: () => number;
+
+	constructor(windowMs = 3_600_000, now: () => number = () => Date.now()) {
+		this.windowMs = windowMs;
+		this.now = now;
+	}
+
+	inc(labels: MetricLabels = {}, delta = 1): void {
+		if (!Number.isFinite(delta)) return;
+		this.events.push({ timestamp: this.now(), labels: { ...labels }, delta });
+		this.prune();
+	}
+
+	count(labels: MetricLabels = {}, durationMs = this.windowMs): number {
+		this.prune();
+		const key = labelKey(labels);
+		const cutoff = this.now() - durationMs;
+		return this.events.filter((event) => event.timestamp >= cutoff && labelKey(event.labels) === key).reduce((sum, event) => sum + event.delta, 0);
+	}
+
+	rate(labels: MetricLabels = {}, durationMs = this.windowMs): number {
+		if (durationMs <= 0) return 0;
+		return this.count(labels, durationMs) / (durationMs / 1000);
+	}
+
+	size(): number {
+		this.prune();
+		return this.events.length;
+	}
+
+	private prune(): void {
+		const cutoff = this.now() - this.windowMs;
+		this.events = this.events.filter((event) => event.timestamp >= cutoff);
+	}
+}