@xiaoso/dsh-tool-plus 0.1.7-beta.0 → 0.1.7-beta.1

package/lib/types/tools/omp/edit/modes/replace.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Fuzzy matching utilities for the edit tool.
+ *
+ * Provides both character-level and line-level fuzzy matching with progressive
+ * fallback strategies for finding text in files.
+ */
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { WritethroughCallback } from "../../../omp/tools/writethrough.ts";
+import type { ToolSession } from "../../../omp/tools/index.ts";
+import type { EditToolDetails } from "../details";
+export interface FuzzyMatch {
+    actualText: string;
+    startIndex: number;
+    startLine: number;
+    confidence: number;
+}
+export interface MatchOutcome {
+    match?: FuzzyMatch;
+    closest?: FuzzyMatch;
+    occurrences?: number;
+    occurrenceLines?: number[];
+    occurrencePreviews?: string[];
+    fuzzyMatches?: number;
+    dominantFuzzy?: boolean;
+}
+export type SequenceMatchStrategy = "exact" | "trim-trailing" | "trim" | "comment-prefix" | "unicode" | "prefix" | "substring" | "fuzzy" | "fuzzy-dominant" | "character";
+export interface SequenceSearchResult {
+    index: number | undefined;
+    confidence: number;
+    matchCount?: number;
+    matchIndices?: number[];
+    strategy?: SequenceMatchStrategy;
+}
+export type ContextMatchStrategy = "exact" | "trim" | "unicode" | "prefix" | "substring" | "fuzzy";
+export interface ContextLineResult {
+    index: number | undefined;
+    confidence: number;
+    matchCount?: number;
+    matchIndices?: number[];
+    strategy?: ContextMatchStrategy;
+}
+export declare class EditMatchError extends Error {
+    readonly path: string;
+    readonly searchText: string;
+    readonly closest: FuzzyMatch | undefined;
+    readonly options: {
+        allowFuzzy: boolean;
+        threshold: number;
+        fuzzyMatches?: number;
+    };
+    constructor(path: string, searchText: string, closest: FuzzyMatch | undefined, options: {
+        allowFuzzy: boolean;
+        threshold: number;
+        fuzzyMatches?: number;
+    });
+    static formatMessage(path: string, searchText: string, closest: FuzzyMatch | undefined, options: {
+        allowFuzzy: boolean;
+        threshold: number;
+        fuzzyMatches?: number;
+    }): string;
+}
+/** Default similarity threshold for fuzzy matching */
+export declare const DEFAULT_FUZZY_THRESHOLD = 0.95;
+/** Compute Levenshtein distance between two strings */
+export declare function levenshteinDistance(a: string, b: string): number;
+/** Compute similarity score between two strings (0 to 1) */
+export declare function similarity(a: string, b: string): number;
+/**
+ * Find a match for target text within content.
+ * Used primarily for replace-mode edits; excluded ranges remain invisible to exact and fuzzy matching.
+ */
+export declare function findMatch(content: string, target: string, options: {
+    allowFuzzy: boolean;
+    threshold?: number;
+    excludedRanges?: readonly {
+        startIndex: number;
+        endIndex: number;
+    }[];
+}): MatchOutcome;
+/**
+ * Find a sequence of pattern lines within content lines.
+ *
+ * Attempts matches with decreasing strictness:
+ * 1. Exact match
+ * 2. Trailing whitespace ignored
+ * 3. All whitespace trimmed
+ * 4. Unicode punctuation normalized
+ * 5. Prefix match (pattern is prefix of line)
+ * 6. Substring match (pattern is substring of line)
+ * 7. Fuzzy similarity match
+ *
+ * @param lines - The lines of the file content
+ * @param pattern - The lines to search for
+ * @param start - Starting index for the search
+ * @param eof - If true, prefer matching at end of file first
+ */
+export declare function seekSequence(lines: string[], pattern: string[], start: number, eof: boolean, options?: {
+    allowFuzzy?: boolean;
+}): SequenceSearchResult;
+export declare function findClosestSequenceMatch(lines: string[], pattern: string[], options?: {
+    start?: number;
+    eof?: boolean;
+}): {
+    index: number | undefined;
+    confidence: number;
+    strategy: SequenceMatchStrategy;
+};
+/**
+ * Find a context line in the file using progressive matching strategies.
+ *
+ * @param lines - The lines of the file content
+ * @param context - The context line to search for
+ * @param startFrom - Starting index for the search
+ */
+export declare function findContextLine(lines: string[], context: string, startFrom: number, options?: {
+    allowFuzzy?: boolean;
+    skipFunctionFallback?: boolean;
+}): ContextLineResult;
+export declare const replaceEditSchema: import("@oh-my-pi/omptype").FluentType<{
+    path: string;
+    old_string: string;
+    new_string: string;
+    replace_all?: boolean | undefined;
+}, {
+    path: string;
+    old_string: string;
+    new_string: string;
+    replace_all?: boolean | undefined;
+}>;
+export type ReplaceParams = typeof replaceEditSchema.infer;
+/**
+ * Internal batch form of {@link ReplaceParams}, produced only by the Cursor
+ * exec bridge: a `pi_edit` frame carries several replacements against one
+ * path but must run as a single tool lifecycle with one aggregate result.
+ * Never advertised to the model — the agent loop validates model calls
+ * against {@link replaceEditSchema}, which has no `edits` field.
+ */
+export interface ReplaceBatchParams {
+    path: string;
+    edits: Omit<ReplaceParams, "path">[];
+}
+export interface ExecuteReplaceOptions {
+    session: ToolSession;
+    path: string;
+    params: Omit<ReplaceParams, "path">;
+    signal?: AbortSignal;
+    allowFuzzy: boolean;
+    fuzzyThreshold: number;
+    writethrough: WritethroughCallback;
+}
+export declare function executeReplace(options: ExecuteReplaceOptions): Promise<AgentToolResult<EditToolDetails, ReplaceParams>>;

package/lib/types/tools/omp/edit/normalize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Text normalization utilities for the edit tool.
+ *
+ * Whitespace, Unicode, and indentation helpers. Line-ending and BOM
+ * primitives live in `@oh-my-pi/hashline` and are re-exported here so
+ * existing consumers see one stable surface.
+ */
+export { type BomResult, detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom, } from "@oh-my-pi/hashline";
+/** Count leading whitespace characters in a line */
+export declare function countLeadingWhitespace(line: string): number;
+/** Get the leading whitespace string from a line */
+export declare function getLeadingWhitespace(line: string): string;
+/** Compute minimum indentation of non-empty lines */
+export declare function minIndent(text: string): number;
+/** Detect the indentation character used in text (space or tab) */
+export declare function detectIndentChar(text: string): string;
+export declare function convertLeadingTabsToSpaces(text: string, spacesPerTab: number): string;
+export declare function normalizeUnicode(s: string): string;
+/**
+ * Normalize a line for fuzzy comparison.
+ * Trims, collapses whitespace, and normalizes punctuation.
+ */
+export declare function normalizeForFuzzy(line: string): string;
+/**
+ * Adjust newText indentation to match the indentation delta between
+ * what was provided (oldText) and what was actually matched (actualText).
+ *
+ * If oldText has 0 indent but actualText has 12 spaces, we add 12 spaces
+ * to each line in newText.
+ */
+export declare function adjustIndentation(oldText: string, actualText: string, newText: string): string;

package/lib/types/tools/omp/edit/notebook.d.ts

@@ -0,0 +1,50 @@
+export type NotebookCellType = "code" | "markdown" | "raw";
+export interface NotebookCell {
+    cell_type: NotebookCellType;
+    source?: string | string[];
+    metadata?: Record<string, unknown>;
+    execution_count?: number | null;
+    outputs?: unknown[];
+    [key: string]: unknown;
+}
+export interface NotebookDocument {
+    cells: NotebookCell[];
+    metadata: Record<string, unknown>;
+    nbformat: number;
+    nbformat_minor: number;
+    [key: string]: unknown;
+}
+export declare function isNotebookPath(filePath: string): boolean;
+export declare function splitNotebookSource(content: string): string[];
+export declare function readNotebookDocument(absolutePath: string, displayPath: string): Promise<NotebookDocument>;
+export declare function applyNotebookEditableText(notebook: NotebookDocument, text: string, displayPath: string): NotebookDocument;
+/**
+ * Decode a notebook for display and for hashline anchoring.
+ *
+ * The decode is the **engine's own codec** — `pi-natives`
+ * `notebookToEditableText`, the same call upstream's read tool makes
+ * (`refs/oh-my-pi/packages/coding-agent/src/tools/read.ts:1599`) — not a
+ * second TS implementation. That matters beyond tidiness: `read` mints the
+ * hashline tag over this projection and the edit engine validates the live
+ * file by projecting it the same way (`crates/pi-edit/src/files.rs:138-142`),
+ * so once both sides run the same code their agreement is structural. A
+ * hand-maintained copy can only *resemble* the engine, and the first
+ * divergence (BOM handling, cell escaping, cell join) silently turns every
+ * edit into "file changed between read and edit".
+ *
+ * Error text is identical to the previous TS decoder, verified over the whole
+ * corpus including BOM and every failure shape: the Rust `NotebookError`
+ * `Display` strings are verbatim ports. Only ENOENT is ours, because the read
+ * has to happen here to keep the `File not found: <display>` message the
+ * `read` tool and the patch/replace modes rely on.
+ *
+ * What stays in this file is the **encode** half (`readNotebookDocument` +
+ * `applyNotebookEditableText` + `serializeEditedNotebookText`), which
+ * `native/writer.ts` no longer uses — the engine serializes notebooks itself
+ * for the hashline path. It survives only because the native surface exposes
+ * no encoder and DSH's own patch/replace/write paths still need one; deleting
+ * it means migrating those modes onto the Rust engine (the same move this
+ * migration made for hashline), which is the remaining half of the work.
+ */
+export declare function readEditableNotebookText(absolutePath: string, displayPath: string): Promise<string>;
+export declare function serializeEditedNotebookText(absolutePath: string, displayPath: string, text: string): Promise<string>;

package/lib/types/tools/omp/edit/read-file.d.ts

@@ -0,0 +1,2 @@
+export declare function readEditFileText(absolutePath: string, path: string): Promise<string>;
+export declare function serializeEditFileText(absolutePath: string, path: string, content: string): Promise<string>;

package/lib/types/tools/omp/edit/snapshot-details.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Bound the size of the `oldText` / `newText` snapshots that edit-tool results
+ * carry in `details`. These fields hold the full pre/post file content; for
+ * large files they balloon the per-turn JSONL line and the session file
+ * (300 KB+ each on the cases reported in #3786) without paying for any LLM
+ * context (provider serializers send only `content`, never `details`).
+ *
+ * Only consumer of the raw snapshots is the ACP event mapper, which builds a
+ * `diff` ToolCallContent for ACP clients (Zed). When the snapshots are pruned
+ * the mapper returns `undefined` for that file and the text content still
+ * flows — diff visualization degrades gracefully for over-threshold edits.
+ */
+import type { EditToolDetails, EditToolPerFileResult } from "./details";
+/**
+ * Combined `oldText` + `newText` character budget for a single edit-tool
+ * result. Applies both per-entry (one file at a time) and as an aggregate
+ * across `perFileResults` (so a many-small-files batch can't accumulate
+ * unbounded snapshot bytes — see #3787 review).
+ *
+ * Picked so typical code-file edits keep ACP diff visualization while
+ * pathological cases (large generated files, full-file rewrites, or
+ * many-file batches) drop the raw snapshots before they hit the
+ * session JSONL.
+ */
+export declare const MAX_EDIT_SNAPSHOT_TEXT_CHARS = 32768;
+/**
+ * Prune oversized `oldText` / `newText` from an edit-tool details payload,
+ * recursing into `perFileResults` when present. Per-file overload comes first
+ * so the more specific shape (required `path`) wins overload resolution at
+ * the per-file call sites.
+ */
+export declare function pruneOversizedEditSnapshots(details: EditToolPerFileResult): EditToolPerFileResult;
+export declare function pruneOversizedEditSnapshots(details: EditToolDetails): EditToolDetails;

package/lib/types/tools/omp/extensibility/skills.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DSH adapter for OMP `extensibility/skills.ts` — the `Skill` type
+ * referenced by `tools/path-utils.ts` (skill:// resolution). DSH has no
+ * skill:// protocol; the type is provided verbatim so path-utils compiles.
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    source: string;
+    /** When true, loaded but excluded from rendered <skills> listing. */
+    hide?: boolean;
+    /** Filesystem-resolved plugin root for Agent Plugin skills. */
+    containRoot?: string;
+    /** Source metadata for display */
+    _source?: {
+        provider: string;
+        kind?: string;
+        category?: string;
+    };
+}

package/lib/types/tools/omp/internal-urls/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * DSH adapter for OMP `internal-urls/` — the internal URL protocol system
+ * (agent://, memory://, skill://, local://, …).
+ *
+ * plan.md 判定：DSH 无 OMP 内部 URL 协议（read/write 不解析这些 scheme），
+ * 因此适配层仅提供 `path-utils` 引用的表面：
+ * - `LocalProtocolOptions`（verbatim 类型）
+ * - `InternalUrlRouter`（空路由：canHandle 恒 false —— DSH 没有可解析的
+ *   内部协议；engine 的调用方在 canHandle=false 时走普通路径解析）
+ */
+export interface LocalProtocolOptions {
+    getArtifactsDir?: () => string | null;
+    getSessionId?: () => string | null;
+}
+/** Raw resource payload shape (verbatim OMP, unused in DSH). */
+export interface InternalResource {
+    url: string;
+    content: string;
+    contentType: 'text/markdown' | 'application/json' | 'text/plain';
+    size?: number;
+    sourcePath?: string;
+    immutable?: boolean;
+    /** 目录形态标记（verbatim 引擎在 resolve 后读取；空路由永不产生）。 */
+    isDirectory?: boolean;
+}
+/** Resolve context passed to router handlers (verbatim OMP surface). */
+export interface ResolveContext {
+    cwd?: string;
+    signal?: AbortSignal;
+    localProtocolOptions?: LocalProtocolOptions;
+    pathOnly?: boolean;
+    settings?: unknown;
+    skills?: readonly unknown[];
+    /** Session-bound `xd://` documentation resolver. */
+    xd?: {
+        read: (name: string | null) => Promise<string>;
+    };
+}
+/** Write context passed to router write handlers (verbatim OMP surface). */
+export interface WriteContext {
+    cwd?: string;
+    signal?: AbortSignal;
+    localProtocolOptions?: LocalProtocolOptions;
+    /** Session-bound `xd://` device dispatcher. */
+    xd?: {
+        write(name: string | null, content: string): Promise<void>;
+    };
+}
+/** Internal URL shape (verbatim OMP minimal surface). */
+export interface InternalUrl {
+    scheme: string;
+    host: string;
+    pathname: string;
+    search?: string;
+    hash?: string;
+}
+/** Loose URL shape accepted by resolvers (parse.ts's InternalUrl extends URL). */
+type InternalUrlLike = {
+    protocol?: string;
+    host?: string;
+    pathname: string;
+    search?: string;
+    hash?: string;
+};
+/** Parse an internal URL into its parts (verbatim OMP semantics). */
+export declare function parseInternalUrl(input: string): InternalUrl;
+/** Minimal router: no internal protocol handlers are registered in DSH. */
+export declare class InternalUrlRouter {
+    #private;
+    static instance(): InternalUrlRouter;
+    canHandle(_url: string): boolean;
+    canResolve(_input: string): boolean;
+    /** Completion is part of the verbatim engine surface（grep.ts）；空路由恒无候选。 */
+    complete(_scheme: string, _query: string, _context?: ResolveContext): Promise<import('./types.ts').UrlCompletion[] | null>;
+    getHandler(_scheme: string): {
+        write?: (url: unknown, content: string, context?: unknown) => Promise<void>;
+    } | undefined;
+    resolve(_url: string, _context?: ResolveContext): Promise<InternalResource>;
+    write(_input: string, _content: string, _context?: WriteContext): Promise<void>;
+}
+/** DSH: no local:// sandbox — resolve to the raw path. */
+export declare function resolveLocalUrlToPath(input: string | InternalUrlLike, _options?: LocalProtocolOptions, _platform?: NodeJS.Platform): string;
+/** DSH: no memory root registry — empty. */
+export declare function memoryRootsFromRegistry(): string[];
+/** DSH: no memory:// backing — resolve to the raw path. */
+export declare function resolveMemoryUrlToPath(url: InternalUrl, _memoryRoot: string): string;
+/** DSH: no local:// sandbox — static handler with no options. */
+export declare class LocalProtocolHandler {
+    static resolveOptions(_context?: ResolveContext): LocalProtocolOptions | undefined;
+}
+/** DSH: no local:// sandbox — the local root is the cwd. */
+export declare function resolveLocalRoot(_options: LocalProtocolOptions, _platform?: NodeJS.Platform): string;
+/** DSH: no vault:// — resolve to the raw path. */
+export declare function resolveVaultUrlToPath(input: string | InternalUrlLike): string;
+/** DSH: no local:// file backing — resolve to nothing (caller falls back to text path). */
+export declare function resolveLocalUrlToFile(_input: string | InternalUrlLike, _context?: ResolveContext): Promise<{
+    path: string;
+    size: number;
+} | null>;
+export {};

package/lib/types/tools/omp/internal-urls/local-protocol.d.ts

@@ -0,0 +1,12 @@
+/**
+ * DSH adapter for OMP `internal-urls/local-protocol.ts`.
+ *
+ * plan.md 判定：DSH 无 local:// 内部协议（internal-urls 空路由
+ * canHandle 恒 false），local:// 解析实现整体删除；仅保留 verbatim 的
+ * `LocalProtocolOptions` 类型面，供 `internal-urls/types.ts` 与 grep 的
+ * verbatim grep.ts 类型引用。
+ */
+export interface LocalProtocolOptions {
+    getArtifactsDir?: () => string | null;
+    getSessionId?: () => string | null;
+}

package/lib/types/tools/omp/internal-urls/parse.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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";
+/**
+ * Extract the lowercased scheme from a URI-shaped input, or `undefined` when
+ * the input does not look like a URI.
+ *
+ * Accepts both hierarchical (`scheme://…`) and opaque (`scheme:rest`) forms —
+ * MCP resource URIs may be opaque (`urn:example:document`, `custom:item`).
+ * The opaque form is guarded against path-like false positives:
+ * - Windows drive paths (`C:\…`, `C:/…`, `C:foo`) — single-letter scheme.
+ * - Filenames with extensions (`foo.ts:50`) — dot in the scheme segment.
+ * - Read-tool selector tails (`Makefile:12`, `README:raw:1-20`).
+ */
+export declare function extractUriScheme(input: string): string | undefined;
+/**
+ * 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/lib/types/tools/omp/internal-urls/types.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Types for the internal URL routing system.
+ *
+ * Internal URLs (`agent://`, `artifact://`, `history://`, `issue://`, `local://`, `mcp://`, `memory://`, `omp://`, `pr://`, `rule://`, `security://`, `skill://`, `ssh://`, `vault://`, and `xd://`) 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;
+    /**
+     * Exact input string this URL was parsed from, before any normalization.
+     * Set by `parseInternalUrl`; used where byte-exact URI matching matters
+     * (e.g. MCP resource URIs compared by string equality).
+     */
+    rawHref?: 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[];
+    /** Session-bound `xd://` documentation resolver. */
+    xd?: {
+        read(name: string | null): Promise<string>;
+    };
+    /**
+     * 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;
+    /**
+     * When set, handlers that would otherwise materialize expensive content
+     * (e.g. reading a multi-MiB artifact into memory just to expose its
+     * `sourcePath`) may return the resource shape without content. Callers
+     * that only need `sourcePath` — search/grep, bash URL expansion — pass
+     * this so a large `artifact://` still resolves to its backing file
+     * without OOM risk. Handlers that cannot separate path from content
+     * ignore the flag.
+     */
+    pathOnly?: 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;
+    /** Session-bound `xd://` device dispatcher. */
+    xd?: {
+        write(name: string | null, content: string): Promise<void>;
+    };
+}
+/**
+ * Handler for a specific internal URL scheme (e.g., agent://, memory://, skill://, xd://).
+ */
+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/lib/types/tools/omp/internal-urls/xd-protocol.d.ts

@@ -0,0 +1,19 @@
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext, WriteContext } from "./types";
+/** Canonical prefix for virtual tool-device URLs. */
+export declare const XD_URL_PREFIX = "xd://";
+/**
+ * Parse an `xd://` URL into its device target.
+ * Returns `null` for other or malformed URLs and `name: null` for the root.
+ */
+export declare function parseXdUrl(input: string): {
+    name: string | null;
+} | null;
+/** Whether a streaming path prefix could still become an `xd://` URL. */
+export declare function couldBecomeXdUrl(partialPath: string): boolean;
+/** Routes session-bound virtual tool devices through `xd://` URLs. */
+export declare class XdProtocolHandler implements ProtocolHandler {
+    readonly scheme = "xd";
+    readonly immutable = true;
+    resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource>;
+    write(url: InternalUrl, content: string, context?: WriteContext): Promise<void>;
+}

package/lib/types/tools/omp/markit/converters/docx.d.ts

@@ -0,0 +1,6 @@
+import type { ConversionResult, Converter, StreamInfo } from "../types";
+export declare class DocxConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, streamInfo: StreamInfo): Promise<ConversionResult>;
+}