@wahack/pi-coding-agent 15.11.0

package/src/internal-urls/parse.ts

@@ -0,0 +1,72 @@
+/**
+ * Internal URL parser that handles colons in the host segment.
+ *
+ * Standard `new URL()` interprets colons as port separators, which breaks
+ * namespaced internal URLs like `skill://plugin:name`. This parser extracts
+ * components via regex first, then falls back to a minimal URL-like object
+ * when `new URL()` fails.
+ *
+ * All code that parses internal URLs (router, protocol handlers, tools)
+ * MUST use this function instead of calling `new URL()` directly.
+ */
+import type { InternalUrl } from "./types";
+
+const SCHEME_HOST_RE = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i;
+const PATHNAME_RE = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*(\/[^?#]*)?/i;
+
+/**
+ * Parse an internal URL into an InternalUrl.
+ *
+ * Handles URLs where `new URL()` would fail (e.g., `skill://plugin:name`
+ * where the colon is not a port separator).
+ */
+export function parseInternalUrl(input: string): InternalUrl {
+	const hostMatch = input.match(SCHEME_HOST_RE);
+	const pathMatch = input.match(PATHNAME_RE);
+
+	let parsed: URL;
+	try {
+		parsed = new URL(input);
+	} catch {
+		// URL parse failed — build a minimal URL-like object from regex matches.
+		if (!hostMatch) {
+			throw new Error(`Invalid URL: ${input}`);
+		}
+		// Extract search and hash from the raw input before constructing the object.
+		const hashIdx = input.indexOf("#");
+		const hash = hashIdx !== -1 ? input.slice(hashIdx) : "";
+		const withoutHash = hashIdx !== -1 ? input.slice(0, hashIdx) : input;
+		const queryIdx = withoutHash.indexOf("?");
+		const search = queryIdx !== -1 ? withoutHash.slice(queryIdx) : "";
+		const queryString = search.slice(1); // strip leading ?
+
+		// Strip search/hash from pathname captured by regex.
+		let rawPathname = pathMatch?.[1] ?? "";
+		if (queryIdx !== -1 && rawPathname.includes("?")) {
+			rawPathname = rawPathname.slice(0, rawPathname.indexOf("?"));
+		}
+
+		parsed = {
+			protocol: `${hostMatch[1]}:`,
+			hostname: hostMatch[2] ?? "",
+			host: hostMatch[2] ?? "",
+			pathname: rawPathname,
+			href: input,
+			search,
+			hash,
+			searchParams: new URLSearchParams(queryString),
+		} as unknown as URL;
+	}
+
+	let rawHost = hostMatch ? hostMatch[2] : parsed.hostname;
+	try {
+		rawHost = decodeURIComponent(rawHost);
+	} catch {
+		// Leave rawHost as-is if decoding fails.
+	}
+
+	const result = parsed as InternalUrl;
+	result.rawHost = rawHost;
+	result.rawPathname = pathMatch?.[1] ?? parsed.pathname;
+	return result;
+}

package/src/internal-urls/registry-helpers.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared helpers for internal-url protocol handlers that resolve IDs against
+ * registered agent sessions.
+ */
+import { AgentRegistry } from "../registry/agent-registry";
+
+/**
+ * Snapshot of artifacts dirs for every registered session, deduped.
+ *
+ * Prefers `sessionManager.getArtifactsDir()` because subagents adopt their
+ * parent's `ArtifactManager` and report the parent's dir there; dedup then
+ * collapses parent + N subagents (the whole agent tree) to one entry. Falls
+ * back to the raw session file (with the `.jsonl` suffix stripped) when no
+ * live session reference is attached.
+ */
+export function artifactsDirsFromRegistry(): string[] {
+	const dirs: string[] = [];
+	for (const ref of AgentRegistry.global().list()) {
+		const dir =
+			ref.session?.sessionManager.getArtifactsDir() ?? (ref.sessionFile ? ref.sessionFile.slice(0, -6) : null);
+		if (!dir) continue;
+		if (!dirs.includes(dir)) dirs.push(dir);
+	}
+	return dirs;
+}

package/src/internal-urls/router.ts

@@ -0,0 +1,105 @@
+/**
+ * Internal URL router for internal protocols (`agent://`, `artifact://`, `history://`, `issue://`, `local://`, `mcp://`, `memory://`, `omp://`, `pr://`, `rule://`, `skill://`, and `vault://`).
+ *
+ * One process-global router with one handler per scheme. Access via
+ * `InternalUrlRouter.instance()`. Handlers are stateless; per-session and
+ * shared state lives in `./state.ts`.
+ */
+import { AgentProtocolHandler } from "./agent-protocol";
+import { ArtifactProtocolHandler } from "./artifact-protocol";
+import { HistoryProtocolHandler } from "./history-protocol";
+import { IssueProtocolHandler, PrProtocolHandler } from "./issue-pr-protocol";
+import { LocalProtocolHandler } from "./local-protocol";
+import { McpProtocolHandler } from "./mcp-protocol";
+import { MemoryProtocolHandler } from "./memory-protocol";
+import { OmpProtocolHandler } from "./omp-protocol";
+import { parseInternalUrl } from "./parse";
+import { RuleProtocolHandler } from "./rule-protocol";
+import { SkillProtocolHandler } from "./skill-protocol";
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion } from "./types";
+import { VaultProtocolHandler } from "./vault-protocol";
+
+export class InternalUrlRouter {
+	static #instance: InternalUrlRouter | undefined;
+
+	#handlers = new Map<string, ProtocolHandler>();
+
+	constructor() {
+		this.register(new OmpProtocolHandler());
+		this.register(new AgentProtocolHandler());
+		this.register(new ArtifactProtocolHandler());
+		this.register(new MemoryProtocolHandler());
+		this.register(new LocalProtocolHandler());
+		this.register(new VaultProtocolHandler());
+		this.register(new SkillProtocolHandler());
+		this.register(new RuleProtocolHandler());
+		this.register(new McpProtocolHandler());
+		this.register(new IssueProtocolHandler());
+		this.register(new PrProtocolHandler());
+		this.register(new HistoryProtocolHandler());
+	}
+
+	/** Process-global router instance. */
+	static instance(): InternalUrlRouter {
+		InternalUrlRouter.#instance ??= new InternalUrlRouter();
+		return InternalUrlRouter.#instance;
+	}
+
+	/** Reset the global instance in tests. */
+	static resetForTests(): void {
+		InternalUrlRouter.#instance = undefined;
+	}
+
+	register(handler: ProtocolHandler): void {
+		this.#handlers.set(handler.scheme.toLowerCase(), handler);
+	}
+
+	unregister(scheme: string): boolean {
+		return this.#handlers.delete(scheme.toLowerCase());
+	}
+
+	getHandler(scheme: string): ProtocolHandler | undefined {
+		return this.#handlers.get(scheme.toLowerCase());
+	}
+
+	canHandle(input: string): boolean {
+		const match = input.match(/^([a-z][a-z0-9+.-]*):\/\//i);
+		if (!match) return false;
+		return this.#handlers.has(match[1].toLowerCase());
+	}
+
+	/** Schemes whose handler supports host/path autocomplete. */
+	completionSchemes(): string[] {
+		const schemes: string[] = [];
+		for (const [scheme, handler] of this.#handlers) {
+			if (handler.complete) schemes.push(scheme);
+		}
+		return schemes;
+	}
+
+	/**
+	 * Candidate completions for the host/path portion of `scheme://<query>`.
+	 * Returns `null` when the scheme is unknown or does not support completion.
+	 */
+	async complete(scheme: string, query: string): Promise<UrlCompletion[] | null> {
+		const handler = this.#handlers.get(scheme.toLowerCase());
+		if (!handler?.complete) return null;
+		return handler.complete(query);
+	}
+
+	async resolve(input: string, context?: ResolveContext): Promise<InternalResource> {
+		const parsed = parseInternalUrl(input);
+		const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+		const handler = this.#handlers.get(scheme);
+
+		if (!handler) {
+			const available = Array.from(this.#handlers.keys())
+				.map(s => `${s}://`)
+				.join(", ");
+			throw new Error(`Unknown protocol: ${scheme}://\nSupported: ${available || "none"}`);
+		}
+
+		const resource = await handler.resolve(parsed as InternalUrl, context);
+		return { ...resource, immutable: resource.immutable ?? handler.immutable };
+	}
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Protocol handler for rule:// URLs.
+ *
+ * URL forms:
+ * - rule://<name> - Reads rule content
+ */
+import { getActiveRules } from "../capability/rule";
+import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+
+export class RuleProtocolHandler implements ProtocolHandler {
+	readonly scheme = "rule";
+	readonly immutable = true;
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const rules = getActiveRules();
+
+		const ruleName = url.rawHost || url.hostname;
+		if (!ruleName) {
+			throw new Error("rule:// URL requires a rule name: rule://<name>");
+		}
+
+		const rule = rules.find(r => r.name === ruleName);
+		if (!rule) {
+			const available = rules.map(r => r.name);
+			const availableStr = available.length > 0 ? available.join(", ") : "none";
+			throw new Error(`Unknown rule: ${ruleName}\nAvailable: ${availableStr}`);
+		}
+
+		return {
+			url: url.href,
+			content: rule.content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(rule.content, "utf-8"),
+			sourcePath: rule.path,
+			notes: [],
+		};
+	}
+
+	async complete(): Promise<UrlCompletion[]> {
+		return getActiveRules().map(rule => ({
+			value: rule.name,
+			...(rule.description ? { description: rule.description } : {}),
+		}));
+	}
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Protocol handler for skill:// URLs.
+ *
+ * Resolves skill names to their SKILL.md files or relative paths within skill directories.
+ *
+ * URL forms:
+ * - skill://<name> - Reads SKILL.md
+ * - skill://<name>/<path> - Reads relative path within skill's baseDir
+ */
+import * as path from "node:path";
+import { getActiveSkills } from "../extensibility/skills";
+import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+
+function getContentType(filePath: string): InternalResource["contentType"] {
+	const ext = path.extname(filePath).toLowerCase();
+	if (ext === ".md") return "text/markdown";
+	return "text/plain";
+}
+
+/**
+ * Validate that a path is safe (no traversal, no absolute paths).
+ */
+export function validateRelativePath(relativePath: string): void {
+	if (path.isAbsolute(relativePath)) {
+		throw new Error("Absolute paths are not allowed in skill:// URLs");
+	}
+
+	const normalized = path.normalize(relativePath);
+	if (normalized.startsWith("..") || normalized.includes("/../") || normalized.includes("/..")) {
+		throw new Error("Path traversal (..) is not allowed in skill:// URLs");
+	}
+}
+
+/**
+ * Handler for skill:// URLs.
+ */
+export class SkillProtocolHandler implements ProtocolHandler {
+	readonly scheme = "skill";
+	readonly immutable = true;
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const skills = getActiveSkills();
+
+		const skillName = url.rawHost || url.hostname;
+		if (!skillName) {
+			throw new Error("skill:// URL requires a skill name: skill://<name>");
+		}
+
+		const skill = skills.find(s => s.name === skillName);
+		if (!skill) {
+			const available = skills.map(s => s.name);
+			const availableStr = available.length > 0 ? available.join(", ") : "none";
+			throw new Error(`Unknown skill: ${skillName}\nAvailable: ${availableStr}`);
+		}
+
+		let targetPath: string;
+		const urlPath = url.pathname;
+		const hasRelativePath = urlPath && urlPath !== "/" && urlPath !== "";
+
+		if (hasRelativePath) {
+			const relativePath = decodeURIComponent(urlPath.slice(1));
+			validateRelativePath(relativePath);
+			targetPath = path.join(skill.baseDir, relativePath);
+
+			const resolvedPath = path.resolve(targetPath);
+			const resolvedBaseDir = path.resolve(skill.baseDir);
+			if (!resolvedPath.startsWith(resolvedBaseDir + path.sep) && resolvedPath !== resolvedBaseDir) {
+				throw new Error("Path traversal is not allowed");
+			}
+		} else {
+			targetPath = skill.filePath;
+		}
+
+		const file = Bun.file(targetPath);
+		if (!(await file.exists())) {
+			throw new Error(`File not found: ${targetPath}`);
+		}
+
+		const content = await file.text();
+		return {
+			url: url.href,
+			content,
+			contentType: getContentType(targetPath),
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: targetPath,
+			notes: [],
+		};
+	}
+
+	async complete(): Promise<UrlCompletion[]> {
+		return getActiveSkills().map(skill => ({
+			value: skill.name,
+			...(skill.description ? { description: skill.description } : {}),
+		}));
+	}
+}

package/src/internal-urls/types.ts

@@ -0,0 +1,152 @@
+/**
+ * Types for the internal URL routing system.
+ *
+ * Internal URLs (`agent://`, `artifact://`, `history://`, `issue://`, `local://`, `mcp://`, `memory://`, `omp://`, `pr://`, `rule://`, `skill://`, and `vault://`) are resolved by tools like read,
+ * providing access to agent outputs and server resources without exposing filesystem paths.
+ */
+
+import type { LocalProtocolOptions } from "./local-protocol";
+
+/**
+ * Raw resource payload returned by protocol handlers. The `immutable` flag is
+ * applied by the router from {@link ProtocolHandler.immutable}, so handlers do
+ * not need to set it themselves.
+ */
+export interface InternalResource {
+	/** Canonical URL that was resolved */
+	url: string;
+	/** Resolved text content */
+	content: string;
+	/** MIME type: text/markdown, application/json, or text/plain */
+	contentType: "text/markdown" | "application/json" | "text/plain";
+	/** Content size in bytes */
+	size?: number;
+	/** Underlying filesystem path (for debugging, not exposed to agent) */
+	sourcePath?: string;
+	/** Additional notes about resolution */
+	notes?: string[];
+	/**
+	 * True when the resolved content cannot be edited by the agent (e.g. sealed
+	 * artifacts, harness docs, machine-generated memory summaries). Hashline
+	 * anchors and similar edit affordances are suppressed for immutable
+	 * resources. Mutable resources (e.g. local://) behave like editable files.
+	 */
+	immutable?: boolean;
+}
+
+/**
+ * A single autocomplete candidate for the host/path portion of a `scheme://`
+ * URL, produced by {@link ProtocolHandler.complete}.
+ */
+export interface UrlCompletion {
+	/**
+	 * The text that follows `scheme://` for this candidate (e.g. `humanizer`,
+	 * `subdir/data.json`, `root`). The caller renders it as `scheme://<value>`.
+	 */
+	value: string;
+	/** Human-facing label for the dropdown. Defaults to {@link value}. */
+	label?: string;
+	/** Optional one-line description shown beside the candidate. */
+	description?: string;
+}
+
+/**
+ * Parsed internal URL with preserved host casing.
+ */
+export interface InternalUrl extends URL {
+	/**
+	 * Raw host segment extracted from input, preserving case.
+	 */
+	rawHost: string;
+	/**
+	 * Raw pathname extracted from input, preserving traversal markers before URL normalization.
+	 */
+	rawPathname?: string;
+}
+
+/**
+ * Caller-supplied context that the router threads into protocol handlers.
+ *
+ * Read tool calls `InternalUrlRouter.resolve(url, { cwd, settings, signal })`
+ * so handlers can resolve relative defaults (e.g. `issue://N` → which repo?)
+ * against the actual session that initiated the read, not whichever session
+ * happens to be registered first in the global `AgentRegistry`.
+ */
+export interface ResolveContext {
+	/** Working directory of the calling session. */
+	cwd?: string;
+	/** Settings of the calling session (used by `issue://`/`pr://` for cache TTLs). */
+	settings?: unknown;
+	/** Caller's abort signal. */
+	signal?: AbortSignal;
+	/**
+	 * Calling session's `local://` root mapping. When present, the local-protocol
+	 * handler resolves the URL against THIS session's artifacts dir instead of
+	 * picking the first `main`-kind session from the global `AgentRegistry`.
+	 *
+	 * Required for correctness in multi-session hosts (cmux/ACP, embedded SDK
+	 * consumers) where multiple sessions are registered as `main` and the
+	 * "first one wins" lookup picks the wrong artifacts directory — see
+	 * [#1608](https://github.com/can1357/oh-my-pi/issues/1608).
+	 */
+	localProtocolOptions?: LocalProtocolOptions;
+}
+
+/**
+ * Caller context for write operations dispatched to host-owned URI handlers.
+ * Mirrors {@link ResolveContext} so handlers that share read/write state can
+ * accept the same shape.
+ */
+export interface WriteContext {
+	/** Working directory of the calling session. */
+	cwd?: string;
+	/** Caller's abort signal. */
+	signal?: AbortSignal;
+	/** Calling session's `local://` root mapping — see {@link ResolveContext.localProtocolOptions}. */
+	localProtocolOptions?: LocalProtocolOptions;
+}
+
+/**
+ * Handler for a specific internal URL scheme (e.g., agent://, memory://, skill://, mcp://).
+ */
+export interface ProtocolHandler {
+	/** The scheme this handler processes (without trailing ://) */
+	readonly scheme: string;
+	/**
+	 * Whether resources produced by this handler are immutable (cannot be
+	 * edited by the agent). When true, callers suppress hashline anchors and
+	 * other edit affordances. When false, resources behave like editable files.
+	 */
+	readonly immutable: boolean;
+	/**
+	 * Resolve an internal URL to its content. The router stamps the
+	 * {@link InternalResource.immutable} flag from {@link ProtocolHandler.immutable}.
+	 *
+	 * @param url Parsed URL object
+	 * @param context Optional caller context. Handlers that depend on caller
+	 *   identity (working directory, settings) **MUST** consume this in
+	 *   preference to global state.
+	 * @throws Error with user-friendly message if resolution fails
+	 */
+	resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+	/**
+	 * Optional write hook. When present, the write tool dispatches
+	 * `write(url, content)` to this handler instead of writing to a filesystem
+	 * path. The handler is responsible for any persistence and validation.
+	 *
+	 * Handlers that omit this method are treated as read-only; the write tool
+	 * surfaces a clear "not writable" error when invoked against them.
+	 */
+	write?(url: InternalUrl, content: string, context?: WriteContext): Promise<void>;
+	/**
+	 * Optional autocomplete hook. Returns candidate completions for the
+	 * host/path portion of a `scheme://` URL while the user composes a prompt.
+	 *
+	 * Implementations **MUST** be fast and local — this runs on every keystroke.
+	 * Schemes backed by network or external CLIs (issue://, pr://, vault://,
+	 * mcp://) omit it. The caller fuzzy-filters the returned set against the
+	 * partially typed `query`, so handlers return their full (bounded) candidate
+	 * list; `query` is provided only so handlers can scope expensive enumeration.
+	 */
+	complete?(query: string): Promise<UrlCompletion[]>;
+}