@oh-my-pi-zen/pi-coding-agent 16.3.6-zen.1

package/src/internal-urls/__tests__/ssh-protocol.test.ts

@@ -0,0 +1,331 @@
+import { afterEach, describe, expect, it, vi } from "bun:test";
+import * as capability from "../../capability";
+import type { SSHHost } from "../../capability/ssh";
+import type { CapabilityResult, SourceMeta } from "../../capability/types";
+import * as fileTransfer from "../../ssh/file-transfer";
+import { parseInternalUrl } from "../parse";
+import { SshProtocolHandler } from "../ssh-protocol";
+
+const SOURCE: SourceMeta = {
+	provider: "ssh-json",
+	providerName: "SSH Config",
+	path: "/test/ssh.json",
+	level: "user",
+};
+
+function mockHosts(hosts: SSHHost[] = []): void {
+	const result: CapabilityResult<SSHHost> = {
+		items: hosts,
+		all: hosts,
+		warnings: [],
+		providers: hosts.length ? ["ssh-json"] : [],
+	};
+	vi.spyOn(capability, "loadCapability").mockResolvedValue(result as CapabilityResult<unknown>);
+}
+
+function mockReadBytes(text: string, truncated = false) {
+	vi.spyOn(fileTransfer, "statRemotePath").mockResolvedValue("file");
+	return vi
+		.spyOn(fileTransfer, "readRemoteFile")
+		.mockResolvedValue({ bytes: new TextEncoder().encode(text), truncated });
+}
+
+describe("SshProtocolHandler", () => {
+	const handler = new SshProtocolHandler();
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("resolves a remote text file byte-exact with no sourcePath", async () => {
+		mockHosts();
+		mockReadBytes("127.0.0.1 a\n");
+		const resource = await handler.resolve(parseInternalUrl("ssh://icaro/etc/hosts"));
+		expect(resource.content).toBe("127.0.0.1 a\n");
+		expect(resource.contentType).toBe("text/plain");
+		// No sourcePath keeps search on the virtual-resource path (stays `ssh://…`).
+		expect(resource.sourcePath).toBeUndefined();
+	});
+
+	it("derives contentType from the file extension", async () => {
+		mockHosts();
+		mockReadBytes("# title\n");
+		expect((await handler.resolve(parseInternalUrl("ssh://icaro/tmp/readme.md"))).contentType).toBe("text/markdown");
+		mockReadBytes("{}\n");
+		expect((await handler.resolve(parseInternalUrl("ssh://icaro/tmp/data.json"))).contentType).toBe(
+			"application/json",
+		);
+	});
+
+	it("rejects user/port overrides on a configured host", async () => {
+		mockHosts([{ _source: SOURCE, name: "icaro", host: "10.0.0.1" }]);
+		mockReadBytes("x");
+		await expect(handler.resolve(parseInternalUrl("ssh://user@icaro:22/x"))).rejects.toThrow(/user\/port overrides/);
+	});
+
+	it("treats an unconfigured authority as an opaque OpenSSH destination", async () => {
+		mockHosts();
+		const spy = mockReadBytes("data\n");
+		await handler.resolve(parseInternalUrl("ssh://bob@h1:2222/x"));
+		expect(spy.mock.calls[0]?.[0]).toMatchObject({ name: "bob@h1:2222", host: "h1", username: "bob", port: 2222 });
+	});
+
+	it("matches a configured reserved-char host via its percent-encoded name", async () => {
+		mockHosts([{ _source: SOURCE, name: "alice@prod", host: "10.0.0.9", username: "alice" }]);
+		const spy = mockReadBytes("ok\n");
+		await handler.resolve(parseInternalUrl("ssh://alice%40prod/etc/hostname"));
+		// Encoded `%40` authority decodes to the alias name → uses the alias's host/user.
+		expect(spy.mock.calls[0]?.[0]).toMatchObject({ name: "alice@prod", host: "10.0.0.9", username: "alice" });
+	});
+
+	it("treats a literal user@host as opaque, not the encoded alias", async () => {
+		mockHosts([{ _source: SOURCE, name: "alice@prod", host: "10.0.0.9", username: "alice" }]);
+		const spy = mockReadBytes("ok\n");
+		// Literal `@`: username=alice, bare host=prod (unconfigured) → opaque, NOT the alias's 10.0.0.9.
+		await handler.resolve(parseInternalUrl("ssh://alice@prod/etc/hostname"));
+		expect(spy.mock.calls[0]?.[0]).toMatchObject({ name: "alice@prod", host: "prod", username: "alice" });
+	});
+
+	it("lists the remote root directory for ssh://host/", async () => {
+		mockHosts();
+		vi.spyOn(fileTransfer, "readRemoteFile").mockRejectedValue(new Error("Is a directory"));
+		vi.spyOn(fileTransfer, "statRemotePath").mockResolvedValue("directory");
+		const listSpy = vi.spyOn(fileTransfer, "listRemoteDir").mockResolvedValue([{ name: "etc", isDirectory: true }]);
+		const res = await handler.resolve(parseInternalUrl("ssh://icaro/"));
+		expect(res.isDirectory).toBe(true);
+		expect(res.content).toBe("etc/");
+		expect(listSpy.mock.calls[0]?.[1]).toBe("/");
+	});
+
+	it("rejects a binary / non-UTF-8 file instead of returning a resource", async () => {
+		mockHosts();
+		vi.spyOn(fileTransfer, "statRemotePath").mockResolvedValue("file");
+		vi.spyOn(fileTransfer, "readRemoteFile").mockResolvedValue({
+			bytes: new Uint8Array([0x7f, 0x45, 0x4c, 0x46, 0x00, 0x01]),
+			truncated: false,
+		});
+		await expect(handler.resolve(parseInternalUrl("ssh://icaro/bin/true"))).rejects.toThrow(/binary or non-UTF-8/);
+	});
+
+	it("rejects a file whose first invalid byte falls past the old 8 KiB sniff window", async () => {
+		mockHosts();
+		vi.spyOn(fileTransfer, "statRemotePath").mockResolvedValue("file");
+		const bytes = new Uint8Array(9001);
+		bytes.fill(0x61); // 9000 'a' bytes — valid UTF-8 within the former 8 KiB window
+		bytes[9000] = 0xff; // lone invalid UTF-8 byte the old prefix sniff never inspected
+		vi.spyOn(fileTransfer, "readRemoteFile").mockResolvedValue({ bytes, truncated: false });
+		await expect(handler.resolve(parseInternalUrl("ssh://icaro/var/log/app.log"))).rejects.toThrow(
+			/binary or non-UTF-8/,
+		);
+	});
+
+	it("rejects a file that exceeds the size cap", async () => {
+		mockHosts();
+		vi.spyOn(fileTransfer, "statRemotePath").mockResolvedValue("file");
+		vi.spyOn(fileTransfer, "readRemoteFile").mockResolvedValue({
+			bytes: new TextEncoder().encode("partial"),
+			truncated: true,
+		});
+		await expect(handler.resolve(parseInternalUrl("ssh://icaro/big.log"))).rejects.toThrow(/exceeds the 1 MiB limit/);
+	});
+
+	it("writes content byte-exact through writeRemoteFile", async () => {
+		mockHosts();
+		const spy = vi.spyOn(fileTransfer, "writeRemoteFile").mockResolvedValue(undefined);
+		await handler.write(parseInternalUrl("ssh://icaro/tmp/x"), "hi\n\t!\n");
+		expect(spy).toHaveBeenCalledTimes(1);
+		expect(spy.mock.calls[0]?.[2]).toEqual(new TextEncoder().encode("hi\n\t!\n"));
+	});
+
+	it("lists a remote directory when the path is not a readable file", async () => {
+		mockHosts();
+		vi.spyOn(fileTransfer, "readRemoteFile").mockRejectedValue(
+			new Error("head: error reading '/etc': Is a directory"),
+		);
+		vi.spyOn(fileTransfer, "statRemotePath").mockResolvedValue("directory");
+		const listSpy = vi.spyOn(fileTransfer, "listRemoteDir").mockResolvedValue([
+			{ name: "conf.d", isDirectory: true },
+			{ name: "hosts", isDirectory: false },
+		]);
+		const res = await handler.resolve(parseInternalUrl("ssh://icaro/etc"));
+		expect(res.isDirectory).toBe(true);
+		expect(res.immutable).toBe(true);
+		expect(res.sourcePath).toBeUndefined();
+		expect(res.content).toBe("conf.d/\nhosts");
+		// read fail → stat → list must target the same remote path, not a peeled/normalized variant.
+		expect(listSpy.mock.calls[0]?.[1]).toBe("/etc");
+	});
+
+	it("renders an empty remote directory", async () => {
+		mockHosts();
+		vi.spyOn(fileTransfer, "readRemoteFile").mockRejectedValue(new Error("Is a directory"));
+		vi.spyOn(fileTransfer, "statRemotePath").mockResolvedValue("directory");
+		vi.spyOn(fileTransfer, "listRemoteDir").mockResolvedValue([]);
+		const res = await handler.resolve(parseInternalUrl("ssh://icaro/empty"));
+		expect(res.content).toBe("(empty directory)");
+		expect(res.isDirectory).toBe(true);
+	});
+
+	it("rethrows the original read error when the path is missing, not a directory", async () => {
+		mockHosts();
+		vi.spyOn(fileTransfer, "readRemoteFile").mockRejectedValue(
+			new Error("head: cannot open '/nope': No such file or directory"),
+		);
+		vi.spyOn(fileTransfer, "statRemotePath").mockResolvedValue("missing");
+		await expect(handler.resolve(parseInternalUrl("ssh://icaro/nope"))).rejects.toThrow(/No such file or directory/);
+	});
+
+	it("rejects a remote special file (FIFO/device) without reading it", async () => {
+		mockHosts();
+		vi.spyOn(fileTransfer, "statRemotePath").mockResolvedValue("other");
+		const readSpy = vi
+			.spyOn(fileTransfer, "readRemoteFile")
+			.mockResolvedValue({ bytes: new Uint8Array(), truncated: false });
+		await expect(handler.resolve(parseInternalUrl("ssh://icaro/dev/zero"))).rejects.toThrow(/not a regular file/);
+		expect(readSpy).not.toHaveBeenCalled();
+	});
+
+	it("autocompletes configured hosts and threads cwd to the capability load", async () => {
+		const spy = vi.spyOn(capability, "loadCapability").mockResolvedValue({
+			items: [
+				{ name: "web1", host: "10.0.0.1", username: "deploy", _source: SOURCE },
+				{ name: "db", host: "db.internal", _source: SOURCE },
+			],
+			all: [],
+			warnings: [],
+			providers: [],
+		} as CapabilityResult<SSHHost>);
+		const candidates = await handler.complete("", { cwd: "/tmp/proj" });
+		expect(candidates.map(c => c.value).sort()).toEqual(["db", "web1"]);
+		expect(candidates.find(c => c.value === "web1")?.description).toContain("deploy@10.0.0.1");
+		expect(spy.mock.calls[0]?.[1]).toEqual({ cwd: "/tmp/proj" });
+	});
+
+	it("lists configured hosts for a bare ssh:// read using the context cwd", async () => {
+		const spy = vi.spyOn(capability, "loadCapability").mockResolvedValue({
+			items: [{ name: "web1", host: "10.0.0.1", _source: SOURCE }],
+			all: [],
+			warnings: [],
+			providers: [],
+		} as CapabilityResult<SSHHost>);
+		const res = await handler.resolve(parseInternalUrl("ssh://"), { cwd: "/tmp/proj" });
+		expect(res.immutable).toBe(true);
+		expect(res.sourcePath).toBeUndefined();
+		expect(res.content).toContain("[web1](ssh://web1/)");
+		expect(spy.mock.calls[0]?.[1]).toEqual({ cwd: "/tmp/proj" });
+	});
+
+	it("shows a helpful message when no hosts are configured", async () => {
+		mockHosts([]);
+		const res = await handler.resolve(parseInternalUrl("ssh://"));
+		expect(res.content).toMatch(/No SSH hosts are configured/);
+	});
+
+	it("rejects a host-less ssh:// URL that carries a path", async () => {
+		mockHosts();
+		await expect(handler.resolve(parseInternalUrl("ssh:///etc/hosts"))).rejects.toThrow(/requires a host/);
+	});
+
+	it("rejects an explicit ssh:// port 0 before connecting", async () => {
+		mockHosts();
+		await expect(handler.resolve(parseInternalUrl("ssh://icaro:0/etc/hostname"))).rejects.toThrow(/port 0/);
+	});
+
+	it("strips IPv6 URL brackets before building the ssh target", async () => {
+		mockHosts();
+		const spy = mockReadBytes("ok\n");
+		await handler.resolve(parseInternalUrl("ssh://[::1]/etc/hostname"));
+		expect(spy.mock.calls[0]?.[0]?.host).toBe("::1");
+	});
+
+	it("matches a configured bracketed-colon alias instead of stripping it as IPv6", async () => {
+		mockHosts([{ name: "[prod:2222]", host: "prod.internal", _source: SOURCE }]);
+		const spy = mockReadBytes("ok\n");
+		await handler.resolve(parseInternalUrl("ssh://%5Bprod%3A2222%5D/etc/hostname"));
+		expect(spy.mock.calls[0]?.[0]?.host).toBe("prod.internal");
+	});
+
+	it("rejects a malformed or out-of-range ssh:// port before connecting", async () => {
+		mockHosts();
+		await expect(handler.resolve(parseInternalUrl("ssh://prod:abc/etc"))).rejects.toThrow(/invalid host or port/);
+		await expect(handler.resolve(parseInternalUrl("ssh://prod:65536/etc"))).rejects.toThrow(/invalid host or port/);
+	});
+
+	it("rejects an empty ssh:// port before connecting", async () => {
+		mockHosts();
+		await expect(handler.resolve(parseInternalUrl("ssh://prod:/etc/hosts"))).rejects.toThrow(/empty port/);
+		await expect(handler.resolve(parseInternalUrl("ssh://user@prod:/etc/hosts"))).rejects.toThrow(/empty port/);
+		await expect(handler.resolve(parseInternalUrl("ssh://[::1]:/etc/hosts"))).rejects.toThrow(/empty port/);
+		await expect(handler.resolve(parseInternalUrl("ssh://prod%2Dblue:/etc/hosts"))).rejects.toThrow(/empty port/);
+		await expect(handler.resolve(parseInternalUrl("ssh://u%2Dname@prod:/etc/hosts"))).rejects.toThrow(/empty port/);
+	});
+
+	it("rejects ssh:// password and empty-username userinfo before matching a host", async () => {
+		mockHosts([{ name: "prod", host: "10.0.0.5", _source: SOURCE }]);
+		await expect(handler.resolve(parseInternalUrl("ssh://user:pass@prod/etc/hosts"))).rejects.toThrow(/password/);
+		await expect(handler.resolve(parseInternalUrl("ssh://:pw@prod/etc/hosts"))).rejects.toThrow(/password/);
+		await expect(handler.resolve(parseInternalUrl("ssh://@prod/etc/hosts"))).rejects.toThrow(/empty username/);
+		await expect(handler.resolve(parseInternalUrl("ssh://@prod:22/etc/hosts"))).rejects.toThrow(/empty username/);
+		await expect(handler.resolve(parseInternalUrl("ssh://user:@prod/etc/hosts"))).rejects.toThrow(
+			/malformed authority/,
+		);
+		await expect(handler.resolve(parseInternalUrl("ssh://:@prod/etc/hosts"))).rejects.toThrow(/malformed authority/);
+		await expect(handler.resolve(parseInternalUrl("ssh://prod%ZZ/etc/hosts"))).rejects.toThrow(/percent-escape/i);
+		await expect(handler.resolve(parseInternalUrl("ssh://user%ZZ@prod/etc/hosts"))).rejects.toThrow(
+			/percent-escape/i,
+		);
+	});
+
+	it("matches a configured colon-suffixed alias via %3A instead of treating it as an empty port", async () => {
+		mockHosts([{ name: "prod:", host: "prod.internal", _source: SOURCE }]);
+		const spy = mockReadBytes("ok\n");
+		await handler.resolve(parseInternalUrl("ssh://prod%3A/etc/hostname"));
+		expect(spy.mock.calls[0]?.[0]?.host).toBe("prod.internal");
+	});
+
+	it("decodes the percent-encoded username and host of an override target", async () => {
+		mockHosts();
+		const spy = mockReadBytes("ok\n");
+		await handler.resolve(parseInternalUrl("ssh://user%40corp@prod%2Dblue/etc/hostname"));
+		const target = spy.mock.calls[0]?.[0];
+		expect(target?.username).toBe("user@corp");
+		expect(target?.host).toBe("prod-blue");
+		expect(target?.name).toBe("user@corp@prod-blue");
+	});
+
+	it("rejects a user/port override on an encoded configured alias", async () => {
+		mockHosts([{ name: "alice@prod", host: "alice.prod.internal", _source: SOURCE }]);
+		await expect(handler.resolve(parseInternalUrl("ssh://bob@alice%40prod/tmp/x"))).rejects.toThrow(
+			/user\/port overrides/,
+		);
+		await expect(handler.resolve(parseInternalUrl("ssh://alice%40prod:22/tmp/x"))).rejects.toThrow(
+			/user\/port overrides/,
+		);
+	});
+
+	it("skips the remote directory listing when skipDirectoryListing is set", async () => {
+		mockHosts();
+		vi.spyOn(fileTransfer, "readRemoteFile").mockRejectedValue(new Error("Is a directory"));
+		vi.spyOn(fileTransfer, "statRemotePath").mockResolvedValue("directory");
+		const listSpy = vi.spyOn(fileTransfer, "listRemoteDir").mockResolvedValue([]);
+
+		const res = await handler.resolve(parseInternalUrl("ssh://h/etc"), { skipDirectoryListing: true });
+		expect(res.isDirectory).toBe(true);
+		expect(listSpy).not.toHaveBeenCalled();
+
+		await handler.resolve(parseInternalUrl("ssh://h/etc"));
+		expect(listSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it("rejects ssh:// URL queries and fragments instead of operating on the truncated path", async () => {
+		mockHosts();
+		// `?`/`#` are URL delimiters, so the query/fragment is stripped from the path;
+		// `ssh://h/tmp/a?draft` would otherwise read/write `/tmp/a`, the wrong file.
+		await expect(handler.resolve(parseInternalUrl("ssh://h/tmp/a?draft"))).rejects.toThrow(/quer/i);
+		await expect(handler.resolve(parseInternalUrl("ssh://h/tmp/a#draft"))).rejects.toThrow(/fragment/i);
+		// A literal `?` in a filename must be percent-encoded (`%3F`) and is then accepted.
+		const spy = mockReadBytes("ok\n");
+		await handler.resolve(parseInternalUrl("ssh://h/tmp/a%3Fdraft"));
+		expect(spy.mock.calls[0]?.[1]).toBe("/tmp/a?draft");
+	});
+});

package/src/internal-urls/agent-protocol.ts

@@ -0,0 +1,146 @@
+/**
+ * Protocol handler for agent:// URLs.
+ *
+ * Resolves agent output IDs against the artifacts directories of every active
+ * session. Parents and subagents share outputs via this registry: a subagent
+ * can read its parent's output IDs because both sessions are registered in
+ * the shared context.
+ *
+ * URL forms:
+ * - agent://<id> - Full output content
+ * - agent://<id>/<path> - JSON extraction via path form
+ * - agent://<id>?q=<query> - JSON extraction via query form
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi-zen/pi-utils";
+import { applyQuery, pathToQuery } from "./json-query";
+import { artifactsDirsFromRegistry } from "./registry-helpers";
+import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+
+/**
+ * Handler for agent:// URLs.
+ *
+ * Resolves output IDs like "reviewer_0" to their artifact files,
+ * with optional JSON extraction.
+ */
+export class AgentProtocolHandler implements ProtocolHandler {
+	readonly scheme = "agent";
+	readonly immutable = true;
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const outputId = url.rawHost || url.hostname;
+		if (!outputId) {
+			throw new Error("agent:// URL requires an output ID: agent://<id>");
+		}
+
+		const urlPath = url.pathname;
+		const queryParam = url.searchParams.get("q");
+		const hasPathExtraction = urlPath && urlPath !== "/" && urlPath !== "";
+		const hasQueryExtraction = queryParam !== null && queryParam !== "";
+
+		if (hasPathExtraction && hasQueryExtraction) {
+			throw new Error("agent:// URL cannot combine path extraction with ?q=");
+		}
+
+		const dirs = artifactsDirsFromRegistry();
+
+		if (dirs.length === 0) {
+			throw new Error("No session - agent outputs unavailable");
+		}
+
+		let foundPath: string | undefined;
+		let anyDirExists = false;
+		const availableIds = new Set<string>();
+
+		for (const dir of dirs) {
+			try {
+				await fs.stat(dir);
+				anyDirExists = true;
+			} catch (err) {
+				if (isEnoent(err)) continue;
+				throw err;
+			}
+			const candidate = path.join(dir, `${outputId}.md`);
+			try {
+				await fs.stat(candidate);
+				foundPath = candidate;
+				break;
+			} catch (err) {
+				if (!isEnoent(err)) throw err;
+				try {
+					const files = await fs.readdir(dir);
+					for (const f of files) {
+						if (f.endsWith(".md")) availableIds.add(f.replace(/\.md$/, ""));
+					}
+				} catch {
+					// Listing failures are non-fatal; continue searching.
+				}
+			}
+		}
+
+		if (!anyDirExists) {
+			throw new Error("No artifacts directory found");
+		}
+
+		if (!foundPath) {
+			const availableStr = availableIds.size > 0 ? [...availableIds].join(", ") : "none";
+			throw new Error(`Not found: ${outputId}\nAvailable: ${availableStr}`);
+		}
+
+		const rawContent = await Bun.file(foundPath).text();
+		const notes: string[] = [];
+		let content = rawContent;
+		let contentType: InternalResource["contentType"] = "text/markdown";
+
+		if (hasPathExtraction || hasQueryExtraction) {
+			let jsonValue: unknown;
+			try {
+				jsonValue = JSON.parse(rawContent);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new Error(`Output ${outputId} is not valid JSON: ${message}`);
+			}
+
+			const query = hasPathExtraction ? pathToQuery(urlPath) : queryParam!;
+			if (query) {
+				const extracted = applyQuery(jsonValue, query);
+				try {
+					content = JSON.stringify(extracted, null, 2) ?? "null";
+				} catch {
+					content = String(extracted);
+				}
+				notes.push(`Extracted: ${query}`);
+			} else {
+				content = JSON.stringify(jsonValue, null, 2);
+			}
+			contentType = "application/json";
+		}
+
+		return {
+			url: url.href,
+			content,
+			contentType,
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: foundPath,
+			notes,
+		};
+	}
+
+	async complete(): Promise<UrlCompletion[]> {
+		const ids = new Set<string>();
+		for (const dir of artifactsDirsFromRegistry()) {
+			let files: string[];
+			try {
+				files = await fs.readdir(dir);
+			} catch (err) {
+				if (isEnoent(err)) continue;
+				throw err;
+			}
+			for (const f of files) {
+				if (f.endsWith(".md")) ids.add(f.slice(0, -3));
+			}
+		}
+		return [...ids].sort().map(value => ({ value }));
+	}
+}

package/src/internal-urls/artifact-protocol.ts

@@ -0,0 +1,151 @@
+/**
+ * Protocol handler for artifact:// URLs.
+ *
+ * Resolves artifact IDs against the artifacts directories of every active
+ * session. Unlike agent://, artifacts are raw text with no JSON extraction.
+ *
+ * URL form:
+ * - artifact://<id> - Full artifact content
+ *
+ * Pagination is handled by the read tool via offset/limit parameters.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi-zen/pi-utils";
+import { artifactsDirsFromRegistry } from "./registry-helpers";
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion } from "./types";
+
+const MAX_INLINE_ARTIFACT_BYTES = 8 * 1024 * 1024;
+
+/** Filesystem location for a session artifact, resolved without materializing its content. */
+export interface ResolvedArtifactFile {
+	id: string;
+	path: string;
+	size: number;
+}
+
+function parseArtifactId(url: InternalUrl): string {
+	const id = url.rawHost || url.hostname;
+	if (!id) {
+		throw new Error("artifact:// URL requires a numeric ID: artifact://0");
+	}
+	if (!/^\d+$/.test(id)) {
+		throw new Error(`artifact:// ID must be numeric, got: ${id}`);
+	}
+	return id;
+}
+
+/** Resolve an `artifact://` URL to its backing file without reading artifact bytes. */
+export async function resolveArtifactFile(url: InternalUrl, context?: ResolveContext): Promise<ResolvedArtifactFile> {
+	const id = parseArtifactId(url);
+
+	// Artifact ids are per-session counters; in multi-session hosts the same
+	// id exists in several dirs. Pin resolution to the calling session's
+	// artifacts dir first so `artifact://3` means *this* session's #3.
+	const dirs = artifactsDirsFromRegistry();
+	const pinnedDir = context?.localProtocolOptions?.getArtifactsDir?.() ?? null;
+	if (pinnedDir) {
+		const pinnedIndex = dirs.indexOf(pinnedDir);
+		if (pinnedIndex >= 0) dirs.splice(pinnedIndex, 1);
+		dirs.unshift(pinnedDir);
+	}
+
+	if (dirs.length === 0) {
+		throw new Error("No session - artifacts unavailable");
+	}
+
+	let foundPath: string | undefined;
+	let anyDirExists = false;
+	const availableIds = new Set<string>();
+
+	for (const dir of dirs) {
+		let files: string[];
+		try {
+			files = await fs.readdir(dir);
+			anyDirExists = true;
+		} catch (err) {
+			if (isEnoent(err)) continue;
+			throw err;
+		}
+		const match = files.find(f => f.startsWith(`${id}.`));
+		if (match) {
+			foundPath = path.join(dir, match);
+			break;
+		}
+		for (const f of files) {
+			const m = f.match(/^(\d+)\./);
+			if (m) availableIds.add(m[1]);
+		}
+	}
+
+	if (!anyDirExists) {
+		throw new Error("No artifacts directory found");
+	}
+
+	if (!foundPath) {
+		const sorted = [...availableIds].sort((a, b) => Number(a) - Number(b));
+		const availableStr = sorted.length > 0 ? sorted.join(", ") : "none";
+		throw new Error(`Artifact ${id} not found. Available: ${availableStr}`);
+	}
+
+	const stat = await Bun.file(foundPath).stat();
+	if (stat.isDirectory()) {
+		throw new Error(`Artifact ${id} resolved to a directory, not a file`);
+	}
+	return { id, path: foundPath, size: stat.size };
+}
+
+export class ArtifactProtocolHandler implements ProtocolHandler {
+	readonly scheme = "artifact";
+	readonly immutable = true;
+
+	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
+		const artifact = await resolveArtifactFile(url, context);
+
+		// Path-only callers (search/grep, bash URL expansion) never touch the
+		// artifact bytes. Return the resource shape so those flows keep working
+		// on artifacts of any size — only content materialization is gated.
+		if (context?.pathOnly) {
+			return {
+				url: url.href,
+				content: "",
+				contentType: "text/plain",
+				size: artifact.size,
+				sourcePath: artifact.path,
+			};
+		}
+
+		if (artifact.size > MAX_INLINE_ARTIFACT_BYTES) {
+			throw new Error(
+				`Artifact ${artifact.id} is ${artifact.size} bytes; full internal resolution is blocked. Use read selectors such as artifact://${artifact.id}:1-3000 or artifact://${artifact.id}:raw:1-3000, and use the artifact file path for search/copy workflows: ${artifact.path}`,
+			);
+		}
+
+		const content = await Bun.file(artifact.path).text();
+		return {
+			url: url.href,
+			content,
+			contentType: "text/plain",
+			size: artifact.size,
+			sourcePath: artifact.path,
+		};
+	}
+
+	async complete(): Promise<UrlCompletion[]> {
+		const ids = new Set<string>();
+		for (const dir of artifactsDirsFromRegistry()) {
+			let files: string[];
+			try {
+				files = await fs.readdir(dir);
+			} catch (err) {
+				if (isEnoent(err)) continue;
+				throw err;
+			}
+			for (const f of files) {
+				const m = f.match(/^(\d+)\./);
+				if (m) ids.add(m[1]!);
+			}
+		}
+		return [...ids].sort((a, b) => Number(a) - Number(b)).map(value => ({ value }));
+	}
+}