@dougbots/avenor-core 0.3.7 → 0.4.1

package/dist/index.js

@@ -7,6 +7,22 @@ import * as os from "node:os";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
 //#region src/client.ts
+function normalizeSubscribeOptions(options) {
+	if (!options) return void 0;
+	const normalized = {};
+	if (options.runtime_id) normalized.runtime_id = options.runtime_id;
+	if (options.replay !== void 0) normalized.replay = options.replay;
+	if (options.limit !== void 0) normalized.limit = Math.max(1, Math.min(256, Math.trunc(options.limit)));
+	if (options.after_seq !== void 0) normalized.after_seq = Math.max(0, Math.trunc(options.after_seq));
+	return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+function subscribeOptionsKey(options) {
+	return JSON.stringify(normalizeSubscribeOptions(options) ?? {});
+}
+function removeResolver(resolvers, target) {
+	const index = resolvers.indexOf(target);
+	if (index >= 0) resolvers.splice(index, 1);
+}
 var Client = class {
 	socket;
 	rl;
@@ -19,6 +35,7 @@ var Client = class {
 	eventDone = false;
 	dropped = 0;
 	subscribed = false;
+	subscriptionKey = subscribeOptionsKey();
 	constructor(socket, opts) {
 		this.socket = socket;
 		this.rl = readline.createInterface({
@@ -59,11 +76,10 @@ var Client = class {
 				if (this.dropped > 0) {
 					const lag = this.dropped;
 					this.dropped = 0;
-					const lagEvent = {
+					this.pushEvent({
 						event: "client.lagged",
 						dropped_count: lag
-					};
-					this.pushEvent(lagEvent);
+					});
 				}
 				this.pushEvent(ev);
 			}
@@ -75,19 +91,28 @@ var Client = class {
 			}
 			this.pending.clear();
 			this.eventDone = true;
-			for (const resolve of this.eventResolvers) resolve({
-				value: void 0,
-				done: true
-			});
+			for (const resolver of this.eventResolvers) {
+				resolver.active = false;
+				resolver.resolve({
+					value: void 0,
+					done: true
+				});
+			}
 			this.eventResolvers = [];
 		});
 	}
 	pushEvent(ev) {
-		if (this.eventResolvers.length > 0) this.eventResolvers.shift()({
-			value: ev,
-			done: false
-		});
-		else if (this.eventQueue.length < 256) this.eventQueue.push(ev);
+		while (this.eventResolvers.length > 0) {
+			const resolver = this.eventResolvers.shift();
+			if (!resolver.active) continue;
+			resolver.active = false;
+			resolver.resolve({
+				value: ev,
+				done: false
+			});
+			return;
+		}
+		if (this.eventQueue.length < 256) this.eventQueue.push(ev);
 		else this.dropped++;
 	}
 	async call(method, params) {
@@ -119,25 +144,90 @@ var Client = class {
 			});
 		});
 	}
-	async subscribe() {
-		if (this.subscribed) return;
+	async subscribe(options) {
+		const key = subscribeOptionsKey(options);
+		if (this.subscribed) {
+			if (key !== subscribeOptionsKey() && key !== this.subscriptionKey) throw new Error("client already subscribed with different options");
+			return;
+		}
 		this.subscribed = true;
-		await this.call("subscribe");
-	}
-	async *events() {
-		await this.subscribe();
-		while (true) {
-			if (this.eventDone) break;
-			if (this.eventQueue.length > 0) {
-				yield this.eventQueue.shift();
-				continue;
+		this.subscriptionKey = key;
+		await this.call("subscribe", normalizeSubscribeOptions(options));
+	}
+	events(options) {
+		let active = true;
+		let pendingResolver = null;
+		let subscribedPromise = null;
+		const ensureSubscribed = async () => {
+			if (!subscribedPromise) subscribedPromise = this.subscribe(options);
+			await subscribedPromise;
+		};
+		const next = async () => {
+			if (!active || this.eventDone) return {
+				value: void 0,
+				done: true
+			};
+			try {
+				await ensureSubscribed();
+			} catch (error) {
+				active = false;
+				throw error;
 			}
-			const result = await new Promise((resolve) => {
-				this.eventResolvers.push(resolve);
+			if (!active || this.eventDone) return {
+				value: void 0,
+				done: true
+			};
+			if (this.eventQueue.length > 0) return {
+				value: this.eventQueue.shift(),
+				done: false
+			};
+			return new Promise((resolve) => {
+				pendingResolver = {
+					resolve,
+					active: true
+				};
+				this.eventResolvers.push(pendingResolver);
 			});
-			if (result.done) break;
-			yield result.value;
-		}
+		};
+		const stop = async () => {
+			if (!active) return {
+				value: void 0,
+				done: true
+			};
+			active = false;
+			if (pendingResolver) {
+				pendingResolver.active = false;
+				removeResolver(this.eventResolvers, pendingResolver);
+				pendingResolver.resolve({
+					value: void 0,
+					done: true
+				});
+				pendingResolver = null;
+			}
+			return {
+				value: void 0,
+				done: true
+			};
+		};
+		return {
+			next,
+			return: stop,
+			async throw(error) {
+				await stop();
+				throw error;
+			},
+			[Symbol.asyncIterator]() {
+				return this;
+			}
+		};
+	}
+	async history(options) {
+		const params = {
+			runtime_id: options.runtime_id,
+			limit: options.limit !== void 0 ? Math.max(1, Math.min(256, Math.trunc(options.limit))) : void 0,
+			after_seq: options.after_seq !== void 0 ? Math.max(0, Math.trunc(options.after_seq)) : void 0
+		};
+		return this.call("history", params);
 	}
 	async status(runtimeId) {
 		const params = runtimeId ? { runtime_id: runtimeId } : void 0;
@@ -190,6 +280,773 @@ function dial(socketPath, opts) {
 	});
 }
 //#endregion
+//#region src/value-fields.ts
+function asRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	return value;
+}
+function stringField(record, ...keys) {
+	if (!record) return void 0;
+	for (const key of keys) {
+		const value = record[key];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+}
+function numberField(record, ...keys) {
+	if (!record) return void 0;
+	for (const key of keys) {
+		const value = record[key];
+		if (typeof value === "number" && Number.isFinite(value)) return value;
+		if (typeof value === "string" && value.trim().length > 0) {
+			const parsed = Number(value);
+			if (Number.isFinite(parsed)) return parsed;
+		}
+	}
+}
+function stringArrayField(record, ...keys) {
+	if (!record) return void 0;
+	for (const key of keys) {
+		const value = record[key];
+		if (!Array.isArray(value)) continue;
+		const items = value.filter((item) => typeof item === "string" && item.length > 0);
+		if (items.length > 0) return items;
+	}
+}
+//#endregion
+//#region src/run-events.ts
+const MAX_TEXT_EXTRACTION_DEPTH = 12;
+const MAX_TEXT_EXTRACTION_ITEMS = 64;
+function extractEventText(value, depth = 0) {
+	if (depth >= MAX_TEXT_EXTRACTION_DEPTH) return void 0;
+	if (typeof value === "string") return value.length > 0 ? value : void 0;
+	if (Array.isArray(value)) {
+		const parts = [];
+		for (const item of value.slice(0, MAX_TEXT_EXTRACTION_ITEMS)) {
+			const text = extractEventText(item, depth + 1);
+			if (text) parts.push(text);
+		}
+		return parts.length > 0 ? parts.join("") : void 0;
+	}
+	const record = asRecord(value);
+	if (!record) return void 0;
+	for (const key of [
+		"delta",
+		"text",
+		"content",
+		"partial",
+		"message",
+		"assistantMessage",
+		"assistantMessageEvent",
+		"data",
+		"result",
+		"output"
+	]) {
+		const text = extractEventText(record[key], depth + 1);
+		if (text) return text;
+	}
+}
+function normalizePermissionOptions(value) {
+	if (!Array.isArray(value)) return [];
+	const options = [];
+	for (const item of value) {
+		const record = asRecord(item);
+		if (!record) continue;
+		const option_id = stringField(record, "option_id", "optionId") ?? "";
+		const label = stringField(record, "label") ?? option_id;
+		const kind = stringField(record, "kind") ?? "";
+		if (!option_id && !label && !kind) continue;
+		options.push({
+			option_id,
+			label,
+			kind
+		});
+	}
+	return options;
+}
+function normalizePermission$1(record) {
+	const request_id = stringField(record, "request_id", "requestID", "id");
+	const description = stringField(record, "description", "title");
+	const question = stringField(record, "question", "message");
+	const tool = stringField(record, "tool");
+	const options = normalizePermissionOptions(record.options);
+	const kind = stringField(record, "kind", "status");
+	if (!request_id && !description && !question && !tool && options.length === 0 && !kind) return;
+	return {
+		request_id,
+		description,
+		question,
+		tool,
+		options,
+		kind
+	};
+}
+function normalizeTool(record, fallbackStatus) {
+	const title = stringField(record, "title", "toolName", "name");
+	const kind = stringField(record, "kind", "toolKind");
+	const id = stringField(record, "tool_call_id", "toolCallId", "call_id", "callId", "id", "message_id", "messageID", "part_id", "partID");
+	const status = stringField(record, "status", "state") ?? fallbackStatus;
+	const preview = extractEventText(record.preview) ?? extractEventText(record.arguments) ?? extractEventText(record.args) ?? extractEventText(record.input) ?? extractEventText(record.result) ?? extractEventText(record.output) ?? extractEventText(record.delta);
+	if (!id && !title && !kind && !status && !preview) return;
+	return {
+		key: id ?? title ?? kind ?? "tool",
+		id,
+		title,
+		kind,
+		status,
+		preview
+	};
+}
+function semanticFingerprint(event, delta, tool, permission, stopReason) {
+	if (delta) return `${event}:${delta.length}:${delta.slice(0, 512)}`;
+	if (tool) return `${event}:${tool.id ?? tool.title ?? tool.kind ?? tool.key}:${tool.status ?? ""}:${tool.preview ?? ""}`;
+	if (permission) return `${event}:${permission.request_id ?? permission.question ?? permission.description ?? permission.tool ?? ""}:${permission.kind ?? ""}`;
+	if (stopReason) return `${event}:${stopReason}`;
+}
+function normalizeRunEvent(input) {
+	const raw = asRecord(input);
+	if (!raw) return null;
+	const source_event = stringField(raw, "event", "type");
+	if (!source_event) return null;
+	const session_id = stringField(raw, "session_id", "sessionID", "sessionId");
+	const runtime_id = stringField(raw, "runtime_id", "runtimeID");
+	const run_id = stringField(raw, "run_id", "runId");
+	const run_label = stringField(raw, "run_label", "runLabel", "label");
+	const seq = numberField(raw, "seq");
+	const ts = numberField(raw, "ts", "timestamp");
+	const phase = stringField(raw, "phase", "status");
+	const phase_label = stringField(raw, "phase_label", "label");
+	const stop_reason = stringField(raw, "stop_reason", "stopReason");
+	const final_output = stringField(raw, "final_output", "finalOutput");
+	const backend = stringField(raw, "backend");
+	const agent = stringField(raw, "agent");
+	const model = stringField(raw, "model");
+	const dir = stringField(raw, "dir");
+	const parent_id = stringField(raw, "parent_id", "parentId");
+	const children = stringArrayField(raw, "children");
+	const event_path = stringField(raw, "event_path", "on_event");
+	const usage = asRecord(raw.usage) ?? void 0;
+	let event = source_event;
+	let alias = false;
+	let delta;
+	let chunk_role;
+	let tool;
+	let permission;
+	switch (source_event) {
+		case "agent.message_chunk":
+			chunk_role = "assistant";
+			delta = extractEventText(raw);
+			break;
+		case "agent.thought_chunk":
+			chunk_role = "thought";
+			delta = extractEventText(raw);
+			break;
+		case "user.message_chunk":
+			chunk_role = "user";
+			delta = extractEventText(raw);
+			break;
+		case "tool.call":
+			tool = normalizeTool(raw, "running");
+			break;
+		case "tool.call_update":
+			tool = normalizeTool(raw);
+			break;
+		case "permission.request":
+		case "permission.response":
+			permission = normalizePermission$1(raw);
+			break;
+		case "avenor.message.delta":
+			event = "agent.message_chunk";
+			alias = true;
+			chunk_role = "assistant";
+			delta = extractEventText(raw);
+			break;
+		case "avenor.message.update": {
+			alias = true;
+			const assistantMessageEvent = asRecord(raw.assistantMessageEvent) ?? raw;
+			const assistantType = stringField(assistantMessageEvent, "type");
+			if (assistantType === "thinking_delta") {
+				event = "agent.thought_chunk";
+				chunk_role = "thought";
+				delta = extractEventText(assistantMessageEvent);
+			} else if (assistantType === "toolcall_start") {
+				event = "tool.call";
+				tool = normalizeTool(assistantMessageEvent, "running");
+			} else if (assistantType === "toolcall_delta" || assistantType === "toolcall_update" || assistantType === "toolcall_end") {
+				event = "tool.call_update";
+				tool = normalizeTool(assistantMessageEvent, assistantType === "toolcall_end" ? "completed" : "running");
+			} else {
+				event = "agent.message_chunk";
+				chunk_role = "assistant";
+				delta = extractEventText(assistantMessageEvent);
+			}
+			break;
+		}
+		case "avenor.tool.start":
+			event = "tool.call";
+			alias = true;
+			tool = normalizeTool(raw, "running");
+			break;
+		case "avenor.tool.update":
+			event = "tool.call_update";
+			alias = true;
+			tool = normalizeTool(raw);
+			break;
+		case "avenor.tool.end":
+			event = "tool.call_update";
+			alias = true;
+			tool = normalizeTool(raw, "completed");
+			break;
+	}
+	return {
+		event,
+		source_event,
+		raw: { ...raw },
+		runtime_id,
+		session_id,
+		run_id,
+		run_label,
+		seq,
+		ts,
+		phase,
+		phase_label,
+		stop_reason,
+		final_output,
+		usage,
+		backend,
+		agent,
+		model,
+		dir,
+		parent_id,
+		children,
+		event_path,
+		delta,
+		chunk_role,
+		tool,
+		permission,
+		alias,
+		semantic_fingerprint: semanticFingerprint(event, delta, tool, permission, stop_reason)
+	};
+}
+//#endregion
+//#region src/run-reducer.ts
+const DEFAULT_RUN_REDUCER_LIMITS = {
+	transcript_entries: 64,
+	text_chars: 4e3,
+	tool_preview_chars: 1e3,
+	tools: 24,
+	permissions: 16,
+	legacy_keys: 128
+};
+function clipText(text, limit) {
+	if (!text) return void 0;
+	if (text.length <= limit) return text;
+	return text.slice(text.length - limit);
+}
+function appendText(current, delta, limit) {
+	if (!delta) return current;
+	return clipText(`${current}${delta}`, limit) ?? current;
+}
+function pushBounded(items, item, limit) {
+	const next = [...items, item];
+	if (next.length <= limit) return next;
+	return next.slice(next.length - limit);
+}
+function toLegacyKey(event) {
+	return JSON.stringify([
+		event.runtime_id ?? event.session_id ?? "",
+		event.event,
+		event.ts ?? "",
+		event.delta ?? "",
+		event.tool?.id ?? event.tool?.title ?? event.tool?.status ?? "",
+		event.permission?.request_id ?? event.permission?.question ?? "",
+		event.stop_reason ?? ""
+	]);
+}
+function normalizeLimits(limits) {
+	return {
+		transcript_entries: Math.max(1, Math.trunc(limits?.transcript_entries ?? DEFAULT_RUN_REDUCER_LIMITS.transcript_entries)),
+		text_chars: Math.max(1, Math.trunc(limits?.text_chars ?? DEFAULT_RUN_REDUCER_LIMITS.text_chars)),
+		tool_preview_chars: Math.max(1, Math.trunc(limits?.tool_preview_chars ?? DEFAULT_RUN_REDUCER_LIMITS.tool_preview_chars)),
+		tools: Math.max(1, Math.trunc(limits?.tools ?? DEFAULT_RUN_REDUCER_LIMITS.tools)),
+		permissions: Math.max(1, Math.trunc(limits?.permissions ?? DEFAULT_RUN_REDUCER_LIMITS.permissions)),
+		legacy_keys: Math.max(1, Math.trunc(limits?.legacy_keys ?? DEFAULT_RUN_REDUCER_LIMITS.legacy_keys))
+	};
+}
+function createRunSnapshot(limits) {
+	return {
+		identity: {},
+		limits: normalizeLimits(limits),
+		ended: false,
+		assistant_text: "",
+		thought_text: "",
+		user_text: "",
+		transcript: [],
+		tools: [],
+		live_tools: [],
+		permissions: [],
+		_seen_seq_by_scope: {},
+		_recent_legacy_keys: []
+	};
+}
+function transcriptText(entry, limits) {
+	if (!entry.text) return entry;
+	return {
+		...entry,
+		text: clipText(entry.text, limits.text_chars)
+	};
+}
+function appendTranscript(snapshot, entry) {
+	const nextEntry = transcriptText(entry, snapshot.limits);
+	const last = snapshot.transcript[snapshot.transcript.length - 1];
+	if (last && last.kind === nextEntry.kind && nextEntry.text && last.text && last.event === nextEntry.event) {
+		const merged = {
+			...last,
+			text: clipText(`${last.text}${nextEntry.text}`, snapshot.limits.text_chars),
+			seq: nextEntry.seq ?? last.seq,
+			ts: nextEntry.ts ?? last.ts
+		};
+		return [...snapshot.transcript.slice(0, -1), merged];
+	}
+	return pushBounded(snapshot.transcript, nextEntry, snapshot.limits.transcript_entries);
+}
+function mergeIdentity(snapshot, event) {
+	return {
+		runtime_id: event.runtime_id ?? snapshot.identity.runtime_id,
+		session_id: event.session_id ?? snapshot.identity.session_id,
+		run_id: event.run_id ?? snapshot.identity.run_id,
+		run_label: event.run_label ?? snapshot.identity.run_label,
+		backend: event.backend ?? snapshot.identity.backend,
+		agent: event.agent ?? snapshot.identity.agent,
+		model: event.model ?? snapshot.identity.model,
+		dir: event.dir ?? snapshot.identity.dir,
+		parent_id: event.parent_id ?? snapshot.identity.parent_id,
+		children: event.children ?? snapshot.identity.children,
+		event_path: event.event_path ?? snapshot.identity.event_path
+	};
+}
+function withToolPreview(tool, limit) {
+	if (!tool) return tool;
+	return {
+		...tool,
+		preview: clipText(tool.preview, limit)
+	};
+}
+function mergeToolState(snapshot, event, live) {
+	const tool = withToolPreview(event.tool, snapshot.limits.tool_preview_chars);
+	if (!tool) return snapshot.tools;
+	const tools = snapshot.tools.map((item) => ({ ...item }));
+	const index = tools.findIndex((item) => item.key === tool.key);
+	const existing = index >= 0 ? tools[index] : void 0;
+	const next = {
+		key: tool.key,
+		id: tool.id ?? existing?.id,
+		title: tool.title ?? existing?.title,
+		kind: tool.kind ?? existing?.kind,
+		status: tool.status ?? existing?.status,
+		preview: clipText(tool.preview ?? existing?.preview, snapshot.limits.tool_preview_chars),
+		started_at: existing?.started_at ?? event.ts,
+		updated_at: event.ts ?? existing?.updated_at,
+		ended_at: live ? existing?.ended_at : event.ts ?? existing?.ended_at,
+		live
+	};
+	if (index >= 0) tools[index] = next;
+	else tools.push(next);
+	return tools.length <= snapshot.limits.tools ? tools : tools.slice(tools.length - snapshot.limits.tools);
+}
+function liveTools(tools) {
+	return tools.filter((tool) => tool.live);
+}
+function mergePermissionHistory(snapshot, permission, resolved = false) {
+	if (!permission) return {
+		pending_permission: resolved ? void 0 : snapshot.pending_permission,
+		permissions: snapshot.permissions
+	};
+	const permissions = snapshot.permissions.map((item) => ({ ...item }));
+	const index = permission.request_id ? permissions.findIndex((item) => item.request_id === permission.request_id) : -1;
+	const entry = {
+		...permission,
+		kind: resolved ? permission.kind ?? "resolved" : permission.kind,
+		options: permission.options.map((option) => ({ ...option }))
+	};
+	if (index >= 0) permissions[index] = {
+		...permissions[index],
+		...entry
+	};
+	else permissions.push(entry);
+	const bounded = permissions.length <= snapshot.limits.permissions ? permissions : permissions.slice(permissions.length - snapshot.limits.permissions);
+	return {
+		pending_permission: resolved ? void 0 : entry,
+		permissions: bounded
+	};
+}
+function shouldSkipSemanticUpdate(snapshot, event) {
+	if (!event.alias || !event.semantic_fingerprint) return false;
+	return snapshot._last_semantic_fingerprint === event.semantic_fingerprint && snapshot._last_source_event !== event.source_event;
+}
+function updateDedupeState(snapshot, event) {
+	const scope = event.runtime_id ?? event.session_id ?? "global";
+	if (event.seq !== void 0) {
+		const seen = snapshot._seen_seq_by_scope[scope] ?? 0;
+		if (event.seq <= seen) return null;
+		return {
+			_seen_seq_by_scope: {
+				...snapshot._seen_seq_by_scope,
+				[scope]: event.seq
+			},
+			_recent_legacy_keys: snapshot._recent_legacy_keys
+		};
+	}
+	const key = toLegacyKey(event);
+	if (snapshot._recent_legacy_keys.includes(key)) return null;
+	const nextKeys = [...snapshot._recent_legacy_keys, key];
+	return {
+		_seen_seq_by_scope: snapshot._seen_seq_by_scope,
+		_recent_legacy_keys: nextKeys.length <= snapshot.limits.legacy_keys ? nextKeys : nextKeys.slice(nextKeys.length - snapshot.limits.legacy_keys)
+	};
+}
+function reduceRunSnapshot(current, input, limits) {
+	const snapshot = limits ? {
+		...current,
+		limits: normalizeLimits({
+			...current.limits,
+			...limits
+		})
+	} : current;
+	const event = normalizeRunEvent(input);
+	if (!event) return snapshot;
+	const dedupe = updateDedupeState(snapshot, event);
+	if (!dedupe) return snapshot;
+	let next = {
+		...snapshot,
+		identity: mergeIdentity(snapshot, event),
+		latest_seq: event.seq ?? snapshot.latest_seq,
+		last_event: event.event,
+		last_ts: event.ts ?? snapshot.last_ts,
+		phase: event.event === "session.end" ? "done" : event.phase ?? snapshot.phase,
+		phase_label: event.phase_label ?? snapshot.phase_label,
+		stop_reason: event.stop_reason ?? snapshot.stop_reason,
+		usage: event.usage ? {
+			...snapshot.usage ?? {},
+			...event.usage
+		} : snapshot.usage,
+		final_output: clipText(event.final_output ?? snapshot.final_output, snapshot.limits.text_chars),
+		_seen_seq_by_scope: dedupe._seen_seq_by_scope,
+		_recent_legacy_keys: dedupe._recent_legacy_keys
+	};
+	if (event.event === "session.end") next.ended = true;
+	if (shouldSkipSemanticUpdate(next, event)) return {
+		...next,
+		_last_semantic_fingerprint: event.semantic_fingerprint ?? next._last_semantic_fingerprint,
+		_last_source_event: event.source_event
+	};
+	switch (event.event) {
+		case "agent.message_chunk": {
+			const text = clipText(event.delta, next.limits.text_chars);
+			next.assistant_text = appendText(next.assistant_text, text, next.limits.text_chars);
+			if (text) next.transcript = appendTranscript(next, {
+				kind: "assistant",
+				event: event.event,
+				source_event: event.source_event,
+				text,
+				seq: event.seq,
+				ts: event.ts
+			});
+			break;
+		}
+		case "agent.thought_chunk": {
+			const text = clipText(event.delta, next.limits.text_chars);
+			next.thought_text = appendText(next.thought_text, text, next.limits.text_chars);
+			if (text) next.transcript = appendTranscript(next, {
+				kind: "thought",
+				event: event.event,
+				source_event: event.source_event,
+				text,
+				seq: event.seq,
+				ts: event.ts
+			});
+			break;
+		}
+		case "user.message_chunk": {
+			const text = clipText(event.delta, next.limits.text_chars);
+			next.user_text = appendText(next.user_text, text, next.limits.text_chars);
+			if (text) next.transcript = appendTranscript(next, {
+				kind: "user",
+				event: event.event,
+				source_event: event.source_event,
+				text,
+				seq: event.seq,
+				ts: event.ts
+			});
+			break;
+		}
+		case "tool.call":
+			next.tools = mergeToolState(next, event, true);
+			next.live_tools = liveTools(next.tools);
+			next.transcript = appendTranscript(next, {
+				kind: "tool",
+				event: event.event,
+				source_event: event.source_event,
+				title: event.tool?.title ?? event.tool?.kind,
+				status: event.tool?.status,
+				text: clipText(event.tool?.preview, next.limits.tool_preview_chars),
+				seq: event.seq,
+				ts: event.ts
+			});
+			break;
+		case "tool.call_update":
+			next.tools = mergeToolState(next, event, ![
+				"completed",
+				"complete",
+				"done",
+				"failed",
+				"cancelled",
+				"canceled"
+			].includes((event.tool?.status ?? "").toLowerCase()));
+			next.live_tools = liveTools(next.tools);
+			next.transcript = appendTranscript(next, {
+				kind: "tool",
+				event: event.event,
+				source_event: event.source_event,
+				title: event.tool?.title ?? event.tool?.kind,
+				status: event.tool?.status,
+				text: clipText(event.tool?.preview, next.limits.tool_preview_chars),
+				seq: event.seq,
+				ts: event.ts
+			});
+			break;
+		case "permission.request": {
+			const permission = mergePermissionHistory(next, event.permission);
+			next.pending_permission = permission.pending_permission;
+			next.permissions = permission.permissions;
+			next.phase = "waiting";
+			next.phase_label = event.permission?.question ?? event.permission?.description ?? event.permission?.tool ?? next.phase_label;
+			next.transcript = appendTranscript(next, {
+				kind: "permission",
+				event: event.event,
+				source_event: event.source_event,
+				request_id: event.permission?.request_id,
+				text: clipText(event.permission?.question ?? event.permission?.description ?? event.permission?.tool, next.limits.text_chars),
+				seq: event.seq,
+				ts: event.ts
+			});
+			break;
+		}
+		case "permission.response": {
+			const permission = mergePermissionHistory(next, event.permission ?? next.pending_permission, true);
+			next.pending_permission = permission.pending_permission;
+			next.permissions = permission.permissions;
+			next.transcript = appendTranscript(next, {
+				kind: "permission",
+				event: event.event,
+				source_event: event.source_event,
+				request_id: event.permission?.request_id ?? next.pending_permission?.request_id,
+				text: clipText(event.permission?.kind ?? event.permission?.description, next.limits.text_chars),
+				seq: event.seq,
+				ts: event.ts
+			});
+			break;
+		}
+		case "agent.status":
+			next.phase = event.phase ?? next.phase;
+			next.phase_label = event.phase_label ?? next.phase_label;
+			next.transcript = appendTranscript(next, {
+				kind: "status",
+				event: event.event,
+				source_event: event.source_event,
+				text: clipText(event.phase_label ?? event.phase, next.limits.text_chars),
+				seq: event.seq,
+				ts: event.ts
+			});
+			break;
+		case "session.end":
+			next.live_tools = [];
+			next.tools = next.tools.map((tool) => ({
+				...tool,
+				live: false
+			}));
+			if (!next.final_output) next.final_output = clipText(next.assistant_text, next.limits.text_chars);
+			next.pending_permission = void 0;
+			next.transcript = appendTranscript(next, {
+				kind: "session",
+				event: event.event,
+				source_event: event.source_event,
+				text: clipText(event.final_output ?? event.stop_reason, next.limits.text_chars),
+				status: event.stop_reason,
+				seq: event.seq,
+				ts: event.ts
+			});
+			break;
+		case "session.start":
+			next.ended = false;
+			next.transcript = appendTranscript(next, {
+				kind: "session",
+				event: event.event,
+				source_event: event.source_event,
+				text: clipText(event.backend, next.limits.text_chars),
+				seq: event.seq,
+				ts: event.ts
+			});
+			break;
+	}
+	return {
+		...next,
+		_last_semantic_fingerprint: event.semantic_fingerprint ?? next._last_semantic_fingerprint,
+		_last_source_event: event.source_event
+	};
+}
+var RunReducer = class {
+	state;
+	constructor(limits, initial) {
+		const base = createRunSnapshot(limits);
+		if (!initial) {
+			this.state = base;
+			return;
+		}
+		const identity = {
+			...base.identity,
+			...initial.identity ?? {}
+		};
+		const scope = identity.runtime_id ?? identity.session_id ?? "global";
+		const seenSeq = initial.latest_seq === void 0 ? {} : { [scope]: initial.latest_seq };
+		this.state = {
+			...base,
+			...initial,
+			identity,
+			limits: base.limits,
+			ended: initial.ended ?? base.ended,
+			assistant_text: initial.assistant_text ?? base.assistant_text,
+			thought_text: initial.thought_text ?? base.thought_text,
+			user_text: initial.user_text ?? base.user_text,
+			transcript: (initial.transcript ?? base.transcript).map((entry) => ({ ...entry })),
+			tools: (initial.tools ?? base.tools).map((tool) => ({ ...tool })),
+			live_tools: (initial.live_tools ?? base.live_tools).map((tool) => ({ ...tool })),
+			pending_permission: initial.pending_permission ? {
+				...initial.pending_permission,
+				options: initial.pending_permission.options.map((option) => ({ ...option }))
+			} : void 0,
+			permissions: (initial.permissions ?? base.permissions).map((permission) => ({
+				...permission,
+				options: permission.options.map((option) => ({ ...option }))
+			})),
+			_seen_seq_by_scope: seenSeq,
+			_recent_legacy_keys: []
+		};
+	}
+	apply(input) {
+		this.state = reduceRunSnapshot(this.state, input);
+		return this.snapshot();
+	}
+	snapshot() {
+		return {
+			...this.state,
+			identity: { ...this.state.identity },
+			usage: this.state.usage ? { ...this.state.usage } : void 0,
+			transcript: this.state.transcript.map((entry) => ({ ...entry })),
+			tools: this.state.tools.map((tool) => ({ ...tool })),
+			live_tools: this.state.live_tools.map((tool) => ({ ...tool })),
+			pending_permission: this.state.pending_permission ? {
+				...this.state.pending_permission,
+				options: this.state.pending_permission.options.map((option) => ({ ...option }))
+			} : void 0,
+			permissions: this.state.permissions.map((permission) => ({
+				...permission,
+				options: permission.options.map((option) => ({ ...option }))
+			})),
+			_seen_seq_by_scope: { ...this.state._seen_seq_by_scope },
+			_recent_legacy_keys: [...this.state._recent_legacy_keys]
+		};
+	}
+};
+//#endregion
+//#region src/run-observer.ts
+function observeRun(client, options = {}) {
+	const reducer = new RunReducer(options.reducer_limits, options.initial_snapshot);
+	const listeners = /* @__PURE__ */ new Set();
+	const pendingNext = [];
+	const streamOptions = {};
+	if (options.runtime_id) {
+		streamOptions.runtime_id = options.runtime_id;
+		streamOptions.replay = options.replay ?? true;
+	} else if (options.replay !== void 0) streamOptions.replay = options.replay;
+	if (options.limit !== void 0) streamOptions.limit = options.limit;
+	if (options.after_seq !== void 0) streamOptions.after_seq = options.after_seq;
+	const iterator = client.events(streamOptions)[Symbol.asyncIterator]();
+	let closed = false;
+	let clientClosed = false;
+	let failure = null;
+	const closeClient = () => {
+		if (!options.close_client || clientClosed) return;
+		clientClosed = true;
+		client.close?.();
+	};
+	const flushPending = (snapshot) => {
+		const unresolved = pendingNext.splice(0, pendingNext.length);
+		for (const waiter of unresolved) {
+			if (failure) {
+				waiter.reject(failure);
+				continue;
+			}
+			if (snapshot && waiter.predicate && !waiter.predicate(snapshot)) {
+				pendingNext.push(waiter);
+				continue;
+			}
+			waiter.resolve(snapshot);
+		}
+	};
+	const loop = (async () => {
+		try {
+			while (!closed) {
+				const result = await iterator.next();
+				if (result.done || closed) break;
+				const snapshot = reducer.apply(result.value);
+				for (const listener of listeners) listener(snapshot, result.value);
+				flushPending(snapshot);
+			}
+		} catch (error) {
+			failure = error instanceof Error ? error : new Error(String(error));
+		} finally {
+			closed = true;
+			flushPending(null);
+		}
+	})();
+	return {
+		get closed() {
+			return closed;
+		},
+		snapshot() {
+			return reducer.snapshot();
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		next(predicate) {
+			if (failure) return Promise.reject(failure);
+			if (closed) return Promise.resolve(null);
+			return new Promise((resolve, reject) => {
+				pendingNext.push({
+					resolve,
+					reject,
+					predicate
+				});
+			});
+		},
+		async close() {
+			try {
+				if (!closed) {
+					closed = true;
+					if (typeof iterator.return === "function") await iterator.return();
+				}
+				await loop.catch(() => {});
+			} finally {
+				closeClient();
+			}
+		}
+	};
+}
+//#endregion
 //#region src/paths.ts
 function avenorHome() {
 	return process.env.AVENOR_HOME || path.join(os.homedir(), ".avenor");
@@ -591,33 +1448,77 @@ function translateStatus(rawPhase, sentinelData) {
 		default: return "running";
 	}
 }
-async function buildRunStatus(client, runInfo, liveStatus) {
+function normalizePermission(raw) {
+	if (!raw) return void 0;
+	const request_id = stringField(raw, "request_id", "requestID") ?? "";
+	const description = stringField(raw, "description", "question", "tool", "title") ?? "";
+	const optionsRaw = raw.options;
+	const options = Array.isArray(optionsRaw) ? optionsRaw.map((item) => {
+		const record = asRecord(item);
+		if (!record) return null;
+		return {
+			option_id: stringField(record, "option_id", "optionId") ?? "",
+			label: stringField(record, "label") ?? "",
+			kind: stringField(record, "kind") ?? ""
+		};
+	}).filter((item) => item !== null) : [];
+	if (!request_id && !description && options.length === 0) return;
+	return {
+		request_id,
+		description,
+		options
+	};
+}
+function extractPendingPermission(liveStatus) {
+	if (!liveStatus) return void 0;
+	const permission = normalizePermission(asRecord(liveStatus.permission));
+	if (permission) return permission;
+	const pendingPermission = liveStatus.pending_permission;
+	if (typeof pendingPermission === "boolean") return;
+	return normalizePermission(asRecord(pendingPermission));
+}
+function buildBaseStatus(source, fallback, translatedStatus) {
+	return {
+		run_id: stringField(source, "run_id") ?? fallback.run_id,
+		label: stringField(source, "label") ?? fallback.label,
+		status: translatedStatus,
+		runtime_id: stringField(source, "runtime_id", "id") ?? fallback.runtime_id,
+		phase: stringField(source, "phase"),
+		phase_label: stringField(source, "phase_label"),
+		pending_permission: extractPendingPermission(source),
+		session_id: stringField(source, "session_id") ?? fallback.session_id,
+		stop_reason: stringField(source, "stop_reason") ?? fallback.stop_reason,
+		backend: stringField(source, "backend"),
+		agent: stringField(source, "agent"),
+		model: stringField(source, "model"),
+		dir: stringField(source, "dir"),
+		parent_id: stringField(source, "parent_id", "parentId"),
+		children: stringArrayField(source, "children"),
+		event_path: stringField(source, "event_path", "on_event"),
+		usage: asRecord(source.usage) ?? void 0,
+		latest_seq: numberField(source, "latest_seq"),
+		final_output: stringField(source, "final_output", "finalOutput")
+	};
+}
+async function buildRunStatus(runInfo, liveStatus) {
 	let sentinel = null;
 	if (await sentinelExists(runInfo.sentinelPath)) sentinel = await parseSentinel$1(runInfo.sentinelPath);
 	const translated = translateStatus(liveStatus?.phase ?? liveStatus?.status ?? "running", sentinel);
-	const result = {
+	return buildBaseStatus(liveStatus ?? {}, {
 		run_id: runInfo.runId,
 		label: runInfo.label,
-		status: translated,
-		runtime_id: liveStatus?.runtime_id ?? runInfo.runtimeId,
-		phase: liveStatus?.phase,
-		phase_label: liveStatus?.phase_label,
-		session_id: sentinel?.SESSION ?? liveStatus?.session_id ?? void 0,
-		stop_reason: sentinel?._status ?? void 0
-	};
-	if (liveStatus?.pending_permission) {
-		const pp = liveStatus.pending_permission;
-		result.pending_permission = {
-			request_id: pp.request_id ?? "",
-			description: pp.description ?? "",
-			options: Array.isArray(pp.options) ? pp.options.map((o) => ({
-				option_id: o.option_id ?? "",
-				label: o.label ?? "",
-				kind: o.kind ?? ""
-			})) : []
-		};
+		runtime_id: runInfo.runtimeId,
+		session_id: sentinel?.SESSION ?? liveStatus?.session_id ?? runInfo.sessionId,
+		stop_reason: sentinel?._status
+	}, translated);
+}
+async function queryLiveStatus(client, runtimeId) {
+	if (!runtimeId) return null;
+	try {
+		return await client.status(runtimeId);
+	} catch {
+		return null;
 	}
-	return result;
 }
 async function statusTool(args) {
 	if (args.supervisorId) {
@@ -626,47 +1527,34 @@ async function statusTool(args) {
 			if (args.runId) {
 				validateRunId(args.runId);
 				const runInfo = isSingleton && sup ? findRunByLabel$3(sup, args.runId) : void 0;
-				if (runInfo) {
-					let liveStatus = null;
-					if (runInfo.runtimeId) try {
-						liveStatus = await client.status(runInfo.runtimeId);
-					} catch {}
-					return buildRunStatus(client, runInfo, liveStatus);
-				}
-				let liveStatus = null;
-				try {
-					liveStatus = await client.status(args.runId);
+				if (runInfo) return buildRunStatus(runInfo, await queryLiveStatus(client, runInfo.runtimeId));
+				let liveStatus = await queryLiveStatus(client, args.runId);
+				if (!liveStatus) try {
+					const entry = (await client.list()).find((item) => {
+						const runtimeId = String(item.runtime_id ?? item.id ?? "");
+						const label = String(item.label ?? "");
+						const runId = String(item.run_id ?? "");
+						return runtimeId === args.runId || label === args.runId || runId === args.runId;
+					});
+					if (entry) liveStatus = await queryLiveStatus(client, String(entry.runtime_id ?? entry.id ?? "")) ?? entry;
 				} catch {}
 				const sentinelPath = liveStatus?.sentinel_file ?? path.join(runsRoot(), args.runId, "sentinel.done");
 				let sentinel = null;
 				if (await sentinelExists(sentinelPath)) sentinel = await parseSentinel$1(sentinelPath);
-				return {
+				return buildBaseStatus(liveStatus ?? {}, {
 					run_id: args.runId,
 					label: args.runId,
-					status: translateStatus(liveStatus?.phase ?? liveStatus?.status ?? "running", sentinel),
-					runtime_id: liveStatus?.runtime_id,
-					phase: liveStatus?.phase,
-					phase_label: liveStatus?.phase_label,
-					session_id: sentinel?.SESSION ?? liveStatus?.session_id ?? void 0,
-					stop_reason: sentinel?._status ?? void 0,
-					pending_permission: liveStatus?.pending_permission ? {
-						request_id: liveStatus.pending_permission.request_id ?? "",
-						description: liveStatus.pending_permission.description ?? "",
-						options: Array.isArray(liveStatus.pending_permission.options) ? liveStatus.pending_permission.options.map((o) => ({
-							option_id: o.option_id ?? "",
-							label: o.label ?? "",
-							kind: o.kind ?? ""
-						})) : []
-					} : void 0
-				};
+					runtime_id: stringField(liveStatus ?? {}, "runtime_id", "id"),
+					session_id: sentinel?.SESSION ?? liveStatus?.session_id,
+					stop_reason: sentinel?._status
+				}, translateStatus(liveStatus?.phase ?? liveStatus?.status ?? "running", sentinel));
 			}
-			return (await client.list()).map((entry) => ({
-				run_id: entry.runtime_id ?? entry.id ?? "",
-				label: entry.label ?? "",
-				status: translateStatus(entry.phase ?? entry.status ?? "running", null),
-				phase: entry.phase,
+			return (await client.list()).map((entry) => buildBaseStatus(entry, {
+				run_id: String(entry.run_id ?? entry.runtime_id ?? entry.id ?? ""),
+				label: String(entry.label ?? entry.runtime_id ?? entry.id ?? ""),
+				runtime_id: String(entry.runtime_id ?? entry.id ?? ""),
 				session_id: entry.session_id
-			}));
+			}, translateStatus(entry.phase ?? entry.status ?? "running", null)));
 		} finally {
 			if (!isSingleton) client.close();
 		}
@@ -675,58 +1563,34 @@ async function statusTool(args) {
 	const client = sup.getClient();
 	if (args.runId) {
 		const runInfo = findRunByLabel$3(sup, args.runId);
-		if (runInfo) {
-			let liveStatus = null;
-			if (runInfo.runtimeId) try {
-				liveStatus = await client.status(runInfo.runtimeId);
-			} catch {}
-			return buildRunStatus(client, runInfo, liveStatus);
-		}
+		if (runInfo) return buildRunStatus(runInfo, await queryLiveStatus(client, runInfo.runtimeId));
 		validateRunId(args.runId);
-		let liveStatus = null;
-		try {
-			liveStatus = await client.status(args.runId);
-		} catch {}
+		const liveStatus = await queryLiveStatus(client, args.runId);
 		const sentinelPath = path.join(runsRoot(), args.runId, "sentinel.done");
 		let sentinel = null;
 		if (await sentinelExists(sentinelPath)) sentinel = await parseSentinel$1(sentinelPath);
-		return {
+		return buildBaseStatus(liveStatus ?? {}, {
 			run_id: args.runId,
 			label: args.runId,
-			status: translateStatus(liveStatus?.phase ?? liveStatus?.status ?? "running", sentinel),
-			phase: liveStatus?.phase,
-			phase_label: liveStatus?.phase_label,
-			session_id: sentinel?.SESSION ?? liveStatus?.session_id ?? void 0,
-			stop_reason: sentinel?._status ?? void 0,
-			pending_permission: liveStatus?.pending_permission ? {
-				request_id: liveStatus.pending_permission.request_id ?? "",
-				description: liveStatus.pending_permission.description ?? "",
-				options: Array.isArray(liveStatus.pending_permission.options) ? liveStatus.pending_permission.options.map((o) => ({
-					option_id: o.option_id ?? "",
-					label: o.label ?? "",
-					kind: o.kind ?? ""
-				})) : []
-			} : void 0
-		};
+			runtime_id: stringField(liveStatus ?? {}, "runtime_id", "id"),
+			session_id: sentinel?.SESSION ?? liveStatus?.session_id,
+			stop_reason: sentinel?._status
+		}, translateStatus(liveStatus?.phase ?? liveStatus?.status ?? "running", sentinel));
 	}
 	const list = await client.list();
 	const results = [];
 	for (const entry of list) {
-		const entryId = entry.runtime_id ?? entry.id ?? "";
-		const entryLabel = entry.label ?? entryId;
+		const entryId = String(entry.runtime_id ?? entry.id ?? "");
+		const entryLabel = String(entry.label ?? entryId);
 		const runInfo = findRunByLabel$3(sup, entryId) ?? findRunByLabel$3(sup, entryLabel);
-		let liveStatus = null;
-		if (runInfo?.runtimeId) try {
-			liveStatus = await client.status(runInfo.runtimeId);
-		} catch {}
-		if (runInfo && liveStatus) results.push(await buildRunStatus(client, runInfo, liveStatus));
-		else results.push({
-			run_id: entryId,
+		const liveStatus = runInfo ? await queryLiveStatus(client, runInfo.runtimeId) : null;
+		if (runInfo && liveStatus) results.push(await buildRunStatus(runInfo, liveStatus));
+		else results.push(buildBaseStatus(entry, {
+			run_id: String(entry.run_id ?? entryId),
 			label: entryLabel,
-			status: translateStatus(entry.phase ?? entry.status ?? "running", null),
-			phase: entry.phase,
+			runtime_id: entryId,
 			session_id: entry.session_id
-		});
+		}, translateStatus(entry.phase ?? entry.status ?? "running", null)));
 	}
 	return results;
 }
@@ -843,41 +1707,240 @@ async function followUpTool(args) {
 }
 //#endregion
 //#region src/tools/events.ts
+const MAX_EVENT_LIMIT = 1e3;
+const MAX_STRING_CHARS = 4e3;
+const MAX_ARRAY_ITEMS = 32;
+const MAX_OBJECT_KEYS = 64;
 function findRunByLabel(sup, runId) {
 	const runs = sup.runs;
 	const byKey = runs.get(runId);
 	if (byKey) return byKey;
 	for (const info of runs.values()) if (info.label === runId) return info;
 }
-async function eventsTool(args) {
-	if (args.supervisorId) throw new Error("eventsTool with explicit supervisorId not supported — event log path must be tracked by the singleton supervisor");
-	const runInfo = findRunByLabel(await Supervisor.get(), args.runId);
-	if (!runInfo) throw new Error(`run not found: ${args.runId}`);
-	const limit = Math.max(1, Math.min(1e3, Math.trunc(args.limit ?? 50)));
-	let raw;
+function normalizeLimit(limit) {
+	return Math.max(1, Math.min(MAX_EVENT_LIMIT, Math.trunc(limit ?? 50)));
+}
+function contextualError(context, error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return /* @__PURE__ */ new Error(`${context}: ${message}`);
+}
+function eventName(record) {
+	const event = record.event;
+	if (typeof event === "string" && event.length > 0) return event;
+	const type = record.type;
+	return typeof type === "string" ? type : "";
+}
+function eventSeq(record) {
+	const value = record.seq;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim().length > 0) {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+}
+function clipValue(value) {
+	if (typeof value === "string") {
+		if (value.length <= MAX_STRING_CHARS) return value;
+		return value.slice(value.length - MAX_STRING_CHARS);
+	}
+	if (Array.isArray(value)) return (value.length <= MAX_ARRAY_ITEMS ? value : value.slice(value.length - MAX_ARRAY_ITEMS)).map((item) => clipValue(item));
+	const record = asRecord(value);
+	if (!record) return value;
+	const result = {};
+	const entries = Object.entries(record).slice(0, MAX_OBJECT_KEYS);
+	for (const [key, item] of entries) result[key] = clipValue(item);
+	return result;
+}
+function clipEvent(record) {
+	return clipValue(record);
+}
+function matchesFilters(record, args) {
+	const name = eventName(record);
+	if (args.types && args.types.length > 0 && !args.types.includes(name)) return false;
+	const seq = eventSeq(record);
+	if (args.after_seq !== void 0 && seq !== void 0 && seq <= args.after_seq) return false;
+	return true;
+}
+async function readNdjsonEvents(filePath, args) {
+	const stream = fs.createReadStream(filePath, { encoding: "utf-8" });
+	const rl = readline.createInterface({
+		input: stream,
+		crlfDelay: Infinity
+	});
+	const events = [];
 	try {
-		const stat = await fs.promises.stat(runInfo.eventLogPath);
-		const tailBytes = Math.min(stat.size, 256 * 1024);
-		const handle = await fs.promises.open(runInfo.eventLogPath, "r");
+		for await (const line of rl) {
+			if (!line.trim()) continue;
+			try {
+				const record = asRecord(JSON.parse(line));
+				if (!record || !matchesFilters(record, args)) continue;
+				events.push(clipEvent(record));
+				if (events.length > args.limit) events.splice(0, events.length - args.limit);
+			} catch {}
+		}
+	} finally {
+		rl.close();
+		stream.close();
+	}
+	return events;
+}
+async function resolveRun(args) {
+	if (args.supervisorId) {
+		const { client, isSingleton, sup } = await getSupervisorClient(args.supervisorId);
+		const runInfo = isSingleton && sup ? findRunByLabel(sup, args.runId) : void 0;
+		if (runInfo) return {
+			client,
+			isSingleton,
+			runInfo,
+			runtimeId: runInfo.runtimeId,
+			eventLogPath: runInfo.eventLogPath
+		};
+		let runtimeId;
+		let eventLogPath;
 		try {
-			const buffer = Buffer.alloc(tailBytes);
-			const start = Math.max(0, stat.size - tailBytes);
-			const { bytesRead } = await handle.read(buffer, 0, tailBytes, start);
-			raw = buffer.subarray(0, bytesRead).toString("utf-8");
-		} finally {
-			await handle.close();
+			const direct = await client.status(args.runId);
+			runtimeId = direct.runtime_id ?? args.runId;
+			eventLogPath = direct.event_path ?? direct.on_event;
+		} catch (statusError) {
+			let list;
+			try {
+				list = await client.list();
+			} catch (listError) {
+				if (!isSingleton) client.close();
+				throw new AggregateError([contextualError(`status lookup for ${args.runId}`, statusError), contextualError("runtime list fallback", listError)], `unable to resolve run ${args.runId}`);
+			}
+			const match = list.find((entry) => {
+				const runtime = String(entry.runtime_id ?? entry.id ?? "");
+				const label = String(entry.label ?? "");
+				const runId = String(entry.run_id ?? "");
+				return runtime === args.runId || label === args.runId || runId === args.runId;
+			});
+			if (!match) {
+				if (!isSingleton) client.close();
+				throw contextualError(`unable to resolve run ${args.runId}`, statusError);
+			}
+			runtimeId = String(match.runtime_id ?? match.id ?? "") || void 0;
+			eventLogPath = match.event_path ?? match.on_event;
 		}
-	} catch {
+		return {
+			client,
+			isSingleton,
+			runtimeId,
+			eventLogPath
+		};
+	}
+	const sup = await Supervisor.get();
+	const runInfo = findRunByLabel(sup, args.runId);
+	if (runInfo) return {
+		client: sup.getClient(),
+		isSingleton: true,
+		runInfo,
+		runtimeId: runInfo.runtimeId,
+		eventLogPath: runInfo.eventLogPath
+	};
+	validateRunId(args.runId);
+	let runtimeId;
+	let eventLogPath;
+	try {
+		const direct = await sup.getClient().status(args.runId);
+		runtimeId = direct.runtime_id ?? args.runId;
+		eventLogPath = direct.event_path ?? direct.on_event;
+	} catch (error) {
+		throw contextualError(`unable to resolve run ${args.runId}`, error);
+	}
+	return {
+		client: sup.getClient(),
+		isSingleton: true,
+		runtimeId,
+		eventLogPath
+	};
+}
+async function eventsTool(args) {
+	const limit = normalizeLimit(args.limit);
+	const resolved = await resolveRun(args);
+	try {
+		const failures = [];
+		if (resolved.eventLogPath) try {
+			return { events: await readNdjsonEvents(resolved.eventLogPath, {
+				types: args.types,
+				limit,
+				after_seq: args.after_seq
+			}) };
+		} catch (error) {
+			failures.push(contextualError(`read event log ${resolved.eventLogPath}`, error));
+		}
+		if (resolved.runtimeId) try {
+			const history = await resolved.client.history({
+				runtime_id: resolved.runtimeId,
+				limit,
+				after_seq: args.after_seq
+			});
+			return { events: Array.isArray(history.events) ? history.events.map((event) => asRecord(event)).filter((event) => event !== null).filter((event) => matchesFilters(event, args)).map((event) => clipEvent(event)) : [] };
+		} catch (error) {
+			failures.push(contextualError(`read history for ${resolved.runtimeId}`, error));
+		}
+		if (failures.length > 0) throw new AggregateError(failures, `unable to read events for run ${args.runId}`);
 		return { events: [] };
+	} finally {
+		if (!resolved.isSingleton) resolved.client.close();
 	}
-	const lines = raw.split("\n").filter((line) => line.trim());
-	let events = [];
-	for (const line of lines) try {
-		events.push(JSON.parse(line));
-	} catch {}
-	if (args.types && args.types.length > 0) events = events.filter((e) => args.types.includes(e.type ?? e.event ?? ""));
-	if (events.length > limit) events = events.slice(events.length - limit);
-	return { events };
+}
+//#endregion
+//#region src/tools/inspect.ts
+function publicSnapshot(snapshot) {
+	const { _seen_seq_by_scope: _seen, _recent_legacy_keys: _recent, _last_semantic_fingerprint: _fingerprint, _last_source_event: _source, ...rest } = snapshot;
+	return rest;
+}
+async function inspectTool(args) {
+	const rawStatus = await statusTool({
+		runId: args.runId,
+		supervisorId: args.supervisorId
+	});
+	const status = Array.isArray(rawStatus) ? rawStatus[0] : rawStatus;
+	if (!status) throw new Error(`run not found: ${args.runId}`);
+	const reducer = new RunReducer();
+	const { events } = await eventsTool({
+		runId: args.runId,
+		supervisorId: args.supervisorId,
+		limit: args.limit,
+		after_seq: args.after_seq
+	});
+	for (const event of events) reducer.apply(event);
+	const snapshot = reducer.snapshot();
+	snapshot.identity = {
+		...snapshot.identity,
+		runtime_id: status.runtime_id ?? snapshot.identity.runtime_id,
+		session_id: status.session_id ?? snapshot.identity.session_id,
+		run_id: status.run_id ?? snapshot.identity.run_id,
+		run_label: status.label ?? snapshot.identity.run_label,
+		backend: status.backend ?? snapshot.identity.backend,
+		agent: status.agent ?? snapshot.identity.agent,
+		model: status.model ?? snapshot.identity.model,
+		dir: status.dir ?? snapshot.identity.dir,
+		parent_id: status.parent_id ?? snapshot.identity.parent_id,
+		children: status.children ?? snapshot.identity.children,
+		event_path: status.event_path ?? snapshot.identity.event_path
+	};
+	snapshot.phase = status.phase ?? snapshot.phase;
+	snapshot.phase_label = status.phase_label ?? snapshot.phase_label;
+	snapshot.latest_seq = status.latest_seq ?? snapshot.latest_seq;
+	snapshot.usage = status.usage ?? snapshot.usage;
+	snapshot.stop_reason = status.stop_reason ?? snapshot.stop_reason;
+	snapshot.final_output = status.final_output ?? snapshot.final_output ?? snapshot.assistant_text;
+	snapshot.pending_permission = status.pending_permission ?? snapshot.pending_permission;
+	const clean = publicSnapshot(snapshot);
+	return {
+		run_id: status.run_id,
+		label: status.label,
+		status,
+		snapshot: clean,
+		transcript: clean.transcript,
+		tools: clean.tools,
+		live_tools: clean.live_tools,
+		permissions: clean.permissions,
+		pending_permission: clean.pending_permission,
+		final_output: clean.final_output
+	};
 }
 //#endregion
 //#region src/tools/shutdown.ts
@@ -936,4 +1999,4 @@ async function shutdownTool(args) {
 	};
 }
 //#endregion
-export { Supervisor, answerPermissionTool, dial, eventsTool, findAvenorBinary, followUpTool, getInstallDir, getVersion, installerBinaryPath, shutdownTool, spawnTool, statusTool };
+export { DEFAULT_RUN_REDUCER_LIMITS, RunReducer, Supervisor, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, normalizeRunEvent, observeRun, reduceRunSnapshot, shutdownTool, spawnTool, statusTool };