@dougbots/avenor-core 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+# @dougbots/avenor-core
+
+Control socket client, supervisor lifecycle, and tool implementations for the avenor agent runner.
+
+Avenor is a CLI daemon that runs AI agent sessions. This package manages that daemon's process and provides typed wrappers around its JSON-RPC control socket — the interface used to spawn runs, check status, follow up on sessions, and shut everything down cleanly.
+
+It is a **private** workspace package consumed by `@dougbots/avenor-mcp` and `@dougbots/avenor-opencode`. It is not published to npm.
+
+## Binary discovery
+
+The avenor binary is located through a three-step fallback:
+
+1. `AVENOR_BIN` environment variable
+2. `avenor` on `PATH` (via `which avenor`)
+3. `~/.botfiles/bin/avenor`
+
+The exported helper `findAvenorBinary()` runs this discovery. The `Supervisor` calls it automatically if no explicit `binaryPath` is given.
+
+## Core concepts
+
+### Client
+
+`dial(socketPath)` connects to an avenor control socket and returns a `Client`. The `Client` speaks JSON-RPC over a Unix socket and exposes methods like `spawn()`, `status()`, `list()`, `shutdown()`, `answerPermission()`, `prompt()`, and `cancel()`. It also provides an async iterable `events()` for streaming runtime events.
+
+### Supervisor
+
+`Supervisor.get()` is a singleton that ensures one avenor `stable` process is running, bound to a per-PID control socket. It starts the binary with `avenor stable --control-socket <path> --idle-timeout 30m`, retries the socket dial until it's ready, and registers signal handlers to clean up on exit.
+
+Spawned runs are tracked in-memory (label → runtime ID, sentinel path, event log path) so follow-ups and status checks can resolve the right runtime.
+
+## Tools
+
+The package exports six self-contained tool functions. Each is designed for embedding in MCP servers or CLI handlers.
+
+### `spawnTool`
+
+Starts a new agent run.
+
+```ts
+import { spawnTool } from '@dougbots/avenor-core'
+
+const result = await spawnTool({
+  agent: 'codex',
+  prompt: 'Write a function to reverse a string',
+  label: 'reverse-string',
+  model: 'claude-sonnet-4',
+})
+// { run_id: '...', label: 'reverse-string', supervisor_id: '/path/to/socket' }
+```
+
+Accepts `agent`, `prompt`, `promptFile`, `label`, `dir`, `timeout`, `model`, `sessionId`, and `supervisorId` (to target a specific socket).
+
+### `statusTool`
+
+Reports status for one or all runs. When `runId` is omitted it lists every run across the supervisor.
+
+```ts
+import { statusTool } from '@dougbots/avenor-core'
+
+const status = await statusTool({ runId: 'reverse-string' })
+// { 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.
+
+### `answerPermissionTool`
+
+Answers a pending permission request for a run. If `requestId` is omitted, it looks up the currently pending request automatically.
+
+```ts
+import { answerPermissionTool } from '@dougbots/avenor-core'
+
+await answerPermissionTool({ runId: 'my-run', optionId: 'allow-once' })
+// { ok: true }
+```
+
+### `followUpTool`
+
+Resumes a completed run by spawning a follow-up run on the same session, preserving conversation context.
+
+```ts
+import { followUpTool } from '@dougbots/avenor-core'
+
+await followUpTool({ runId: 'reverse-string', message: 'Now optimize it for speed' })
+// { run_id: '...', label: 'reverse-string-followup' }
+```
+
+### `eventsTool`
+
+Reads recent events from a run's on-disk event log. Optionally filters by event type and limits the count (default 50, max 1000).
+
+```ts
+import { eventsTool } from '@dougbots/avenor-core'
+
+const events = await eventsTool({ runId: 'my-run', types: ['tool_use', 'error'], limit: 20 })
+```
+
+⚠️ Only supported through the singleton `Supervisor` — passing an explicit `supervisorId` will throw.
+
+### `shutdownTool`
+
+Shuts down the avenor daemon. Pass `force: true` for an immediate kill instead of graceful termination. Cleans up sentinel files and event logs for tracked runs.
+
+```ts
+import { shutdownTool } from '@dougbots/avenor-core'
+
+const result = await shutdownTool({ force: false })
+// { ok: true, cleaned_up: ['/path/to/sentinel.done', ...] }
+```
+
+## Quick start
+
+```ts
+import { Supervisor, spawnTool, statusTool, shutdownTool } from '@dougbots/avenor-core'
+
+// 1. The supervisor auto-starts avenor. Call get() early — it's a singleton.
+const sup = await Supervisor.get()
+
+// 2. Spawn a run
+const { run_id } = await spawnTool({
+  agent: 'codex',
+  prompt: 'Review src/app.ts for security issues',
+  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', ... }
+
+// 4. Clean up
+await shutdownTool()
+```
+
+## Exports
+
+| Export | Kind | Description |
+|---|---|---|
+| `dial` | function | Connect to a control socket, returning a `Client` |
+| `Client` | class | JSON-RPC client for the avenor daemon |
+| `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) |
+| `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 |
+| `shutdownTool` | function | Stop the avenor daemon and clean up |

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import * as net from "node:net";
+
+//#region src/client.d.ts
+interface Event {
+  event: string;
+  session_id?: string;
+  runtime_id?: string;
+  [key: string]: unknown;
+}
+interface SpawnParams {
+  agent: string;
+  prompt_file?: string;
+  prompt?: string;
+  dir?: string;
+  label?: string;
+  timeout?: number;
+  model?: string;
+  session_id?: string;
+  sentinel_file?: string;
+  on_event?: string;
+  [key: string]: unknown;
+}
+declare class Client {
+  private socket;
+  private rl;
+  private nextID;
+  private pending;
+  private started;
+  private callTimeout;
+  private eventQueue;
+  private eventResolvers;
+  private eventDone;
+  private dropped;
+  private subscribed;
+  constructor(socket: net.Socket, opts?: {
+    callTimeoutMs?: number;
+  });
+  private startReadLoop;
+  private pushEvent;
+  call(method: string, params?: unknown): Promise<unknown>;
+  private subscribe;
+  events(): AsyncIterable<Event>;
+  status(runtimeId?: string): Promise<Record<string, unknown>>;
+  list(): Promise<Array<Record<string, unknown>>>;
+  spawn(params: SpawnParams): Promise<Record<string, unknown>>;
+  shutdown(mode: string): Promise<void>;
+  answerPermission(runtimeId: string, requestId: string, optionId: string): Promise<void>;
+  prompt(runtimeId: string, text: string): Promise<void>;
+  cancel(runtimeId?: string): Promise<void>;
+  close(): void;
+}
+declare function dial(socketPath: string, opts?: {
+  callTimeoutMs?: number;
+}): Promise<Client>;
+//#endregion
+//#region src/supervisor.d.ts
+interface RunInfo {
+  label: string;
+  sentinelPath: string;
+  eventLogPath: string;
+  runtimeId?: string;
+  sessionId?: string;
+}
+interface SupervisorOptions {
+  binaryPath?: string;
+  callTimeoutMs?: number;
+}
+declare function findAvenorBinary(): string;
+declare class Supervisor {
+  private static instance;
+  private static cleanupRegistered;
+  private static registerCleanup;
+  private client;
+  private childProcess;
+  private socketPath;
+  private crashed;
+  private crashCode;
+  private runs;
+  private binaryPath;
+  private callTimeoutMs;
+  private constructor();
+  static get(opts?: SupervisorOptions): Promise<Supervisor>;
+  private startProcess;
+  get supervisorId(): string;
+  static isCurrentInstance(supervisorId: string): boolean;
+  static currentInstance(): Supervisor | null;
+  getClient(): Client;
+  spawn(params: SpawnParams): Promise<RunInfo>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/tools/spawn.d.ts
+declare function spawnTool(args: {
+  agent: string;
+  prompt?: string;
+  promptFile?: string;
+  label?: string;
+  dir?: string;
+  timeout?: string;
+  model?: string;
+  sessionId?: string;
+  supervisorId?: string;
+}): Promise<{
+  run_id: string;
+  label: string;
+  supervisor_id: string;
+}>;
+//#endregion
+//#region src/tools/status.d.ts
+interface StatusResult {
+  run_id: string;
+  label: string;
+  status: string;
+  phase?: string;
+  phase_label?: string;
+  pending_permission?: {
+    request_id: string;
+    description: string;
+    options: Array<{
+      option_id: string;
+      label: string;
+      kind: string;
+    }>;
+  };
+  session_id?: string;
+  stop_reason?: string;
+}
+declare function statusTool(args: {
+  runId?: string;
+  supervisorId?: string;
+}): Promise<StatusResult | StatusResult[]>;
+//#endregion
+//#region src/tools/answer-permission.d.ts
+declare function answerPermissionTool(args: {
+  runId: string;
+  optionId: string;
+  requestId?: string;
+  supervisorId?: string;
+}): Promise<{
+  ok: boolean;
+}>;
+//#endregion
+//#region src/tools/follow-up.d.ts
+declare function followUpTool(args: {
+  runId: string;
+  message: string;
+  label?: string;
+  supervisorId?: string;
+}): Promise<{
+  run_id: string;
+  label: string;
+}>;
+//#endregion
+//#region src/tools/events.d.ts
+declare function eventsTool(args: {
+  runId: string;
+  types?: string[];
+  limit?: number;
+  supervisorId?: string;
+}): Promise<Array<{
+  type: string;
+  ts: number;
+  [key: string]: unknown;
+}>>;
+//#endregion
+//#region src/tools/shutdown.d.ts
+declare function shutdownTool(args: {
+  supervisorId?: string;
+  force?: boolean;
+}): Promise<{
+  ok: boolean;
+  cleaned_up: string[];
+}>;
+//#endregion
+export { type Client, type Event, type RunInfo, type SpawnParams, type StatusResult, Supervisor, type SupervisorOptions, answerPermissionTool, dial, eventsTool, findAvenorBinary, followUpTool, shutdownTool, spawnTool, statusTool };

package/dist/index.js

@@ -0,0 +1,854 @@
+import * as net from "node:net";
+import * as readline from "node:readline";
+import { execSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+//#region src/client.ts
+var Client = class {
+	socket;
+	rl;
+	nextID = 0;
+	pending = /* @__PURE__ */ new Map();
+	started = false;
+	callTimeout;
+	eventQueue = [];
+	eventResolvers = [];
+	eventDone = false;
+	dropped = 0;
+	subscribed = false;
+	constructor(socket, opts) {
+		this.socket = socket;
+		this.rl = readline.createInterface({
+			input: socket,
+			crlfDelay: Infinity
+		});
+		this.callTimeout = opts?.callTimeoutMs ?? 3e4;
+		this.socket.on("error", (err) => {
+			this.pushEvent({
+				event: "protocol-error",
+				message: err.message
+			});
+		});
+	}
+	startReadLoop() {
+		if (this.started) return;
+		this.started = true;
+		this.rl.on("line", (line) => {
+			let parsed;
+			try {
+				parsed = JSON.parse(line);
+			} catch {
+				return;
+			}
+			if (parsed.id !== void 0 && parsed.id !== null) {
+				const id = Number(parsed.id);
+				const pc = this.pending.get(id);
+				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}`));
+					else pc.resolve(parsed.result);
+				}
+				return;
+			}
+			if (parsed.method === "event" && parsed.params) {
+				const ev = { ...parsed.params };
+				if (this.dropped > 0) {
+					const lag = this.dropped;
+					this.dropped = 0;
+					const lagEvent = {
+						event: "client.lagged",
+						dropped_count: lag
+					};
+					this.pushEvent(lagEvent);
+				}
+				this.pushEvent(ev);
+			}
+		});
+		this.rl.on("close", () => {
+			for (const [, pc] of this.pending) {
+				clearTimeout(pc.timer);
+				pc.reject(/* @__PURE__ */ new Error("read response: connection closed"));
+			}
+			this.pending.clear();
+			this.eventDone = true;
+			for (const resolve of this.eventResolvers) 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);
+		else this.dropped++;
+	}
+	async call(method, params) {
+		this.startReadLoop();
+		const id = ++this.nextID;
+		const req = {
+			jsonrpc: "2.0",
+			id,
+			method
+		};
+		if (params !== void 0) req.params = params;
+		const data = JSON.stringify(req) + "\n";
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(/* @__PURE__ */ new Error("read response: timeout"));
+			}, this.callTimeout);
+			this.pending.set(id, {
+				resolve,
+				reject,
+				timer
+			});
+			this.socket.write(data, (err) => {
+				if (err) {
+					clearTimeout(timer);
+					this.pending.delete(id);
+					reject(/* @__PURE__ */ new Error(`write request: ${err.message}`));
+				}
+			});
+		});
+	}
+	async subscribe() {
+		if (this.subscribed) 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;
+			}
+			const result = await new Promise((resolve) => {
+				this.eventResolvers.push(resolve);
+			});
+			if (result.done) break;
+			yield result.value;
+		}
+	}
+	async status(runtimeId) {
+		const params = runtimeId ? { runtime_id: runtimeId } : void 0;
+		return this.call("status", params);
+	}
+	async list() {
+		return this.call("list");
+	}
+	async spawn(params) {
+		return this.call("spawn", params);
+	}
+	async shutdown(mode) {
+		await this.call("shutdown", { mode });
+	}
+	async answerPermission(runtimeId, requestId, optionId) {
+		await this.call("answer_permission", {
+			runtime_id: runtimeId,
+			request_id: requestId,
+			option_id: optionId
+		});
+	}
+	async prompt(runtimeId, text) {
+		await this.call("prompt", {
+			runtime_id: runtimeId,
+			text
+		});
+	}
+	async cancel(runtimeId) {
+		const params = runtimeId ? { runtime_id: runtimeId } : void 0;
+		await this.call("cancel", params);
+	}
+	close() {
+		this.rl.close();
+		this.socket.destroy();
+	}
+};
+function dial(socketPath, opts) {
+	return new Promise((resolve, reject) => {
+		const socket = net.createConnection({ path: socketPath });
+		const onConnect = () => {
+			socket.removeListener("error", onError);
+			resolve(new Client(socket, opts));
+		};
+		const onError = (err) => {
+			socket.removeListener("connect", onConnect);
+			reject(/* @__PURE__ */ new Error(`dial control socket: ${err.message}`));
+		};
+		socket.on("connect", onConnect);
+		socket.on("error", onError);
+	});
+}
+//#endregion
+//#region src/paths.ts
+function avenorHome() {
+	return process.env.AVENOR_HOME || path.join(os.homedir(), ".avenor");
+}
+function socketsRoot() {
+	return path.join(avenorHome(), "sockets");
+}
+function runsRoot() {
+	return path.join(avenorHome(), "runs");
+}
+function ensureRunPaths(runId) {
+	const runDir = path.join(runsRoot(), runId);
+	fs.mkdirSync(runDir, {
+		recursive: true,
+		mode: 448
+	});
+	return {
+		runDir,
+		sentinelPath: path.join(runDir, "sentinel.done"),
+		eventLogPath: path.join(runDir, "events.log")
+	};
+}
+//#endregion
+//#region src/supervisor.ts
+function findAvenorBinary() {
+	const envBin = process.env.AVENOR_BIN;
+	if (envBin) try {
+		fs.accessSync(envBin, fs.constants.X_OK);
+		return envBin;
+	} catch {
+		throw new Error(`AVENOR_BIN path not executable: ${envBin}`);
+	}
+	try {
+		const binPath = execSync("which avenor", { encoding: "utf-8" }).trim();
+		if (binPath) {
+			fs.accessSync(binPath, fs.constants.X_OK);
+			return binPath;
+		}
+	} catch {}
+	const homeBin = path.join(os.homedir(), ".botfiles", "bin", "avenor");
+	try {
+		fs.accessSync(homeBin, fs.constants.X_OK);
+		return homeBin;
+	} catch {}
+	throw new Error("avenor binary not found. Set AVENOR_BIN=/path/to/avenor or ensure 'avenor' is on PATH.");
+}
+var Supervisor = class Supervisor {
+	static instance = null;
+	static cleanupRegistered = false;
+	static registerCleanup() {
+		if (Supervisor.cleanupRegistered) return;
+		Supervisor.cleanupRegistered = true;
+		const cleanup = () => {
+			if (Supervisor.instance?.childProcess) Supervisor.instance.childProcess.kill();
+		};
+		process.on("exit", cleanup);
+		process.on("SIGINT", () => {
+			cleanup();
+			process.exit();
+		});
+		process.on("SIGTERM", () => {
+			cleanup();
+			process.exit();
+		});
+	}
+	client = null;
+	childProcess = null;
+	socketPath;
+	crashed = false;
+	crashCode = null;
+	runs = /* @__PURE__ */ new Map();
+	binaryPath;
+	callTimeoutMs;
+	constructor(binaryPath, socketPath, opts) {
+		this.binaryPath = binaryPath;
+		this.socketPath = socketPath;
+		this.callTimeoutMs = opts?.callTimeoutMs ?? 3e4;
+	}
+	static async get(opts) {
+		if (Supervisor.instance && !Supervisor.instance.crashed) return Supervisor.instance;
+		Supervisor.registerCleanup();
+		const binaryPath = opts?.binaryPath ?? findAvenorBinary();
+		const socketDir = socketsRoot();
+		fs.mkdirSync(socketDir, {
+			recursive: true,
+			mode: 448
+		});
+		const socketPath = path.join(socketDir, `avenor-mcp-${process.pid}.sock`);
+		let socketExists = false;
+		try {
+			await fs.promises.access(socketPath, fs.constants.R_OK | fs.constants.W_OK);
+			socketExists = true;
+		} catch {}
+		if (socketExists) try {
+			const probeClient = await dial(socketPath, { callTimeoutMs: 2e3 });
+			try {
+				await probeClient.status();
+				probeClient.close();
+				const client = await dial(socketPath);
+				const sup = new Supervisor(binaryPath, socketPath, opts);
+				sup.client = client;
+				Supervisor.instance = sup;
+				return sup;
+			} catch {
+				probeClient.close();
+				try {
+					await fs.promises.unlink(socketPath);
+				} catch {}
+			}
+		} catch {
+			try {
+				await fs.promises.unlink(socketPath);
+			} catch {}
+		}
+		const sup = new Supervisor(binaryPath, socketPath, opts);
+		await sup.startProcess();
+		Supervisor.instance = sup;
+		return sup;
+	}
+	startProcess() {
+		return new Promise((resolve, reject) => {
+			let resolved = false;
+			this.childProcess = spawn(this.binaryPath, [
+				"stable",
+				"--control-socket",
+				this.socketPath,
+				"--idle-timeout",
+				"30m"
+			], { detached: false });
+			this.childProcess.on("exit", (code, signal) => {
+				if (!resolved) {
+					resolved = true;
+					reject(/* @__PURE__ */ new Error(`avenor exited with code ${code}${signal ? " signal " + signal : ""} during startup`));
+					return;
+				}
+				if (code !== 0 || signal) {
+					this.crashed = true;
+					this.crashCode = code ?? -1;
+					if (this.client) {
+						try {
+							this.client.close();
+						} catch {}
+						this.client = null;
+					}
+				}
+			});
+			this.childProcess.on("error", (err) => {
+				if (!resolved) {
+					resolved = true;
+					reject(/* @__PURE__ */ new Error(`failed to start avenor: ${err.message}`));
+				}
+			});
+			const timeout = setTimeout(() => {
+				if (!resolved) {
+					resolved = true;
+					reject(/* @__PURE__ */ new Error("timed out waiting for avenor socket"));
+				}
+			}, 1e4);
+			const retryDial = async () => {
+				while (!resolved) try {
+					await new Promise((r) => setTimeout(r, 100));
+					this.client = await dial(this.socketPath, { callTimeoutMs: this.callTimeoutMs });
+					clearTimeout(timeout);
+					resolved = true;
+					resolve();
+					return;
+				} catch {}
+			};
+			retryDial();
+		});
+	}
+	get supervisorId() {
+		return this.socketPath;
+	}
+	static isCurrentInstance(supervisorId) {
+		return Supervisor.instance !== null && Supervisor.instance.supervisorId === supervisorId;
+	}
+	static currentInstance() {
+		return Supervisor.instance;
+	}
+	getClient() {
+		if (this.crashed) throw new Error(`avenor supervisor crashed (exit code ${this.crashCode}). Call avenor_shutdown to clean up and retry.`);
+		if (!this.client) throw new Error("supervisor not started");
+		return this.client;
+	}
+	async spawn(params) {
+		const client = this.getClient();
+		const runId = crypto.randomUUID();
+		const { sentinelPath, eventLogPath } = ensureRunPaths(runId);
+		const spawnParams = {
+			...params,
+			label: params.label ?? runId,
+			sentinel_file: sentinelPath,
+			on_event: eventLogPath
+		};
+		const result = await client.spawn(spawnParams);
+		const runInfo = {
+			label: spawnParams.label ?? runId,
+			sentinelPath: result.sentinel_file ?? sentinelPath,
+			eventLogPath: result.on_event ?? eventLogPath,
+			runtimeId: result.runtime_id,
+			sessionId: result.session_id
+		};
+		this.runs.set(runInfo.label, runInfo);
+		this.runs.set(runId, runInfo);
+		return runInfo;
+	}
+	async close() {
+		if (this.client) try {
+			await this.client.shutdown("graceful");
+		} catch {}
+		if (this.childProcess) {
+			this.childProcess.kill();
+			this.childProcess = null;
+		}
+		if (this.client) {
+			try {
+				this.client.close();
+			} catch {}
+			this.client = null;
+		}
+		try {
+			await fs.promises.unlink(this.socketPath);
+		} catch {}
+		this.crashed = false;
+		this.crashCode = null;
+		this.runs.clear();
+		Supervisor.instance = null;
+	}
+};
+//#endregion
+//#region src/tools/validate.ts
+function validateRunId(id) {
+	if (!/^[a-zA-Z0-9_-]+$/.test(id)) throw new Error(`invalid run_id: ${id}`);
+}
+function validateTimeout(value) {
+	const trimmed = value.trim();
+	const match = /^(\d+)([smh]?)$/.exec(trimmed);
+	if (!match) throw new Error(`invalid timeout: ${value}`);
+	const amount = Number(match[1]);
+	const unit = match[2];
+	if (!Number.isFinite(amount) || amount <= 0) throw new Error(`invalid timeout: ${value}`);
+	if (unit === "m") return amount * 60;
+	if (unit === "h") return amount * 3600;
+	return amount;
+}
+function validateSupervisorSocketPath(supervisorId) {
+	const canonical = fs.realpathSync(supervisorId);
+	const root = fs.realpathSync(socketsRoot());
+	const relative = path.relative(root, canonical);
+	if (relative.startsWith("..") || path.isAbsolute(relative) || !/^avenor-mcp-[^/\\]+\.sock$/.test(path.basename(canonical))) throw new Error(`invalid supervisorId: ${supervisorId}`);
+	return canonical;
+}
+//#endregion
+//#region src/tools/spawn.ts
+async function spawnTool(args) {
+	const runId = crypto.randomUUID();
+	const label = args.label ?? runId;
+	if (args.supervisorId) {
+		const client = await dial(validateSupervisorSocketPath(args.supervisorId));
+		const { sentinelPath, eventLogPath } = ensureRunPaths(runId);
+		try {
+			return {
+				run_id: (await client.spawn({
+					agent: args.agent,
+					prompt: args.prompt,
+					prompt_file: args.promptFile,
+					label,
+					dir: args.dir,
+					timeout: args.timeout !== void 0 ? validateTimeout(args.timeout) : void 0,
+					model: args.model,
+					session_id: args.sessionId,
+					sentinel_file: sentinelPath,
+					on_event: eventLogPath
+				})).runtime_id ?? runId,
+				label,
+				supervisor_id: args.supervisorId
+			};
+		} finally {
+			client.close();
+		}
+	}
+	const sup = await Supervisor.get();
+	await sup.spawn({
+		agent: args.agent,
+		prompt: args.prompt,
+		prompt_file: args.promptFile,
+		label,
+		dir: args.dir,
+		timeout: args.timeout !== void 0 ? validateTimeout(args.timeout) : void 0,
+		model: args.model,
+		session_id: args.sessionId
+	});
+	return {
+		run_id: runId,
+		label,
+		supervisor_id: sup.supervisorId
+	};
+}
+//#endregion
+//#region src/tools/status.ts
+function findRunByLabel$3(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$1(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 sentinelExists(filePath) {
+	try {
+		await fs.promises.access(filePath, fs.constants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function translateStatus(rawPhase, sentinelData) {
+	const sentinelStatus = sentinelData?._status;
+	switch (rawPhase) {
+		case "idle":
+		case "running": return "running";
+		case "ended":
+			if (sentinelStatus) switch (sentinelStatus) {
+				case "DONE": return "done";
+				case "FAILED": return "failed";
+				case "TIMEOUT": return "timeout";
+				case "KILLED": return "killed";
+				case "BLOCKED": return "failed";
+				default: return "running";
+			}
+			return "running";
+		case "DONE": return "done";
+		case "FAILED": return "failed";
+		case "TIMEOUT": return "timeout";
+		case "KILLED": return "killed";
+		case "BLOCKED": return "failed";
+		default: return "running";
+	}
+}
+async function buildRunStatus(client, 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 = {
+		run_id: runInfo.label,
+		label: runInfo.label,
+		status: translated,
+		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 ?? ""
+			})) : []
+		};
+	}
+	return result;
+}
+async function statusTool(args) {
+	if (args.supervisorId) {
+		const client = await dial(validateSupervisorSocketPath(args.supervisorId));
+		try {
+			if (args.runId) {
+				validateRunId(args.runId);
+				let liveStatus = null;
+				try {
+					liveStatus = await client.status(args.runId);
+				} 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 {
+					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
+				};
+			}
+			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,
+				session_id: entry.session_id
+			}));
+		} finally {
+			client.close();
+		}
+	}
+	const sup = await Supervisor.get();
+	const client = sup.getClient();
+	if (args.runId) {
+		const runInfo = findRunByLabel$3(sup, args.runId);
+		if (!runInfo) throw new Error(`run not found: ${args.runId}`);
+		let liveStatus = null;
+		if (runInfo.runtimeId) try {
+			liveStatus = await client.status(runInfo.runtimeId);
+		} catch {}
+		return buildRunStatus(client, runInfo, liveStatus);
+	}
+	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 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,
+			label: entryLabel,
+			status: translateStatus(entry.phase ?? entry.status ?? "running", null),
+			phase: entry.phase,
+			session_id: entry.session_id
+		});
+	}
+	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;
+	if (args.supervisorId) client = await dial(validateSupervisorSocketPath(args.supervisorId));
+	else {
+		sup = await Supervisor.get();
+		client = sup.getClient();
+	}
+	try {
+		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 (args.supervisorId) 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 = await dial(validateSupervisorSocketPath(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);
+			await client.spawn({
+				agent,
+				prompt: args.message,
+				label: followUpLabel,
+				session_id: sentinel.SESSION,
+				sentinel_file: followUpSentinelPath,
+				on_event: eventLogPath
+			});
+			return {
+				run_id: followUpRunId,
+				label: followUpLabel
+			};
+		} finally {
+			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.label,
+		label: followUpRun.label
+	};
+}
+//#endregion
+//#region src/tools/events.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 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;
+	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");
+		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();
+		}
+	} catch {
+		return [];
+	}
+	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/shutdown.ts
+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");
+			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 {}
+			}
+			await sup.close();
+		} else {
+			const client = await dial(supervisorId);
+			try {
+				await client.shutdown(args.force ? "force" : "graceful");
+			} catch {} finally {
+				client.close();
+			}
+		}
+		return {
+			ok: true,
+			cleaned_up: cleanedUp
+		};
+	}
+	const sup = await Supervisor.get();
+	try {
+		await sup.getClient().shutdown(args.force ? "force" : "graceful");
+	} catch {}
+	const runs = sup.runs;
+	for (const info of runs.values()) {
+		try {
+			fs.unlinkSync(info.sentinelPath);
+			cleanedUp.push(info.sentinelPath);
+		} catch {}
+		try {
+			fs.unlinkSync(info.eventLogPath);
+			cleanedUp.push(info.eventLogPath);
+		} catch {}
+	}
+	await sup.close();
+	return {
+		ok: true,
+		cleaned_up: cleanedUp
+	};
+}
+//#endregion
+export { Supervisor, answerPermissionTool, dial, eventsTool, findAvenorBinary, followUpTool, shutdownTool, spawnTool, statusTool };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@dougbots/avenor-core",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "bun test",
+    "test:e2e": "AVENOR_REAL_INTEGRATION=1 bun test",
+    "dev": "tsdown --watch"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.12",
+    "@types/node": "^25.8.0",
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3",
+    "unrun": "^0.3.0"
+  }
+}