@dougbots/avenor-core 0.12.0 → 0.12.1

package/dist/index.d.ts

@@ -144,6 +144,11 @@ interface WorkflowControllerCreateParams {
   controller_id: string;
   max_inflight: number;
 }
+declare class RpcError extends Error {
+  readonly code: number;
+  readonly data?: unknown;
+  constructor(code: number, message: string, data?: unknown);
+}
 declare class Client {
   private socket;
   private rl;
@@ -163,7 +168,9 @@ declare class Client {
   });
   private startReadLoop;
   private pushEvent;
-  call(method: string, params?: unknown): Promise<unknown>;
+  call(method: string, params?: unknown, opts?: {
+    timeoutMs?: number;
+  }): Promise<unknown>;
   subscribe(options?: SubscribeOptions): Promise<void>;
   events(options?: SubscribeOptions): AsyncIterableIterator<Event>;
   history(options: HistoryOptions): Promise<HistoryResult>;
@@ -194,7 +201,7 @@ declare class Client {
   workflowControllerEnable(controllerId: string): Promise<Record<string, unknown>>;
   workflowControllerDisable(controllerId: string, reason: string): Promise<Record<string, unknown>>;
   brokerSend(fromRunId: string, toRunId: string, message: string, role?: string): Promise<void>;
-  brokerAsk(toRunId: string, message: string, role?: string): Promise<Record<string, unknown>>;
+  brokerAsk(toRunId: string, message: string, role?: string, timeoutMs?: number): Promise<Record<string, unknown>>;
   brokerPeers(): Promise<Array<Record<string, unknown>>>;
   brokerCancel(messageId: string): Promise<void>;
   brokerReceive(): Promise<Array<{
@@ -424,8 +431,16 @@ declare class Supervisor {
   getRunByReference(reference: string): RunInfo | undefined;
   /** Match a stored run by its broker runtime ID. */
   getRunByRuntimeId(runtimeId: string): RunInfo | undefined;
+  /**
+   * The live singleton when it owns supervisorId, null otherwise. Single
+   * source of truth for the ownership check, so callers cannot observe
+   * isCurrentInstance true while currentInstance is null.
+   */
+  static getInstance(supervisorId: string): Supervisor | null;
   static isCurrentInstance(supervisorId: string): boolean;
   static currentInstance(): Supervisor | null;
+  /** Iterate stored runs without exposing the internal map. */
+  forEachRun(callback: (info: RunInfo) => void): void;
   getClient(): Client;
   spawn(params: SpawnParams, runId?: `${string}-${string}-${string}-${string}-${string}`, metadata?: SpawnMetadata): Promise<RunInfo>;
   close(options?: {
@@ -491,6 +506,12 @@ interface StatusToolArgs {
   supervisorId?: string;
   view?: StatusView;
 }
+/** List form of the status tool result (no runId). structuredContent must be
+ * an object, so the runs array is wrapped with a count. */
+interface StatusListResult {
+  runs: StatusResult[];
+  count: number;
+}
 interface StatusResult {
   run_id: string;
   label: string;
@@ -529,7 +550,7 @@ interface StatusResult {
   final_output?: string;
   final_output_truncated?: boolean;
 }
-declare const statusTool: (args: StatusToolArgs) => Promise<StatusResult | StatusResult[]>;
+declare const statusTool: (args: StatusToolArgs) => Promise<StatusResult | StatusListResult>;
 //#endregion
 //#region src/tools/events.d.ts
 interface EventsToolArgs {
@@ -633,6 +654,7 @@ interface AskToolArgs {
   toRunId: string;
   message: string;
   supervisorId?: string;
+  timeoutMs?: number;
 }
 interface AskResult {
   reply: string;
@@ -771,4 +793,4 @@ type WorkflowReadyResult = Record<string, unknown>;
 declare function createWorkflowReadyTool(getSupervisorClient: GetSupervisorClient): (args: WorkflowReadyToolArgs) => Promise<WorkflowReadyResult>;
 declare const workflowReadyTool: (args: WorkflowReadyToolArgs) => Promise<WorkflowReadyResult>;
 //#endregion
-export { type AskResult, type AskToolArgs, type BrokerReceiveArgs, type BrokerReceiveResult, type BrokerReplyArgs, type BrokerReplyResult, type CancelResult, type CancelToolArgs, type Client, DEFAULT_RUN_REDUCER_LIMITS, type Event, type ExecutionIdentity, type FollowUpToolArgs, type FollowUpToolResult, type HistoryOptions, type HistoryResult, type InboundAsk, type InspectResult, type NormalizedRunEvent, type ObserveRunOptions, type PeerEntry, type PeersResult, 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 SpawnMetadata, type SpawnParams, type SpawnResult, type SpawnSelectionInput, type SpawnToolArgs, type SpawnToolResult, type StatusResult, type StatusToolArgs, type StatusView, type SubscribeOptions, Supervisor, type SupervisorOptions, THINKING_LEVELS, type ThinkingLevel, type ThinkingOutcome, type WorkflowCompleteParams, type WorkflowCompleteResult, type WorkflowCompleteToolArgs, type WorkflowControllerCreateParams, type WorkflowControllerStatusResult, type WorkflowControllerStatusToolArgs, type WorkflowEventsResult, type WorkflowEventsToolArgs, type WorkflowGateOperation, type WorkflowGateParams, type WorkflowGateResult, type WorkflowGateToolArgs, type WorkflowHeartbeatParams, type WorkflowInspectResult, type WorkflowInspectToolArgs, type WorkflowReadyResult, type WorkflowReadyToolArgs, type WorkflowStatusResult, type WorkflowStatusToolArgs, type WorkflowWaitResult, type WorkflowWaitToolArgs, answerPermissionTool, askTool, brokerReceiveTool, brokerReplyTool, cancelTool, createRunSnapshot, createWorkflowCompleteTool, createWorkflowControllerStatusTool, createWorkflowEventsTool, createWorkflowGateTool, createWorkflowInspectTool, createWorkflowReadyTool, createWorkflowStatusTool, createWorkflowWaitTool, dial, evaluateThinkingPolicy, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, isThinkingLevel, normalizeRunEvent, observeRun, peersTool, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, validateThinking, validateThinkingForBackend, validateThinkingForBackendResume, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool };
+export { type AskResult, type AskToolArgs, type BrokerReceiveArgs, type BrokerReceiveResult, type BrokerReplyArgs, type BrokerReplyResult, type CancelResult, type CancelToolArgs, type Client, DEFAULT_RUN_REDUCER_LIMITS, type Event, type ExecutionIdentity, type FollowUpToolArgs, type FollowUpToolResult, type HistoryOptions, type HistoryResult, type InboundAsk, type InspectResult, type NormalizedRunEvent, type ObserveRunOptions, type PeerEntry, type PeersResult, type ResultResult, type ResultToolArgs, RpcError, 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 SpawnMetadata, type SpawnParams, type SpawnResult, type SpawnSelectionInput, type SpawnToolArgs, type SpawnToolResult, type StatusListResult, type StatusResult, type StatusToolArgs, type StatusView, type SubscribeOptions, Supervisor, type SupervisorOptions, THINKING_LEVELS, type ThinkingLevel, type ThinkingOutcome, type WorkflowCompleteParams, type WorkflowCompleteResult, type WorkflowCompleteToolArgs, type WorkflowControllerCreateParams, type WorkflowControllerStatusResult, type WorkflowControllerStatusToolArgs, type WorkflowEventsResult, type WorkflowEventsToolArgs, type WorkflowGateOperation, type WorkflowGateParams, type WorkflowGateResult, type WorkflowGateToolArgs, type WorkflowHeartbeatParams, type WorkflowInspectResult, type WorkflowInspectToolArgs, type WorkflowReadyResult, type WorkflowReadyToolArgs, type WorkflowStatusResult, type WorkflowStatusToolArgs, type WorkflowWaitResult, type WorkflowWaitToolArgs, answerPermissionTool, askTool, brokerReceiveTool, brokerReplyTool, cancelTool, createRunSnapshot, createWorkflowCompleteTool, createWorkflowControllerStatusTool, createWorkflowEventsTool, createWorkflowGateTool, createWorkflowInspectTool, createWorkflowReadyTool, createWorkflowStatusTool, createWorkflowWaitTool, dial, evaluateThinkingPolicy, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, isThinkingLevel, normalizeRunEvent, observeRun, peersTool, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, validateThinking, validateThinkingForBackend, validateThinkingForBackendResume, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool };

package/dist/index.js

@@ -25,6 +25,16 @@ function removeResolver(resolvers, target) {
 	const index = resolvers.indexOf(target);
 	if (index >= 0) resolvers.splice(index, 1);
 }
+var RpcError = class extends Error {
+	code;
+	data;
+	constructor(code, message, data) {
+		super(`rpc error [${code}]: ${message}`);
+		this.name = "RpcError";
+		this.code = code;
+		this.data = data;
+	}
+};
 var Client = class {
 	socket;
 	rl;
@@ -73,7 +83,7 @@ var Client = class {
 				if (pc) {
 					clearTimeout(pc.timer);
 					this.pending.delete(id);
-					if (parsed.error) pc.reject(/* @__PURE__ */ new Error(`rpc error [${parsed.error.code}]: ${parsed.error.message}`));
+					if (parsed.error) pc.reject(new RpcError(parsed.error.code, parsed.error.message, parsed.error.data));
 					else pc.resolve(parsed.result);
 				}
 				return;
@@ -123,7 +133,7 @@ var Client = class {
 		if (this.eventQueue.length < 256) this.eventQueue.push(ev);
 		else this.dropped++;
 	}
-	async call(method, params) {
+	async call(method, params, opts) {
 		if (this.isClosed()) throw new Error("control socket is closed");
 		this.startReadLoop();
 		const id = ++this.nextID;
@@ -134,11 +144,14 @@ var Client = class {
 		};
 		if (params !== void 0) req.params = params;
 		const data = JSON.stringify(req) + "\n";
+		const MAX_TIMER_MS = 2147483647;
+		const requested = opts?.timeoutMs !== void 0 ? !Number.isFinite(opts.timeoutMs) || opts.timeoutMs > MAX_TIMER_MS - 1e4 ? MAX_TIMER_MS : Math.max(this.callTimeout, opts.timeoutMs + 1e4) : this.callTimeout;
+		const timeout = Number.isFinite(requested) ? Math.min(requested, MAX_TIMER_MS) : MAX_TIMER_MS;
 		return new Promise((resolve, reject) => {
 			const timer = setTimeout(() => {
 				this.pending.delete(id);
 				reject(/* @__PURE__ */ new Error("read response: timeout"));
-			}, this.callTimeout);
+			}, timeout);
 			this.pending.set(id, {
 				resolve,
 				reject,
@@ -386,12 +399,14 @@ var Client = class {
 			role: role ?? "agent"
 		});
 	}
-	async brokerAsk(toRunId, message, role) {
-		return await this.call("broker_ask", {
+	async brokerAsk(toRunId, message, role, timeoutMs) {
+		const params = {
 			to_run_id: toRunId,
 			message,
 			role: role ?? "agent"
-		});
+		};
+		if (timeoutMs !== void 0) params.timeout_ms = timeoutMs;
+		return await this.call("broker_ask", params, timeoutMs !== void 0 ? { timeoutMs } : void 0);
 	}
 	async brokerPeers() {
 		return (await this.call("broker_peers")).sessions ?? [];
@@ -1534,12 +1549,24 @@ var Supervisor = class Supervisor {
 		if (!runtimeId) return void 0;
 		for (const runInfo of this.runs.values()) if (runInfo.runtimeId === runtimeId) return runInfo;
 	}
+	/**
+	* The live singleton when it owns supervisorId, null otherwise. Single
+	* source of truth for the ownership check, so callers cannot observe
+	* isCurrentInstance true while currentInstance is null.
+	*/
+	static getInstance(supervisorId) {
+		return Supervisor.instance !== null && Supervisor.instance.supervisorId === supervisorId ? Supervisor.instance : null;
+	}
 	static isCurrentInstance(supervisorId) {
-		return Supervisor.instance !== null && Supervisor.instance.supervisorId === supervisorId;
+		return Supervisor.getInstance(supervisorId) !== null;
 	}
 	static currentInstance() {
 		return Supervisor.instance;
 	}
+	/** Iterate stored runs without exposing the internal map. */
+	forEachRun(callback) {
+		for (const runInfo of this.runs.values()) callback(runInfo);
+	}
 	getClient() {
 		if (this.crashed) {
 			const state = this.crashCode === 0 ? "exited" : "crashed";
@@ -1689,8 +1716,8 @@ async function getSupervisorClient(supervisorId) {
 		};
 	}
 	const id = validateSupervisorSocketPath(supervisorId);
-	const current = Supervisor.currentInstance();
-	if (current !== null && validateSupervisorSocketPath(current.supervisorId) === id) return {
+	const current = Supervisor.getInstance(id);
+	if (current !== null) return {
 		client: current.getClient(),
 		isSingleton: true,
 		sup: current,
@@ -2371,7 +2398,10 @@ async function executeStatusTool(args, getSupervisorClient) {
 					session_id: entry.session_id
 				}, translateStatus(rawStatusPhase(entry), null)), args.view));
 			}
-			return results;
+			return {
+				runs: results,
+				count: results.length
+			};
 		} finally {
 			if (!isSingleton) client.close();
 		}
@@ -2409,7 +2439,10 @@ async function executeStatusTool(args, getSupervisorClient) {
 			session_id: entry.session_id
 		}, translateStatus(rawStatusPhase(entry), null)), args.view));
 	}
-	return results;
+	return {
+		runs: results,
+		count: results.length
+	};
 }
 function createStatusTool(getSupervisorClient) {
 	return (args) => executeStatusTool(args, getSupervisorClient);
@@ -2837,6 +2870,15 @@ function rejectSessionConflict(sentinel, liveStatus) {
 	const liveStopReason = value(liveStatus?.stop_reason);
 	if (sentinelStopReason === "session_id_conflict" || liveStopReason === "session_id_conflict") throw new Error("run is not resumable: session_id_conflict");
 }
+const RESUMABLE_SENTINEL_STATUSES = new Set([
+	"DONE",
+	"FAILED",
+	"BLOCKED"
+]);
+function rejectNotResumableStatus(sentinel) {
+	const status = (sentinel?._status ?? "").trim().toUpperCase();
+	if (status !== "" && !RESUMABLE_SENTINEL_STATUSES.has(status)) throw new Error(`run is not resumable (status: ${status.toLowerCase()})`);
+}
 async function executeFollowUpTool(args, getSupervisorClient) {
 	if (args.supervisorId) {
 		const { client, isSingleton, sup, supervisorId } = await getSupervisorClient(args.supervisorId);
@@ -2852,6 +2894,7 @@ async function executeFollowUpTool(args, getSupervisorClient) {
 			} catch {}
 			const sentinel = await parseSentinel(liveStatus?.sentinel_file ?? runInfo?.sentinelPath ?? path.join(runsRoot(), args.runId, "sentinel.done"));
 			rejectSessionConflict(sentinel, liveStatus);
+			rejectNotResumableStatus(sentinel);
 			const sessionId = sentinel?.SESSION ?? liveStatus?.session_id ?? fallbackSessionId;
 			if (!sessionId) throw new Error("run has no session to resume");
 			const agent = resolvedIdentity(liveStatus, "effective_agent", "agent", runInfo?.effectiveAgent, runInfo?.agent);
@@ -2930,6 +2973,7 @@ async function executeFollowUpTool(args, getSupervisorClient) {
 	if (!runInfo) throw new Error(`run not found: ${args.runId}`);
 	const sentinel = await parseSentinel(runInfo.sentinelPath);
 	rejectSessionConflict(sentinel, null);
+	rejectNotResumableStatus(sentinel);
 	const sessionId = sentinel?.SESSION ?? runInfo.sessionId;
 	if (!sessionId) throw new Error("run has no session to resume");
 	const client = sup.getClient();
@@ -2982,21 +3026,23 @@ async function shutdownTool(args) {
 	const cleanedUp = [];
 	if (args.supervisorId) {
 		const supervisorId = validateSupervisorSocketPath(args.supervisorId);
-		if (Supervisor.isCurrentInstance(supervisorId)) {
-			const sup = Supervisor.currentInstance();
-			if (!sup) throw new Error("supervisor not started");
+		const sup = Supervisor.getInstance(supervisorId);
+		if (sup) {
 			await sup.getClient().shutdown(args.force ? "force" : "graceful");
-			const runs = sup.runs;
-			for (const info of runs.values()) {
-				try {
-					await fs.promises.unlink(info.sentinelPath);
-					cleanedUp.push(info.sentinelPath);
-				} catch {}
-				try {
-					await fs.promises.unlink(info.eventLogPath);
-					cleanedUp.push(info.eventLogPath);
-				} catch {}
-			}
+			const cleanups = [];
+			sup.forEachRun((info) => {
+				cleanups.push((async () => {
+					try {
+						await fs.promises.unlink(info.sentinelPath);
+						cleanedUp.push(info.sentinelPath);
+					} catch {}
+					try {
+						await fs.promises.unlink(info.eventLogPath);
+						cleanedUp.push(info.eventLogPath);
+					} catch {}
+				})());
+			});
+			await Promise.all(cleanups);
 			await sup.close({ skipShutdown: true });
 		} else {
 			const client = await dial(supervisorId);
@@ -3030,8 +3076,7 @@ async function shutdownTool(args) {
 	try {
 		await sup.getClient().shutdown(args.force ? "force" : "graceful");
 	} catch {}
-	const runs = sup.runs;
-	for (const info of runs.values()) {
+	sup.forEachRun((info) => {
 		try {
 			fs.unlinkSync(info.sentinelPath);
 			cleanedUp.push(info.sentinelPath);
@@ -3040,7 +3085,7 @@ async function shutdownTool(args) {
 			fs.unlinkSync(info.eventLogPath);
 			cleanedUp.push(info.eventLogPath);
 		} catch {}
-	}
+	});
 	await sup.close({ skipShutdown: true });
 	return {
 		ok: true,
@@ -3063,11 +3108,24 @@ async function executeAskTool(args, getSupervisorClient) {
 	const { client, isSingleton, sup, supervisorId } = await getSupervisorClient(args.supervisorId);
 	try {
 		const target = (isSingleton && sup ? findLocalRunByReference(sup, args.toRunId) : findExternalRun(supervisorId, args.toRunId))?.runtimeId ?? args.toRunId;
-		const result = await client.brokerAsk(target, args.message);
-		return {
-			reply: extractReplyMessage(result),
-			from_run_id: result.from_run_id ?? ""
-		};
+		const timeoutMs = args.timeoutMs !== void 0 && Number.isFinite(args.timeoutMs) && args.timeoutMs > 0 ? args.timeoutMs : void 0;
+		try {
+			const result = await client.brokerAsk(target, args.message, void 0, timeoutMs);
+			return {
+				reply: extractReplyMessage(result),
+				from_run_id: result.from_run_id ?? ""
+			};
+		} catch (error) {
+			if (error instanceof RpcError && error.data && typeof error.data === "object") {
+				const data = error.data;
+				const messageId = data.message_id;
+				if (typeof messageId === "string" && messageId) {
+					if (data.pending === false) throw new Error(`ask failed (message_id: ${messageId} — the pending ask was already withdrawn): ${error.message}`);
+					throw new Error(`ask failed (message_id: ${messageId} — pass to avenor_cancel to withdraw): ${error.message}`);
+				}
+			}
+			throw error;
+		}
 	} finally {
 		if (!isSingleton) client.close();
 	}
@@ -3247,4 +3305,4 @@ function createWorkflowReadyTool(getSupervisorClient) {
 }
 const workflowReadyTool = createWorkflowReadyTool(getSupervisorClient);
 //#endregion
-export { DEFAULT_RUN_REDUCER_LIMITS, RunReducer, Supervisor, THINKING_LEVELS, answerPermissionTool, askTool, brokerReceiveTool, brokerReplyTool, cancelTool, createRunSnapshot, createWorkflowCompleteTool, createWorkflowControllerStatusTool, createWorkflowEventsTool, createWorkflowGateTool, createWorkflowInspectTool, createWorkflowReadyTool, createWorkflowStatusTool, createWorkflowWaitTool, dial, evaluateThinkingPolicy, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, isThinkingLevel, normalizeRunEvent, observeRun, peersTool, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, validateThinking, validateThinkingForBackend, validateThinkingForBackendResume, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool };
+export { DEFAULT_RUN_REDUCER_LIMITS, RpcError, RunReducer, Supervisor, THINKING_LEVELS, answerPermissionTool, askTool, brokerReceiveTool, brokerReplyTool, cancelTool, createRunSnapshot, createWorkflowCompleteTool, createWorkflowControllerStatusTool, createWorkflowEventsTool, createWorkflowGateTool, createWorkflowInspectTool, createWorkflowReadyTool, createWorkflowStatusTool, createWorkflowWaitTool, dial, evaluateThinkingPolicy, eventsTool, extractEventText, findAvenorBinary, followUpTool, getInstallDir, getVersion, inspectTool, installerBinaryPath, isThinkingLevel, normalizeRunEvent, observeRun, peersTool, reduceRunSnapshot, resultTool, shutdownTool, socketsRoot, spawnTool, statusTool, validateSpawnSelection, validateThinking, validateThinkingForBackend, validateThinkingForBackendResume, workflowCompleteTool, workflowControllerStatusTool, workflowEventsTool, workflowGateTool, workflowInspectTool, workflowReadyTool, workflowStatusTool, workflowWaitTool };

package/package.json

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