@oh-my-pi/pi-coding-agent 15.10.4 → 15.10.5

package/src/edit/diff.ts

@@ -6,6 +6,7 @@
  */
 import * as Diff from "diff";
 import { resolveToCwd } from "../tools/path-utils";
+import { type BlockContextSource, findBlockContextLines } from "../utils/block-context";
 import { DEFAULT_FUZZY_THRESHOLD, EditMatchError, findMatch } from "./modes/replace";
 import { adjustIndentation, normalizeToLF, stripBom } from "./normalize";
 import { readEditFileText } from "./read-file";
@@ -54,11 +55,109 @@ function formatNumberedDiffLine(prefix: "+" | "-" | " ", lineNum: number, conten
 	return `${prefix}${lineNum}|${content}`;
 }
 
+type DiffSource = "old" | "new";
+
+interface ParsedNumberedDiffRow {
+	prefix: "+" | "-" | " ";
+	lineNumber: number;
+	content: string;
+	source: DiffSource;
+}
+
+function parseNumberedDiffRow(row: string): ParsedNumberedDiffRow | undefined {
+	const match = /^([+\- ])(\d+)\|(.*)$/s.exec(row);
+	if (!match) return undefined;
+	const prefix = match[1] as "+" | "-" | " ";
+	const lineNumber = Number.parseInt(match[2], 10);
+	if (!Number.isFinite(lineNumber)) return undefined;
+	return {
+		prefix,
+		lineNumber,
+		content: match[3] ?? "",
+		source: prefix === "+" ? "new" : "old",
+	};
+}
+
+function isDiffChangeRow(row: string | undefined): boolean {
+	return row !== undefined && (row.startsWith("+") || row.startsWith("-"));
+}
+
+function adjustedContextInsertIndex(rows: readonly string[], index: number): number {
+	let start = index;
+	while (start > 0 && isDiffChangeRow(rows[start - 1])) start--;
+	let end = index;
+	while (end < rows.length && isDiffChangeRow(rows[end])) end++;
+	return index > start && index < end ? end : index;
+}
+
+function insertBracketContextRows(
+	rows: string[],
+	source: DiffSource,
+	contextLines: ReadonlyMap<number, string>,
+	seenRows: Set<string>,
+): void {
+	const context = [...contextLines].sort(([left], [right]) => left - right);
+	for (const [lineNumber, text] of context) {
+		const row = formatNumberedDiffLine(" ", lineNumber, text);
+		if (seenRows.has(row)) continue;
+
+		let insertIndex = rows.length;
+		let previousSourceLine: number | undefined;
+		let nextSourceLine: number | undefined;
+		for (let i = 0; i < rows.length; i++) {
+			const parsed = parseNumberedDiffRow(rows[i]);
+			if (!parsed || parsed.source !== source) continue;
+			if (parsed.lineNumber < lineNumber) {
+				previousSourceLine = parsed.lineNumber;
+				continue;
+			}
+			nextSourceLine = parsed.lineNumber;
+			insertIndex = i;
+			break;
+		}
+
+		const chunk: string[] = [];
+		if (previousSourceLine !== undefined && lineNumber > previousSourceLine + 1) chunk.push("...");
+		chunk.push(row);
+		if (nextSourceLine !== undefined && nextSourceLine > lineNumber + 1) chunk.push("...");
+
+		const adjustedIndex = adjustedContextInsertIndex(rows, insertIndex);
+		rows.splice(adjustedIndex, 0, ...chunk);
+		for (const inserted of chunk) seenRows.add(inserted);
+	}
+}
+
+function addMatchingBracketContextRows(
+	rows: string[],
+	oldLines: readonly string[],
+	newLines: readonly string[],
+	source: BlockContextSource,
+): void {
+	const oldVisible: number[] = [];
+	const newVisible: number[] = [];
+	const seenRows = new Set(rows);
+
+	for (const row of rows) {
+		const parsed = parseNumberedDiffRow(row);
+		if (!parsed) continue;
+		if (parsed.source === "old") oldVisible.push(parsed.lineNumber);
+		else newVisible.push(parsed.lineNumber);
+	}
+
+	insertBracketContextRows(rows, "old", findBlockContextLines(oldLines, oldVisible, source), seenRows);
+	insertBracketContextRows(rows, "new", findBlockContextLines(newLines, newVisible, source), seenRows);
+}
+
 /**
  * Generate a unified diff string with line numbers and context.
  * Returns both the diff string and the first changed line number (in the new file).
  */
-export function generateDiffString(oldContent: string, newContent: string, contextLines = 2): DiffResult {
+export function generateDiffString(
+	oldContent: string,
+	newContent: string,
+	contextLines = 2,
+	source: BlockContextSource = {},
+): DiffResult {
 	const parts = Diff.diffLines(oldContent, newContent);
 	const output: string[] = [];
 
@@ -133,8 +232,10 @@ export function generateDiffString(oldContent: string, newContent: string, conte
 					newLineNum++;
 				}
 
+				// Mid-skip placeholder is omitted too: the jump between the trailing
+				// number of the leading context and the leading number of the
+				// trailing context conveys the gap, just like leading/trailing skips.
 				if (middleSkip > 0) {
-					output.push(formatNumberedDiffLine(" ", oldLineNum, "..."));
 					oldLineNum += middleSkip;
 					newLineNum += middleSkip;
 					for (const line of linesToShow.slice(firstChunkLength)) {
@@ -160,6 +261,8 @@ export function generateDiffString(oldContent: string, newContent: string, conte
 		}
 	}
 
+	addMatchingBracketContextRows(output, oldContent.split("\n"), newContent.split("\n"), source);
+
 	return { diff: output.join("\n"), firstChangedLine };
 }
 
@@ -187,7 +290,12 @@ export interface ReplaceResult {
  * Generate a unified diff string without file headers.
  * Returns both the diff string and the first changed line number (in the new file).
  */
-export function generateUnifiedDiffString(oldContent: string, newContent: string, contextLines = 3): DiffResult {
+export function generateUnifiedDiffString(
+	oldContent: string,
+	newContent: string,
+	contextLines = 3,
+	source: BlockContextSource = {},
+): DiffResult {
 	const patch = Diff.structuredPatch("", "", oldContent, newContent, "", "", { context: contextLines });
 	const output: string[] = [];
 	let firstChangedLine: number | undefined;
@@ -218,6 +326,8 @@ export function generateUnifiedDiffString(oldContent: string, newContent: string
 		}
 	}
 
+	addMatchingBracketContextRows(output, oldContent.split("\n"), newContent.split("\n"), source);
+
 	return { diff: output.join("\n"), firstChangedLine };
 }
 
@@ -805,7 +915,7 @@ export async function computeEditDiff(
 			};
 		}
 
-		return generateDiffString(normalizedContent, result.content);
+		return generateDiffString(normalizedContent, result.content, undefined, { path });
 	} catch (err) {
 		return { error: err instanceof Error ? err.message : String(err) };
 	}

package/src/edit/hashline/diff.ts

@@ -230,7 +230,7 @@ export async function computeHashlineSectionDiff(
 		if (options.streaming) return buildStreamingSectionDiff(section, normalized);
 		const result = applyPreviewEdits({ section, absolutePath, normalized, snapshots, options });
 		if (normalized === result.text) return { error: `No changes would be made to ${section.path}.` };
-		return generateDiffString(normalized, result.text);
+		return generateDiffString(normalized, result.text, undefined, { path: section.path });
 	} catch (err) {
 		return { error: err instanceof Error ? err.message : String(err) };
 	}

package/src/edit/hashline/execute.ts

@@ -97,7 +97,7 @@ function renderSection(result: PatchSectionResult, diagnostics: FileDiagnosticsR
 		};
 	}
 
-	const diff = generateDiffString(result.before, result.after);
+	const diff = generateDiffString(result.before, result.after, undefined, { path: result.path });
 	const preview = buildCompactDiffPreview(diff.diff);
 	const meta = outputMeta()
 		.diagnostics(diagnostics?.summary ?? "", diagnostics?.messages ?? [])

package/src/edit/modes/patch.ts

@@ -1571,7 +1571,9 @@ export async function computePatchDiff(
 		if (!normalizedOld && !normalizedNew) {
 			return { diff: "", firstChangedLine: undefined };
 		}
-		return generateUnifiedDiffString(normalizedOld, normalizedNew);
+		return generateUnifiedDiffString(normalizedOld, normalizedNew, undefined, {
+			path: result.change.newPath ?? result.change.path,
+		});
 	} catch (err) {
 		return { error: err instanceof Error ? err.message : String(err) };
 	}
@@ -1785,7 +1787,9 @@ export async function executePatchSingle(
 	if (result.change.type === "update" && result.change.oldContent && result.change.newContent) {
 		const normalizedOld = normalizeToLF(stripBom(result.change.oldContent).text);
 		const normalizedNew = normalizeToLF(stripBom(result.change.newContent).text);
-		diffResult = generateUnifiedDiffString(normalizedOld, normalizedNew);
+		diffResult = generateUnifiedDiffString(normalizedOld, normalizedNew, undefined, {
+			path: result.change.newPath ?? result.change.path,
+		});
 	}
 
 	let resultText: string;

package/src/edit/modes/replace.ts

@@ -1078,7 +1078,7 @@ export async function executeReplaceSingle(
 	);
 	invalidateFsScanAfterWrite(absolutePath);
 
-	const diffResult = generateDiffString(normalizedContent, result.content);
+	const diffResult = generateDiffString(normalizedContent, result.content, undefined, { path });
 	const resultText =
 		result.count > 1
 			? `Successfully replaced ${result.count} occurrences in ${path}.`

package/src/edit/renderer.ts

@@ -260,6 +260,7 @@ function renderEditHeader(
 	uiTheme: Theme,
 	options: {
 		icon: "pending" | "success" | "error";
+		iconOverride?: string;
 		spinnerFrame?: number;
 		op?: Operation;
 		rawPath: string;
@@ -279,8 +280,16 @@ function renderEditHeader(
 	const formatted = formatEditDescription(options.rawPath, uiTheme, descriptionOptions);
 	const suffix = `${options.statsSuffix ?? ""}${options.extraSuffix ?? ""}`;
 	const buildHeader = (description: string): string =>
-		renderStatusLine({ icon: options.icon, spinnerFrame: options.spinnerFrame, title, description }, uiTheme) +
-		suffix;
+		renderStatusLine(
+			{
+				icon: options.icon,
+				iconOverride: options.iconOverride,
+				spinnerFrame: options.spinnerFrame,
+				title,
+				description,
+			},
+			uiTheme,
+		) + suffix;
 
 	const header = buildHeader(formatted.description);
 	const overflow = visibleWidth(header) - editHeaderLabelBudget(width, uiTheme);
@@ -633,6 +642,7 @@ function renderSingleFileResult(
 		const statsSuffix = headerDiff ? formatDiffStatsSuffix(headerDiff, uiTheme) : "";
 		const header = renderEditHeader(width, uiTheme, {
 			icon: isError ? "error" : "success",
+			iconOverride: !isError && !options.isPartial ? uiTheme.styledSymbol("tool.edit", "accent") : undefined,
 			op,
 			rawPath,
 			rename,

package/src/eval/__tests__/helpers-local-roots.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "bun:test";
+import * as path from "node:path";
+import { TempDir } from "@oh-my-pi/pi-utils";
+import { createHelpers, type HelperContext } from "../js/shared/helpers";
+
+/**
+ * The eval helpers (`read`/`write`/`append`) must substitute injected on-disk
+ * roots for internal-URL schemes. Without it, `write("local://x.md")` hits a
+ * stdlib `path.resolve` that collapses `local://` to `local:/`, creating a junk
+ * `local:` directory under the cwd instead of landing where `read local://x.md`
+ * resolves. These lock the substitution contract and its guards.
+ */
+function makeCtx(cwd: string, roots: Record<string, string>): HelperContext {
+	return {
+		cwd: () => cwd,
+		env: new Map(),
+		localRoots: () => roots,
+		emitStatus: () => {},
+	};
+}
+
+describe("eval js helpers internal-url resolution", () => {
+	it("writes, reads, and appends local:// under the injected root", async () => {
+		using tmp = TempDir.createSync("@eval-helpers-local-");
+		const root = path.join(tmp.path(), "local");
+		const helpers = createHelpers(makeCtx(tmp.path(), { local: root }));
+
+		const written = await helpers.writeFile("local://notes/merge-map.md", "hello");
+		expect(written).toBe(path.join(root, "notes", "merge-map.md"));
+		expect(await Bun.file(written).text()).toBe("hello");
+		expect(await helpers.read("local://notes/merge-map.md")).toBe("hello");
+
+		await helpers.append("local://notes/merge-map.md", " world");
+		expect(await helpers.read("local://notes/merge-map.md")).toBe("hello world");
+
+		// Regression: no literal `local:` directory created under the cwd.
+		expect(await Bun.file(path.join(tmp.path(), "local:")).exists()).toBe(false);
+		expect(await Bun.file(path.join(tmp.path(), "local:", "notes", "merge-map.md")).exists()).toBe(false);
+	});
+
+	it("rejects traversal and schemes without an injected root", async () => {
+		using tmp = TempDir.createSync("@eval-helpers-guard-");
+		const helpers = createHelpers(makeCtx(tmp.path(), { local: path.join(tmp.path(), "local") }));
+
+		await expect(helpers.writeFile("local://../escape.md", "x")).rejects.toThrow(/traversal|escapes/i);
+		await expect(helpers.writeFile("memory://x.md", "x")).rejects.toThrow(/not supported/i);
+		await expect(helpers.read("https://example.com/page")).rejects.toThrow(/not supported/i);
+	});
+
+	it("leaves plain relative and absolute paths resolving against the cwd", async () => {
+		using tmp = TempDir.createSync("@eval-helpers-plain-");
+		const helpers = createHelpers(makeCtx(tmp.path(), {}));
+
+		const rel = await helpers.writeFile("foo/bar.txt", "bar");
+		expect(rel).toBe(path.join(tmp.path(), "foo", "bar.txt"));
+		expect(await helpers.read("foo/bar.txt")).toBe("bar");
+	});
+});

package/src/eval/backend.ts

@@ -1,3 +1,4 @@
+import { buildEvalUrlRoots, type LocalProtocolOptions } from "../internal-urls";
 import type { ToolSession } from "../tools";
 import type { EvalDisplayOutput, EvalLanguage, EvalStatusEvent } from "./types";
 
@@ -56,3 +57,17 @@ export interface ExecutorBackend {
 	/** Execute one cell. Caller invokes once per cell and aggregates results. */
 	execute(code: string, opts: ExecutorBackendExecOptions): Promise<ExecutorBackendResult>;
 }
+
+/**
+ * Resolve the on-disk roots that the eval helpers substitute for internal-URL
+ * schemes (currently `local://`). Prefers the session's own
+ * {@link LocalProtocolOptions} — the exact mapping `read local://…` uses — so an
+ * eval `write("local://x")` and a later `read local://x` agree on the location.
+ */
+export function resolveEvalUrlRoots(session: ToolSession): Record<string, string> {
+	const options: LocalProtocolOptions = session.localProtocolOptions ?? {
+		getArtifactsDir: () => session.getArtifactsDir?.() ?? null,
+		getSessionId: () => session.getSessionId?.() ?? null,
+	};
+	return buildEvalUrlRoots(options);
+}

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

@@ -68,6 +68,7 @@ export async function executeInVmContext(options: {
 	sessionId: string;
 	cwd: string;
 	session: ToolSession;
+	localRoots?: Record<string, string>;
 	reset?: boolean;
 	code: string;
 	filename: string;
@@ -100,7 +101,7 @@ export async function executeInVmContext(options: {
 	}
 	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);
@@ -132,6 +133,7 @@ async function runOnce(
 		sessionId: string;
 		cwd: string;
 		session: ToolSession;
+		localRoots?: Record<string, string>;
 		code: string;
 		filename: string;
 		runState: VmRunState;
@@ -171,7 +173,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 {

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 {
@@ -96,6 +98,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:";
@@ -30,6 +35,7 @@ export default {
 			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,6 +24,12 @@ 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;
 }
 
@@ -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,7 +82,7 @@ export function createHelpers(ctx: HelperContext): HelperBundle {
 			return filePath;
 		},
 		append: async (rawPath, content) => {
-			const target = resolvePath(ctx, rawPath);
+			const target = resolveHelperPath(ctx, rawPath, "write");
 			await Bun.write(
 				target,
 				`${await Bun.file(target)
@@ -202,19 +208,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()) {

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

@@ -42,6 +42,11 @@ export interface RuntimeOptions {
 	 * via `setRunScope()` instead.
 	 */
 	extraGlobals?: Record<string, unknown>;
+	/**
+	 * On-disk roots the helpers substitute for internal-URL schemes (e.g.
+	 * `{ local: "/…/artifacts/local" }`). Stable for the worker's lifetime.
+	 */
+	localRoots?: Record<string, string>;
 }
 
 // Strict base64: characters from the standard alphabet plus optional `=` padding, and a
@@ -126,15 +131,18 @@ export class JsRuntime {
 	#env: Map<string, string>;
 	#als = new AsyncLocalStorage<RunContext>();
 	#moduleLoader: LocalModuleLoader;
+	#localRoots: Record<string, string>;
 
 	constructor(opts: RuntimeOptions) {
 		this.#cwd = opts.initialCwd;
 		this.sessionId = opts.sessionId;
 		this.#env = new Map();
 		this.#moduleLoader = new LocalModuleLoader(this.sessionId);
+		this.#localRoots = opts.localRoots ?? {};
 		this.helpers = createHelpers({
 			cwd: () => this.#activeCwd(),
 			env: this.#env,
+			localRoots: () => this.#localRoots,
 			emitStatus: event => this.#activeHooks("emitStatus")?.onDisplay({ type: "status", event }),
 		});
 		this.#install(opts.extraGlobals);

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

@@ -71,6 +71,7 @@ export class WorkerCore {
 		this.#runtime = new JsRuntime({
 			initialCwd: snapshot.cwd,
 			sessionId: snapshot.sessionId,
+			localRoots: snapshot.localRoots,
 		});
 		return this.#runtime;
 	}

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/py/executor.ts

@@ -56,6 +56,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 `PI_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
@@ -275,6 +282,7 @@ const MANAGED_KERNEL_ENV_KEYS = [
 	"PI_TOOL_BRIDGE_URL",
 	"PI_TOOL_BRIDGE_TOKEN",
 	"PI_TOOL_BRIDGE_SESSION",
+	"PI_EVAL_LOCAL_ROOTS",
 ] as const;
 
 function buildKernelEnvPatch(options: {
@@ -282,13 +290,16 @@ function buildKernelEnvPatch(options: {
 	artifactsDir?: string;
 	bridgeSessionId?: string;
 	bridge?: { url: string; token: string };
+	localRoots?: Record<string, string>;
 }): KernelRuntimeEnv {
+	const localRoots = options.localRoots;
 	return {
 		PI_SESSION_FILE: options.sessionFile ?? null,
 		PI_ARTIFACTS_DIR: options.artifactsDir ?? null,
 		PI_TOOL_BRIDGE_URL: options.bridge?.url ?? null,
 		PI_TOOL_BRIDGE_TOKEN: options.bridge?.token ?? null,
 		PI_TOOL_BRIDGE_SESSION: options.bridge && options.bridgeSessionId ? options.bridgeSessionId : null,
+		PI_EVAL_LOCAL_ROOTS: localRoots && Object.keys(localRoots).length > 0 ? JSON.stringify(localRoots) : null,
 	};
 }
 
@@ -297,6 +308,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> = {};

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";
 
@@ -34,6 +39,7 @@ export default {
 			kernelMode,
 			sessionFile: opts.sessionFile,
 			artifactsDir: opts.session.getArtifactsDir?.() ?? undefined,
+			localRoots: resolveEvalUrlRoots(opts.session),
 			kernelOwnerId: opts.kernelOwnerId,
 			reset: opts.reset,
 			artifactPath: opts.artifactPath,