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

package/lib/types/tools/omp/tools/path-utils.d.ts

@@ -0,0 +1,326 @@
+import type { Skill } from "../extensibility/skills";
+import { type LocalProtocolOptions } from "../internal-urls";
+export declare function expandTilde(filePath: string, home?: string): string;
+export declare function expandPath(filePath: string): string;
+export declare function normalizeWindowsDriveAliasPath(filePath: string, platform?: NodeJS.Platform): string;
+/**
+ * Inclusive line range describing one selector segment (e.g. `50-100`,
+ * `301-`, or `50+10`). `endLine` is `undefined` for open-ended ranges.
+ */
+export interface LineRange {
+    startLine: number;
+    endLine: number | undefined;
+}
+/** Parse a single `N`, `N-M`, `N-`, `N+K`, or `..`-aliased (`N..M`, `N..`) chunk. Throws via {@link ToolError} on invalid bounds. */
+export declare function parseLineRangeChunk(sel: string): LineRange | null;
+/**
+ * Parse a comma-separated list of line ranges (e.g. `5-16,960-973`). Returns
+ * the ranges in ascending order with overlapping/adjacent ranges merged so
+ * downstream consumers can stream the file in a single forward pass per range.
+ */
+export declare function parseLineRanges(sel: string): [LineRange, ...LineRange[]] | null;
+/**
+ * Extract the line-range component from a read-tool selector that may also
+ * carry a verbatim/index display mode (`raw`, `conflicts`) — alone or compounded
+ * with a range (`raw:50-100`, `50-100:raw`). Returns the parsed ranges when the
+ * selector names any, otherwise `undefined` (pure `raw`/`conflicts`/none).
+ *
+ * Used by content search, which honors line ranges as a match filter but has no
+ * use for verbatim/conflict display modes — so those selectors are accepted and
+ * treated as an unfiltered, whole-resource search rather than rejected.
+ */
+export declare function selectorLineRanges(sel: string | undefined): [LineRange, ...LineRange[]] | undefined;
+/** Return `true` when `lineNumber` (1-indexed) falls in any of the supplied ranges. */
+export declare function isLineInRanges(lineNumber: number, ranges: readonly LineRange[]): boolean;
+export declare function splitPathAndSel(rawPath: string): {
+    path: string;
+    sel?: string;
+};
+/**
+ * Three-way probe for whether the exact filesystem entry named by `filePath`
+ * exists. `stat` (used earlier) failed for reasons other than "no such file"
+ * (dangling symlink, `EACCES` on a parent, transient I/O), and each of those
+ * silently reinterpreted a real literal path such as `test:1-2` as `test`
+ * plus selector `1-2` (issue #4618). `lstat` inspects the entry itself, so a
+ * dangling symlink is still detected as present; ambiguous errors resolve to
+ * `"unknown"` so callers keep the raw path instead of guessing.
+ *
+ * `ENAMETOOLONG` resolves to `"missing"` rather than `"unknown"`: a path whose
+ * component or whole length exceeds the OS limit can never name a real single
+ * entry, so it is strictly stronger evidence of non-existence than `ENOENT`.
+ * Without this, a semicolon-joined `path` list long enough to trip the limit
+ * (bare filenames past `NAME_MAX`, or a total past `PATH_MAX`) was read as one
+ * literal path and the delimited split was suppressed (issue #7597).
+ */
+export declare function probeLiteralPathExists(filePath: string, cwd: string): Promise<"exists" | "missing" | "unknown">;
+/**
+ * Async sibling of {@link splitPathAndSel} that prefers a literal filesystem
+ * path over selector interpretation. Filenames whose tail matches the selector
+ * grammar (e.g. `test:1-2`, `log:raw`) are legal on POSIX; without this the
+ * strict splitter peels the tail and both `read` and `grep` refuse to open the
+ * real file (issue #4618). The literal wins on a confirmed `lstat`, and also
+ * on `"unknown"` (`EACCES` on a parent, transient I/O), so an unreachable
+ * literal is never silently reinterpreted as `path + selector`. Only a
+ * definitive `ENOENT`/`ENOTDIR` falls back to the strict split.
+ */
+export declare function splitPathAndSelPreferringLiteral(rawPath: string, cwd: string): Promise<{
+    path: string;
+    sel?: string;
+}>;
+/**
+ * Variant of {@link splitPathAndSel} for internal URLs (`scheme://...`).
+ *
+ * The filesystem-path splitter is intentionally conservative: it refuses to
+ * peel a trailing `:<chunk>` unless that chunk matches the strict selector
+ * grammar. That rule is right for filesystem paths (a file named `a:1-50` is
+ * legal) but wrong for internal URLs, where any trailing `:<chunk>` after the
+ * scheme is unambiguously a read-tool selector — even if malformed (e.g.
+ * `artifact://3:raw:-100`).
+ *
+ * This function iteratively peels selector-shaped chunks (well-formed plus
+ * common malformed shapes like `:-N`) so the rest of the read tool can pass a
+ * clean URL to the protocol handler and surface selector errors via parseSel
+ * instead of as misleading "host invalid" errors from the handler. Schemes
+ * whose resource URIs may legitimately contain colons (`mcp://`) are skipped.
+ *
+ * Falls back to the input unchanged when nothing matches.
+ */
+export declare function splitInternalUrlSel(rawPath: string): {
+    path: string;
+    sel?: string;
+};
+/**
+ * Peel a read-tool selector off an internal-URL write target so `write` resolves
+ * the same file `read` does (e.g. `ssh://h/f:raw` -> `ssh://h/f`). Only the
+ * whole-file display modes `raw`/`conflicts` are accepted (they do not change
+ * which bytes are written); any other selector-shaped tail `splitInternalUrlSel`
+ * peels — a line range, a compound like `raw:1-20`, or a malformed `:-N` — throws,
+ * because `write` addresses a whole file, not a partial range, and silently
+ * stripping it would write to a path the caller never named. Non-URL paths and
+ * URLs without a selector pass through unchanged.
+ */
+export declare function peelWriteUrlSelector(rawPath: string): string;
+export declare function normalizeLocalScheme(filePath: string): string;
+export declare function isInternalUrlPath(filePath: string): boolean;
+/**
+ * True when a tool path argument references the `ssh://` scheme anywhere.
+ *
+ * Substring (not anchored) on purpose: it feeds the read/search/write approval
+ * tier, which runs synchronously on the raw args. `search` only flattens a
+ * delimited `paths: "a,ssh://h/x"` into separate entries *after* approval, so an
+ * anchored check would let an embedded `ssh://` slip through at the read tier.
+ * Matching the literal `ssh://` substring also tracks exactly what routes to the
+ * SSH handler; over-matching only over-prompts (fail-closed).
+ */
+export declare function pathTargetsSsh(path: string): boolean;
+/**
+ * True when a path is specifically an `ssh://` URL (anchored scheme match).
+ * Unlike {@link pathTargetsSsh} (substring, for the pre-expansion approval
+ * scan), this is the exact per-entry check used to reject `ssh://` *before* a
+ * side-effecting `InternalUrlRouter.resolve` in tools that need a local file.
+ */
+export declare function isSshUrl(path: string): boolean;
+/**
+ * True when the read tool's URL parser (`parseReadUrlTarget` in fetch.ts) would
+ * recognize this path as a readable external URL: a strict `http(s)://`, a
+ * collapsed `http(s):/host` (Node path normalization folds `//` → `/`), or a
+ * scheme-less `www.` spelling. Keep in sync with `parseReadUrlTarget`.
+ */
+export declare function isReadableUrlPath(value: string): boolean;
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ *
+ * A bare root slash is treated as a workspace-root alias for tool inputs. Users
+ * often pass `/` to mean “search from here”, and letting tools escape to the
+ * filesystem root is almost never what they intended.
+ */
+export declare function resolveToCwd(filePath: string, cwd: string): string;
+/**
+ * Resolve a path that MUST stay inside `cwd`, or `null` when it would escape.
+ *
+ * {@link resolveToCwd} deliberately honors absolute paths, `~`, and `..` —
+ * correct for a path a user typed, wrong for one a remote peer supplied.
+ * Callers handling untrusted input (Cursor's `download_path`) use this instead:
+ * only a non-empty relative path landing under the live cwd is accepted, so
+ * neither `/etc/passwd` nor `../../escape` can be written through.
+ *
+ * The lexical check alone is not containment: a symlink inside the workspace
+ * can point anywhere, so `out/config` under a `ws/out -> /elsewhere` link is
+ * relative, `..`-free, and still writes outside. Both the target and its
+ * deepest existing ancestor are therefore realpath-resolved — the ancestor
+ * because a download names a file that does not exist yet, so the link in its
+ * path is the only thing that can be resolved before the write.
+ *
+ * The cwd itself is rejected: a download names a file, never the directory.
+ */
+export declare function confineToWorkspace(filePath: string, cwd: string): string | null;
+export declare function formatPathRelativeToCwd(filePath: string, cwd: string, options?: {
+    trailingSlash?: boolean;
+}): string;
+/**
+ * Strip matching surrounding double quotes from a path string.
+ * Common when users paste quoted paths from Windows Explorer or shell copy-paste.
+ * Only double quotes — single quotes are valid POSIX filename characters.
+ * Tradeoff: a POSIX path literally starting AND ending with " would also be unquoted.
+ * Accepted because such names are virtually nonexistent in practice.
+ */
+export declare function stripOuterDoubleQuotes(input: string): string;
+export declare function normalizePathLikeInput(input: string): string;
+/**
+ * Normalize a path argument that may arrive as a single string, a JSON-encoded
+ * string array (`'["a.ts"]'`), or an actual array into a flat `string[]`.
+ * Delimited single strings (`"a.ts b.ts"`) are left for
+ * {@link expandDelimitedPathEntries} to split.
+ */
+export declare function toPathList(input: string | string[] | undefined): string[];
+export declare function hasGlobPathChars(filePath: string): boolean;
+type PathEntrySplitter = (item: string) => {
+    basePath: string;
+};
+/**
+ * Split one path-like entry whose multiple targets were flattened into one
+ * string. Existing paths are kept intact, so real filenames containing spaces,
+ * commas, or semicolons win over delimiter recovery.
+ */
+export declare function splitDelimitedPathEntry(entry: string, cwd: string, options?: {
+    splitter?: PathEntrySplitter;
+    routedUrlPredicate?: (entry: string) => boolean;
+}): Promise<string[] | null>;
+/** Expand delimited entries in-place while preserving unsplit entries. */
+export declare function expandDelimitedPathEntries(entries: readonly string[], cwd: string, options?: {
+    splitter?: PathEntrySplitter;
+}): Promise<string[]>;
+export interface ParsedSearchPath {
+    basePath: string;
+    glob?: string;
+}
+export interface ParsedFindPattern {
+    basePath: string;
+    globPattern: string;
+    hasGlob: boolean;
+}
+export interface ResolvedSearchTarget {
+    basePath: string;
+    glob?: string;
+}
+export interface ResolvedMultiSearchPath {
+    basePath: string;
+    glob?: string;
+    scopePath: string;
+    exactFilePaths?: string[];
+    targets?: ResolvedSearchTarget[];
+}
+export interface ResolvedFindTarget {
+    basePath: string;
+    globPattern: string;
+    hasGlob: boolean;
+}
+export interface ResolvedMultiFindPattern {
+    targets: ResolvedFindTarget[];
+    scopePath: string;
+}
+export declare function parseSearchPath(filePath: string): ParsedSearchPath;
+/**
+ * Async sibling of {@link parseSearchPath} that prefers literal interpretation
+ * when a path containing glob metacharacters resolves to an existing entry on
+ * disk. Disambiguates Next.js/SvelteKit routes like `apps/[id]/page.tsx` —
+ * without this, `[id]` is parsed as a glob character class and silently
+ * matches nothing.
+ */
+export declare function parseSearchPathPreferringLiteral(filePath: string, cwd: string): Promise<ParsedSearchPath>;
+export declare function parseFindPattern(pattern: string): ParsedFindPattern;
+export declare function combineSearchGlobs(prefixGlob?: string, suffixGlob?: string): string | undefined;
+export declare function resolveExplicitSearchPaths(pathItems: string[], cwd: string, suffixGlob?: string, fanOutFileItems?: boolean): Promise<ResolvedMultiSearchPath | undefined>;
+export declare function resolveExplicitFindPatterns(patternItems: string[], cwd: string): Promise<ResolvedMultiFindPattern | undefined>;
+/**
+ * Result of partitioning a list of user-supplied paths/globs into entries whose
+ * base directory currently exists on disk versus those that do not.
+ *
+ * Used by multi-path tools (search, find, ast_grep, ast_edit) to tolerate one
+ * or more missing entries in a multi-path call: the surviving entries should
+ * still be searched, with the missing entries surfaced as a non-fatal warning.
+ */
+export interface PartitionedPaths {
+    /** Raw input strings whose resolved base path exists. */
+    valid: string[];
+    /** Raw input strings whose resolved base path is missing (ENOENT). */
+    missing: string[];
+}
+/**
+ * Stat each input's base path concurrently; return entries split by existence.
+ *
+ * `splitter` is expected to be {@link parseFindPattern} or
+ * {@link parseSearchPath}: both return a `basePath` field that this helper
+ * resolves against `cwd` and stats. ENOENT is the only swallowed error — every
+ * other stat failure (permission, IO, etc.) propagates so callers do not silently
+ * skip paths that exist but are unreadable.
+ *
+ * Order of `valid` and `missing` follows the input order, so callers can rely
+ * on `valid[0]` matching the first surviving user-supplied entry.
+ */
+export declare function partitionExistingPaths(items: string[], cwd: string, splitter: (item: string) => {
+    basePath: string;
+}): Promise<PartitionedPaths>;
+export declare function resolveReadPath(filePath: string, cwd: string): string;
+/**
+ * Find a unique workspace entry whose trailing path matches a missing authored path.
+ * Returns `null` for no match, ambiguity, timeout, or scan failure.
+ */
+export declare function findUniqueWorkspaceSuffix(rawPath: string, cwd: string, signal?: AbortSignal): Promise<{
+    absolutePath: string;
+    displayPath: string;
+} | null>;
+/** Local file materialized from a readable external URL for shared tool-scope resolution. */
+export interface ResolvedExternalSearchUrl {
+    /** Absolute or cwd-relative file path to search. */
+    sourcePath: string;
+    /** True when the materialized file must not mint editable anchors. */
+    immutable?: boolean;
+}
+export interface ToolScopeOptions {
+    rawPaths: string[];
+    cwd: string;
+    /** Verb used in the "Cannot {action} internal URL without a backing file: …" message. */
+    internalUrlAction: string;
+    /** Collect absolute paths flagged immutable by their internal-URL handler. */
+    trackImmutableSources?: boolean;
+    /** Honor `exactFilePaths` from {@link resolveExplicitSearchPaths} (search-only). */
+    surfaceExactFilePaths?: boolean;
+    /** Fan plain-file entries out into per-target scans instead of folding them
+     * into a directory walk's glob union (search-only: the caller must dedupe
+     * matches from overlapping targets). */
+    fanOutFileTargets?: boolean;
+    /** Extra hint appended to "Path not found" when stat fails and the user supplied multiple paths. */
+    multipathStatHint?: string;
+    /** Calling session's settings — forwarded to the internal-URL router so caller-aware handlers (issue://, pr://) honor it. */
+    settings?: unknown;
+    /** Caller's abort signal — forwarded to the internal-URL router. */
+    signal?: AbortSignal;
+    /** Calling session's `local://` root mapping — pins resolutions to the calling session. */
+    localProtocolOptions?: LocalProtocolOptions;
+    /** Calling session's loaded skills — lets skill:// resolve without process-global state. */
+    skills?: readonly Skill[];
+    /** Materialize readable external URLs to local text files before scope derivation. */
+    resolveExternalUrl?: (rawPath: string) => Promise<ResolvedExternalSearchUrl | undefined>;
+}
+export interface ToolScopeResolution {
+    searchPath: string;
+    scopePath: string;
+    globFilter: string | undefined;
+    isDirectory: boolean;
+    multiTargets?: ResolvedSearchTarget[];
+    exactFilePaths?: string[];
+    missingPaths: string[];
+    immutableSourcePaths: Set<string>;
+}
+/**
+ * Shared path-input pipeline for `search`, `ast_grep`, and `ast_edit`:
+ *  1. normalize + reject empty paths,
+ *  2. resolve internal URLs through {@link InternalUrlRouter} to backing files,
+ *  3. partition existing vs missing when multiple paths are supplied,
+ *  4. derive a single search base path / glob, or a multi-target list,
+ *  5. stat the resolved base path so callers can branch on directory vs file scope.
+ */
+export declare function resolveToolSearchScope(opts: ToolScopeOptions): Promise<ToolScopeResolution>;
+export {};

package/lib/types/tools/omp/tools/plan-mode-guard.d.ts

@@ -0,0 +1,33 @@
+import type { ToolSession } from "../../omp/tools/index.ts";
+/** Strip the hashline `[path#TAG]` wrapper from a write/edit target so the inner
+ *  filesystem path drives both authorization and resolution. Only unwraps inputs
+ *  that match the strict hashline header shape (`[path]` or `[path#XXXX]` with a
+ *  4-hex tag); anything else returns the original string so the downstream
+ *  resolver surfaces the real error. Exported for callers (e.g. `write`) that
+ *  make scheme/bridge-routing decisions before {@link resolvePlanPath} runs. */
+export declare function unwrapHashlineHeaderPath(targetPath: string): string;
+/** True when `targetPath` resolves into the session-local artifact sandbox.
+ *  Routes through {@link resolvePlanPath} so the guard and the eventual write
+ *  always agree on the absolute target (including bracketed hashline headers,
+ *  `local://` URLs, and bare absolute paths). Files inside the sandbox are not
+ *  part of the working tree, so plan mode treats them as freely writable
+ *  scratch/plan space — and tag-based path recovery may rebind onto them. */
+export declare function targetsLocalSandbox(session: ToolSession, targetPath: string): boolean;
+/**
+ * Resolve a write/edit target to its absolute filesystem path, honoring the
+ * `local://` and `vault://` schemes. Plain paths resolve against the session cwd.
+ * Bracketed hashline headers (`[path#TAG]`) are unwrapped first so the inner
+ * filesystem path drives resolution — keeping the plan-mode guard and the
+ * eventual write in lockstep.
+ */
+export declare function resolvePlanPath(session: ToolSession, targetPath: string): string;
+/**
+ * Plan mode keeps the working tree read-only while letting the agent draft its
+ * plan. Writes and edits to the `local://` artifact sandbox are allowed (that is
+ * where the plan and any scratch notes live); anything that would touch the
+ * working tree — or rename/delete a file — is rejected.
+ */
+export declare function enforcePlanModeWrite(session: ToolSession, targetPath: string, options?: {
+    move?: string;
+    op?: "create" | "update" | "delete";
+}): void;

package/lib/types/tools/omp/tools/read-archive.d.ts

@@ -0,0 +1,16 @@
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { ToolSession } from "../../omp/sdk.ts";
+import type { ReadToolDetails } from "./read";
+import { type SuffixMatchCache } from "./read-path-resolution";
+import { type ParsedSelector } from "./read-selector";
+interface ResolvedArchiveReadPath {
+    absolutePath: string;
+    archiveSubPath: string;
+    suffixResolution?: {
+        from: string;
+        to: string;
+    };
+}
+export declare function resolveArchiveReadPath(session: ToolSession, readPath: string, suffixCache: SuffixMatchCache, signal?: AbortSignal): Promise<ResolvedArchiveReadPath | null>;
+export declare function readArchive(session: ToolSession, readPath: string, parsedSel: ParsedSelector, resolvedArchivePath: ResolvedArchiveReadPath, signal?: AbortSignal): Promise<AgentToolResult<ReadToolDetails>>;
+export {};

package/lib/types/tools/omp/tools/read-format.d.ts

@@ -0,0 +1,104 @@
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { ToolSession } from "../../omp/sdk.ts";
+import { type LineEntry } from "../../omp/utils/block-context.ts";
+import { type LineRange } from "../../omp/tools/path-utils.ts";
+import type { ReadToolDetails } from "./read";
+export interface HashlineHeaderContext {
+    header: string;
+    tag: string;
+    fullText?: string;
+}
+export declare function formatReadHashlineHeader(displayPath: string, tag: string): string;
+export declare function readHashlineHeaderContext(session: ToolSession, absolutePath: string, cwd: string): Promise<HashlineHeaderContext>;
+export declare function hashlineHeaderContext(displayPath: string, tag: string): HashlineHeaderContext;
+export declare function prependHashlineHeader(text: string, context: HashlineHeaderContext | undefined): string;
+export declare function formatTextWithMode(text: string, startNum: number, shouldAddHashLines: boolean, shouldAddLineNumbers: boolean): string;
+export declare const BRACKET_CONTEXT_ELLIPSIS = "\u2026";
+export declare function formatLineEntriesWithMode(entries: readonly LineEntry[], shouldAddHashLines: boolean, shouldAddLineNumbers: boolean): string;
+/**
+ * Decide whether the kept lines surrounding an elided range collapse to a
+ * single brace-pair line in the rendered summary. Returns true when the head
+ * line ends with `{` / `(` / `[` and the tail line is the matching closer
+ * (optionally followed by terminating punctuation like `;`, `,`, or further
+ * closers — e.g. `};`, `})`, `]);`).
+ */
+export declare function canMergeBracePair(headLine: string, tailLine: string): boolean;
+export declare function formatSingleLine(line: number, text: string, shouldAddHashLines: boolean, shouldAddLineNumbers: boolean): string;
+export declare function formatMergedBraceLine(startLine: number, endLine: number, headText: string, tailText: string, shouldAddHashLines: boolean, shouldAddLineNumbers: boolean): {
+    model: string;
+    display: string;
+};
+export declare function countTextLines(text: string): number;
+export declare function contiguousLineNumbers(startLine: number, count: number): number[];
+export declare function lineNumbersFromSpans(spans: readonly {
+    startLine: number;
+    endLine: number;
+}[]): number[];
+/** Inclusive line range describing one elided span in a structural summary. */
+export interface ElidedRange {
+    start: number;
+    end: number;
+}
+/**
+ * Footer appended to summarized reads telling the model how to recover the
+ * elided body. Without this hint, agents either ignore the `…`/`{ … }`
+ * markers or burn a turn guessing the right selector (see issue #1046). The
+ * footer demonstrates the multi-range selector syntax with concrete sample
+ * ranges drawn from the actual elision so the model re-reads only what it
+ * needs instead of falling back to `:raw` or whole-file reads.
+ */
+export declare function formatSummaryElisionFooter(readPath: string, elidedRanges: ReadonlyArray<ElidedRange>, elidedLines: number): string;
+export declare const READ_CHUNK_SIZE: number;
+/**
+ * Context lines added around an explicit range read. Anchor-stale failures
+ * cluster on edits whose anchors land just outside the most recent read
+ * window, but the data (`scripts/session-stats/analyze_selector_reads.py`)
+ * shows most follow-up reads are disjoint hops, not adjacent extensions —
+ * so symmetric padding rarely pays for itself.
+ *
+ * Leading=1 catches accidental single-line reads where the anchor is the
+ * line immediately above the requested start. Trailing=3 buffers the
+ * common case where the agent asks for a narrow range and then needs the
+ * next few lines to disambiguate an anchor.
+ */
+export declare const RANGE_LEADING_CONTEXT_LINES = 1;
+export declare const RANGE_TRAILING_CONTEXT_LINES = 3;
+export declare function buildInMemoryTextResult(session: ToolSession, text: string, offset: number | undefined, limit: number | undefined, options: {
+    details?: ReadToolDetails;
+    sourcePath?: string;
+    sourceUrl?: string;
+    sourceInternal?: string;
+    entityLabel: string;
+    ignoreResultLimits?: boolean;
+    raw?: boolean;
+    immutable?: boolean;
+}): AgentToolResult<ReadToolDetails>;
+/**
+ * Render a multi-range read against in-memory text. Each range emits a
+ * formatted block with its own anchors / line numbers, blocks are joined
+ * with an elision separator, and ranges past EOF surface as `[…]` notices
+ * so the model can correct the next call. No leading/trailing context is
+ * added — multi-range callers always specify exact bounds.
+ */
+export declare function buildInMemoryMultiRangeResult(session: ToolSession, text: string, ranges: readonly LineRange[], options: {
+    details?: ReadToolDetails;
+    sourcePath?: string;
+    sourceUrl?: string;
+    sourceInternal?: string;
+    entityLabel: string;
+    raw?: boolean;
+    immutable?: boolean;
+}): AgentToolResult<ReadToolDetails>;
+export declare function decodeUtf8Text(bytes: Uint8Array): string | null;
+export declare function prependSuffixResolutionNotice(text: string, suffixResolution?: {
+    from: string;
+    to: string;
+}): string;
+/**
+ * Tag Markdown reads for the TUI's formatted preview, gated on the opt-in
+ * `read.renderMarkdown` setting. Off by default; when disabled, no local
+ * read is tagged `text/markdown`, so the renderer output is identical to
+ * the pre-setting behavior. Internal-URL reads keep their protocol-supplied
+ * `contentType` and render as Markdown regardless of the setting.
+ */
+export declare function markMarkdownContentType(session: ToolSession, details: ReadToolDetails, filePath: string): ReadToolDetails;

package/lib/types/tools/omp/tools/read-path-resolution.d.ts

@@ -0,0 +1,19 @@
+import type { ToolSession } from "../../omp/sdk.ts";
+export declare function isRemoteMountPath(absolutePath: string): boolean;
+export declare function isNotFoundError(error: unknown): boolean;
+/** Per-execute memo of suffix-glob lookups; `null` records a confirmed miss. */
+export type SuffixMatchCache = Map<string, {
+    absolutePath: string;
+    displayPath: string;
+} | null>;
+/**
+ * Memoized {@link findUniqueWorkspaceSuffix} for a single read call. A missing
+ * path with archive/sqlite extensions probes the workspace once per stage
+ * (archive candidates, sqlite candidates, plain path) — each glob carries a
+ * 5s timeout, so repeated lookups of the same string stack into a long
+ * stall before erroring. The cache collapses repeats within one execute().
+ */
+export declare function findSuffixMatchCached(session: ToolSession, cache: SuffixMatchCache, rawPath: string, signal?: AbortSignal): Promise<{
+    absolutePath: string;
+    displayPath: string;
+} | null>;

package/lib/types/tools/omp/tools/read-selector.d.ts

@@ -0,0 +1,27 @@
+import type { LineRange } from "../../omp/tools/path-utils.ts";
+/** Parsed representation of a path-embedded selector. */
+export type ParsedSelector = {
+    kind: "none";
+} | {
+    kind: "raw";
+} | {
+    kind: "conflicts";
+} | {
+    kind: "lines";
+    ranges: [LineRange, ...LineRange[]];
+    raw?: boolean;
+};
+/** Returns true when the selector requested verbatim/raw output (alone or combined with a range). */
+export declare function isRawSelector(parsed: ParsedSelector): boolean;
+/** Returns true when the selector requested multiple line ranges. */
+export declare function isMultiRange(parsed: ParsedSelector): boolean;
+export declare function parseSel(sel: string | undefined): ParsedSelector;
+/**
+ * Convert a single-range selector to the offset/limit pair used by internal pagination.
+ * Returns the FIRST range only — multi-range callers MUST branch on `isMultiRange` before
+ * calling this helper.
+ */
+export declare function selToOffsetLimit(parsed: ParsedSelector): {
+    offset?: number;
+    limit?: number;
+};

package/lib/types/tools/omp/tools/read-sqlite.d.ts

@@ -0,0 +1,16 @@
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { ToolSession } from "../../omp/sdk.ts";
+import type { ReadToolDetails } from "./read";
+import { type SuffixMatchCache } from "./read-path-resolution";
+interface ResolvedSqliteReadPath {
+    absolutePath: string;
+    sqliteSubPath: string;
+    queryString: string;
+    suffixResolution?: {
+        from: string;
+        to: string;
+    };
+}
+export declare function resolveSqliteReadPath(session: ToolSession, readPath: string, suffixCache: SuffixMatchCache, signal?: AbortSignal): Promise<ResolvedSqliteReadPath | null>;
+export declare function readSqlite(resolvedSqlitePath: ResolvedSqliteReadPath, signal?: AbortSignal): Promise<AgentToolResult<ReadToolDetails>>;
+export {};

package/lib/types/tools/omp/tools/read-summary.d.ts

@@ -0,0 +1,15 @@
+import { type SummaryResult } from "@oh-my-pi/pi-natives";
+import type { ToolSession } from "../../omp/sdk.ts";
+import { type ElidedRange } from "./read-format";
+/**
+ * Prose files (Markdown flavors and plain text) skip code-block summarization
+ * unless `read.summarize.prose` opts them in.
+ */
+export declare function isProseSummaryPath(filePath: string): boolean;
+export declare function trySummarize(session: ToolSession, absolutePath: string, fileSize: number, signal?: AbortSignal): Promise<SummaryResult | null>;
+export declare function renderSummary(session: ToolSession, summary: SummaryResult): {
+    text: string;
+    displayText: string;
+    elidedRanges: ElidedRange[];
+    elidedLines: number;
+};

package/lib/types/tools/omp/tools/read.d.ts

@@ -0,0 +1,70 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, ToolTier } from "@oh-my-pi/pi-agent-core";
+import type { ToolSession } from "../../omp/sdk.ts";
+import { type TruncationResult } from "../../omp/session/streaming-output.ts";
+import { type OutputMeta } from "../../omp/tools/output-meta.ts";
+declare const readSchema: import("@oh-my-pi/omptype").FluentType<{
+    path: string;
+}, {
+    path: string;
+}>;
+export type ReadToolInput = typeof readSchema.infer;
+export interface ReadToolDetails {
+    kind?: "file" | "url";
+    truncation?: TruncationResult;
+    isDirectory?: boolean;
+    resolvedPath?: string;
+    suffixResolution?: {
+        from: string;
+        to: string;
+    };
+    /** DSH image bridge (拍板#22): committed attachment facts for an image read. */
+    image?: import("../../shared/image-bridge.ts").SavedImageRef;
+    url?: string;
+    finalUrl?: string;
+    contentType?: string;
+    method?: string;
+    notes?: string[];
+    meta?: OutputMeta;
+    /** Full on-disk byte size recorded before applying a file range. */
+    fileSize?: number;
+    /** Full source line count when the read reached EOF and the count is exact. */
+    totalLines?: number;
+    /** Raw text + start line for user-visible TUI rendering, set when content is text-like.
+     * Mirrors the same lines the model receives but without hashline/line-number prefixes,
+     * so the TUI can render the file content with its own gutter without re-parsing the formatted text. */
+    displayContent?: {
+        text: string;
+        startLine: number;
+        lineNumbers?: Array<number | null>;
+    };
+    summary?: {
+        lines: number;
+        elidedSpans: number;
+        elidedLines: number;
+    };
+    /** Number of unresolved git conflicts surfaced by this read (TUI uses for inline `⚠ N` badge). */
+    conflictCount?: number;
+    /** Paths recovered from a delimited read argument; used only by the TUI to render one call as multiple read rows. */
+    displayReadTargets?: string[];
+}
+type ReadParams = ReadToolInput;
+/**
+ * Read tool implementation.
+ *
+ * Reads files with support for images, converted documents (via markit), and text.
+ * Directories return a formatted listing with modification times.
+ */
+export declare class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "read";
+    readonly approval: (args: unknown) => ToolTier;
+    readonly label = "Read";
+    readonly loadMode = "essential";
+    description: string;
+    get parameters(): typeof readSchema;
+    readonly strict = true;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: ReadParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<ReadToolDetails>, _toolContext?: AgentToolContext): Promise<AgentToolResult<ReadToolDetails>>;
+}
+export {};

package/lib/types/tools/omp/tools/render-utils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Formatting helpers shared by the tool engines.
+ *
+ * The TUI renderer utilities that used to live here were cut with the TUI
+ * layer (plan.md 拍板#17); what remains is what the engines themselves use.
+ */
+export { replaceTabs, truncateToWidth } from "@oh-my-pi/pi-tui";
+export { formatAge, formatBytes, formatCount, formatDuration, pluralize } from "@oh-my-pi/pi-utils";
+/**
+ * Extract domain from URL, stripping www. prefix.
+ */
+export declare function getDomain(url: string): string;
+export declare function shortenPath(filePath: unknown, homeDir?: string): string;
+export type CodeFrameMarker = "" | " " | "*" | "+" | "-" | ">";
+export declare function formatCodeFrameLine(marker: CodeFrameMarker, lineNumber: string | number, content: string, lineNumberWidth: number): string;
+export declare const PARSE_ERRORS_LIMIT = 20;
+export declare function dedupeParseErrors(errors: string[] | undefined): string[];
+export declare function formatParseErrors(errors: string[], total?: number): string[];
+/**
+ * Cap an upstream parse-error list to {@link PARSE_ERRORS_LIMIT} unique entries,
+ * preserving the original deduplicated total. Use this at the source so tool
+ * details never carry thousands of per-file parse errors into traces or
+ * renderers.
+ */
+export declare function capParseErrors(errors: string[] | undefined, limit?: number): {
+    errors: string[];
+    total: number;
+};