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

package/lib/types/tools/omp/tools/conflict-detect.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Detect and resolve unresolved git merge conflicts that surface in `read`
+ * output.
+ *
+ * Workflow:
+ *   1. `read` collects lines from disk as usual.
+ *   2. `scanConflictLines` inspects those lines (no extra I/O) for
+ *      well-formed `<<<<<<<` / `=======` / `>>>>>>>` blocks.
+ *   3. Each completed block is registered with the session's
+ *      `ConflictHistory`, which assigns it a stable id.
+ *   4. The read output is returned verbatim with a short footer naming
+ *      every conflict id surfaced, and the agent calls
+ *      `write({ path: "conflict://<id>", content })` to splice the
+ *      recorded region with the chosen content.
+ *
+ * Marker shape is strict: only column-0 markers of the exact prefix length
+ * followed by either EOL or a single space + label count. Lines that
+ * merely start with `<` or `=` never match.
+ */
+import type { ToolSession } from "./index";
+export interface ConflictBlock {
+    /** 1-indexed line of the `<<<<<<<` marker. */
+    startLine: number;
+    /** 1-indexed line of the `=======` separator. */
+    separatorLine: number;
+    /** 1-indexed line of the `>>>>>>>` marker. */
+    endLine: number;
+    /** 1-indexed line of the `|||||||` base marker (diff3 only). */
+    baseLine?: number;
+    oursLabel?: string;
+    baseLabel?: string;
+    theirsLabel?: string;
+    oursLines: string[];
+    baseLines?: string[];
+    theirsLines: string[];
+}
+/**
+ * Scan an already-collected array of file lines for completed conflict
+ * blocks. `firstLineNumber` is the 1-indexed line number of `lines[0]`
+ * (so a windowed read starting at line 200 passes `firstLineNumber: 200`).
+ *
+ * Only fully-closed blocks (opener + separator + closer all present in
+ * the window) are returned. A block whose closer is past the window's
+ * tail is dropped — the agent will see the open marker and can widen
+ * the read.
+ */
+export declare function scanConflictLines(lines: readonly string[], firstLineNumber: number): ConflictBlock[];
+/**
+ * Scan a whole file for unresolved conflict blocks.
+ *
+ * Reads at most `maxBytes` (default 10 MB) so this stays cheap on
+ * pathological files. Files truncated by the cap report
+ * `scanTruncated: true`; only complete blocks within the scanned prefix
+ * are returned, so trailing partial markers never invent fake blocks.
+ */
+export declare function scanFileForConflicts(absolutePath: string, options?: {
+    maxBytes?: number;
+}): Promise<{
+    blocks: ConflictBlock[];
+    scanTruncated: boolean;
+}>;
+/**
+ * Recorded conflict block keyed by a session-stable id. The history is
+ * append-only; ids stay valid even after later writes resolve other
+ * blocks in the same file, so retries don't depend on re-reading.
+ */
+export interface ConflictEntry extends ConflictBlock {
+    id: number;
+    absolutePath: string;
+    displayPath: string;
+}
+/** Per-session log of conflict regions surfaced by `read`. */
+export declare class ConflictHistory {
+    #private;
+    /**
+     * Register a conflict block. Returns the (possibly pre-existing) entry
+     * — if the same `absolutePath`+`startLine` was registered before, the
+     * earlier id is reused so a re-read does not inflate the counter or
+     * orphan the prior id. The recorded region is overwritten on re-read
+     * so the splice always reflects the current marker positions on disk.
+     */
+    register(input: Omit<ConflictEntry, "id">): ConflictEntry;
+    get(id: number): ConflictEntry | undefined;
+    /** Snapshot every registered entry in insertion (id) order. */
+    entries(): ConflictEntry[];
+    /** Drop a single entry by id. Used after a successful resolve. */
+    invalidate(id: number): void;
+    /** Drop every entry referencing `absolutePath`. Used after a successful resolve. */
+    invalidatePath(absolutePath: string): void;
+}
+/** Lazily attach a `ConflictHistory` to the session and return it. */
+export declare function getConflictHistory(session: ToolSession): ConflictHistory;
+/** A side of a conflict block that the `read` tool can render via `conflict://N/<scope>`. */
+export type ConflictScope = "ours" | "theirs" | "base";
+/** Parsed `conflict://<N>` / `conflict://<N>/<scope>` / `conflict://*` URI. */
+export interface ParsedConflictUri {
+    /** `"*"` selects every currently-registered conflict (bulk write only). */
+    id: number | "*";
+    scope?: ConflictScope;
+    /**
+     * When `raw` was a malformed `<file-prefix>:conflict://…` path, the
+     * stripped prefix is preserved here so callers can surface a gentle
+     * "you don't need the file path" note. `undefined` for clean URIs.
+     */
+    recoveredPrefix?: string;
+}
+/**
+ * Parse a `conflict://<N>`, `conflict://<N>/<scope>`, or `conflict://*` URI.
+ *
+ * Returns `null` for non-conflict paths; throws `ToolError` for a
+ * well-formed scheme with an invalid id or scope so the agent gets a
+ * clear actionable message rather than a confusing "not found" later.
+ *
+ * `*` is the bulk-write wildcard — only valid as `conflict://*` (no
+ * scope segment). Use it with `write({ path: "conflict://*", content })`
+ * to apply `content` (with optional `@ours` / `@theirs` / `@base` /
+ * `@both` shorthand) to every currently-registered conflict in one shot.
+ */
+export declare function parseConflictUri(raw: string): ParsedConflictUri | null;
+/** Result of {@link spliceConflict}: the new file text plus any boundary-echo repair applied. */
+export interface ConflictSplice {
+    text: string;
+    /** Replacement lines dropped because they duplicated the context directly above the region. */
+    trimmedLeading: number;
+    /** Replacement lines dropped because they duplicated the context directly below the region. */
+    trimmedTrailing: number;
+}
+/**
+ * Splice the conflict region recorded in `entry` out of `originalText`
+ * and replace it with `replacement` (markers and all sides included).
+ *
+ * Works like the edit tool's patch infra: locates the recorded marker
+ * block by content (anchored to `entry.startLine` as the preferred
+ * match), so out-of-band edits earlier in the file that shift line
+ * numbers don't break resolution. Throws clearly when the marker block
+ * has actually been altered or removed.
+ *
+ * Boundary-echo repair (same philosophy as the edit tool's hashline
+ * keeper repair): models frequently paste the "whole resolved function"
+ * including the lines that live directly before/after the marker block,
+ * which the verbatim splice would duplicate. Replacement lines that
+ * exactly echo the adjacent context are dropped when the echo is
+ * unambiguous — two or more consecutive lines, or a single line whose
+ * removal fixes a delimiter-balance mismatch against the recorded sides.
+ */
+export declare function spliceConflict(originalText: string, entry: ConflictEntry, replacement: string): ConflictSplice;
+/**
+ * True when two registered blocks record the same marker-block content
+ * (labels and all sides). Out-of-band edits can shift a block's line
+ * numbers between reads, registering a fresh id while the stale one
+ * persists; callers use content identity to treat a locate-miss for the
+ * stale twin as "already resolved" instead of a hard failure.
+ */
+export declare function conflictRegionsEqual(a: ConflictBlock, b: ConflictBlock): boolean;
+/**
+ * True when the entry's recorded marker block still occurs in `content`
+ * (LF-normalized — recorded sections are stored LF). Distinguishes a stale
+ * re-registration of a just-resolved region (no longer present) from a
+ * DISTINCT conflict block that happens to be byte-identical (still present
+ * elsewhere in the file and must stay addressable).
+ */
+export declare function conflictRegionPresent(content: string, entry: ConflictBlock): boolean;
+/**
+ * Expand `@ours` / `@theirs` / `@base` / `@both` line tokens against the
+ * recorded sections of `entry`. A token only triggers when it is the
+ * entire content of a line (after CRLF normalisation), so `@ours` inside
+ * actual code is left alone. Other lines pass through verbatim.
+ *
+ * - `@ours`    → expands to the recorded `oursLines` (in order).
+ * - `@theirs`  → expands to the recorded `theirsLines` (in order).
+ * - `@base`    → expands to `baseLines`; throws if no base section was
+ *               recorded (i.e. the conflict was 2-way, not diff3).
+ * - `@both`    → expands to `oursLines` then `theirsLines`.
+ */
+export declare function expandContentTokens(content: string, entry: ConflictEntry): string;
+/**
+ * Materialise a conflict block for `conflict://<N>` reads (and their
+ * `/ours` / `/theirs` / `/base` scopes).
+ *
+ * Returns:
+ * - `lines`: the lines to render, ordered top-to-bottom.
+ * - `startLine`: the 1-indexed file line number `lines[0]` corresponds
+ *   to, so the read formatter can label hashline anchors with the
+ *   original file positions.
+ *
+ * Bare (no scope) returns the full block including marker lines. A
+ * scoped view returns only that side's body — `base` throws when the
+ * recorded conflict is a 2-way merge with no base section.
+ */
+export declare function renderConflictRegion(entry: ConflictEntry, scope: ConflictScope | undefined): {
+    lines: string[];
+    startLine: number;
+};
+/**
+ * Build a compact diff-style footer describing the conflicts registered
+ * during a read. Designed to be appended after the file content.
+ *
+ * Format:
+ *
+ *     ⚠ N unresolved conflicts detected
+ *     - ours = HEAD
+ *     - theirs = feature/x
+ *     NOTICE: …
+ *
+ *     ──── #1  L42-48 ────
+ *     <<< ours
+ *     …ours body…
+ *     === base ≡ ours
+ *     >>> theirs
+ *     …theirs body…
+ *
+ * Labels are aggregated once at the top from the first entry that has
+ * them; when a section body equals another section's body the redundant
+ * body is collapsed to `≡ <other>`.
+ */
+export interface FormatConflictWarningOptions {
+    /**
+     * Total number of conflicts in the underlying file. If greater than
+     * `entries.length` the header notes how many are visible vs the total
+     * and points at `:conflicts` for the compact list.
+     */
+    totalInFile?: number;
+    /** Display path used inside the `:conflicts` hint. */
+    displayPath?: string;
+    /** Whether the underlying file scan hit its byte cap. */
+    scanTruncated?: boolean;
+}
+export declare function formatConflictWarning(entries: readonly ConflictEntry[], options?: FormatConflictWarningOptions): string;
+/**
+ * Render a single-line-per-block index of every conflict in a file.
+ * Used by the `<path>:conflicts` read selector to give the agent a cheap overview
+ * of a heavily-conflicted file without dumping every body.
+ */
+export declare function formatConflictSummary(entries: readonly ConflictEntry[], options?: {
+    displayPath: string;
+    scanTruncated?: boolean;
+}): string;

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

@@ -0,0 +1,103 @@
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { FetchImpl } from "@oh-my-pi/pi-ai";
+import type { Settings } from "../config/settings";
+import type { ToolSession } from "../sdk";
+import type { AgentStorage } from "../session/agent-storage";
+import { type OutputMeta } from "./output-meta";
+import { type LineRange } from "./path-utils";
+export interface ParsedReadUrlTarget {
+    path: string;
+    raw: boolean;
+    offset?: number;
+    limit?: number;
+    /** Populated only when the selector carries 2+ ranges. Single-range stays on offset/limit. */
+    ranges?: readonly LineRange[];
+}
+export declare function parseReadUrlTarget(readPath: string): ParsedReadUrlTarget | null;
+/** Reader backends for {@link renderHtmlToText}, in default priority order. */
+export type FetchProvider = "native" | "trafilatura" | "lynx" | "parallel" | "jina" | "browser";
+export declare const FETCH_PROVIDER_ORDER: readonly FetchProvider[];
+/**
+ * Render HTML to markdown by trying reader backends in priority order: native
+ * (in-process), trafilatura, lynx, Parallel, Jina, then the browser
+ * (headless-Chromium JS rendering, see {@link renderUrlWithBrowser} — gated
+ * behind `browser.readerEnabled`). The `providers.fetch` setting picks the
+ * order — `auto` uses the default above; any specific backend is tried first,
+ * then the remaining backends as fallbacks. Every backend's output must clear
+ * the same quality gate (>100 non-whitespace chars and not
+ * {@link isLowQualityOutput}) before it is accepted, otherwise the next
+ * backend is tried.
+ *
+ * When the raw HTML is a CSR app shell (script-heavy, text-light), output
+ * from {@link CSR_SUSCEPTIBLE} backends (which cannot execute page
+ * JavaScript) is held back as low quality so the chain still reaches the
+ * browser backend; with no usable browser the parked shell is returned as
+ * before, so degradation is unchanged. The browser's own output on a shell
+ * is accepted as-is (a noscript remnant is expected in it).
+ *
+ * The overall `timeout` budget bounds the whole call; remote backends (Parallel,
+ * Jina) are additionally capped at `REMOTE_READER_MAX_MS` so a hung endpoint
+ * cannot starve later renderers — especially the purely-local native converter,
+ * which always works on already-loaded HTML. Only a real `userSignal`
+ * cancellation aborts the chain (#1449).
+ */
+export declare function renderHtmlToText(url: string, html: string, timeout: number, settings: Settings, userSignal: AbortSignal | undefined, storage: AgentStorage | null, fetchOverride?: FetchImpl): Promise<{
+    content: string;
+    ok: boolean;
+    method: string;
+}>;
+/**
+ * Detect a client-side-rendered (CSR) app shell in raw HTML: script-dense
+ * markup with almost no statically visible text. Such pages only produce body
+ * content after JavaScript executes, so JS-unaware extractors (native/
+ * trafilatura/lynx) necessarily return a shell remnant (title/meta remnants)
+ * while the browser backend can render the real body. Deliberately
+ * conservative — compact HTML, multiple script tags, sparse static text — so
+ * genuine SSR pages are never flagged and their rendering order is unchanged.
+ * @returns true when the HTML looks like an unrendered SPA shell.
+ */
+export declare function isCsrHtmlShell(html: string): boolean;
+interface FetchImagePayload {
+    data: string;
+    mimeType: string;
+}
+export interface ReadUrlToolDetails {
+    kind: "url";
+    url: string;
+    finalUrl: string;
+    contentType: string;
+    method: string;
+    truncated: boolean;
+    notes: string[];
+    meta?: OutputMeta;
+    /** DSH (拍板#22): committed attachment facts when the URL image went through the bridge. */
+    image?: import("../../shared/image-bridge.ts").SavedImageRef;
+}
+interface ReadUrlEntry {
+    artifactId?: string;
+    artifactPath?: string;
+    details: ReadUrlToolDetails;
+    image?: FetchImagePayload;
+    output: string;
+    content: string;
+}
+/** Fetch and render a URL for a read or search operation. */
+export declare function fetchReadUrl(session: ToolSession, params: {
+    path: string;
+    raw?: boolean;
+}, signal?: AbortSignal, options?: {
+    ensureArtifact?: boolean;
+}): Promise<ReadUrlEntry>;
+/** Materialize rendered URL body text to a local file for tools that require filesystem paths. */
+export declare function materializeReadUrlToFile(session: ToolSession, params: {
+    path: string;
+    raw?: boolean;
+}, signal?: AbortSignal): Promise<{
+    path: string;
+    details: ReadUrlToolDetails;
+}>;
+export declare function executeReadUrl(session: ToolSession, params: {
+    path: string;
+    raw?: boolean;
+}, signal?: AbortSignal): Promise<AgentToolResult<ReadUrlToolDetails>>;
+export {};

package/lib/types/tools/omp/tools/file-recorder.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Creates a deduplicating recorder for relative file paths.
+ * Preserves insertion order in `list`; subsequent duplicates are ignored.
+ */
+export declare function createFileRecorder(): {
+    record: (relativePath: string) => void;
+    list: string[];
+};
+/**
+ * Strip native virtual-root prefixes and format file paths relative to cwd when
+ * they are inside cwd. Paths outside cwd remain absolute.
+ */
+export declare function formatResultPath(filePath: string, isDirectory: boolean, basePath: string, cwd: string): string;

package/lib/types/tools/omp/tools/fs-cache-invalidation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Invalidate shared filesystem scan caches after a content write/update.
+ */
+export declare function invalidateFsScanAfterWrite(path: string): void;
+/**
+ * Invalidate shared filesystem scan caches after deleting a file.
+ */
+export declare function invalidateFsScanAfterDelete(path: string): void;
+/**
+ * Invalidate shared filesystem scan caches after a rename/move.
+ *
+ * Some watchers care about the disappearance at the old path; others about the
+ * appearance at the new one. Bust both to keep callers honest.
+ */
+export declare function invalidateFsScanAfterRename(oldPath: string, newPath: string): void;

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

@@ -0,0 +1,86 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
+import { type TruncationResult } from "../../omp/session/streaming-output.ts";
+import type { ToolSession } from "../../omp/sdk.ts";
+import { type OutputMeta } from "../../omp/tools/output-meta.ts";
+declare const findSchema: import("@oh-my-pi/omptype").FluentType<{
+    path?: string | undefined;
+    gitignore?: boolean | undefined;
+    hidden?: boolean | undefined;
+    limit?: number | undefined;
+}, {
+    path?: string | undefined;
+    gitignore?: boolean | undefined;
+    hidden?: boolean | undefined;
+    limit?: number | undefined;
+}>;
+export type GlobToolInput = typeof findSchema.infer;
+export interface GlobToolDetails {
+    truncation?: TruncationResult;
+    resultLimitReached?: number;
+    meta?: OutputMeta;
+    scopePath?: string;
+    fileCount?: number;
+    files?: string[];
+    truncated?: boolean;
+    error?: string;
+    /** Working directory at search time. Used by the renderer to resolve relative
+     * file paths to absolute paths for OSC 8 hyperlinks. */
+    cwd?: string;
+    /** User-supplied paths whose base directory was missing on disk. The tool
+     * skipped these and continued with the surviving entries; surfaced as a
+     * non-fatal warning in the renderer and in the model-facing text. */
+    missingPaths?: string[];
+}
+/**
+ * Pluggable operations for the find tool.
+ * Override these to delegate file search to remote systems (e.g., SSH).
+ */
+export interface GlobOperations {
+    /** Check if path exists */
+    exists: (absolutePath: string) => Promise<boolean> | boolean;
+    /** Optional stat for distinguishing files vs directories. */
+    stat?: (absolutePath: string) => Promise<{
+        isFile(): boolean;
+        isDirectory(): boolean;
+    }> | {
+        isFile(): boolean;
+        isDirectory(): boolean;
+    };
+    /** Find files matching glob pattern. Returns relative paths. */
+    glob: (pattern: string, cwd: string, options: {
+        ignore: string[];
+        limit: number;
+    }) => Promise<string[]> | string[];
+}
+export interface GlobToolOptions {
+    /** Custom operations for find. Default: local filesystem + rg */
+    operations?: GlobOperations;
+    /** Remap slash-only paths to the session cwd before root-search validation. */
+    rootPathAlias?: boolean;
+}
+export declare class GlobTool implements AgentTool<typeof findSchema, GlobToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "glob";
+    readonly approval: "read";
+    readonly loadMode = "essential";
+    readonly label = "Glob";
+    get description(): string;
+    readonly parameters: import("@oh-my-pi/omptype").FluentType<{
+        path?: string | undefined;
+        gitignore?: boolean | undefined;
+        hidden?: boolean | undefined;
+        limit?: number | undefined;
+    }, {
+        path?: string | undefined;
+        gitignore?: boolean | undefined;
+        hidden?: boolean | undefined;
+        limit?: number | undefined;
+    }>;
+    readonly examples: readonly ToolExample<typeof findSchema.infer>[];
+    readonly strict = true;
+    constructor(session: ToolSession, options?: GlobToolOptions);
+    execute(_toolCallId: string, params: typeof findSchema.infer, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<GlobToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<GlobToolDetails>>;
+}
+export {};

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

@@ -0,0 +1,102 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, ToolTier } from "@oh-my-pi/pi-agent-core";
+import { type TruncationResult } from "../../omp/session/streaming-output.ts";
+import type { ToolSession } from "../../omp/sdk.ts";
+import type { OutputMeta } from "../../omp/tools/output-meta.ts";
+declare const searchSchema: import("@oh-my-pi/omptype").FluentType<{
+    pattern: string;
+    path?: string | undefined;
+    case?: boolean | undefined;
+    gitignore?: boolean | undefined;
+    skip?: number | null | undefined;
+}, {
+    pattern: string;
+    path?: string | undefined;
+    case?: boolean | undefined;
+    gitignore?: boolean | undefined;
+    skip?: number | null | undefined;
+}>;
+export type GrepToolInput = typeof searchSchema.infer;
+/** Maximum number of distinct files surfaced in a single response. The
+ * agent paginates further pages via `skip`. */
+export declare const DEFAULT_FILE_LIMIT = 20;
+/** Per-file match cap for multi-file searches — keeps a single hot file
+ * from crowding out diverse hits. Applied in JS after grep returns. */
+export declare const MULTI_FILE_PER_FILE_MATCHES = 20;
+/** Per-file match cap for single-file searches — there's no diversity
+ * concern when the scope is one file. */
+export declare const SINGLE_FILE_MATCHES = 200;
+export interface GrepToolDetails {
+    truncation?: TruncationResult;
+    fileLimitReached?: number;
+    perFileLimitReached?: number;
+    linesTruncated?: boolean;
+    meta?: OutputMeta;
+    scopePath?: string;
+    matchCount?: number;
+    fileCount?: number;
+    files?: string[];
+    fileMatches?: Array<{
+        path: string;
+        count: number;
+    }>;
+    truncated?: boolean;
+    error?: string;
+    /** Pre-formatted text for the user-visible TUI render. Mirrors the model-facing
+     * `result.text` lines but uses a `│` gutter and `*` to mark match lines (vs space for
+     * context). The TUI uses this directly so it never parses model-facing hashline anchors. */
+    displayContent?: string;
+    /** Absolute base directory used during search. Used by the renderer to resolve
+     * display-relative paths to absolute paths for OSC 8 hyperlinks. */
+    searchPath?: string;
+    /** Session cwd at search time. The renderer resolves the display-relative
+     * (cwd-relative) header/match paths against this for OSC 8 hyperlinks;
+     * `searchPath` is the scope label target, not the display-path base. */
+    cwd?: string;
+    /** User-supplied paths whose base directory was missing on disk. The tool
+     * skipped these and continued with the surviving entries; surfaced as a
+     * non-fatal warning in the renderer and in the model-facing text. */
+    missingPaths?: string[];
+}
+type SearchParams = typeof searchSchema.infer;
+/**
+ * Construction-time overrides for callers that are not the model.
+ *
+ * The model-facing schema deliberately does not grow these: they exist for
+ * wire bridges (the Cursor `pi_grep` frame) whose protocol carries an explicit
+ * context width and total match cap, and which would otherwise have to drop
+ * them. Unset means "use the session settings / built-in caps" — the behavior
+ * every model-issued call keeps.
+ */
+export interface GrepToolOptions {
+    /** Overrides `grep.contextBefore`/`grep.contextAfter` for every call on this instance. */
+    context?: number;
+    /** Caps total surfaced matches. Applied on top of the built-in per-file and file-window caps, never above them. */
+    totalMatchLimit?: number;
+}
+export declare class GrepTool implements AgentTool<typeof searchSchema, GrepToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "grep";
+    readonly approval: (args: unknown) => ToolTier;
+    readonly label = "Grep";
+    readonly loadMode = "discoverable";
+    readonly summary = "Grep file contents using ripgrep (fast regex search)";
+    get description(): string;
+    readonly parameters: import("@oh-my-pi/omptype").FluentType<{
+        pattern: string;
+        path?: string | undefined;
+        case?: boolean | undefined;
+        gitignore?: boolean | undefined;
+        skip?: number | null | undefined;
+    }, {
+        pattern: string;
+        path?: string | undefined;
+        case?: boolean | undefined;
+        gitignore?: boolean | undefined;
+        skip?: number | null | undefined;
+    }>;
+    readonly strict = true;
+    constructor(session: ToolSession, options?: GrepToolOptions);
+    execute(_toolCallId: string, params: SearchParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<GrepToolDetails>, _toolContext?: AgentToolContext): Promise<AgentToolResult<GrepToolDetails>>;
+}
+export {};

package/lib/types/tools/omp/tools/grouped-file-output.d.ts

@@ -0,0 +1,70 @@
+/**
+ * One file's contribution to a grouped file output. The header itself is generated
+ * by `formatGroupedFiles` (one `#` per nesting level); use `headerSuffix` to tack
+ * on extras like ` (1 replacement)`.
+ */
+export interface GroupedFileSection {
+    /** Optional suffix appended to the file header. */
+    headerSuffix?: string;
+    /** Body lines emitted into the textual model output. */
+    modelLines: string[];
+    /** Body lines emitted into the display output. Defaults to `modelLines`. */
+    displayLines?: string[];
+    /** When true, the file (and its header) is omitted entirely. */
+    skip?: boolean;
+}
+export interface GroupedFilesOutput {
+    model: string[];
+    display: string[];
+}
+/**
+ * Render a list of files as a multi-level, prefix-folded directory tree shared by
+ * grep, ast-grep, ast-edit, and the LSP diagnostic formatter.
+ *
+ * Layout (one `#` per level; the shared prefix folds into the top header):
+ *   # packages/pkg/src/
+ *   ## root.ts
+ *   …body…
+ *   ## nested/
+ *   ### child.ts
+ *   …body…
+ *
+ * Files in the (folded) project root become single-`#` headers with no parent
+ * directory line. A blank line precedes every directory header and every
+ * root-level file so the renderers can split the output into collapsible groups.
+ */
+export declare function formatGroupedFiles(files: string[], renderFile: (filePath: string) => GroupedFileSection): GroupedFilesOutput;
+/** Per-line classification of grouped output, used by renderers for hyperlinks. */
+export interface GroupedLineContext {
+    /** Directory header, file header, or any non-header body/content line. */
+    kind: "dir" | "file" | "content";
+    /** Number of leading `#` for headers; 0 for content lines. */
+    depth: number;
+    /** Resolved absolute path of the dir/file a header points at (when resolvable). */
+    headerPath?: string;
+    /** For content lines, the absolute path of the owning file (line hyperlinks). */
+    filePath?: string;
+    /** Header is an internal/url-like target the caller resolves itself. */
+    isUrl?: boolean;
+}
+/**
+ * Walk grouped output lines, tracking a directory stack keyed by header depth, so
+ * each header and body line can be linked back to its absolute filesystem path.
+ * Reconstruction is stack-based (not per-blank-group) so nested directory headers
+ * resolve correctly across the whole output.
+ *
+ * `headerBase` is the directory the displayed (folded) header paths are relative
+ * to — for grep/ast tools that is the session cwd, since display paths are
+ * formatted relative to cwd regardless of the (sub)directory the search was
+ * scoped to. `fileScope` is the initial owning file for body lines that appear
+ * before any header (single-file scopes have no `#` headers); it defaults to
+ * `headerBase` and should be passed the scoped file's absolute path.
+ */
+export declare function classifyGroupedLines(lines: readonly string[], headerBase: string | undefined, fileScope?: string | undefined): GroupedLineContext[];
+/**
+ * Split line indices into blank-line-separated groups, mirroring
+ * `splitGroupsByBlankLine`: when any blank line is present, break on runs of
+ * blanks; otherwise return a single group of the non-empty lines. Returning
+ * indices lets callers slice parallel arrays (raw lines, styled lines, contexts).
+ */
+export declare function groupLineIndicesByBlank(rawLines: readonly string[]): number[][];

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

@@ -0,0 +1,23 @@
+/**
+ * DSH adapter type shim for OMP `tools/index.ts`.
+ *
+ * The original is the 746-line OMP tool-registry barrel (imports every
+ * built-in tool and re-exports the whole toolbox). The tool-plus adapters
+ * only consume its `ToolSession` and `Tool` types, so this shared shim
+ * re-exports those from the shared DSH adapter (`../sdk`) and pi-agent-core.
+ * No tool registries are carried.
+ *
+ * NOTE (step.md 决策记录): registry barrel intentionally not ported —
+ * decision pending user confirmation.
+ */
+import type { AgentTool } from '@oh-my-pi/pi-agent-core';
+import type { Settings } from '../config/settings.ts';
+declare module '@oh-my-pi/pi-agent-core' {
+    interface AgentToolContext {
+        hasUI?: boolean;
+        toolNames?: string[];
+    }
+}
+export type { ToolSession } from '../sdk.ts';
+export type { Settings };
+export type Tool = AgentTool<any, any, any>;

package/lib/types/tools/omp/tools/list-limit.d.ts

@@ -0,0 +1,12 @@
+import type { LimitsMeta } from "./output-meta";
+export interface ListLimitResult<T> {
+    items: T[];
+    limitReached?: number;
+    meta: Partial<LimitsMeta>;
+}
+export interface ListLimitOptions {
+    limit?: number;
+    headLimit?: number;
+    limitType?: "match" | "result";
+}
+export declare function applyListLimit<T>(items: T[], options: ListLimitOptions): ListLimitResult<T>;