@prometheus-ai/agent 0.5.4 → 0.5.8

package/src/eval/completion-bridge.ts

@@ -0,0 +1,203 @@
+/**
+ * Host-side handler for the eval `completion()` helper.
+ *
+ * Both eval runtimes (JS worker + Python kernel) route helper→host calls
+ * through {@link callSessionTool}. Reserving the synthetic tool name
+ * {@link EVAL_COMPLETION_BRIDGE_NAME} lets a single host handler serve both
+ * transports without registering an agent-visible tool: cell code calls
+ * `completion(prompt, opts)`, the prelude forwards `{ prompt, model, system?, schema? }`
+ * through the bridge, and this module performs one stateless completion.
+ *
+ * The call is oneshot and toolless from the model's perspective — pure text
+ * in, text (or, with `schema`, a structured object) out.
+ */
+import { instrumentedCompleteSimple, resolveTelemetry } from "@prometheus-ai/agent-core";
+import { type Api, Effort, type Model, type Tool } from "@prometheus-ai/ai";
+import { getSupportedEfforts } from "@prometheus-ai/catalog/model-thinking";
+import { z } from "zod/v4";
+import { extractTextContent, extractToolCall, parseJsonPayload } from "../commit/utils";
+
+import {
+	expandRoleAlias,
+	formatModelString,
+	getModelMatchPreferences,
+	resolveModelFromString,
+} from "../config/model-resolver";
+import type { ToolSession } from "../tools";
+import { ToolError } from "../tools/tool-errors";
+import { withBridgeTimeoutPause } from "./bridge-timeout";
+import type { JsStatusEvent } from "./js/shared/types";
+
+/** Synthetic bridge name reserved for the `completion()` helper across both runtimes. */
+export const EVAL_COMPLETION_BRIDGE_NAME = "__completion__";
+
+/** Synthetic tool the model is forced to call when a `schema` is supplied. */
+const STRUCTURED_TOOL_NAME = "respond";
+
+type CompletionTier = "smol" | "default" | "slow";
+
+const TIER_TO_PATTERN: Record<CompletionTier, string> = {
+	smol: "pi/smol",
+	default: "pi/default",
+	slow: "pi/slow",
+};
+
+const completionArgsSchema = z.object({
+	prompt: z.string().min(1, "prompt must be a non-empty string"),
+	model: z.enum(["smol", "default", "slow"]).default("default"),
+	system: z.string().optional(),
+	schema: z.record(z.string(), z.unknown()).optional(),
+});
+
+export interface EvalCompletionBridgeOptions {
+	session: ToolSession;
+	signal?: AbortSignal;
+	emitStatus?: (event: JsStatusEvent) => void;
+}
+
+export interface EvalCompletionResult {
+	text: string;
+	details: { model: string; tier: CompletionTier; structured: boolean };
+}
+
+/**
+ * Resolve a tier to a concrete {@link Model}. `default` prefers the session's
+ * active model and falls back to the `pi/default` role; `smol`/`slow` resolve
+ * their respective role patterns. Returns `undefined` when nothing matches.
+ */
+function resolveTierModel(tier: CompletionTier, session: ToolSession): Model<Api> | undefined {
+	const modelRegistry = session.modelRegistry;
+	if (!modelRegistry) return undefined;
+	const available = modelRegistry.getAvailable();
+	if (available.length === 0) return undefined;
+
+	const matchPreferences = getModelMatchPreferences(session.settings);
+	const resolve = (pattern: string | undefined): Model<Api> | undefined => {
+		if (!pattern) return undefined;
+		const expanded = expandRoleAlias(pattern, session.settings);
+		return resolveModelFromString(expanded, available, matchPreferences, modelRegistry);
+	};
+
+	if (tier === "default") {
+		const activePattern = session.getActiveModelString?.() ?? session.getModelString?.();
+		return resolve(activePattern) ?? resolve(TIER_TO_PATTERN.default);
+	}
+	return resolve(TIER_TO_PATTERN[tier]);
+}
+
+/**
+ * Choose the reasoning effort for a tier. Only `slow` opts into thinking, and
+ * only on reasoning-capable models — guarding against `requireSupportedEffort`
+ * throwing downstream on models that cannot reason. Clamps to the highest
+ * supported effort so a reasoning model without `high` does not 400.
+ */
+function reasoningForTier(tier: CompletionTier, model: Model<Api>): Effort | undefined {
+	if (tier !== "slow" || !model.reasoning) return undefined;
+	const efforts = getSupportedEfforts(model);
+	if (efforts.length === 0) return undefined;
+	return efforts.includes(Effort.High) ? Effort.High : efforts[efforts.length - 1];
+}
+
+/**
+ * Run a single stateless completion on behalf of an eval cell's `completion()` call.
+ * Returns a `{ text, details }` value shaped like a {@link callSessionTool}
+ * result so the existing bridge transport carries it to either runtime.
+ */
+export async function runEvalCompletion(
+	args: unknown,
+	options: EvalCompletionBridgeOptions,
+): Promise<EvalCompletionResult> {
+	const parsed = completionArgsSchema.safeParse(args);
+	if (!parsed.success) {
+		const issue = parsed.error.issues[0];
+		const where = issue?.path.length ? `${issue.path.join(".")}: ` : "";
+		throw new ToolError(`completion() received invalid arguments: ${where}${issue?.message ?? "bad input"}`);
+	}
+	const { prompt, model: tier, system, schema } = parsed.data;
+
+	const model = resolveTierModel(tier, options.session);
+	if (!model) {
+		throw new ToolError(
+			`completion() could not resolve a model for the "${tier}" tier. Configure modelRoles.${tier === "default" ? "default" : tier} or ensure a provider is available.`,
+		);
+	}
+
+	const registry = options.session.modelRegistry;
+	const apiKey = await registry?.getApiKey(model);
+	if (!registry || !apiKey) {
+		throw new ToolError(
+			`completion() has no API key for ${formatModelString(model)}. Configure credentials for this provider or choose another tier.`,
+		);
+	}
+
+	const tools: Tool[] | undefined = schema
+		? [
+				{
+					name: STRUCTURED_TOOL_NAME,
+					description: "Return your answer by calling this tool with the requested structured fields.",
+					parameters: schema,
+					strict: false,
+				},
+			]
+		: undefined;
+
+	const telemetry = resolveTelemetry(options.session.getTelemetry?.(), options.session.getSessionId?.() ?? undefined);
+
+	// Some providers (notably openai-codex) require a non-empty `instructions`
+	// field on every Responses request and 400 with "Instructions are required"
+	// when it is missing. Fall back to a minimal default so `completion(prompt)` works
+	// without forcing every caller to pass a `system` prompt.
+	const systemPrompt = system ? [system] : ["You are a helpful assistant."];
+
+	// Suspend eval timeout accounting while the model request owns control. The
+	// timeout clock restarts once the bridge returns to the cell runtime.
+	const response = await withBridgeTimeoutPause(options.emitStatus, () =>
+		instrumentedCompleteSimple(
+			model,
+			{
+				systemPrompt,
+				messages: [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }],
+				tools,
+			},
+			{
+				apiKey: registry.resolver(model, options.session.getSessionId?.() ?? undefined),
+				signal: options.signal,
+				reasoning: reasoningForTier(tier, model),
+				toolChoice: schema ? { type: "tool", name: STRUCTURED_TOOL_NAME } : undefined,
+			},
+			{ telemetry, oneshotKind: "eval_completion" },
+		),
+	);
+
+	if (response.stopReason === "error") {
+		throw new ToolError(response.errorMessage ?? "completion() request failed.");
+	}
+	if (response.stopReason === "aborted") {
+		throw new ToolError("completion() request aborted.");
+	}
+
+	let resultText: string;
+	if (schema) {
+		const call = extractToolCall(response, STRUCTURED_TOOL_NAME);
+		let value: unknown;
+		if (call) {
+			value = call.arguments;
+		} else {
+			const text = extractTextContent(response);
+			if (!text) throw new ToolError("completion() returned no structured response.");
+			try {
+				value = parseJsonPayload(text);
+			} catch {
+				throw new ToolError("completion() did not return a structured response matching the schema.");
+			}
+		}
+		resultText = JSON.stringify(value);
+	} else {
+		resultText = extractTextContent(response);
+		if (!resultText) throw new ToolError("completion() returned no text output.");
+	}
+
+	options.emitStatus?.({ op: "completion", model: formatModelString(model), tier, chars: resultText.length });
+
+	return { text: resultText, details: { model: formatModelString(model), tier, structured: Boolean(schema) } };
+}

package/src/eval/idle-timeout.ts

@@ -3,11 +3,9 @@
  *
  * A cell's `timeout` bounds time while the Python kernel or JS VM is in control.
  * Host-side bridge calls can {@link pause} the watchdog so delegated
- * `agent()`/`parallel()`/`llm()` work is ignored completely, then {@link resume}
+ * `agent()`/`parallel()`/`completion()` work is ignored completely, then {@link resume}
  * starts a fresh timeout window once the runtime gets control back.
  *
- * The active timer self-reschedules instead of being torn down on every
- * activity event, so frequent activity costs one timestamp write per event.
  * Pause is reference-counted because `parallel()` can have multiple bridge calls
  * in flight at once.
  */
@@ -36,11 +34,6 @@ export class IdleTimeout {
 		return this.#idleMs;
 	}
 
-	/** Record runtime activity, pushing the active deadline forward by `idleMs`. */
-	bump(): void {
-		if (this.#settled || this.#pauseDepth > 0) return;
-		this.#deadlineMs = Date.now() + this.#idleMs;
-	}
 	/** Suspend timeout accounting while control is delegated to host-side work. */
 	pause(): void {
 		if (this.#settled) return;
@@ -86,8 +79,8 @@ export class IdleTimeout {
 		if (this.#settled || this.#pauseDepth > 0) return;
 		const remainingMs = this.#deadlineMs - Date.now();
 		if (remainingMs > 0) {
-			// A bump moved the deadline forward after this timer was armed; wait
-			// out the remaining window instead of firing early.
+			// The deadline moved forward (resume re-arming) after this timer was
+			// armed; wait out the remaining window instead of firing early.
 			this.#arm(remainingMs);
 			return;
 		}

package/src/eval/js/context-manager.ts

@@ -1,13 +1,10 @@
-import { isCompiledBinary, logger, Snowflake } from "@prometheus-ai/utils";
+import { logger, Snowflake, workerHostEntry } from "@prometheus-ai/utils";
 import type { ToolSession } from "../../tools";
 import { ToolAbortError, ToolError } from "../../tools/tool-errors";
 import { callSessionTool, type JsStatusEvent } from "./tool-bridge";
 import { WorkerCore } from "./worker-core";
-// Worker entry. See `tab-supervisor.ts` for the rationale behind the
-// literal-string + `new URL(import.meta.url)` hybrid: the literal is what
-// Bun's `--compile` bundler discovers, the `new URL` form is what makes dev
-// runs portable across cwds. The worker is registered as an additional
-// `--compile` entrypoint in `scripts/build-binary.ts`.
+// Coding-agent binary/bundle workers route through the CLI entrypoint with a
+// hidden argv mode, so compiled/npm builds only need one JavaScript entry.
 import type {
 	JsDisplayOutput,
 	RunErrorPayload,
@@ -30,6 +27,7 @@ interface WorkerHandle {
 	mode: "worker" | "inline";
 	send(msg: WorkerInbound): void;
 	onMessage(handler: (msg: WorkerOutbound) => void): () => void;
+	close(): Promise<boolean>;
 	terminate(): Promise<void>;
 }
 
@@ -52,14 +50,22 @@ interface JsSession {
 
 const sessions = new Map<string, JsSession>();
 const startingSessions = new Map<string, Promise<JsSession>>();
-const resettingSessions = new Set<string>();
-const READY_TIMEOUT_MS_DEFAULT = 5_000;
+const resettingSessions = new Map<string, Promise<void>>();
+// Worker startup (module-graph import + WorkerCore construction) is infrastructure
+// cost, not user compute. Floor it independently of Bun's 5s default per-test timeout
+// so a slow cold-start under load isn't aborted mid-init — terminating a still-
+// initializing Bun worker triggers the same kind of terminate-race that motivates
+// avoiding `vm.runInContext` (see shared/indirect-eval.ts), here surfacing as a
+// SIGILL/SIGSEGV. Callers that pass a larger per-cell budget still dominate.
+const WORKER_INIT_TIMEOUT_MS = 15_000;
+const WORKER_CLOSE_TIMEOUT_MS = 1_000;
 
 export async function executeInVmContext(options: {
 	sessionKey: string;
 	sessionId: string;
 	cwd: string;
 	session: ToolSession;
+	localRoots?: Record<string, string>;
 	reset?: boolean;
 	code: string;
 	filename: string;
@@ -67,21 +73,32 @@ export async function executeInVmContext(options: {
 	runState: VmRunState;
 }): Promise<{ value: unknown }> {
 	if (options.reset) {
-		if (resettingSessions.has(options.sessionKey)) {
-			throw new ToolError("JS context reset already in progress");
-		}
-		resettingSessions.add(options.sessionKey);
-		try {
-			await resetVmContext(options.sessionKey);
-		} finally {
-			resettingSessions.delete(options.sessionKey);
+		// Coalesce concurrent resets: an existing in-flight reset already
+		// produces a fresh context, so a follow-up `reset: true` cell should
+		// just wait for it rather than failing the user-visible call.
+		const inFlight = resettingSessions.get(options.sessionKey);
+		if (inFlight) await inFlight.catch(() => undefined);
+		else {
+			const resetPromise = resetVmContext(options.sessionKey);
+			resettingSessions.set(
+				options.sessionKey,
+				resetPromise.then(() => undefined),
+			);
+			try {
+				await resetPromise;
+			} finally {
+				resettingSessions.delete(options.sessionKey);
+			}
 		}
-	} else if (resettingSessions.has(options.sessionKey)) {
-		throw new ToolError("JS context reset in progress");
+	} else {
+		// Internal coordination: wait for any in-flight reset to settle and
+		// then run on the freshly-rebuilt context.
+		const inFlight = resettingSessions.get(options.sessionKey);
+		if (inFlight) await inFlight.catch(() => undefined);
 	}
 	const session = await acquireSession(
 		options.sessionKey,
-		{ cwd: options.cwd, sessionId: options.sessionId },
+		{ cwd: options.cwd, sessionId: options.sessionId, localRoots: options.localRoots },
 		options.timeoutMs,
 	);
 	return await runOnce(session, options);
@@ -91,7 +108,7 @@ export async function resetVmContext(sessionKey: string): Promise<void> {
 	const session = sessions.get(sessionKey) ?? (await startingSessions.get(sessionKey)?.catch(() => undefined));
 	if (!session) return;
 	sessions.delete(sessionKey);
-	await killSession(session, new ToolError("JS context reset"));
+	await killSession(session, new ToolError("JS context reset"), { force: false });
 }
 
 export async function disposeAllVmContexts(): Promise<void> {
@@ -104,7 +121,7 @@ export async function disposeAllVmContexts(): Promise<void> {
 		if (!all.includes(result.value)) all.push(result.value);
 	}
 	sessions.clear();
-	await Promise.all(all.map(session => killSession(session, new ToolError("JS context disposed"))));
+	await Promise.all(all.map(session => killSession(session, new ToolError("JS context disposed"), { force: false })));
 }
 
 async function runOnce(
@@ -113,6 +130,7 @@ async function runOnce(
 		sessionId: string;
 		cwd: string;
 		session: ToolSession;
+		localRoots?: Record<string, string>;
 		code: string;
 		filename: string;
 		runState: VmRunState;
@@ -137,7 +155,7 @@ async function runOnce(
 		// Cancel any in-flight tool calls first.
 		for (const ctrl of pending.toolCalls.values()) ctrl.abort(abortError);
 		// Hard-kill the worker — only way to interrupt synchronous user code.
-		void killSessionFor(session, abortError);
+		void killSessionFor(session, abortError, { force: true });
 	};
 
 	if (options.runState.signal?.aborted) {
@@ -152,7 +170,7 @@ async function runOnce(
 			runId,
 			code: options.code,
 			filename: options.filename,
-			snapshot: { cwd: options.cwd, sessionId: options.sessionId },
+			snapshot: { cwd: options.cwd, sessionId: options.sessionId, localRoots: options.localRoots },
 		});
 		return await promise;
 	} finally {
@@ -191,9 +209,9 @@ async function acquireSession(sessionKey: string, snapshot: SessionSnapshot, tim
 			handleSessionMessage(session, msg);
 		});
 		try {
-			// Cold-start can exceed 5s on slow hosts. Let the caller's per-cell timeout dominate so
-			// users can grant more headroom when they raise `timeout` on a cell.
-			const readyTimeoutMs = Math.max(READY_TIMEOUT_MS_DEFAULT, timeoutMs ?? 0);
+			// Init headroom is the fixed infrastructure floor; the caller's per-cell timeout
+			// dominates when larger so users can grant more by raising `timeout` on a cell.
+			const readyTimeoutMs = Math.max(WORKER_INIT_TIMEOUT_MS, timeoutMs ?? 0);
 			await raceWithTimeout(readyPromise, readyTimeoutMs, "Timed out initializing JS eval worker");
 			worker.send({ type: "init", snapshot });
 			sessions.set(sessionKey, session);
@@ -277,14 +295,14 @@ function settlePending(session: JsSession, msg: Extract<WorkerOutbound, { type:
 	pending.reject(errorFromPayload(msg.error));
 }
 
-async function killSessionFor(session: JsSession, error: Error): Promise<void> {
+async function killSessionFor(session: JsSession, error: Error, options: { force: boolean }): Promise<void> {
 	if (sessions.get(session.sessionKey) === session) {
 		sessions.delete(session.sessionKey);
 	}
-	await killSession(session, error);
+	await killSession(session, error, options);
 }
 
-async function killSession(session: JsSession, error: Error): Promise<void> {
+async function killSession(session: JsSession, error: Error, options: { force: boolean }): Promise<void> {
 	if (session.state === "dead") return;
 	session.state = "dead";
 	for (const pending of session.pending.values()) {
@@ -294,6 +312,11 @@ async function killSession(session: JsSession, error: Error): Promise<void> {
 		pending.reject(error);
 	}
 	session.pending.clear();
+	if (options.force) {
+		await session.worker.terminate().catch(() => undefined);
+		return;
+	}
+	if (await session.worker.close().catch(() => false)) return;
 	await session.worker.terminate().catch(() => undefined);
 }
 
@@ -358,8 +381,9 @@ async function raceWithTimeout<T>(promise: Promise<T>, timeoutMs: number, reason
 
 async function spawnJsWorker(): Promise<WorkerHandle> {
 	try {
-		const worker = isCompiledBinary()
-			? new Worker("./packages/coding-agent/src/eval/js/worker-entry.ts", { type: "module" })
+		const hostEntry = workerHostEntry();
+		const worker = hostEntry
+			? new Worker(hostEntry, { type: "module", argv: ["__prometheus_js_eval_worker"] })
 			: new Worker(new URL("./worker-entry.ts", import.meta.url).href, { type: "module" });
 		return wrapBunWorker(worker);
 	} catch (err) {
@@ -381,6 +405,38 @@ function wrapBunWorker(worker: Worker): WorkerHandle {
 			worker.addEventListener("message", wrap);
 			return () => worker.removeEventListener("message", wrap);
 		},
+		async close() {
+			const { promise: closed, resolve } = Promise.withResolvers<boolean>();
+			let settled = false;
+			let sawClosedAck = false;
+			let sawWorkerExit = false;
+			let timeout: NodeJS.Timeout | undefined;
+			let unsubscribe = (): void => {};
+			const finish = (value: boolean): void => {
+				if (settled) return;
+				settled = true;
+				if (timeout) clearTimeout(timeout);
+				unsubscribe();
+				worker.removeEventListener("close", onClose);
+				resolve(value);
+			};
+			const finishIfClosed = (): void => {
+				if (sawClosedAck && sawWorkerExit) finish(true);
+			};
+			const onClose = (): void => {
+				sawWorkerExit = true;
+				finishIfClosed();
+			};
+			unsubscribe = this.onMessage(msg => {
+				if (msg.type !== "closed") return;
+				sawClosedAck = true;
+				finishIfClosed();
+			});
+			worker.addEventListener("close", onClose);
+			timeout = setTimeout(() => finish(false), WORKER_CLOSE_TIMEOUT_MS);
+			worker.postMessage({ type: "close" } satisfies WorkerInbound);
+			return await closed;
+		},
 		async terminate() {
 			worker.terminate();
 		},
@@ -417,6 +473,27 @@ function spawnInlineWorker(): WorkerHandle {
 			hostListeners.add(handler);
 			return () => hostListeners.delete(handler);
 		},
+		async close() {
+			const { promise: closed, resolve } = Promise.withResolvers<boolean>();
+			let settled = false;
+			let timeout: NodeJS.Timeout | undefined;
+			let unsubscribe = (): void => {};
+			const finish = (value: boolean): void => {
+				if (settled) return;
+				settled = true;
+				if (timeout) clearTimeout(timeout);
+				unsubscribe();
+				hostListeners.clear();
+				workerListeners.clear();
+				resolve(value);
+			};
+			unsubscribe = this.onMessage(msg => {
+				if (msg.type === "closed") finish(true);
+			});
+			this.send({ type: "close" });
+			timeout = setTimeout(() => finish(false), WORKER_CLOSE_TIMEOUT_MS);
+			return await closed;
+		},
 		async terminate() {
 			hostListeners.clear();
 			workerListeners.clear();

package/src/eval/js/executor.ts

@@ -24,6 +24,8 @@ export interface JsExecutorOptions {
 	artifactPath?: string;
 	artifactId?: string;
 	session: ToolSession;
+	/** On-disk roots the helpers substitute for internal-URL schemes (e.g. `local://`). */
+	localRoots?: Record<string, string>;
 }
 
 export interface JsResult {
@@ -61,9 +63,13 @@ function isTimeoutReason(reason: unknown): boolean {
 }
 
 function formatJsTimeoutAnnotation(timeoutMs: number | undefined): string {
-	if (timeoutMs === undefined) return "Command timed out";
+	// Timeout cancellation force-kills the worker (the only way to interrupt
+	// synchronous user code), which discards the persistent VM state. Say so,
+	// or the model will keep referencing variables that no longer exist.
+	const reset = "The JS worker was force-killed and its VM state was reset; variables from earlier cells are gone.";
+	if (timeoutMs === undefined) return `Command timed out. ${reset}`;
 	const secs = Math.max(1, Math.round(timeoutMs / 1000));
-	return `Command timed out after ${secs} seconds`;
+	return `Command timed out after ${secs} seconds. ${reset}`;
 }
 
 export async function executeJs(code: string, options: JsExecutorOptions): Promise<JsResult> {
@@ -96,6 +102,7 @@ export async function executeJs(code: string, options: JsExecutorOptions): Promi
 			sessionId: options.sessionId,
 			cwd: options.cwd ?? options.session.cwd,
 			session: options.session,
+			localRoots: options.localRoots,
 			reset: options.reset,
 			code,
 			filename: `js-cell-${crypto.randomUUID()}.js`,

package/src/eval/js/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 { executeJs } from "./executor";
 
 const JS_SESSION_PREFIX = "js:";
@@ -25,11 +30,10 @@ export default {
 			sessionId: namespaceSessionId(opts.sessionId),
 			sessionFile: opts.sessionFile,
 			reset: opts.reset,
-			artifactPath: opts.artifactPath,
-			artifactId: opts.artifactId,
 			onChunk: opts.onChunk,
 			onStatus: opts.onStatus,
 			session: opts.session,
+			localRoots: resolveEvalUrlRoots(opts.session),
 		});
 		return {
 			output: result.output,

package/src/eval/js/shared/helpers.ts

@@ -24,11 +24,17 @@ export interface HelperOptions {
 export interface HelperContext {
 	cwd(): string;
 	env: Map<string, string>;
+	/**
+	 * On-disk roots for internal-URL schemes the helpers accept (e.g.
+	 * `{ local: "/…/artifacts/local" }`). A path like `local://x.md` is rewritten
+	 * to `<root>/x.md` before any filesystem op; unknown schemes are rejected.
+	 */
+	localRoots(): Record<string, string>;
 	emitStatus(event: JsStatusEvent): void;
 }
 
 /**
- * The set of functions exposed to user code via `globalThis.__prometheus_helpers__`. The JS
+ * The set of functions exposed to user code via `globalThis.__omp_helpers__`. The JS
  * prelude reads from this bag and attaches short aliases (`read`, `write`, `tree`, ...)
  * onto the global scope.
  */
@@ -66,7 +72,7 @@ export function createHelpers(ctx: HelperContext): HelperBundle {
 			if (!isWriteData(data)) {
 				throw new ToolError("write() expects string, Blob, ArrayBuffer, or TypedArray data");
 			}
-			const filePath = resolvePath(ctx, rawPath);
+			const filePath = resolveHelperPath(ctx, rawPath, "write");
 			if (typeof data === "string" || data instanceof Blob || data instanceof ArrayBuffer) {
 				await Bun.write(filePath, data);
 			} else {
@@ -76,13 +82,12 @@ export function createHelpers(ctx: HelperContext): HelperBundle {
 			return filePath;
 		},
 		append: async (rawPath, content) => {
-			const target = resolvePath(ctx, rawPath);
-			await Bun.write(
-				target,
-				`${await Bun.file(target)
-					.text()
-					.catch(() => "")}${content}`,
-			);
+			const target = resolveHelperPath(ctx, rawPath, "write");
+			// O(1) append; read-all+rewrite both raced concurrent writers and went
+			// quadratic when called in a loop. Bun.write creates parent dirs, so
+			// keep that behavior for the append path too.
+			await fs.promises.mkdir(path.dirname(target), { recursive: true });
+			await fs.promises.appendFile(target, content, "utf-8");
 			ctx.emitStatus({
 				op: "append",
 				path: target,
@@ -202,19 +207,60 @@ function getMergedEnv(ctx: HelperContext): Record<string, string> {
 	return merged;
 }
 
+const INTERNAL_URL_RE = /^([a-z][a-z0-9+.-]*):\/\/(.*)$/i;
+
 function resolvePath(ctx: HelperContext, value: string): string {
 	if (path.isAbsolute(value)) return path.normalize(value);
 	return path.resolve(ctx.cwd(), value);
 }
 
+/**
+ * Map a raw helper path to an absolute filesystem path. Plain paths resolve
+ * against the cwd; an internal-URL whose scheme has an injected root (e.g.
+ * `local://`) is rewritten under that root; any other `scheme://` is rejected
+ * so we never silently create a literal `scheme:/` directory.
+ */
+function resolveHelperPath(ctx: HelperContext, rawPath: string, op: "read" | "write"): string {
+	const match = INTERNAL_URL_RE.exec(rawPath);
+	if (!match) return resolvePath(ctx, rawPath);
+	const scheme = match[1].toLowerCase();
+	const root = ctx.localRoots()[scheme];
+	if (!root) {
+		throw new ToolError(`Protocol paths are not supported by ${op}(): ${rawPath}`);
+	}
+	return resolveUnderRoot(scheme, root, match[2], rawPath);
+}
+
+/** Resolve an internal-URL relative path under its root, mirroring the host
+ *  local-protocol handler: decode, reject absolute/traversal, confine to root. */
+function resolveUnderRoot(scheme: string, root: string, rawRelative: string, rawPath: string): string {
+	let relative: string;
+	try {
+		relative = decodeURIComponent(rawRelative.replaceAll("\\", "/"));
+	} catch {
+		throw new ToolError(`Invalid URL encoding in ${scheme}:// path: ${rawPath}`);
+	}
+	const rootPath = path.resolve(root);
+	if (relative === "") return rootPath;
+	if (path.isAbsolute(relative)) {
+		throw new ToolError(`Absolute paths are not allowed in ${scheme}:// URLs: ${rawPath}`);
+	}
+	const normalized = path.normalize(relative);
+	if (normalized.startsWith("..") || normalized.includes("/../") || normalized.includes("/..")) {
+		throw new ToolError(`Path traversal (..) is not allowed in ${scheme}:// URLs: ${rawPath}`);
+	}
+	const resolved = path.resolve(rootPath, normalized);
+	if (resolved !== rootPath && !resolved.startsWith(`${rootPath}${path.sep}`)) {
+		throw new ToolError(`${scheme}:// path escapes its root: ${rawPath}`);
+	}
+	return resolved;
+}
+
 async function resolveRegularFile(
 	ctx: HelperContext,
 	rawPath: string,
 ): Promise<{ filePath: string; file: Bun.BunFile; size: number }> {
-	if (/^[a-z][a-z0-9+.-]*:\/\//i.test(rawPath)) {
-		throw new ToolError(`Protocol paths are not supported by read(): ${rawPath}`);
-	}
-	const filePath = resolvePath(ctx, rawPath);
+	const filePath = resolveHelperPath(ctx, rawPath, "read");
 	const file = Bun.file(filePath);
 	const stat = await file.stat();
 	if (stat.isDirectory()) {