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

package/src/index.ts

@@ -7,41 +7,66 @@ export { StringEnum } from "@oh-my-pi/pi-ai";
 export { Container, Markdown, Spacer, Text } from "@oh-my-pi/pi-tui";
 // Logging
 export { logger } from "@oh-my-pi/pi-utils";
-export { getAgentDir, VERSION } from "./config";
+export type { FileDiagnosticsResult } from "$c/lsp/index";
+// UI components for extensions
 export {
-	AgentSession,
-	type AgentSessionConfig,
-	type AgentSessionEvent,
-	type AgentSessionEventListener,
-	type ModelCycleResult,
-	type PromptOptions,
-	type SessionStats,
-} from "./core/agent-session";
-// Auth and model registry
-export { type ApiKeyCredential, type AuthCredential, AuthStorage, type OAuthCredential } from "./core/auth-storage";
-// Compaction
+	ArminComponent,
+	AssistantMessageComponent,
+	BashExecutionComponent,
+	BorderedLoader,
+	BranchSummaryMessageComponent,
+	CompactionSummaryMessageComponent,
+	CustomEditor,
+	CustomMessageComponent,
+	DynamicBorder,
+	FooterComponent,
+	HookEditorComponent as ExtensionEditorComponent,
+	HookInputComponent as ExtensionInputComponent,
+	HookSelectorComponent as ExtensionSelectorComponent,
+	LoginDialogComponent,
+	ModelSelectorComponent,
+	OAuthSelectorComponent,
+	type RenderDiffOptions,
+	renderDiff,
+	SessionSelectorComponent,
+	type SettingsCallbacks,
+	SettingsSelectorComponent,
+	ShowImagesSelectorComponent,
+	ThemeSelectorComponent,
+	ThinkingSelectorComponent,
+	ToolExecutionComponent,
+	type ToolExecutionOptions,
+	TreeSelectorComponent,
+	truncateToVisualLines,
+	UserMessageComponent,
+	UserMessageSelectorComponent,
+	type VisualTruncateResult,
+} from "$c/modes/components/index";
+// Theme utilities for custom tools
 export {
-	type BranchPreparation,
-	type BranchSummaryResult,
-	type CollectEntriesResult,
-	type CompactionResult,
-	type CutPointResult,
-	calculateContextTokens,
-	collectEntriesForBranchSummary,
-	compact,
-	DEFAULT_COMPACTION_SETTINGS,
-	estimateTokens,
-	type FileOperations,
-	findCutPoint,
-	findTurnStartIndex,
-	type GenerateBranchSummaryOptions,
-	generateBranchSummary,
-	generateSummary,
-	getLastAssistantUsage,
-	prepareBranchEntries,
-	serializeConversation,
-	shouldCompact,
-} from "./core/compaction/index";
+	getLanguageFromPath,
+	getMarkdownTheme,
+	getSelectListTheme,
+	getSettingsListTheme,
+	highlightCode,
+	initTheme,
+	Theme,
+	type ThemeColor,
+} from "$c/modes/theme/theme";
+export { getAgentDir, VERSION } from "./config";
+export { formatKeyHint, formatKeyHints } from "./config/keybindings";
+export { ModelRegistry } from "./config/model-registry";
+// Prompt templates
+export type { PromptTemplate } from "./config/prompt-templates";
+export {
+	type CompactionSettings,
+	type ImageSettings,
+	type LspSettings,
+	type RetrySettings,
+	type Settings,
+	SettingsManager,
+	type SkillsSettings,
+} from "./config/settings-manager";
 // Custom commands
 export type {
 	CustomCommand,
@@ -50,7 +75,7 @@ export type {
 	CustomCommandSource,
 	CustomCommandsLoadResult,
 	LoadedCustomCommand,
-} from "./core/custom-commands/types";
+} from "./extensibility/custom-commands/types";
 export type {
 	AgentToolUpdateCallback,
 	CustomTool,
@@ -63,9 +88,9 @@ export type {
 	ExecResult,
 	LoadedCustomTool,
 	RenderResultOptions,
-} from "./core/custom-tools/index";
+} from "./extensibility/custom-tools/index";
 // Custom tools
-export { CustomToolLoader, discoverAndLoadCustomTools, loadCustomTools } from "./core/custom-tools/index";
+export { CustomToolLoader, discoverAndLoadCustomTools, loadCustomTools } from "./extensibility/custom-tools/index";
 export type {
 	AppAction,
 	Extension,
@@ -97,7 +122,7 @@ export type {
 	UserBashEventResult,
 	UserPythonEvent,
 	UserPythonEventResult,
-} from "./core/extensions/index";
+} from "./extensibility/extensions/index";
 // Extension types and utilities
 export {
 	discoverAndLoadExtensions,
@@ -110,14 +135,34 @@ export {
 	isLsToolResult,
 	isReadToolResult,
 	isWriteToolResult,
-} from "./core/extensions/index";
+} from "./extensibility/extensions/index";
 // Hook system types (legacy re-export)
-export type * from "./core/hooks/index";
-export { formatKeyHint, formatKeyHints } from "./core/keybindings";
-export { convertToLlm } from "./core/messages";
-export { ModelRegistry } from "./core/model-registry";
-// Prompt templates
-export type { PromptTemplate } from "./core/prompt-templates";
+export type * from "./extensibility/hooks/index";
+// Skills
+export {
+	type LoadSkillsFromDirOptions,
+	type LoadSkillsResult,
+	loadSkills,
+	loadSkillsFromDir,
+	type Skill,
+	type SkillFrontmatter,
+	type SkillWarning,
+} from "./extensibility/skills";
+// Slash commands
+export { type FileSlashCommand, loadSlashCommands as discoverSlashCommands } from "./extensibility/slash-commands";
+// Main entry point
+export { main } from "./main";
+// Run modes for programmatic SDK usage
+export {
+	InteractiveMode,
+	type InteractiveModeOptions,
+	type PrintModeOptions,
+	RpcClient,
+	type RpcClientOptions,
+	type RpcEventListener,
+	runPrintMode,
+	runRpcMode,
+} from "./modes/index";
 // SDK for programmatic usage
 export {
 	// Factory
@@ -149,7 +194,42 @@ export {
 	ReadTool,
 	type ToolSession,
 	WriteTool,
-} from "./core/sdk";
+} from "./sdk";
+export {
+	AgentSession,
+	type AgentSessionConfig,
+	type AgentSessionEvent,
+	type AgentSessionEventListener,
+	type ModelCycleResult,
+	type PromptOptions,
+	type SessionStats,
+} from "./session/agent-session";
+// Auth and model registry
+export { type ApiKeyCredential, type AuthCredential, AuthStorage, type OAuthCredential } from "./session/auth-storage";
+// Compaction
+export {
+	type BranchPreparation,
+	type BranchSummaryResult,
+	type CollectEntriesResult,
+	type CompactionResult,
+	type CutPointResult,
+	calculateContextTokens,
+	collectEntriesForBranchSummary,
+	compact,
+	DEFAULT_COMPACTION_SETTINGS,
+	estimateTokens,
+	type FileOperations,
+	findCutPoint,
+	findTurnStartIndex,
+	type GenerateBranchSummaryOptions,
+	generateBranchSummary,
+	generateSummary,
+	getLastAssistantUsage,
+	prepareBranchEntries,
+	serializeConversation,
+	shouldCompact,
+} from "./session/compaction/index";
+export { convertToLlm } from "./session/messages";
 export {
 	type BranchSummaryEntry,
 	buildSessionContext,
@@ -171,29 +251,7 @@ export {
 	SessionManager,
 	type SessionMessageEntry,
 	type ThinkingLevelChangeEntry,
-} from "./core/session-manager";
-export {
-	type CompactionSettings,
-	type ImageSettings,
-	type LspSettings,
-	type RetrySettings,
-	type Settings,
-	SettingsManager,
-	type SkillsSettings,
-} from "./core/settings-manager";
-// Skills
-export {
-	formatSkillsForPrompt,
-	type LoadSkillsFromDirOptions,
-	type LoadSkillsResult,
-	loadSkills,
-	loadSkillsFromDir,
-	type Skill,
-	type SkillFrontmatter,
-	type SkillWarning,
-} from "./core/skills";
-// Slash commands
-export { type FileSlashCommand, loadSlashCommands as discoverSlashCommands } from "./core/slash-commands";
+} from "./session/session-manager";
 // Tools (detail types and utilities)
 export {
 	type BashToolDetails,
@@ -217,64 +275,5 @@ export {
 	truncateLine,
 	truncateTail,
 	type WriteToolDetails,
-} from "./core/tools/index";
-export type { FileDiagnosticsResult } from "./core/tools/lsp/index";
-// Main entry point
-export { main } from "./main";
-// Run modes for programmatic SDK usage
-export {
-	InteractiveMode,
-	type InteractiveModeOptions,
-	type PrintModeOptions,
-	RpcClient,
-	type RpcClientOptions,
-	type RpcEventListener,
-	runPrintMode,
-	runRpcMode,
-} from "./modes/index";
-// UI components for extensions
-export {
-	ArminComponent,
-	AssistantMessageComponent,
-	BashExecutionComponent,
-	BorderedLoader,
-	BranchSummaryMessageComponent,
-	CompactionSummaryMessageComponent,
-	CustomEditor,
-	CustomMessageComponent,
-	DynamicBorder,
-	FooterComponent,
-	HookEditorComponent as ExtensionEditorComponent,
-	HookInputComponent as ExtensionInputComponent,
-	HookSelectorComponent as ExtensionSelectorComponent,
-	LoginDialogComponent,
-	ModelSelectorComponent,
-	OAuthSelectorComponent,
-	type RenderDiffOptions,
-	renderDiff,
-	SessionSelectorComponent,
-	type SettingsCallbacks,
-	SettingsSelectorComponent,
-	ShowImagesSelectorComponent,
-	ThemeSelectorComponent,
-	ThinkingSelectorComponent,
-	ToolExecutionComponent,
-	type ToolExecutionOptions,
-	TreeSelectorComponent,
-	truncateToVisualLines,
-	UserMessageComponent,
-	UserMessageSelectorComponent,
-	type VisualTruncateResult,
-} from "./modes/interactive/components/index";
-// Theme utilities for custom tools
-export {
-	getLanguageFromPath,
-	getMarkdownTheme,
-	getSelectListTheme,
-	getSettingsListTheme,
-	highlightCode,
-	initTheme,
-	Theme,
-	type ThemeColor,
-} from "./modes/interactive/theme/theme";
+} from "./tools/index";
 export { getShellConfig } from "./utils/shell";

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

@@ -0,0 +1,126 @@
+/**
+ * Protocol handler for agent:// URLs.
+ *
+ * Resolves agent output IDs to artifact files in the session directory.
+ *
+ * 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";
+import * as path from "node:path";
+import { applyQuery, pathToQuery } from "./json-query";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface AgentProtocolOptions {
+	/**
+	 * Returns the artifacts directory path, or null if no session.
+	 * Artifacts directory is the session file path without .jsonl extension.
+	 */
+	getArtifactsDir: () => string | null;
+}
+
+/**
+ * List available output IDs in artifacts directory.
+ */
+function listAvailableOutputs(artifactsDir: string): string[] {
+	try {
+		const files = fs.readdirSync(artifactsDir);
+		return files.filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * 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";
+
+	constructor(private readonly options: AgentProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const artifactsDir = this.options.getArtifactsDir();
+		if (!artifactsDir) {
+			throw new Error("No session - agent outputs unavailable");
+		}
+
+		if (!fs.existsSync(artifactsDir)) {
+			throw new Error("No artifacts directory found");
+		}
+
+		// Extract output ID from host
+		const outputId = url.rawHost || url.hostname;
+		if (!outputId) {
+			throw new Error("agent:// URL requires an output ID: agent://<id>");
+		}
+
+		// Check for conflicting extraction methods
+		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=");
+		}
+
+		// Load the output file
+		const outputPath = path.join(artifactsDir, `${outputId}.md`);
+		if (!fs.existsSync(outputPath)) {
+			const available = listAvailableOutputs(artifactsDir);
+			const availableStr = available.length > 0 ? available.join(", ") : "none";
+			throw new Error(`Not found: ${outputId}\nAvailable: ${availableStr}`);
+		}
+
+		const rawContent = await Bun.file(outputPath).text();
+		const notes: string[] = [];
+
+		// Handle extraction
+		let content = rawContent;
+		let contentType: InternalResource["contentType"] = "text/markdown";
+
+		if (hasPathExtraction || hasQueryExtraction) {
+			// Parse JSON
+			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}`);
+			}
+
+			// Convert path to query if needed
+			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 {
+				// Empty path/query means return full JSON
+				content = JSON.stringify(jsonValue, null, 2);
+			}
+			contentType = "application/json";
+		}
+
+		return {
+			url: url.href,
+			content,
+			contentType,
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: outputPath,
+			notes,
+		};
+	}
+}

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("");
+}