jeopi-cli 16.2.14 → 16.2.17

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

@@ -0,0 +1,13 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+/**
+ * Handler for agent:// URLs.
+ *
+ * Resolves output IDs like "reviewer_0" to their artifact files,
+ * with optional JSON extraction.
+ */
+export declare class AgentProtocolHandler implements ProtocolHandler {
+    readonly scheme = "agent";
+    readonly immutable = true;
+    resolve(url: InternalUrl): Promise<InternalResource>;
+    complete(): Promise<UrlCompletion[]>;
+}

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

@@ -0,0 +1,7 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion } from "./types";
+export declare class ArtifactProtocolHandler implements ProtocolHandler {
+    readonly scheme = "artifact";
+    readonly immutable = true;
+    resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+    complete(): Promise<UrlCompletion[]>;
+}

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

@@ -0,0 +1,19 @@
+export interface DocsIndex {
+    /** Sorted documentation file names, relative to `docs/`. */
+    readonly filenames: readonly string[];
+    /** Resolve a doc body by path; inflates the embedded bodies off-thread, lazily, on first call. */
+    getBody(relativePath: string): Promise<string | undefined>;
+}
+/**
+ * Decode a populated two-line embed (`<filenames JSON>\n<base64 gzip of bodies>`)
+ * into a lazily-inflating index, or `null` when there is no newline separator
+ * (the empty placeholder, or a malformed payload — the caller decides which).
+ * Reading `filenames` never touches the blob; the bodies are gunzipped off the
+ * event loop into a path→content table on the first `getBody` call, and that
+ * work is shared across concurrent reads.
+ */
+export declare function decodeDocsIndex(embed: string): DocsIndex | null;
+/** Sorted list of available documentation file names (relative to `docs/`). */
+export declare function getDocFilenames(): readonly string[];
+/** Resolve a documentation file's content, or `undefined` when not found. */
+export declare function getEmbeddedDoc(relativePath: string): Promise<string | undefined>;

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

@@ -0,0 +1,9 @@
+import type { InternalResource } from "./types";
+/**
+ * Builds a text resource for a filesystem directory resolved by an internal URL handler.
+ *
+ * The resource is flagged immutable so the read tool never mints hashline edit
+ * anchors against a directory listing — only file resources from the same
+ * handler stay editable.
+ */
+export declare function buildDirectoryResource(url: string, directoryPath: string, notes?: string[]): Promise<InternalResource>;

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

@@ -0,0 +1,14 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+/**
+ * Handler for history:// URLs.
+ *
+ * Resolves agent ids against the global AgentRegistry, serving transcripts
+ * for both live and parked agents.
+ */
+export declare class HistoryProtocolHandler implements ProtocolHandler {
+    #private;
+    readonly scheme = "history";
+    readonly immutable = false;
+    resolve(url: InternalUrl): Promise<InternalResource>;
+    complete(): Promise<UrlCompletion[]>;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * 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 "./history-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 * from "./ssh-protocol";
+export type * from "./types";
+export * from "./vault-protocol";

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,79 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion } from "./types";
+export interface LocalProtocolOptions {
+    getArtifactsDir?: () => string | null;
+    getSessionId?: () => string | null;
+}
+/** Resolve the session-scoped local:// root, shortening long Windows artifact paths before writes hit MAX_PATH. */
+export declare function resolveLocalRoot(options: LocalProtocolOptions, platform?: NodeJS.Platform): string;
+/** Resolve a local:// URL to an on-disk path under the active session's local root. */
+export declare function resolveLocalUrlToPath(input: string | InternalUrl, options: LocalProtocolOptions, platform?: NodeJS.Platform): string;
+/**
+ * On-disk roots the eval helpers (`read`/`write`) substitute for
+ * internal-URL schemes so e.g. `write("local://x.md")` lands where a later
+ * `read local://x.md` resolves — instead of a literal `local:/` directory under
+ * the cwd (a stdlib `pathlib.Path`/`path.resolve` collapses `local://` to
+ * `local:/`). Keyed by scheme without the `://`. Currently only `local`, but the
+ * shape is a map so additional file-backed schemes can be added without
+ * re-plumbing the worker boundary.
+ */
+export declare function buildEvalUrlRoots(options: LocalProtocolOptions): Record<string, string>;
+/**
+ * Resolve a local:// URL to a regular on-disk file, applying the same
+ * realpath + containment guarantees as {@link LocalProtocolHandler.resolve}
+ * but WITHOUT reading or UTF-8-decoding its contents. Returns null when there
+ * is no active session or when the URL targets the root listing or a directory;
+ * throws the handler's not-found and "escapes local root" errors for missing
+ * files and symlink escapes.
+ *
+ * Options are resolved via {@link LocalProtocolHandler.resolveOptions} so the
+ * caller-options → override → registry order matches router resolution exactly.
+ * The read tool uses this to detect and emit image files from their real path
+ * before the text-only resource contract would decode the binary into mojibake.
+ */
+export declare function resolveLocalUrlToFile(input: string | InternalUrl, context?: ResolveContext): Promise<{
+    path: string;
+    size: number;
+} | null>;
+/**
+ * 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. **Caller-supplied** `context.localProtocolOptions` (the actual session
+     *    that initiated the `read`/`find`/`search`/`router.resolve` call). This
+     *    is what keeps `local://` reads pinned to the calling session in
+     *    multi-session hosts (cmux/ACP, embedded SDK consumers) where every
+     *    session registers as `kind: "main"` and "first one wins" would route
+     *    to the wrong artifacts directory.
+     * 2. Explicit process-global override installed via {@link setOverride}
+     *    (used by SDK consumers with a custom artifacts/session-id mapping and
+     *    by code paths that do not have a calling session, e.g. TUI hyperlink
+     *    resolution).
+     * 3. The first `main`-kind session in `AgentRegistry.global()`. Its
+     *    `SessionManager` supplies both `getArtifactsDir` and `getSessionId`.
+     *    Last-resort fallback — every caller that has a session reference
+     *    SHOULD thread it through `context` so this branch is never taken in
+     *    multi-session setups.
+     */
+    static resolveOptions(context?: ResolveContext): LocalProtocolOptions | undefined;
+    resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+    complete(_query?: string, context?: ResolveContext): Promise<UrlCompletion[]>;
+}

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,24 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } from "./types";
+/**
+ * Snapshot of memory roots for every registered session, deduped.
+ * Each session has its own cwd (possibly a worktree), so subagents and main
+ * may see different roots.
+ */
+export declare function memoryRootsFromRegistry(): string[];
+/**
+ * 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>;
+    complete(): Promise<UrlCompletion[]>;
+}

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

@@ -0,0 +1,13 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, UrlCompletion } 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>;
+    complete(): Promise<UrlCompletion[]>;
+}

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,12 @@
+export declare function registerArtifactsDir(dir: string): () => void;
+export declare function resetRegisteredArtifactDirsForTests(): void;
+/**
+ * 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,21 @@
+import type { InternalResource, ProtocolHandler, ResolveContext, UrlCompletion } 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;
+    /** Schemes whose handler supports host/path autocomplete. */
+    completionSchemes(): string[];
+    /**
+     * Candidate completions for the host/path portion of `scheme://<query>`.
+     * Returns `null` when the scheme is unknown or does not support completion.
+     */
+    complete(scheme: string, query: string, context?: ResolveContext): Promise<UrlCompletion[] | null>;
+    resolve(input: string, context?: ResolveContext): Promise<InternalResource>;
+}

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

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

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

@@ -0,0 +1,14 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion } 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, context?: ResolveContext): Promise<InternalResource>;
+    complete(): Promise<UrlCompletion[]>;
+}

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

@@ -0,0 +1,10 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, UrlCompletion, WriteContext } from "./types";
+export declare class SshProtocolHandler implements ProtocolHandler {
+    #private;
+    readonly scheme = "ssh";
+    readonly immutable = false;
+    resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+    /** Autocomplete the host segment of `ssh://` with the configured SSH hosts. */
+    complete(_query?: string, context?: ResolveContext): Promise<UrlCompletion[]>;
+    write(url: InternalUrl, content: string, context?: WriteContext): Promise<void>;
+}

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

@@ -0,0 +1,165 @@
+/**
+ * Types for the internal URL routing system.
+ *
+ * Internal URLs (`agent://`, `artifact://`, `history://`, `issue://`, `local://`, `mcp://`, `memory://`, `omp://`, `pr://`, `rule://`, `skill://`, `ssh://`, and `vault://`) are resolved by tools like read,
+ * providing access to agent outputs and server resources without exposing filesystem paths.
+ */
+import type { Skill } from "../extensibility/skills";
+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;
+    /**
+     * True when the resource is a directory listing rather than file content.
+     * `search` refuses to grep such a resource when it has no `sourcePath` — a
+     * remote `ssh://` listing has no local path to recurse, so its listing text
+     * must never be mistaken for the directory's contents.
+     */
+    isDirectory?: 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;
+    /** Calling session's loaded skills. Prefer this over process-global skill state. */
+    skills?: readonly Skill[];
+    /**
+     * When set, handlers that would otherwise materialize an expensive directory
+     * listing (e.g. the ssh:// handler draining a full remote `ls`) instead return
+     * the directory shape (`isDirectory: true`) with empty content. `search`/`find`
+     * reject directory resources, so they never need the listing.
+     */
+    skipDirectoryListing?: boolean;
+}
+/**
+ * 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.
+     * `context.cwd`/`context.localProtocolOptions` carry the caller's working dir
+     * and session, for handlers whose candidates are project- or session-scoped
+     * (e.g. ssh:// hosts from a project `ssh.json`, local:// roots per session).
+     */
+    complete?(query?: string, context?: ResolveContext): Promise<UrlCompletion[]>;
+}

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

@@ -0,0 +1,93 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, WriteContext } from "./types";
+type ContentType = InternalResource["contentType"];
+type VaultParamValue = string | true;
+type VaultParams = Record<string, VaultParamValue>;
+type FileOp = "outline" | "backlinks" | "links" | "tags" | "properties" | "tasks" | "wordcount" | "history" | "base";
+type VaultOp = "search" | "daily" | "daily-path" | "tags" | "tag" | "tasks" | "orphans" | "unresolved" | "deadends" | "bases" | "bookmarks" | "recents" | "templates" | "aliases" | "properties" | "property";
+export interface VaultReference {
+    vault: string | null;
+    active: boolean;
+    forwardVault: boolean;
+    display: string;
+}
+export type ParsedVaultUrl = {
+    kind: "list-vaults";
+    url: string;
+    params: VaultParams;
+} | {
+    kind: "vault-info";
+    url: string;
+    ref: VaultReference;
+    params: VaultParams;
+} | {
+    kind: "fs-dir";
+    url: string;
+    ref: VaultReference;
+    relativePath: string;
+    params: VaultParams;
+} | {
+    kind: "fs-file";
+    url: string;
+    ref: VaultReference;
+    relativePath: string;
+    params: VaultParams;
+} | {
+    kind: "file-op";
+    url: string;
+    ref: VaultReference;
+    relativePath: string;
+    op: FileOp;
+    params: VaultParams;
+} | {
+    kind: "vault-op";
+    url: string;
+    ref: VaultReference;
+    op: VaultOp;
+    params: VaultParams;
+};
+export interface ObsidianSpawnResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface VaultProtocolHandlerOptions {
+    spawnObsidian?: typeof spawnObsidian;
+    resolveObsidianBinary?: () => string | null;
+}
+interface CliInvocation {
+    args: string[];
+    contentType: ContentType;
+    opLabel: string;
+}
+export declare function parseVaultUrl(input: string | InternalUrl): ParsedVaultUrl;
+export declare function spawnObsidian(bin: string, args: string[], signal?: AbortSignal, timeoutMs?: number): Promise<ObsidianSpawnResult>;
+export declare function resolveObsidianBinary(): string | null;
+/**
+ * Whether the `vault://` protocol is enabled in the active settings profile.
+ *
+ * Reads `vault.enabled` from the global settings singleton. Falls back to the
+ * schema default when settings are not yet initialized (e.g. during isolated
+ * unit tests that exercise the handler before the host calls `Settings.init`).
+ */
+export declare function isVaultEnabled(): boolean;
+export declare function hasObsidian(): boolean;
+export declare class VaultDisabledError extends Error {
+    constructor();
+}
+export declare function resolveVaultUrlToPath(input: string | InternalUrl): string;
+export declare function buildObsidianCliInvocation(parsed: Extract<ParsedVaultUrl, {
+    kind: "file-op" | "vault-op";
+}>): CliInvocation;
+export declare class VaultProtocolHandler implements ProtocolHandler {
+    #private;
+    readonly scheme = "vault";
+    readonly immutable = false;
+    constructor(options?: VaultProtocolHandlerOptions);
+    static resetForTests(): void;
+    static setObsidianBinaryForTests(value: string | null | undefined): void;
+    static setVaultDirectoryForTests(entries: ReadonlyMap<string, string> | Record<string, string> | undefined): void;
+    static setActiveVaultPathForTests(vaultPath: string | undefined): void;
+    resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+    write(url: InternalUrl, content: string, context?: WriteContext): Promise<void>;
+}
+export {};