@oh-my-pi/pi-coding-agent 6.9.69 → 8.0.0

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

@@ -0,0 +1,93 @@
+/**
+ * Protocol handler for artifact:// URLs.
+ *
+ * Resolves artifact IDs to files in the session artifacts directory.
+ * 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";
+import * as path from "node:path";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface ArtifactProtocolOptions {
+	/**
+	 * Returns the artifacts directory path, or null if no session.
+	 */
+	getArtifactsDir: () => string | null;
+}
+
+/**
+ * List available artifact IDs in the directory.
+ */
+function listAvailableArtifacts(artifactsDir: string): string[] {
+	try {
+		const files = fs.readdirSync(artifactsDir);
+		return files
+			.filter((f) => /^\d+\./.test(f))
+			.map((f) => f.split(".")[0])
+			.sort((a, b) => Number(a) - Number(b));
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Handler for artifact:// URLs.
+ *
+ * Resolves numeric artifact IDs to their text content.
+ * Artifacts are created by tools when output is truncated.
+ */
+export class ArtifactProtocolHandler implements ProtocolHandler {
+	readonly scheme = "artifact";
+
+	constructor(private readonly options: ArtifactProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const artifactsDir = this.options.getArtifactsDir();
+		if (!artifactsDir) {
+			throw new Error("No session - artifacts unavailable");
+		}
+
+		// Extract artifact ID from host
+		const id = url.rawHost || url.hostname;
+		if (!id) {
+			throw new Error("artifact:// URL requires a numeric ID: artifact://0");
+		}
+
+		// Validate ID is numeric
+		if (!/^\d+$/.test(id)) {
+			throw new Error(`artifact:// ID must be numeric, got: ${id}`);
+		}
+
+		// Check directory exists
+		if (!fs.existsSync(artifactsDir)) {
+			throw new Error("No artifacts directory found");
+		}
+
+		// Find file matching ID prefix
+		const files = fs.readdirSync(artifactsDir);
+		const match = files.find((f) => f.startsWith(`${id}.`));
+
+		if (!match) {
+			const available = listAvailableArtifacts(artifactsDir);
+			const availableStr = available.length > 0 ? available.join(", ") : "none";
+			throw new Error(`Artifact ${id} not found. Available: ${availableStr}`);
+		}
+
+		const filePath = path.join(artifactsDir, match);
+		const content = await Bun.file(filePath).text();
+
+		return {
+			url: url.href,
+			content,
+			contentType: "text/plain",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: filePath,
+		};
+	}
+}

package/src/internal-urls/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Internal URL routing system for agent:// and skill:// URLs.
+ *
+ * This module provides a unified way to resolve internal URLs without
+ * exposing filesystem paths to the agent.
+ *
+ * @example
+ * ```ts
+ * import { InternalUrlRouter, AgentProtocolHandler, SkillProtocolHandler } from './internal-urls';
+ *
+ * const router = new InternalUrlRouter();
+ * router.register(new AgentProtocolHandler({ getArtifactsDir: () => sessionDir }));
+ * router.register(new SkillProtocolHandler({ getSkills: () => skills }));
+ *
+ * if (router.canHandle('agent://reviewer_0')) {
+ *   const resource = await router.resolve('agent://reviewer_0');
+ *   console.log(resource.content);
+ * }
+ * ```
+ */
+
+export { AgentProtocolHandler, type AgentProtocolOptions } from "./agent-protocol";
+export { ArtifactProtocolHandler, type ArtifactProtocolOptions } from "./artifact-protocol";
+export { applyQuery, parseQuery, pathToQuery } from "./json-query";
+export { InternalUrlRouter } from "./router";
+export { RuleProtocolHandler, type RuleProtocolOptions } from "./rule-protocol";
+export { SkillProtocolHandler, type SkillProtocolOptions } from "./skill-protocol";
+export type { InternalResource, InternalUrl, ProtocolHandler } from "./types";

package/src/internal-urls/json-query.ts

@@ -0,0 +1,126 @@
+/**
+ * JSON query parser and executor for agent:// URL extraction.
+ *
+ * Supports jq-like syntax: .foo, [0], .foo.bar[0].baz, ["special-key"]
+ * Also supports path form: /foo/bar/0 -> .foo.bar[0]
+ */
+
+/**
+ * Parse a jq-like query string into tokens.
+ *
+ * @example
+ * parseQuery(".foo.bar[0]") // ["foo", "bar", 0]
+ * parseQuery(".foo['special-key']") // ["foo", "special-key"]
+ */
+export function parseQuery(query: string): Array<string | number> {
+	let input = query.trim();
+	if (!input) return [];
+	if (input.startsWith(".")) input = input.slice(1);
+	if (!input) return [];
+
+	const tokens: Array<string | number> = [];
+	let i = 0;
+
+	const isIdentChar = (ch: string) => /[A-Za-z0-9_-]/.test(ch);
+
+	while (i < input.length) {
+		const ch = input[i];
+		if (ch === ".") {
+			i++;
+			continue;
+		}
+		if (ch === "[") {
+			const closeIndex = input.indexOf("]", i + 1);
+			if (closeIndex === -1) {
+				throw new Error(`Invalid query: missing ] in ${query}`);
+			}
+			const raw = input.slice(i + 1, closeIndex).trim();
+			if (!raw) {
+				throw new Error(`Invalid query: empty [] in ${query}`);
+			}
+			const quote = raw[0];
+			if ((quote === '"' || quote === "'") && raw.endsWith(quote)) {
+				let inner = raw.slice(1, -1);
+				inner = inner.replace(/\\(["'\\])/g, "$1");
+				tokens.push(inner);
+			} else if (/^\d+$/.test(raw)) {
+				tokens.push(Number(raw));
+			} else {
+				tokens.push(raw);
+			}
+			i = closeIndex + 1;
+			continue;
+		}
+
+		const start = i;
+		while (i < input.length && isIdentChar(input[i])) {
+			i++;
+		}
+		if (start === i) {
+			throw new Error(`Invalid query: unexpected token '${input[i]}' in ${query}`);
+		}
+		const ident = input.slice(start, i);
+		tokens.push(ident);
+	}
+
+	return tokens;
+}
+
+/**
+ * Apply a parsed query to a JSON value.
+ *
+ * @example
+ * applyQuery({ foo: { bar: [1, 2, 3] } }, ".foo.bar[0]") // 1
+ */
+export function applyQuery(data: unknown, query: string): unknown {
+	const tokens = parseQuery(query);
+	let current: unknown = data;
+	for (const token of tokens) {
+		if (current === null || current === undefined) return undefined;
+		if (typeof token === "number") {
+			if (!Array.isArray(current)) return undefined;
+			current = current[token];
+			continue;
+		}
+		if (typeof current !== "object") return undefined;
+		const record = current as Record<string, unknown>;
+		current = record[token];
+	}
+	return current;
+}
+
+/**
+ * Convert a URL path form to a query string.
+ *
+ * Path form: /foo/bar/0 -> .foo.bar[0]
+ * Trailing slash is normalized (ignored).
+ *
+ * Segments that are not valid identifiers use bracket notation: ['segment']
+ */
+export function pathToQuery(urlPath: string): string {
+	if (!urlPath || urlPath === "/") return "";
+
+	const segments = urlPath.split("/").filter(Boolean);
+	if (segments.length === 0) return "";
+
+	const parts: string[] = [];
+	for (const segment of segments) {
+		let decoded = segment;
+		try {
+			decoded = decodeURIComponent(segment);
+		} catch {
+			decoded = segment;
+		}
+		const isIdentifier = /^[A-Za-z0-9_-]+$/.test(decoded);
+		if (/^\d+$/.test(decoded)) {
+			parts.push(`[${decoded}]`);
+		} else if (isIdentifier) {
+			parts.push(`.${decoded}`);
+		} else {
+			const escaped = decoded.replace(/\\/g, String.raw`\\`).replace(/'/g, String.raw`\'`);
+			parts.push(`['${escaped}']`);
+		}
+	}
+
+	return parts.join("");
+}

package/src/internal-urls/router.ts

@@ -0,0 +1,69 @@
+/**
+ * Internal URL router for resolving agent:// and skill:// URLs.
+ */
+
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+/**
+ * Router for internal URL schemes.
+ *
+ * Dispatches URLs like `agent://output_id` or `skill://skill-name` to
+ * registered protocol handlers.
+ */
+export class InternalUrlRouter {
+	private handlers = new Map<string, ProtocolHandler>();
+
+	/**
+	 * Register a protocol handler.
+	 * @param handler Handler to register (uses handler.scheme as key)
+	 */
+	register(handler: ProtocolHandler): void {
+		this.handlers.set(handler.scheme, handler);
+	}
+
+	/**
+	 * Check if the router can handle a URL.
+	 * @param input URL string to check
+	 */
+	canHandle(input: string): boolean {
+		const match = input.match(/^([a-z][a-z0-9+.-]*):\/\//i);
+		if (!match) return false;
+		const scheme = match[1].toLowerCase();
+		return this.handlers.has(scheme);
+	}
+
+	/**
+	 * Resolve an internal URL to its content.
+	 * @param input URL string (e.g., "agent://reviewer_0", "skill://notion-pages")
+	 * @throws Error if scheme is not registered or resolution fails
+	 */
+	async resolve(input: string): Promise<InternalResource> {
+		let parsed: URL;
+		try {
+			parsed = new URL(input);
+		} catch {
+			throw new Error(`Invalid URL: ${input}`);
+		}
+
+		const hostMatch = input.match(/^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i);
+		let rawHost = hostMatch ? hostMatch[2] : parsed.hostname;
+		try {
+			rawHost = decodeURIComponent(rawHost);
+		} catch {
+			// Leave rawHost as-is if decoding fails.
+		}
+		(parsed as InternalUrl).rawHost = rawHost;
+
+		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"}`);
+		}
+
+		return handler.resolve(parsed as InternalUrl);
+	}
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Protocol handler for rule:// URLs.
+ *
+ * Resolves rule names to their content files.
+ *
+ * URL forms:
+ * - rule://<name> - Reads rule content
+ */
+
+import type { Rule } from "$c/capability/rule";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface RuleProtocolOptions {
+	/**
+	 * Returns the currently loaded rules.
+	 */
+	getRules: () => readonly Rule[];
+}
+
+/**
+ * Handler for rule:// URLs.
+ *
+ * Resolves rule names to their content.
+ */
+export class RuleProtocolHandler implements ProtocolHandler {
+	readonly scheme = "rule";
+
+	constructor(private readonly options: RuleProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const rules = this.options.getRules();
+
+		// Extract rule name from host
+		const ruleName = url.rawHost || url.hostname;
+		if (!ruleName) {
+			throw new Error("rule:// URL requires a rule name: rule://<name>");
+		}
+
+		// Find the rule
+		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: [],
+		};
+	}
+}

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

@@ -0,0 +1,112 @@
+/**
+ * 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 type { Skill } from "$c/extensibility/skills";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface SkillProtocolOptions {
+	/**
+	 * Returns the currently loaded skills.
+	 */
+	getSkills: () => readonly Skill[];
+}
+
+/**
+ * Get content type based on file extension.
+ */
+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).
+ */
+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.
+ *
+ * Resolves skill names to their content files.
+ */
+export class SkillProtocolHandler implements ProtocolHandler {
+	readonly scheme = "skill";
+
+	constructor(private readonly options: SkillProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const skills = this.options.getSkills();
+
+		// Extract skill name from host
+		const skillName = url.rawHost || url.hostname;
+		if (!skillName) {
+			throw new Error("skill:// URL requires a skill name: skill://<name>");
+		}
+
+		// Find the skill
+		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}`);
+		}
+
+		// Determine the file to read
+		let targetPath: string;
+		const urlPath = url.pathname;
+		const hasRelativePath = urlPath && urlPath !== "/" && urlPath !== "";
+
+		if (hasRelativePath) {
+			// Read relative path within skill's baseDir
+			const relativePath = decodeURIComponent(urlPath.slice(1)); // Remove leading /
+			validateRelativePath(relativePath);
+			targetPath = path.join(skill.baseDir, relativePath);
+
+			// Verify the resolved path is still within baseDir
+			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 {
+			// Read SKILL.md
+			targetPath = skill.filePath;
+		}
+
+		// Read the file
+		const file = Bun.file(targetPath);
+		if (!(await file.exists())) {
+			throw new Error(`File not found: ${targetPath}`);
+		}
+
+		const content = await file.text();
+		const contentType = getContentType(targetPath);
+
+		return {
+			url: url.href,
+			content,
+			contentType,
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: targetPath,
+			notes: [],
+		};
+	}
+}

package/src/internal-urls/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Types for the internal URL routing system.
+ *
+ * Internal URLs (agent://, skill://) are resolved by tools like fetch and read,
+ * providing access to agent outputs and skill files without exposing filesystem paths.
+ */
+
+/**
+ * Resolved internal resource returned by protocol handlers.
+ */
+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[];
+}
+
+/**
+ * Parsed internal URL with preserved host casing.
+ */
+export interface InternalUrl extends URL {
+	/**
+	 * Raw host segment extracted from input, preserving case.
+	 */
+	rawHost: string;
+}
+
+/**
+ * Handler for a specific internal URL scheme (e.g., agent://, skill://).
+ */
+export interface ProtocolHandler {
+	/** The scheme this handler processes (without trailing ://) */
+	readonly scheme: string;
+	/**
+	 * Resolve an internal URL to its content.
+	 * @param url Parsed URL object
+	 * @throws Error with user-friendly message if resolution fails
+	 */
+	resolve(url: InternalUrl): Promise<InternalResource>;
+}