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

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>;
+}

package/src/{core/python-executor.ts → ipy/executor.ts}

@@ -6,8 +6,8 @@ import {
 	type KernelExecuteResult,
 	type PreludeHelper,
 	PythonKernel,
-} from "./python-kernel";
-import { OutputSink } from "./streaming-output";
+} from "$c/ipy/kernel";
+import { OutputSink } from "$c/session/streaming-output";
 export type PythonKernelMode = "session" | "per-call";
 
 export interface PythonExecutorOptions {
@@ -29,6 +29,11 @@ export interface PythonExecutorOptions {
 	useSharedGateway?: boolean;
 	/** Session file path for accessing task outputs */
 	sessionFile?: string;
+	/** Artifacts directory for $ARTIFACTS env var and artifact storage */
+	artifactsDir?: string;
+	/** Artifact path/id for full output storage */
+	artifactPath?: string;
+	artifactId?: string;
 }
 
 export interface PythonKernelExecutor {
@@ -44,8 +49,16 @@ export interface PythonResult {
 	cancelled: boolean;
 	/** Whether the output was truncated */
 	truncated: boolean;
-	/** Path to temp file containing full output (if output exceeded truncation threshold) */
-	fullOutputPath?: string;
+	/** Artifact ID if full output was saved to artifact storage */
+	artifactId?: string;
+	/** Total number of lines in the output stream */
+	totalLines: number;
+	/** Total number of bytes in the output stream */
+	totalBytes: number;
+	/** Number of lines included in the output text */
+	outputLines: number;
+	/** Number of bytes included in the output text */
+	outputBytes: number;
 	/** Rich display outputs captured from display_data/execute_result */
 	displayOutputs: KernelDisplayOutput[];
 	/** Whether stdin was requested */
@@ -124,8 +137,15 @@ async function createKernelSession(
 	cwd: string,
 	useSharedGateway?: boolean,
 	sessionFile?: string,
+	artifactsDir?: string,
 ): Promise<KernelSession> {
-	const env = sessionFile ? { OMP_SESSION_FILE: sessionFile } : undefined;
+	const env: Record<string, string> | undefined =
+		sessionFile || artifactsDir
+			? {
+					...(sessionFile ? { OMP_SESSION_FILE: sessionFile } : {}),
+					...(artifactsDir ? { ARTIFACTS: artifactsDir } : {}),
+				}
+			: undefined;
 	const kernel = await PythonKernel.start({ cwd, useSharedGateway, env });
 	const session: KernelSession = {
 		id: sessionId,
@@ -152,6 +172,7 @@ async function restartKernelSession(
 	cwd: string,
 	useSharedGateway?: boolean,
 	sessionFile?: string,
+	artifactsDir?: string,
 ): Promise<void> {
 	session.restartCount += 1;
 	if (session.restartCount > 1) {
@@ -162,7 +183,13 @@ async function restartKernelSession(
 	} catch (err) {
 		logger.warn("Failed to shutdown crashed kernel", { error: err instanceof Error ? err.message : String(err) });
 	}
-	const env = sessionFile ? { OMP_SESSION_FILE: sessionFile } : undefined;
+	const env: Record<string, string> | undefined =
+		sessionFile || artifactsDir
+			? {
+					...(sessionFile ? { OMP_SESSION_FILE: sessionFile } : {}),
+					...(artifactsDir ? { ARTIFACTS: artifactsDir } : {}),
+				}
+			: undefined;
 	const kernel = await PythonKernel.start({ cwd, useSharedGateway, env });
 	session.kernel = kernel;
 	session.dead = false;
@@ -187,17 +214,18 @@ async function withKernelSession<T>(
 	handler: (kernel: PythonKernel) => Promise<T>,
 	useSharedGateway?: boolean,
 	sessionFile?: string,
+	artifactsDir?: string,
 ): Promise<T> {
 	let session = kernelSessions.get(sessionId);
 	if (!session) {
-		session = await createKernelSession(sessionId, cwd, useSharedGateway, sessionFile);
+		session = await createKernelSession(sessionId, cwd, useSharedGateway, sessionFile, artifactsDir);
 		kernelSessions.set(sessionId, session);
 	}
 
 	const run = async (): Promise<T> => {
 		session!.lastUsedAt = Date.now();
 		if (session!.dead || !session!.kernel.isAlive()) {
-			await restartKernelSession(session!, cwd, useSharedGateway, sessionFile);
+			await restartKernelSession(session!, cwd, useSharedGateway, sessionFile, artifactsDir);
 		}
 		try {
 			const result = await handler(session!.kernel);
@@ -207,7 +235,7 @@ async function withKernelSession<T>(
 			if (!session!.dead && session!.kernel.isAlive()) {
 				throw err;
 			}
-			await restartKernelSession(session!, cwd, useSharedGateway, sessionFile);
+			await restartKernelSession(session!, cwd, useSharedGateway, sessionFile, artifactsDir);
 			const result = await handler(session!.kernel);
 			session!.restartCount = 0;
 			return result;
@@ -227,7 +255,11 @@ async function executeWithKernel(
 	code: string,
 	options: PythonExecutorOptions | undefined,
 ): Promise<PythonResult> {
-	const sink = new OutputSink({ onChunk: options?.onChunk });
+	const sink = new OutputSink({
+		onChunk: options?.onChunk,
+		artifactPath: options?.artifactPath,
+		artifactId: options?.artifactId,
+	});
 	const displayOutputs: KernelDisplayOutput[] = [];
 
 	try {
@@ -291,9 +323,16 @@ export async function executePython(code: string, options?: PythonExecutorOption
 	const kernelMode = options?.kernelMode ?? "session";
 	const useSharedGateway = options?.useSharedGateway;
 	const sessionFile = options?.sessionFile;
+	const artifactsDir = options?.artifactsDir;
 
 	if (kernelMode === "per-call") {
-		const env = sessionFile ? { OMP_SESSION_FILE: sessionFile } : undefined;
+		const env: Record<string, string> | undefined =
+			sessionFile || artifactsDir
+				? {
+						...(sessionFile ? { OMP_SESSION_FILE: sessionFile } : {}),
+						...(artifactsDir ? { ARTIFACTS: artifactsDir } : {}),
+					}
+				: undefined;
 		const kernel = await PythonKernel.start({ cwd, useSharedGateway, env });
 		try {
 			return await executeWithKernel(kernel, code, options);
@@ -315,5 +354,6 @@ export async function executePython(code: string, options?: PythonExecutorOption
 		async (kernel) => executeWithKernel(kernel, code, options),
 		useSharedGateway,
 		sessionFile,
+		artifactsDir,
 	);
 }