@oh-my-pi/pi-coding-agent 15.1.1 → 15.1.3

package/dist/types/internal-urls/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Internal URL routing system for internal protocols like agent://, memory://,
+ * skill://, mcp://, and local://.
+ *
+ * One process-global `InternalUrlRouter` is shared across sessions. Handlers
+ * are stateless; they pull whatever they need (active skills/rules, active
+ * MCP/async managers, AgentRegistry-listed sessions) from the owning module
+ * on each resolve call.
+ */
+export * from "./agent-protocol";
+export * from "./artifact-protocol";
+export * from "./issue-pr-protocol";
+export * from "./json-query";
+export * from "./local-protocol";
+export * from "./mcp-protocol";
+export * from "./memory-protocol";
+export * from "./omp-protocol";
+export * from "./parse";
+export * from "./router";
+export * from "./rule-protocol";
+export * from "./skill-protocol";
+export type * from "./types";

package/dist/types/internal-urls/issue-pr-protocol.d.ts

@@ -0,0 +1,17 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext } from "./types";
+/**
+ * Handler for `issue://` URLs.
+ */
+export declare class IssueProtocolHandler implements ProtocolHandler {
+    readonly scheme = "issue";
+    readonly immutable = true;
+    resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+}
+/**
+ * Handler for `pr://` URLs.
+ */
+export declare class PrProtocolHandler implements ProtocolHandler {
+    readonly scheme = "pr";
+    readonly immutable = true;
+    resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+}

package/dist/types/internal-urls/json-query.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare function parseQuery(query: string): Array<string | number>;
+/**
+ * Apply a parsed query to a JSON value.
+ *
+ * @example
+ * applyQuery({ foo: { bar: [1, 2, 3] } }, ".foo.bar[0]") // 1
+ */
+export declare function applyQuery(data: unknown, query: string): unknown;
+/**
+ * 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 declare function pathToQuery(urlPath: string): string;

package/dist/types/internal-urls/local-protocol.d.ts

@@ -0,0 +1,39 @@
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+export interface LocalProtocolOptions {
+    getArtifactsDir?: () => string | null;
+    getSessionId?: () => string | null;
+}
+export declare function resolveLocalRoot(options: LocalProtocolOptions): string;
+export declare function resolveLocalUrlToPath(input: string | InternalUrl, options: LocalProtocolOptions): string;
+/**
+ * Protocol handler for local:// URLs.
+ *
+ * URL forms:
+ * - local:// - Lists files at the session local root
+ * - local://<path> - Reads a file under the session local root
+ */
+export declare class LocalProtocolHandler implements ProtocolHandler {
+    #private;
+    readonly scheme = "local";
+    readonly immutable = false;
+    /**
+     * Install a process-global override that wins over the AgentRegistry-based
+     * derivation. Used by SDK consumers that wire `localProtocolOptions` on
+     * `createAgentSession` and by subagents that share their parent's root.
+     */
+    static setOverride(value: LocalProtocolOptions | undefined): void;
+    /** Reset the process-global override. Test-only. */
+    static resetOverrideForTests(): void;
+    /**
+     * Returns the active local-protocol options.
+     *
+     * Resolution order:
+     * 1. Explicit override installed via {@link setOverride} (used by subagents
+     *    that share their parent's root and by SDK consumers with a custom
+     *    artifacts/session id mapping).
+     * 2. The main session in `AgentRegistry.global()`. Its `SessionManager`
+     *    supplies both `getArtifactsDir` and `getSessionId`.
+     */
+    static resolveOptions(): LocalProtocolOptions | undefined;
+    resolve(url: InternalUrl): Promise<InternalResource>;
+}

package/dist/types/internal-urls/mcp-protocol.d.ts

@@ -0,0 +1,12 @@
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+/**
+ * Protocol handler for mcp:// URLs.
+ *
+ * URL form:
+ * - mcp://<resource-uri> (e.g. mcp://test://notes, mcp://ibkr://portfolio/positions)
+ */
+export declare class McpProtocolHandler implements ProtocolHandler {
+    readonly scheme = "mcp";
+    readonly immutable = true;
+    resolve(url: InternalUrl): Promise<InternalResource>;
+}

package/dist/types/internal-urls/memory-protocol.d.ts

@@ -0,0 +1,17 @@
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+/**
+ * Resolve a memory:// URL to an absolute filesystem path under memory root.
+ */
+export declare function resolveMemoryUrlToPath(url: InternalUrl, memoryRoot: string): string;
+/**
+ * Protocol handler for memory:// URLs.
+ *
+ * Walks every active session's memory root. Worktree-based subagents have
+ * their own root; first one containing the file wins. Parent and subagent
+ * sharing a cwd see the same file regardless of order.
+ */
+export declare class MemoryProtocolHandler implements ProtocolHandler {
+    readonly scheme = "memory";
+    readonly immutable = true;
+    resolve(url: InternalUrl): Promise<InternalResource>;
+}

package/dist/types/internal-urls/omp-protocol.d.ts

@@ -0,0 +1,12 @@
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+/**
+ * Handler for omp:// URLs.
+ *
+ * Resolves documentation file names to their content, or lists available docs.
+ */
+export declare class OmpProtocolHandler implements ProtocolHandler {
+    #private;
+    readonly scheme = "omp";
+    readonly immutable = true;
+    resolve(url: InternalUrl): Promise<InternalResource>;
+}

package/dist/types/internal-urls/parse.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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";
+/**
+ * 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 declare function parseInternalUrl(input: string): InternalUrl;

package/dist/types/internal-urls/registry-helpers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function artifactsDirsFromRegistry(): string[];

package/dist/types/internal-urls/router.d.ts

@@ -0,0 +1,14 @@
+import type { InternalResource, ProtocolHandler, ResolveContext } from "./types";
+export declare class InternalUrlRouter {
+    #private;
+    constructor();
+    /** Process-global router instance. */
+    static instance(): InternalUrlRouter;
+    /** Reset the global instance in tests. */
+    static resetForTests(): void;
+    register(handler: ProtocolHandler): void;
+    unregister(scheme: string): boolean;
+    getHandler(scheme: string): ProtocolHandler | undefined;
+    canHandle(input: string): boolean;
+    resolve(input: string, context?: ResolveContext): Promise<InternalResource>;
+}

package/dist/types/internal-urls/rule-protocol.d.ts

@@ -0,0 +1,6 @@
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+export declare class RuleProtocolHandler implements ProtocolHandler {
+    readonly scheme = "rule";
+    readonly immutable = true;
+    resolve(url: InternalUrl): Promise<InternalResource>;
+}

package/dist/types/internal-urls/skill-protocol.d.ts

@@ -0,0 +1,13 @@
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+/**
+ * Validate that a path is safe (no traversal, no absolute paths).
+ */
+export declare function validateRelativePath(relativePath: string): void;
+/**
+ * Handler for skill:// URLs.
+ */
+export declare class SkillProtocolHandler implements ProtocolHandler {
+    readonly scheme = "skill";
+    readonly immutable = true;
+    resolve(url: InternalUrl): Promise<InternalResource>;
+}

package/dist/types/internal-urls/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Types for the internal URL routing system.
+ *
+ * Internal URLs (agent://, artifact://, memory://, skill://, rule://, mcp://, omp://, local://) are resolved by tools like read,
+ * providing access to agent outputs and server resources without exposing filesystem paths.
+ */
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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>;
+}

package/dist/types/lsp/client.d.ts

@@ -0,0 +1,65 @@
+import type { LspClient, ServerConfig } from "./types";
+/**
+ * Configure the idle timeout for LSP clients.
+ * @param ms - Timeout in milliseconds, or null/undefined to disable
+ */
+export declare function setIdleTimeout(ms: number | null | undefined): void;
+/** Timeout for warmup initialize requests (5 seconds) */
+export declare const WARMUP_TIMEOUT_MS = 5000;
+/**
+ * Get or create an LSP client for the given server configuration and working directory.
+ * @param config - Server configuration
+ * @param cwd - Working directory
+ * @param initTimeoutMs - Optional timeout for the initialize request (defaults to 30s)
+ */
+export declare function getOrCreateClient(config: ServerConfig, cwd: string, initTimeoutMs?: number): Promise<LspClient>;
+/**
+ * Ensure a file is opened in the LSP client.
+ * Sends didOpen notification if the file is not already tracked.
+ */
+export declare function ensureFileOpen(client: LspClient, filePath: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Wait for the server's initial project loading to complete.
+ * Races the server's $/progress tracking against the abort signal.
+ * Returns immediately if loading already completed or timed out.
+ */
+export declare function waitForProjectLoaded(client: LspClient, signal?: AbortSignal): Promise<void>;
+/**
+ * Sync in-memory content to the LSP client without reading from disk.
+ * Use this to provide instant feedback during edits before the file is saved.
+ */
+export declare function syncContent(client: LspClient, filePath: string, content: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Notify LSP that a file was saved.
+ * Assumes content was already synced via syncContent - just sends didSave.
+ */
+export declare function notifySaved(client: LspClient, filePath: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Refresh a file in the LSP client.
+ * Increments version, sends didChange and didSave notifications.
+ */
+export declare function refreshFile(client: LspClient, filePath: string, signal?: AbortSignal): Promise<void>;
+export declare function shutdownClient(key: string): Promise<void>;
+/**
+ * Send an LSP request and wait for response.
+ */
+export declare function sendRequest(client: LspClient, method: string, params: unknown, signal?: AbortSignal, timeoutMs?: number): Promise<unknown>;
+/**
+ * Send an LSP notification (no response expected).
+ */
+export declare function sendNotification(client: LspClient, method: string, params: unknown): Promise<void>;
+/**
+ * Shutdown all LSP clients.
+ */
+export declare function shutdownAll(): Promise<void>;
+/** Status of an LSP server */
+export interface LspServerStatus {
+    name: string;
+    status: "connecting" | "ready" | "error";
+    fileTypes: string[];
+    error?: string;
+}
+/**
+ * Get status of all active LSP clients.
+ */
+export declare function getActiveClients(): LspServerStatus[];

package/dist/types/lsp/clients/biome-client.d.ts

@@ -0,0 +1,16 @@
+import type { Diagnostic, LinterClient, ServerConfig } from "../../lsp/types";
+/**
+ * Biome CLI-based linter client.
+ * Parses Biome's --reporter=json output into LSP Diagnostic format.
+ */
+export declare class BiomeClient implements LinterClient {
+    #private;
+    private readonly config;
+    private readonly cwd;
+    /** Factory method for creating BiomeClient instances */
+    static create(config: ServerConfig, cwd: string): LinterClient;
+    constructor(config: ServerConfig, cwd: string);
+    format(filePath: string, content: string): Promise<string>;
+    lint(filePath: string): Promise<Diagnostic[]>;
+    dispose(): void;
+}

package/dist/types/lsp/clients/index.d.ts

@@ -0,0 +1,19 @@
+import type { LinterClient, ServerConfig } from "../../lsp/types";
+/**
+ * Linter client implementations.
+ *
+ * The LinterClient interface provides a common API for formatters and linters.
+ * Different implementations can use LSP protocol, CLI tools, or other mechanisms.
+ */
+export { BiomeClient } from "./biome-client";
+export { LspLinterClient } from "./lsp-linter-client";
+export { SwiftLintClient } from "./swiftlint-client";
+/**
+ * Get or create a linter client for a server configuration.
+ * Uses the server's custom factory if provided, otherwise falls back to LSP.
+ */
+export declare function getLinterClient(serverName: string, config: ServerConfig, cwd: string): LinterClient;
+/**
+ * Clear all cached linter clients.
+ */
+export declare function clearLinterClientCache(): void;

package/dist/types/lsp/clients/lsp-linter-client.d.ts

@@ -0,0 +1,16 @@
+import type { Diagnostic, LinterClient, ServerConfig } from "../../lsp/types";
+/**
+ * LSP-based linter client implementation.
+ * Wraps the existing LSP client infrastructure.
+ */
+export declare class LspLinterClient implements LinterClient {
+    #private;
+    private readonly config;
+    private readonly cwd;
+    /** Factory method for creating LspLinterClient instances */
+    static create(config: ServerConfig, cwd: string): LinterClient;
+    constructor(config: ServerConfig, cwd: string);
+    format(filePath: string, content: string): Promise<string>;
+    lint(filePath: string): Promise<Diagnostic[]>;
+    dispose(): void;
+}

package/dist/types/lsp/clients/swiftlint-client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SwiftLint CLI-based linter client.
+ * Parses SwiftLint's JSON reporter output into LSP Diagnostic format.
+ */
+import type { Diagnostic, LinterClient, ServerConfig } from "../../lsp/types";
+/**
+ * SwiftLint CLI-based linter client.
+ * Runs `swiftlint lint --reporter json` and converts violations to LSP diagnostics.
+ */
+export declare class SwiftLintClient implements LinterClient {
+    #private;
+    private readonly config;
+    private readonly cwd;
+    /** Factory method for creating SwiftLintClient instances */
+    static create(config: ServerConfig, cwd: string): LinterClient;
+    constructor(config: ServerConfig, cwd: string);
+    format(_filePath: string, content: string): Promise<string>;
+    lint(filePath: string): Promise<Diagnostic[]>;
+    dispose(): void;
+}

package/dist/types/lsp/config.d.ts

@@ -0,0 +1,65 @@
+import type { ServerConfig } from "./types";
+export interface LspConfig {
+    servers: Record<string, ServerConfig>;
+    /** Idle timeout in milliseconds. If set, LSP clients will be shutdown after this period of inactivity. Disabled by default. */
+    idleTimeoutMs?: number;
+}
+/**
+ * Check if any root marker file exists in the directory
+ */
+export declare function hasRootMarkers(cwd: string, markers: string[]): boolean;
+/**
+ * Resolve a command to an executable path.
+ * Checks project-local bin directories first, then falls back to $PATH.
+ *
+ * @param command - The command name (e.g., "typescript-language-server")
+ * @param cwd - Working directory to search from
+ * @returns Absolute path to the executable, or null if not found
+ */
+export declare function resolveCommand(command: string, cwd: string): string | null;
+/**
+ * Load LSP configuration.
+ *
+ * Priority (highest to lowest):
+ * 1. Project root: lsp.json/.lsp.json/lsp.yml/.lsp.yml/lsp.yaml/.lsp.yaml
+ * 2. Project config dirs: .omp/lsp.*, .pi/lsp.*, .claude/lsp.* (+ hidden variants)
+ * 3. User config dirs: ~/.omp/agent/lsp.*, ~/.pi/agent/lsp.*, ~/.claude/lsp.* (+ hidden variants)
+ * 4. User home root: ~/lsp.*, ~/.lsp.*
+ * 5. Auto-detect from project markers + available binaries
+ *
+ * Config files are merged from lowest to highest priority; later files override earlier settings.
+ *
+ * Config file format (JSON or YAML):
+ * ```json
+ * {
+ *   "servers": {
+ *     "typescript-language-server": {
+ *       "command": "typescript-language-server",
+ *       "args": ["--stdio", "--log-level", "4"],
+ *       "disabled": false
+ *     },
+ *     "my-custom-server": {
+ *       "command": "/path/to/server",
+ *       "args": ["--stdio"],
+ *       "fileTypes": [".xyz"],
+ *       "rootMarkers": [".xyz-project"]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function loadConfig(cwd: string): LspConfig;
+/**
+ * Find all servers that can handle a file based on extension.
+ * Returns servers sorted with primary (non-linter) servers first.
+ */
+export declare function getServersForFile(config: LspConfig, filePath: string): Array<[string, ServerConfig]>;
+/**
+ * Find the primary server for a file (prefers type-checkers over linters).
+ * Used for operations like definition, hover, references that need type intelligence.
+ */
+export declare function getServerForFile(config: LspConfig, filePath: string): [string, ServerConfig] | null;
+/**
+ * Check if a server has a specific capability
+ */
+export declare function hasCapability(config: ServerConfig, capability: keyof NonNullable<ServerConfig["capabilities"]>): boolean;

package/dist/types/lsp/edits.d.ts

@@ -0,0 +1,16 @@
+import type { TextEdit, WorkspaceEdit } from "./types";
+/**
+ * Apply text edits to a string in-memory.
+ * Edits are applied in reverse order (bottom-to-top) to preserve line/character indices.
+ */
+export declare function applyTextEditsToString(content: string, edits: TextEdit[]): string;
+/**
+ * Apply text edits to a file.
+ * Edits are applied in reverse order (bottom-to-top) to preserve line/character indices.
+ */
+export declare function applyTextEdits(filePath: string, edits: TextEdit[]): Promise<void>;
+/**
+ * Apply a workspace edit (collection of file changes).
+ * Returns array of applied change descriptions.
+ */
+export declare function applyWorkspaceEdit(edit: WorkspaceEdit, cwd: string): Promise<string[]>;