@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/eval/js/worker-entry.ts

@@ -18,6 +18,12 @@ const transport: Transport = {
 		} catch {
 			// Already closed.
 		}
+
+		// `parentPort.close()` only disconnects the channel in Bun; it does not
+		// make the Worker emit `close` or reap ref'ed user handles. Exit from
+		// inside the worker after `WorkerCore` has sent the `closed` ack so the
+		// host can observe real worker exit without calling `Worker.terminate()`.
+		setTimeout(() => process.exit(0), 0);
 	},
 };
 

package/src/eval/js/worker-protocol.ts

@@ -5,6 +5,12 @@ export type { JsDisplayOutput } from "./shared/types";
 export interface SessionSnapshot {
 	cwd: string;
 	sessionId: string;
+	/**
+	 * On-disk roots the helpers substitute for internal-URL schemes
+	 * (e.g. `{ local: "/…/artifacts/local" }`). Lets `read`/`write`/`append`
+	 * accept `local://…` paths instead of writing a literal `local:/` directory.
+	 */
+	localRoots?: Record<string, string>;
 }
 
 export interface RunErrorPayload {

package/src/eval/llm-bridge.ts

@@ -12,7 +12,8 @@
  * in, text (or, with `schema`, a structured object) out.
  */
 import { instrumentedCompleteSimple, resolveTelemetry } from "@prometheus-ai/agent-core";
-import { type Api, Effort, getSupportedEfforts, type Model, type Tool } from "@prometheus-ai/ai";
+import { type Api, Effort, type Model, type Tool } from "@prometheus-ai/ai";
+import { getSupportedEfforts } from "@prometheus-ai/catalog/model-thinking";
 import * as z from "zod/v4";
 import { extractTextContent, extractToolCall, parseJsonPayload } from "../commit/utils";
 import { expandRoleAlias, formatModelString, resolveModelFromString } from "../config/model-resolver";

package/src/eval/py/__tests__/prelude.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "bun:test";
+import { PYTHON_PRELUDE } from "../prelude";
+
+describe("python prelude", () => {
+	it("exposes read(path, offset?, limit?) with positional optional args", () => {
+		// The eval docs advertise `read(path, offset?=1, limit?=None)`. A
+		// keyword-only signature (`def read(path, *, offset=1, limit=None)`)
+		// makes `read("file", 10)` raise `TypeError: read() takes 1 positional
+		// argument but 2 were given`, which agents in the wild repeatedly hit.
+		// Lock the contract so the helper accepts both positional and keyword
+		// forms.
+		const match = PYTHON_PRELUDE.match(/def\s+read\(([^)]+)\)/);
+		expect(match).not.toBeNull();
+		const signature = match?.[1] ?? "";
+		expect(signature).not.toContain("*,");
+		expect(signature).toContain("offset");
+		expect(signature).toContain("limit");
+	});
+});

package/src/eval/py/executor.ts

@@ -1,7 +1,8 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 
 import { getProjectDir, logger } from "@prometheus-ai/utils";
-import { isSettingsInitialized, Settings, settings } from "../../config/settings";
+import { Settings } from "../../config/settings";
 import { OutputSink } from "../../session/streaming-output";
 import type { ToolSession } from "../../tools";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../../tools/output-meta";
@@ -15,6 +16,7 @@ import {
 	type KernelRuntimeEnv,
 	PythonKernel,
 } from "./kernel";
+import { resolveExplicitPythonRuntime } from "./runtime";
 import { ensurePyToolBridge, registerPyToolBridge } from "./tool-bridge";
 
 export type PythonKernelMode = "session" | "per-call";
@@ -42,6 +44,11 @@ export interface PythonExecutorOptions {
 	kernelOwnerId?: string;
 	/** Kernel mode (session reuse vs per-call) */
 	kernelMode?: PythonKernelMode;
+	/**
+	 * Explicit interpreter path (`python.interpreter` resolved from the
+	 * session's settings). Skips automatic runtime discovery when set.
+	 */
+	interpreter?: string;
 	/** Restart the kernel before executing */
 	reset?: boolean;
 	/** Session file path for accessing task outputs */
@@ -56,6 +63,13 @@ export interface PythonExecutorOptions {
 	/** Artifact path/id for full output storage */
 	artifactPath?: string;
 	artifactId?: string;
+	/**
+	 * On-disk roots the prelude helpers (`read`/`write`/`append`) substitute for
+	 * internal-URL schemes (e.g. `{ local: "/…/artifacts/local" }`). Exported to
+	 * the kernel as `PROMETHEUS_EVAL_LOCAL_ROOTS` (JSON) so `write("local://x")` lands
+	 * where `read local://x` resolves instead of a literal `local:/` directory.
+	 */
+	localRoots?: Record<string, string>;
 	/**
 	 * ToolSession used to resolve host-side `tool.<name>(args)` calls made from
 	 * the Python prelude's bridge proxy. When omitted, the bridge env vars are
@@ -109,9 +123,9 @@ export interface PythonResult {
 // ---------------------------------------------------------------------------
 // Session bookkeeping
 //
-// One PythonKernel subprocess per (session id, cwd) tuple. The runner mutates
-// process-global cwd/sys.path during execution, so cross-directory work MUST
-// never share a live kernel. Multiple agent owners can still register against
+// One PythonKernel subprocess per (session id, cwd, interpreter) tuple. The
+// runner mutates process-global cwd/sys.path during execution, so cross-directory
+// work must never share a live kernel. Multiple agent owners can still register against
 // the same tuple; the kernel stays alive until the last owner detaches.
 // ---------------------------------------------------------------------------
 
@@ -126,14 +140,25 @@ interface PythonSession {
 
 const sessions = new Map<string, PythonSession>();
 const startingSessions = new Map<string, Promise<PythonSession>>();
-const resettingSessions = new Set<string>();
+const resettingSessions = new Map<string, Promise<void>>();
 
 function normalizeSessionCwd(cwd: string): string {
 	return path.resolve(cwd);
 }
 
-function buildSessionKey(sessionId: string, cwd: string): string {
-	return `${sessionId}\0${normalizeSessionCwd(cwd)}`;
+function normalizeExplicitInterpreter(cwd: string, interpreter: string | undefined): string {
+	if (interpreter === undefined) return "";
+	const resolved = resolveExplicitPythonRuntime(interpreter, cwd, {}).pythonPath;
+	try {
+		return fs.realpathSync.native(resolved);
+	} catch {
+		return resolved;
+	}
+}
+
+function buildSessionKey(sessionId: string, cwd: string, interpreter: string | undefined): string {
+	const normalizedCwd = normalizeSessionCwd(cwd);
+	return `${sessionId}\0${normalizedCwd}\0${normalizeExplicitInterpreter(normalizedCwd, interpreter)}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -275,6 +300,7 @@ const MANAGED_KERNEL_ENV_KEYS = [
 	"PROMETHEUS_TOOL_BRIDGE_URL",
 	"PROMETHEUS_TOOL_BRIDGE_TOKEN",
 	"PROMETHEUS_TOOL_BRIDGE_SESSION",
+	"PROMETHEUS_EVAL_LOCAL_ROOTS",
 ] as const;
 
 function buildKernelEnvPatch(options: {
@@ -282,13 +308,16 @@ function buildKernelEnvPatch(options: {
 	artifactsDir?: string;
 	bridgeSessionId?: string;
 	bridge?: { url: string; token: string };
+	localRoots?: Record<string, string>;
 }): KernelRuntimeEnv {
+	const localRoots = options.localRoots;
 	return {
 		PROMETHEUS_SESSION_FILE: options.sessionFile ?? null,
 		PROMETHEUS_ARTIFACTS_DIR: options.artifactsDir ?? null,
 		PROMETHEUS_TOOL_BRIDGE_URL: options.bridge?.url ?? null,
 		PROMETHEUS_TOOL_BRIDGE_TOKEN: options.bridge?.token ?? null,
 		PROMETHEUS_TOOL_BRIDGE_SESSION: options.bridge && options.bridgeSessionId ? options.bridgeSessionId : null,
+		PROMETHEUS_EVAL_LOCAL_ROOTS: localRoots && Object.keys(localRoots).length > 0 ? JSON.stringify(localRoots) : null,
 	};
 }
 
@@ -297,6 +326,7 @@ function buildKernelEnv(options: {
 	artifactsDir?: string;
 	bridgeSessionId?: string;
 	bridge?: { url: string; token: string };
+	localRoots?: Record<string, string>;
 }): Record<string, string> | undefined {
 	const patch = buildKernelEnvPatch(options);
 	const env: Record<string, string> = {};
@@ -314,6 +344,7 @@ async function startKernel(cwd: string, options: PythonExecutorOptions): Promise
 		env: buildKernelEnv(options),
 		signal: options.signal,
 		deadlineMs: options.deadlineMs,
+		interpreter: options.interpreter,
 	});
 }
 
@@ -476,18 +507,17 @@ async function executeWithKernel(
 	code: string,
 	options: PythonExecutorOptions | undefined,
 ): Promise<PythonResult> {
-	const activeSettings = isSettingsInitialized() ? settings : undefined;
+	const settings = await Settings.init();
 	const sink = new OutputSink({
 		onChunk: options?.onChunk,
 		artifactPath: options?.artifactPath,
 		artifactId: options?.artifactId,
-		headBytes: resolveOutputSinkHeadBytes(activeSettings),
-		maxColumns: resolveOutputMaxColumns(activeSettings),
+		headBytes: resolveOutputSinkHeadBytes(settings),
+		maxColumns: resolveOutputMaxColumns(settings),
 	});
 	const displayOutputs: KernelDisplayOutput[] = [];
 	const deadlineMs = getExecutionDeadlineMs(options);
 	let executionTimeoutMs: number | undefined;
-	const annotationTimeoutMs = options?.timeoutMs ?? options?.idleTimeoutMs;
 
 	// Collect every display output and, for status events, stream them live so
 	// long-running bridge helpers (e.g. `agent()`) surface progress mid-cell.
@@ -525,7 +555,7 @@ async function executeWithKernel(
 
 		if (result.cancelled) {
 			const annotation = result.timedOut
-				? formatKernelTimeoutAnnotation(annotationTimeoutMs ?? executionTimeoutMs, result.kernelKilled ?? false)
+				? formatKernelTimeoutAnnotation(executionTimeoutMs ?? options?.idleTimeoutMs, result.kernelKilled ?? false)
 				: undefined;
 			return {
 				exitCode: undefined,
@@ -563,7 +593,7 @@ async function executeWithKernel(
 				displayOutputs,
 				stdinRequested: false,
 				...(await sink.dump(
-					timedOut ? formatTimeoutAnnotation(annotationTimeoutMs ?? executionTimeoutMs) : undefined,
+					timedOut ? formatTimeoutAnnotation(executionTimeoutMs ?? options?.idleTimeoutMs) : undefined,
 				)),
 			};
 		}
@@ -576,7 +606,10 @@ async function executeWithKernel(
 }
 
 async function ensureKernelAvailable(cwd: string, options: PythonExecutorOptions): Promise<void> {
-	const availability = await waitForPromiseWithCancellation(checkPythonKernelAvailability(cwd), options);
+	const availability = await waitForPromiseWithCancellation(
+		checkPythonKernelAvailability(cwd, options.interpreter),
+		options,
+	);
 	if (!availability.ok) {
 		throw new Error(availability.reason ?? "Python kernel unavailable");
 	}
@@ -607,22 +640,34 @@ async function executePerCall(code: string, cwd: string, options: PythonExecutor
 
 async function executeOnSession(code: string, cwd: string, options: PythonExecutorOptions): Promise<PythonResult> {
 	const sessionId = options.sessionId ?? `session:${cwd}`;
-	const sessionKey = buildSessionKey(sessionId, cwd);
+	const sessionKey = buildSessionKey(sessionId, cwd, options.interpreter);
 	if (options.bridge && !options.bridgeSessionId) {
 		options.bridgeSessionId = sessionId;
 	}
 	if (options.reset) {
-		if (resettingSessions.has(sessionKey)) {
-			throw new Error("Python kernel reset already in progress");
-		}
-		resettingSessions.add(sessionKey);
-		try {
-			await resetSession(sessionKey);
-		} finally {
-			resettingSessions.delete(sessionKey);
+		// Coalesce concurrent resets: if another reset is in flight for this
+		// session, await it instead of throwing — the caller's intent ("start
+		// from a clean kernel") is satisfied once that reset settles.
+		const inFlight = resettingSessions.get(sessionKey);
+		if (inFlight) await inFlight.catch(() => undefined);
+		else {
+			const resetPromise = resetSession(sessionKey);
+			resettingSessions.set(
+				sessionKey,
+				resetPromise.then(() => undefined),
+			);
+			try {
+				await resetPromise;
+			} finally {
+				resettingSessions.delete(sessionKey);
+			}
 		}
-	} else if (resettingSessions.has(sessionKey)) {
-		throw new Error("Python kernel reset in progress");
+	} else {
+		// A reset already in progress is an internal coordination state, not a
+		// user-visible failure. Wait for it to clear, then proceed with the
+		// requested execution on the freshly-restarted kernel.
+		const inFlight = resettingSessions.get(sessionKey);
+		if (inFlight) await inFlight.catch(() => undefined);
 	}
 	const session = await acquireSession(sessionKey, sessionId, cwd, options);
 	if (options.signal?.aborted) {
@@ -680,7 +725,6 @@ export async function executePython(code: string, options?: PythonExecutorOption
 				isTimedOutCancellation(executionOptions.signal.reason, executionOptions.signal),
 			);
 		}
-		await Settings.init();
 		await ensureKernelAvailable(cwd, executionOptions);
 		await ensureToolBridge(executionOptions);
 

package/src/eval/py/index.ts

@@ -1,5 +1,10 @@
 import type { ToolSession } from "../../tools";
-import type { ExecutorBackend, ExecutorBackendExecOptions, ExecutorBackendResult } from "../backend";
+import {
+	type ExecutorBackend,
+	type ExecutorBackendExecOptions,
+	type ExecutorBackendResult,
+	resolveEvalUrlRoots,
+} from "../backend";
 import { executePython, type PythonExecutorOptions } from "./executor";
 import { checkPythonKernelAvailability } from "./kernel";
 
@@ -14,13 +19,17 @@ function readSetting<T>(session: ToolSession, key: string): T | undefined {
 	return settings?.get?.(key);
 }
 
+function readInterpreterSetting(session: ToolSession): string | undefined {
+	return readSetting<string>(session, "python.interpreter")?.trim() || undefined;
+}
+
 export default {
 	id: "python",
 	label: "Python",
 	highlightLang: "python",
 
 	async isAvailable(session: ToolSession): Promise<boolean> {
-		const availability = await checkPythonKernelAvailability(session.cwd);
+		const availability = await checkPythonKernelAvailability(session.cwd, readInterpreterSetting(session));
 		return availability.ok;
 	},
 
@@ -32,12 +41,12 @@ export default {
 			signal: opts.signal,
 			sessionId: namespaceSessionId(opts.sessionId),
 			kernelMode,
+			interpreter: readInterpreterSetting(opts.session),
 			sessionFile: opts.sessionFile,
 			artifactsDir: opts.session.getArtifactsDir?.() ?? undefined,
+			localRoots: resolveEvalUrlRoots(opts.session),
 			kernelOwnerId: opts.kernelOwnerId,
 			reset: opts.reset,
-			artifactPath: opts.artifactPath,
-			artifactId: opts.artifactId,
 			onChunk: opts.onChunk,
 			onStatus: opts.onStatus,
 			toolSession: opts.session,

package/src/eval/py/kernel.ts

@@ -17,7 +17,13 @@ import { Settings } from "../../config/settings";
 import { type KernelDisplayOutput, renderKernelDisplay } from "./display";
 import { PYTHON_PRELUDE } from "./prelude";
 import RUNNER_SCRIPT from "./runner.py" with { type: "text" };
-import { enumeratePythonRuntimes, filterEnv, type PythonRuntime, resolvePythonRuntime } from "./runtime";
+import {
+	enumeratePythonRuntimes,
+	filterEnv,
+	type PythonRuntime,
+	resolveExplicitPythonRuntime,
+	resolvePythonRuntime,
+} from "./runtime";
 import { hostHasInheritableConsole, shouldHideKernelWindow } from "./spawn-options";
 
 export type { KernelDisplayOutput, PythonStatusEvent } from "./display";
@@ -96,6 +102,11 @@ interface KernelLifecycleOptions {
 interface KernelStartOptions extends KernelLifecycleOptions {
 	cwd: string;
 	env?: Record<string, string | undefined>;
+	/**
+	 * Explicit interpreter path (`python.interpreter` from the session's
+	 * settings). When set, runtime discovery is skipped entirely.
+	 */
+	interpreter?: string;
 }
 
 interface KernelShutdownOptions {
@@ -129,15 +140,40 @@ function throwIfAborted(signal: AbortSignal | undefined, fallbackReason: string)
 	throw createAbortError("AbortError", typeof reason === "string" ? reason : fallbackReason);
 }
 
-export async function checkPythonKernelAvailability(cwd: string): Promise<PythonKernelAvailability> {
+// Cache successful probes per resolved cwd + explicit interpreter: every cell
+// otherwise pays one (or two — backend.isAvailable + ensureKernelAvailable)
+// interpreter spawns even when the kernel is already hot. Failures are not
+// cached so installing a Python mid-session is picked up on the next attempt.
+const availabilityCache = new Map<string, Promise<PythonKernelAvailability>>();
+
+export async function checkPythonKernelAvailability(
+	cwd: string,
+	interpreter?: string,
+): Promise<PythonKernelAvailability> {
 	if (isBunTestRuntime() || $flag("PROMETHEUS_PYTHON_SKIP_CHECK")) {
 		return { ok: true };
 	}
+	const resolvedCwd = path.resolve(cwd);
+	const key = `${resolvedCwd}\0${interpreter ?? ""}`;
+	const cached = availabilityCache.get(key);
+	if (cached) return await cached;
+	const probe = probePythonKernelAvailability(resolvedCwd, interpreter);
+	availabilityCache.set(key, probe);
+	const result = await probe;
+	if (!result.ok && availabilityCache.get(key) === probe) {
+		availabilityCache.delete(key);
+	}
+	return result;
+}
+
+async function probePythonKernelAvailability(cwd: string, interpreter?: string): Promise<PythonKernelAvailability> {
 	try {
 		const settings = await Settings.init();
 		const { env } = settings.getShellConfig();
 		const baseEnv = filterEnv(env);
-		const runtimes = enumeratePythonRuntimes(cwd, baseEnv);
+		const runtimes = interpreter
+			? [resolveExplicitPythonRuntime(interpreter, cwd, baseEnv)]
+			: enumeratePythonRuntimes(cwd, baseEnv);
 		if (runtimes.length === 0) {
 			return { ok: false, reason: "Python executable not found on PATH" };
 		}
@@ -220,6 +256,7 @@ export class PythonKernel {
 			"PythonKernel.start:availabilityCheck",
 			checkPythonKernelAvailability,
 			options.cwd,
+			options.interpreter,
 		);
 		if (!availability.ok) {
 			throw new Error(availability.reason ?? "Python kernel unavailable");
@@ -232,7 +269,9 @@ export class PythonKernel {
 		let runtime = availability.runtime;
 		if (!runtime) {
 			const { env: shellEnv } = (await Settings.init()).getShellConfig();
-			runtime = resolvePythonRuntime(options.cwd, filterEnv(shellEnv));
+			runtime = options.interpreter
+				? resolveExplicitPythonRuntime(options.interpreter, options.cwd, filterEnv(shellEnv))
+				: resolvePythonRuntime(options.cwd, filterEnv(shellEnv));
 		}
 		const spawnEnv: Record<string, string> = {};
 		for (const [key, value] of Object.entries(runtime.env)) {
@@ -700,10 +739,10 @@ function buildInitScript(cwd: string, env?: Record<string, string | undefined>):
 	const envPayload = Object.fromEntries(envEntries);
 	return [
 		"import os, sys",
-		`__prometheus_cwd = ${JSON.stringify(cwd)}`,
-		"os.chdir(__prometheus_cwd)",
-		`__prometheus_env = ${JSON.stringify(envPayload)}`,
-		"for __prometheus_key, __prometheus_val in __prometheus_env.items():\n    os.environ[__prometheus_key] = __prometheus_val",
-		"if __prometheus_cwd not in sys.path:\n    sys.path.insert(0, __prometheus_cwd)",
+		`__omp_cwd = ${JSON.stringify(cwd)}`,
+		"os.chdir(__omp_cwd)",
+		`__omp_env = ${JSON.stringify(envPayload)}`,
+		"for __omp_key, __omp_val in __omp_env.items():\n    os.environ[__omp_key] = __omp_val",
+		"if __omp_cwd not in sys.path:\n    sys.path.insert(0, __omp_cwd)",
 	].join("\n");
 }

package/src/eval/py/prelude.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 # Prometheus prelude helpers (loaded once into the runner namespace)
-if "__prometheus_prelude_loaded__" not in globals():
-    __prometheus_prelude_loaded__ = True
+if "__omp_prelude_loaded__" not in globals():
+    __omp_prelude_loaded__ = True
     from pathlib import Path
-    import os, json, math
+    import os, json, math, re
+    from urllib.parse import unquote
 
-    # __prometheus_display is injected by runner.py before the prelude executes; it
+    # __omp_display is injected by runner.py before the prelude executes; it
     # mirrors IPython's display() semantics with the same MIME bundle output.
-    _prometheus_display = __prometheus_display  # type: ignore[name-defined]
+    _omp_display = __omp_display  # type: ignore[name-defined]
 
     _PRESENTABLE_REPRS = (
         "_repr_mimebundle_",
@@ -23,20 +24,20 @@ if "__prometheus_prelude_loaded__" not in globals():
     def display(value):
         """Render a value. Falls back to a JSON+text/plain bundle for plain dict/list/tuple."""
         if any(hasattr(value, attr) for attr in _PRESENTABLE_REPRS):
-            _prometheus_display(value)
+            _omp_display(value)
             return
         if isinstance(value, (dict, list, tuple)):
             try:
                 bundle = {"application/json": value, "text/plain": repr(value)}
-                _prometheus_display(bundle, raw=True)
+                _omp_display(bundle, raw=True)
                 return
             except Exception:
                 pass
-        _prometheus_display(value)
+        _omp_display(value)
 
     def _emit_status(op: str, **data):
         """Emit structured status event for TUI rendering."""
-        _prometheus_display({"application/x-prometheus-status": {"op": op, **data}}, raw=True)
+        _omp_display({"application/x-prometheus-status": {"op": op, **data}}, raw=True)
 
 
     def env(key: str | None = None, value: str | None = None):
@@ -53,9 +54,47 @@ if "__prometheus_prelude_loaded__" not in globals():
         _emit_status("env", key=key, value=val, action="get")
         return val
 
-    def read(path: str | Path, *, offset: int = 1, limit: int | None = None) -> str:
+    _PROMETHEUS_INTERNAL_URL_RE = re.compile(r"^([a-z][a-z0-9+.-]*)://(.*)$", re.IGNORECASE)
+
+    def _resolve_omp_path(path: str | Path) -> Path:
+        """Map a helper path to a real filesystem Path.
+
+        A `scheme://…` whose scheme has an injected on-disk root (e.g.
+        `local://`, via PROMETHEUS_EVAL_LOCAL_ROOTS) is rewritten under that root so it
+        lands where `read local://…` resolves — not a literal `local:/`
+        directory under the cwd (which `Path("local://x")` collapses to). Plain
+        paths pass through unchanged; any other `scheme://` is rejected."""
+        if not isinstance(path, str):
+            return Path(path)
+        match = _PROMETHEUS_INTERNAL_URL_RE.match(path)
+        if not match:
+            return Path(path)
+        scheme = match.group(1).lower()
+        try:
+            roots = json.loads(os.environ.get("PROMETHEUS_EVAL_LOCAL_ROOTS") or "{}")
+        except (ValueError, TypeError):
+            roots = {}
+        root = roots.get(scheme) if isinstance(roots, dict) else None
+        if not root:
+            raise ValueError(f"Protocol paths are not supported by this helper: {path}")
+        relative = unquote(match.group(2).replace("\\", "/"))
+        # Mirror the host `path.resolve`/`resolveLocalUrlToPath`: normalize and
+        # make absolute WITHOUT realpath'ing symlinks (Path.resolve would turn
+        # /tmp into /private/tmp and diverge from the read-side resolution).
+        root_path = os.path.abspath(root)
+        if relative == "":
+            return Path(root_path)
+        rel_path = Path(relative)
+        if rel_path.is_absolute() or ".." in rel_path.parts:
+            raise ValueError(f"Unsafe {scheme}:// path (absolute or traversal): {path}")
+        resolved = os.path.abspath(os.path.join(root_path, relative))
+        if resolved != root_path and not resolved.startswith(root_path + os.sep):
+            raise ValueError(f"{scheme}:// path escapes its root: {path}")
+        return Path(resolved)
+
+    def read(path: str | Path, offset: int = 1, limit: int | None = None) -> str:
         """Read file contents. offset/limit are 1-indexed line numbers."""
-        p = Path(path)
+        p = _resolve_omp_path(path)
         data = p.read_text(encoding="utf-8")
         lines = data.splitlines(keepends=True)
         if offset > 1 or limit is not None:
@@ -69,7 +108,7 @@ if "__prometheus_prelude_loaded__" not in globals():
 
     def write(path: str | Path, content: str) -> Path:
         """Write file contents (create parents)."""
-        p = Path(path)
+        p = _resolve_omp_path(path)
         p.parent.mkdir(parents=True, exist_ok=True)
         p.write_text(content, encoding="utf-8")
         _emit_status("write", path=str(p), chars=len(content))
@@ -77,7 +116,7 @@ if "__prometheus_prelude_loaded__" not in globals():
 
     def append(path: str | Path, content: str) -> Path:
         """Append to file."""
-        p = Path(path)
+        p = _resolve_omp_path(path)
         p.parent.mkdir(parents=True, exist_ok=True)
         with p.open("a", encoding="utf-8") as f:
             f.write(content)
@@ -389,8 +428,8 @@ if "__prometheus_prelude_loaded__" not in globals():
         """POST one request to the host tool bridge and return its `value`."""
         import urllib.request, urllib.error
         base, token, session = _tool_proxy_from_env()
-        _run_id_getter = globals().get("__prometheus_current_run_id__")
-        _run_id = _run_id_getter() if callable(_run_id_getter) else globals().get("__prometheus_run_id__")
+        _run_id_getter = globals().get("__omp_current_run_id__")
+        _run_id = _run_id_getter() if callable(_run_id_getter) else globals().get("__omp_run_id__")
         payload = json.dumps(
             {"session": session, "run": _run_id, "name": name, "args": args}
         ).encode("utf-8")
@@ -463,8 +502,8 @@ if "__prometheus_prelude_loaded__" not in globals():
 
     tool = _ToolProxy()
 
-    def llm(prompt, *, model="default", system=None, schema=None):
-        """Oneshot, stateless LLM call against a model tier.
+    def completion(prompt, *, model="default", system=None, schema=None):
+        """Oneshot, stateless completion against a model tier.
 
         `model` selects a tier: "smol", "default" (the session's active model),
         or "slow". Pass `system` for a system prompt. Pass a JSON-Schema dict
@@ -472,6 +511,17 @@ if "__prometheus_prelude_loaded__" not in globals():
         returned instead of the completion text.
         """
         args = {"prompt": prompt, "model": model}
+        if system is not None:
+            args["system"] = system
+        if schema is not None:
+            args["schema"] = schema
+        res = _bridge_call("__completion__", args)
+        text = res.get("text") if isinstance(res, dict) else res
+        return json.loads(text) if schema is not None else text
+
+    def llm(prompt, *, model="default", system=None, schema=None):
+        """Oneshot, stateless LLM call against a model tier."""
+        args = {"prompt": prompt, "model": model}
         if system is not None:
             args["system"] = system
         if schema is not None:
@@ -480,21 +530,20 @@ if "__prometheus_prelude_loaded__" not in globals():
         text = res.get("text") if isinstance(res, dict) else res
         return json.loads(text) if schema is not None else text
 
-    def agent(prompt, *, agent_type="task", model=None, context=None, label=None, schema=None):
+    def agent(prompt, *, agent_type="task", model=None, label=None, schema=None):
         """Run a subagent and return its final output.
 
         `agent_type` selects the subagent definition (default "task"). Pass
-        `model` to override that agent's model, `context` for shared background,
-        `label` for the output artifact id, and `schema` to request structured
-        JSON output; when `schema` is supplied the parsed object is returned.
+        `model` to override that agent's model, `label` for the output artifact
+        id, and `schema` to request structured JSON output; when `schema` is
+        supplied the parsed object is returned. Share background by writing a
+        local:// file and referencing it in the prompt.
         """
         args = {"prompt": prompt}
         if agent_type is not None:
             args["agentType"] = agent_type
         if model is not None:
             args["model"] = model
-        if context is not None:
-            args["context"] = context
         if label is not None:
             args["label"] = label
         if schema is not None:
@@ -582,7 +631,7 @@ if "__prometheus_prelude_loaded__" not in globals():
 
     def phase(title):
         """Record the current readable phase and emit a status ``phase`` event."""
-        globals()["__prometheus_current_phase__"] = str(title)
+        globals()["__omp_current_phase__"] = str(title)
         _emit_status("phase", title=str(title))
         return None