@dougbots/avenor-core 0.4.1 → 0.5.1

package/README.md

@@ -59,11 +59,24 @@ Reports status for one or all runs. When `runId` is omitted it lists every run a
 ```ts
 import { statusTool } from '@dougbots/avenor-core'
 
-const status = await statusTool({ runId: 'reverse-string' })
+const status = await statusTool({ runId: 'reverse-string', view: 'lifecycle' })
 // { run_id: 'reverse-string', label: 'reverse-string', status: 'running', ... }
 ```
 
-Status values: `running`, `done`, `failed`, `timeout`, `killed`. If a permission request is pending, the result includes `pending_permission` with available options.
+Status values: `running`, `done`, `failed`, `timeout`, `killed`. If a permission request is pending, the result includes `pending_permission` with available options. The `lifecycle` view omits final output and diagnostic metadata; `full` remains the default for compatibility.
+
+### `resultTool`
+
+Waits for one run to finish and returns its bounded final output without transcript or event details.
+
+```ts
+import { resultTool } from '@dougbots/avenor-core'
+
+const result = await resultTool({ runId: 'reverse-string', timeout: '5m' })
+// { run_id: 'reverse-string', status: 'done', ready: true, output: '...' }
+```
+
+Set `wait: false` for a non-blocking availability check. A pending permission returns immediately; an expired result wait returns `ready: false` and `timed_out: true` without stopping the run.
 
 ### `answerPermissionTool`
 
@@ -113,7 +126,7 @@ const result = await shutdownTool({ force: false })
 ## Quick start
 
 ```ts
-import { Supervisor, spawnTool, statusTool, shutdownTool } from '@dougbots/avenor-core'
+import { Supervisor, resultTool, spawnTool, shutdownTool } from '@dougbots/avenor-core'
 
 // 1. The supervisor auto-starts avenor. Call get() early — it's a singleton.
 const sup = await Supervisor.get()
@@ -125,13 +138,9 @@ const { run_id } = await spawnTool({
   label: 'security-review',
 })
 
-// 3. Poll until complete
-let state = await statusTool({ runId: run_id })
-while (state.status === 'running' || state.status === undefined) {
-  await new Promise(r => setTimeout(r, 2000))
-  state = await statusTool({ runId: run_id })
-}
-console.log(state) // { run_id, label, status: 'done', ... }
+// 3. Wait for the bounded final output
+const result = await resultTool({ runId: run_id })
+console.log(result) // { run_id, label, status: 'done', ready: true, output: '...' }
 
 // 4. Clean up
 await shutdownTool()
@@ -146,7 +155,8 @@ await shutdownTool()
 | `Supervisor` | class | Singleton avenor process lifecycle manager |
 | `findAvenorBinary` | function | Discover the avenor binary path |
 | `spawnTool` | function | Start a new agent run |
-| `statusTool` | function | Query run status (single or all) |
+| `statusTool` | function | Query run lifecycle status (single or all) |
+| `resultTool` | function | Wait for and retrieve one run's bounded final output |
 | `answerPermissionTool` | function | Answer a pending permission request |
 | `followUpTool` | function | Resume a session with a follow-up prompt |
 | `eventsTool` | function | Read recent events from a run's event log |

package/dist/index.d.ts

@@ -289,6 +289,7 @@ declare function spawnTool(args: {
 }>;
 //#endregion
 //#region src/tools/status.d.ts
+type StatusView = 'lifecycle' | 'full';
 interface StatusResult {
   run_id: string;
   label: string;
@@ -321,8 +322,51 @@ interface StatusResult {
 declare function statusTool(args: {
   runId?: string;
   supervisorId?: string;
+  view?: StatusView;
 }): Promise<StatusResult | StatusResult[]>;
 //#endregion
+//#region src/tools/inspect.d.ts
+interface InspectResult {
+  run_id: string;
+  label: string;
+  status: StatusResult;
+  snapshot: Omit<RunSnapshot, '_seen_seq_by_scope' | '_recent_legacy_keys' | '_last_semantic_fingerprint' | '_last_source_event'>;
+  transcript: RunSnapshot['transcript'];
+  tools: RunSnapshot['tools'];
+  live_tools: RunSnapshot['live_tools'];
+  permissions: RunSnapshot['permissions'];
+  pending_permission?: RunSnapshot['pending_permission'];
+  final_output?: string;
+}
+declare function inspectTool(args: {
+  runId: string;
+  supervisorId?: string;
+  limit?: number;
+  after_seq?: number;
+}): Promise<InspectResult>;
+//#endregion
+//#region src/tools/result.d.ts
+interface ResultResult {
+  run_id: string;
+  label: string;
+  status: string;
+  ready: boolean;
+  runtime_id?: string;
+  session_id?: string;
+  stop_reason?: string;
+  pending_permission?: StatusResult['pending_permission'];
+  output?: string;
+  timed_out?: boolean;
+}
+interface ResultToolArgs {
+  runId: string;
+  supervisorId?: string;
+  wait?: boolean;
+  timeout?: string;
+  signal?: AbortSignal;
+}
+declare function resultTool(args: ResultToolArgs): Promise<ResultResult>;
+//#endregion
 //#region src/tools/answer-permission.d.ts
 declare function answerPermissionTool(args: {
   runId: string;
@@ -360,26 +404,6 @@ declare function eventsTool(args: {
   }>;
 }>;
 //#endregion
-//#region src/tools/inspect.d.ts
-interface InspectResult {
-  run_id: string;
-  label: string;
-  status: StatusResult;
-  snapshot: Omit<RunSnapshot, '_seen_seq_by_scope' | '_recent_legacy_keys' | '_last_semantic_fingerprint' | '_last_source_event'>;
-  transcript: RunSnapshot['transcript'];
-  tools: RunSnapshot['tools'];
-  live_tools: RunSnapshot['live_tools'];
-  permissions: RunSnapshot['permissions'];
-  pending_permission?: RunSnapshot['pending_permission'];
-  final_output?: string;
-}
-declare function inspectTool(args: {
-  runId: string;
-  supervisorId?: string;
-  limit?: number;
-  after_seq?: number;
-}): Promise<InspectResult>;
-//#endregion
 //#region src/tools/shutdown.d.ts
 declare function shutdownTool(args: {
   supervisorId?: string;
@@ -389,4 +413,4 @@ declare function shutdownTool(args: {
   cleaned_up: string[];
 }>;
 //#endregion
-export { type Client, DEFAULT_RUN_REDUCER_LIMITS, type Event, type HistoryOptions, type HistoryResult, type InspectResult, type NormalizedRunEvent, type ObserveRunOptions, type RunChunkRole, type RunIdentity, type RunInfo, type RunObserver, type RunObserverClient, type RunPermissionOption, type RunPermissionSummary, RunReducer, type RunReducerLimits, type RunSnapshot, type RunSnapshotSeed, type RunToolState, type RunToolSummary, type RunTranscriptEntry, type SpawnParams, type StatusResult, type SubscribeOptions, Supervisor, type SupervisorOptions, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, normalizeRunEvent, observeRun, reduceRunSnapshot, shutdownTool, spawnTool, statusTool };
+export { type Client, DEFAULT_RUN_REDUCER_LIMITS, type Event, type HistoryOptions, type HistoryResult, type InspectResult, type NormalizedRunEvent, type ObserveRunOptions, type ResultResult, type ResultToolArgs, type RunChunkRole, type RunIdentity, type RunInfo, type RunObserver, type RunObserverClient, type RunPermissionOption, type RunPermissionSummary, RunReducer, type RunReducerLimits, type RunSnapshot, type RunSnapshotSeed, type RunToolState, type RunToolSummary, type RunTranscriptEntry, type SpawnParams, type StatusResult, type StatusView, type SubscribeOptions, Supervisor, type SupervisorOptions, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, normalizeRunEvent, observeRun, reduceRunSnapshot, resultTool, shutdownTool, spawnTool, statusTool };

package/dist/index.js

@@ -1479,7 +1479,7 @@ function extractPendingPermission(liveStatus) {
 }
 function buildBaseStatus(source, fallback, translatedStatus) {
 	return {
-		run_id: stringField(source, "run_id") ?? fallback.run_id,
+		run_id: fallback.prefer_fallback_run_id ? fallback.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,
@@ -1500,6 +1500,20 @@ function buildBaseStatus(source, fallback, translatedStatus) {
 		final_output: stringField(source, "final_output", "finalOutput")
 	};
 }
+function shapeStatusResult(result, view = "full") {
+	if (view === "full") return result;
+	if (view !== "lifecycle") throw new Error(`invalid status view: ${String(view)}`);
+	return {
+		run_id: result.run_id,
+		label: result.label,
+		status: result.status,
+		...result.runtime_id !== void 0 && { runtime_id: result.runtime_id },
+		...result.phase !== void 0 && { phase: result.phase },
+		...result.phase_label !== void 0 && { phase_label: result.phase_label },
+		...result.pending_permission !== void 0 && { pending_permission: result.pending_permission },
+		...result.latest_seq !== void 0 && { latest_seq: result.latest_seq }
+	};
+}
 async function buildRunStatus(runInfo, liveStatus) {
 	let sentinel = null;
 	if (await sentinelExists(runInfo.sentinelPath)) sentinel = await parseSentinel$1(runInfo.sentinelPath);
@@ -1507,6 +1521,7 @@ async function buildRunStatus(runInfo, liveStatus) {
 	return buildBaseStatus(liveStatus ?? {}, {
 		run_id: runInfo.runId,
 		label: runInfo.label,
+		prefer_fallback_run_id: true,
 		runtime_id: runInfo.runtimeId,
 		session_id: sentinel?.SESSION ?? liveStatus?.session_id ?? runInfo.sessionId,
 		stop_reason: sentinel?._status
@@ -1527,7 +1542,7 @@ async function statusTool(args) {
 			if (args.runId) {
 				validateRunId(args.runId);
 				const runInfo = isSingleton && sup ? findRunByLabel$3(sup, args.runId) : void 0;
-				if (runInfo) return buildRunStatus(runInfo, await queryLiveStatus(client, runInfo.runtimeId));
+				if (runInfo) return shapeStatusResult(await buildRunStatus(runInfo, await queryLiveStatus(client, runInfo.runtimeId)), args.view);
 				let liveStatus = await queryLiveStatus(client, args.runId);
 				if (!liveStatus) try {
 					const entry = (await client.list()).find((item) => {
@@ -1541,20 +1556,20 @@ async function statusTool(args) {
 				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 buildBaseStatus(liveStatus ?? {}, {
+				return shapeStatusResult(buildBaseStatus(liveStatus ?? {}, {
 					run_id: args.runId,
 					label: args.runId,
 					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));
+				}, translateStatus(liveStatus?.phase ?? liveStatus?.status ?? "running", sentinel)), args.view);
 			}
-			return (await client.list()).map((entry) => buildBaseStatus(entry, {
+			return (await client.list()).map((entry) => shapeStatusResult(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)));
+			}, translateStatus(entry.phase ?? entry.status ?? "running", null)), args.view));
 		} finally {
 			if (!isSingleton) client.close();
 		}
@@ -1563,19 +1578,19 @@ async function statusTool(args) {
 	const client = sup.getClient();
 	if (args.runId) {
 		const runInfo = findRunByLabel$3(sup, args.runId);
-		if (runInfo) return buildRunStatus(runInfo, await queryLiveStatus(client, runInfo.runtimeId));
+		if (runInfo) return shapeStatusResult(await buildRunStatus(runInfo, await queryLiveStatus(client, runInfo.runtimeId)), args.view);
 		validateRunId(args.runId);
 		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 buildBaseStatus(liveStatus ?? {}, {
+		return shapeStatusResult(buildBaseStatus(liveStatus ?? {}, {
 			run_id: args.runId,
 			label: args.runId,
 			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));
+		}, translateStatus(liveStatus?.phase ?? liveStatus?.status ?? "running", sentinel)), args.view);
 	}
 	const list = await client.list();
 	const results = [];
@@ -1584,134 +1599,23 @@ async function statusTool(args) {
 		const entryLabel = String(entry.label ?? entryId);
 		const runInfo = findRunByLabel$3(sup, entryId) ?? findRunByLabel$3(sup, entryLabel);
 		const liveStatus = runInfo ? await queryLiveStatus(client, runInfo.runtimeId) : null;
-		if (runInfo && liveStatus) results.push(await buildRunStatus(runInfo, liveStatus));
-		else results.push(buildBaseStatus(entry, {
+		if (runInfo && liveStatus) results.push(shapeStatusResult(await buildRunStatus(runInfo, liveStatus), args.view));
+		else results.push(shapeStatusResult(buildBaseStatus(entry, {
 			run_id: String(entry.run_id ?? entryId),
 			label: entryLabel,
 			runtime_id: entryId,
 			session_id: entry.session_id
-		}, translateStatus(entry.phase ?? entry.status ?? "running", null)));
+		}, translateStatus(entry.phase ?? entry.status ?? "running", null)), args.view));
 	}
 	return results;
 }
 //#endregion
-//#region src/tools/answer-permission.ts
-function findRunByLabel$2(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 answerPermissionTool(args) {
-	let client;
-	let sup = null;
-	let requestId = args.requestId;
-	let supervisorId;
-	let isSingleton = false;
-	if (args.supervisorId) ({client, isSingleton, sup, supervisorId} = await getSupervisorClient(args.supervisorId));
-	else {
-		sup = await Supervisor.get();
-		client = sup.getClient();
-	}
-	try {
-		validateRunId(args.runId);
-		const runtimeId = (sup ? findRunByLabel$2(sup, args.runId) : void 0)?.runtimeId ?? args.runId;
-		if (!requestId) {
-			const pp = (await client.status(runtimeId))?.pending_permission;
-			if (!pp?.request_id) throw new Error("no pending permission request for this run");
-			requestId = pp.request_id;
-		}
-		await client.answerPermission(runtimeId, requestId, args.optionId);
-		return { ok: true };
-	} finally {
-		if (supervisorId && !isSingleton) client.close();
-	}
-}
-//#endregion
-//#region src/tools/follow-up.ts
-function findRunByLabel$1(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 parseSentinel(filePath) {
-	try {
-		const content = (await fs.promises.readFile(filePath, "utf-8")).trim();
-		if (!content) return null;
-		const lines = content.split("\n");
-		const result = {};
-		result._status = lines[0];
-		for (let i = 1; i < lines.length; i++) {
-			const line = lines[i].trim();
-			if (!line) continue;
-			const eq = line.indexOf("=");
-			if (eq > 0) result[line.substring(0, eq)] = line.substring(eq + 1);
-		}
-		return result;
-	} catch {
-		return null;
-	}
-}
-async function followUpTool(args) {
-	if (args.supervisorId) {
-		const { client, isSingleton } = await getSupervisorClient(args.supervisorId);
-		try {
-			validateRunId(args.runId);
-			let liveStatus = null;
-			try {
-				liveStatus = await client.status(args.runId);
-			} catch {}
-			const sentinel = await parseSentinel(liveStatus?.sentinel_file ?? path.join(runsRoot(), args.runId, "sentinel.done"));
-			if (!sentinel?.SESSION) throw new Error("run has no session to resume");
-			const agent = liveStatus?.agent ?? "codex";
-			const followUpRunId = crypto.randomUUID();
-			const followUpLabel = args.label ?? `${args.runId}-followup`;
-			const { sentinelPath: followUpSentinelPath, eventLogPath } = ensureRunPaths(followUpRunId);
-			return {
-				run_id: (await client.spawn({
-					agent,
-					prompt: args.message,
-					label: followUpLabel,
-					session_id: sentinel.SESSION,
-					sentinel_file: followUpSentinelPath,
-					on_event: eventLogPath
-				})).runtime_id ?? followUpRunId,
-				label: followUpLabel
-			};
-		} finally {
-			if (!isSingleton) client.close();
-		}
-	}
-	const sup = await Supervisor.get();
-	const runInfo = findRunByLabel$1(sup, args.runId);
-	if (!runInfo) throw new Error(`run not found: ${args.runId}`);
-	const sentinel = await parseSentinel(runInfo.sentinelPath);
-	if (!sentinel?.SESSION) throw new Error("run has no session to resume");
-	const client = sup.getClient();
-	let agent = "codex";
-	if (runInfo.runtimeId) try {
-		agent = (await client.status(runInfo.runtimeId))?.agent ?? "codex";
-	} catch {}
-	const followUpLabel = args.label ?? `${runInfo.label}-followup`;
-	const followUpRun = await sup.spawn({
-		agent,
-		prompt: args.message,
-		session_id: sentinel.SESSION,
-		label: followUpLabel
-	});
-	return {
-		run_id: followUpRun.runId,
-		label: followUpRun.label
-	};
-}
-//#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) {
+function findRunByLabel$2(sup, runId) {
 	const runs = sup.runs;
 	const byKey = runs.get(runId);
 	if (byKey) return byKey;
@@ -1787,7 +1691,7 @@ async function readNdjsonEvents(filePath, args) {
 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;
+		const runInfo = isSingleton && sup ? findRunByLabel$2(sup, args.runId) : void 0;
 		if (runInfo) return {
 			client,
 			isSingleton,
@@ -1830,7 +1734,7 @@ async function resolveRun(args) {
 		};
 	}
 	const sup = await Supervisor.get();
-	const runInfo = findRunByLabel(sup, args.runId);
+	const runInfo = findRunByLabel$2(sup, args.runId);
 	if (runInfo) return {
 		client: sup.getClient(),
 		isSingleton: true,
@@ -1943,6 +1847,200 @@ async function inspectTool(args) {
 	};
 }
 //#endregion
+//#region src/tools/result.ts
+const DEFAULT_POLL_INTERVAL_MS = 1e3;
+const TERMINAL_STATUSES = new Set([
+	"done",
+	"failed",
+	"timeout",
+	"killed"
+]);
+function abortError() {
+	const error = /* @__PURE__ */ new Error("result wait cancelled");
+	error.name = "AbortError";
+	return error;
+}
+function sleep(ms, signal) {
+	if (signal?.aborted) return Promise.reject(abortError());
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(abortError());
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+const defaultDeps = {
+	status: statusTool,
+	inspect: inspectTool,
+	sleep,
+	now: Date.now,
+	pollIntervalMs: DEFAULT_POLL_INTERVAL_MS
+};
+function toResult(status, timedOut = false) {
+	const ready = TERMINAL_STATUSES.has(status.status);
+	return {
+		run_id: status.run_id,
+		label: status.label,
+		status: status.status,
+		ready,
+		runtime_id: status.runtime_id,
+		session_id: status.session_id,
+		stop_reason: status.stop_reason,
+		pending_permission: status.pending_permission,
+		output: ready ? status.final_output : void 0,
+		timed_out: timedOut || void 0
+	};
+}
+async function executeResultTool(args, deps) {
+	const wait = args.wait ?? true;
+	const timeoutMs = args.timeout === void 0 ? void 0 : validateTimeout(args.timeout) * 1e3;
+	const deadline = timeoutMs === void 0 ? void 0 : deps.now() + timeoutMs;
+	const pollIntervalMs = Math.max(1, deps.pollIntervalMs);
+	while (true) {
+		if (args.signal?.aborted) throw abortError();
+		const raw = await deps.status({
+			runId: args.runId,
+			supervisorId: args.supervisorId,
+			view: "full"
+		});
+		const status = Array.isArray(raw) ? raw[0] : raw;
+		if (!status) throw new Error(`run not found: ${args.runId}`);
+		if (TERMINAL_STATUSES.has(status.status)) {
+			if (!status.final_output) try {
+				const inspected = await deps.inspect({
+					runId: args.runId,
+					supervisorId: args.supervisorId
+				});
+				status.final_output = inspected.final_output ?? inspected.snapshot.final_output ?? inspected.snapshot.assistant_text;
+			} catch {}
+			return toResult(status);
+		}
+		if (status.status === "waiting" || !wait) return toResult(status);
+		if (deadline !== void 0 && deps.now() >= deadline) return toResult(status, true);
+		const delay = deadline === void 0 ? pollIntervalMs : Math.min(pollIntervalMs, Math.max(1, deadline - deps.now()));
+		await deps.sleep(delay, args.signal);
+	}
+}
+async function resultTool(args) {
+	return executeResultTool(args, defaultDeps);
+}
+//#endregion
+//#region src/tools/answer-permission.ts
+function findRunByLabel$1(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 answerPermissionTool(args) {
+	let client;
+	let sup = null;
+	let requestId = args.requestId;
+	let supervisorId;
+	let isSingleton = false;
+	if (args.supervisorId) ({client, isSingleton, sup, supervisorId} = await getSupervisorClient(args.supervisorId));
+	else {
+		sup = await Supervisor.get();
+		client = sup.getClient();
+	}
+	try {
+		validateRunId(args.runId);
+		const runtimeId = (sup ? findRunByLabel$1(sup, args.runId) : void 0)?.runtimeId ?? args.runId;
+		if (!requestId) {
+			const pp = (await client.status(runtimeId))?.pending_permission;
+			if (!pp?.request_id) throw new Error("no pending permission request for this run");
+			requestId = pp.request_id;
+		}
+		await client.answerPermission(runtimeId, requestId, args.optionId);
+		return { ok: true };
+	} finally {
+		if (supervisorId && !isSingleton) client.close();
+	}
+}
+//#endregion
+//#region src/tools/follow-up.ts
+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 parseSentinel(filePath) {
+	try {
+		const content = (await fs.promises.readFile(filePath, "utf-8")).trim();
+		if (!content) return null;
+		const lines = content.split("\n");
+		const result = {};
+		result._status = lines[0];
+		for (let i = 1; i < lines.length; i++) {
+			const line = lines[i].trim();
+			if (!line) continue;
+			const eq = line.indexOf("=");
+			if (eq > 0) result[line.substring(0, eq)] = line.substring(eq + 1);
+		}
+		return result;
+	} catch {
+		return null;
+	}
+}
+async function followUpTool(args) {
+	if (args.supervisorId) {
+		const { client, isSingleton } = await getSupervisorClient(args.supervisorId);
+		try {
+			validateRunId(args.runId);
+			let liveStatus = null;
+			try {
+				liveStatus = await client.status(args.runId);
+			} catch {}
+			const sentinel = await parseSentinel(liveStatus?.sentinel_file ?? path.join(runsRoot(), args.runId, "sentinel.done"));
+			if (!sentinel?.SESSION) throw new Error("run has no session to resume");
+			const agent = liveStatus?.agent ?? "codex";
+			const followUpRunId = crypto.randomUUID();
+			const followUpLabel = args.label ?? `${args.runId}-followup`;
+			const { sentinelPath: followUpSentinelPath, eventLogPath } = ensureRunPaths(followUpRunId);
+			return {
+				run_id: (await client.spawn({
+					agent,
+					prompt: args.message,
+					label: followUpLabel,
+					session_id: sentinel.SESSION,
+					sentinel_file: followUpSentinelPath,
+					on_event: eventLogPath
+				})).runtime_id ?? followUpRunId,
+				label: followUpLabel
+			};
+		} finally {
+			if (!isSingleton) client.close();
+		}
+	}
+	const sup = await Supervisor.get();
+	const runInfo = findRunByLabel(sup, args.runId);
+	if (!runInfo) throw new Error(`run not found: ${args.runId}`);
+	const sentinel = await parseSentinel(runInfo.sentinelPath);
+	if (!sentinel?.SESSION) throw new Error("run has no session to resume");
+	const client = sup.getClient();
+	let agent = "codex";
+	if (runInfo.runtimeId) try {
+		agent = (await client.status(runInfo.runtimeId))?.agent ?? "codex";
+	} catch {}
+	const followUpLabel = args.label ?? `${runInfo.label}-followup`;
+	const followUpRun = await sup.spawn({
+		agent,
+		prompt: args.message,
+		session_id: sentinel.SESSION,
+		label: followUpLabel
+	});
+	return {
+		run_id: followUpRun.runId,
+		label: followUpRun.label
+	};
+}
+//#endregion
 //#region src/tools/shutdown.ts
 async function shutdownTool(args) {
 	const cleanedUp = [];
@@ -1999,4 +2097,4 @@ async function shutdownTool(args) {
 	};
 }
 //#endregion
-export { DEFAULT_RUN_REDUCER_LIMITS, RunReducer, Supervisor, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, normalizeRunEvent, observeRun, reduceRunSnapshot, shutdownTool, spawnTool, statusTool };
+export { DEFAULT_RUN_REDUCER_LIMITS, RunReducer, Supervisor, answerPermissionTool, createRunSnapshot, dial, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, normalizeRunEvent, observeRun, reduceRunSnapshot, resultTool, shutdownTool, spawnTool, statusTool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougbots/avenor-core",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "type": "module",
   "repository": {
     "type": "git",