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

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>;

package/lib/types/tools/omp/tools/match-line-format.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Format a single line of match output for grep/ast-grep style results.
+ *
+ * Matched lines are prefixed with `*`; context lines are prefixed with a single
+ * space so line numbers align in column. In hashline mode the line uses the
+ * editable `LINE:content` shape under a snapshot-tag header; in plain mode it
+ * keeps the legacy `LINE|content` display-only shape. Line numbers are never padded.
+ */
+export declare function formatMatchLine(lineNumber: number, line: string, isMatch: boolean, options: {
+    useHashLines: boolean;
+}): string;

package/lib/types/tools/omp/tools/output-meta.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Structured metadata for tool outputs.
+ *
+ * Tools populate details.meta using the fluent OutputMetaBuilder.
+ * DSH adapters format notices themselves via formatOutputNotice; the OMP-side
+ * auto-wrap/spill machinery was cut with the TUI layer (plan.md 拍板#17).
+ */
+import { type Settings } from "../config/settings";
+import type { OutputSummary, TruncationResult } from "../session/streaming-output";
+/**
+ * Truncation metadata for the output notice.
+ */
+export interface TruncationMeta {
+    direction: "head" | "tail" | "middle";
+    truncatedBy: "lines" | "bytes" | "middle";
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    maxBytes?: number;
+    /** Line range shown (1-indexed, inclusive). Omitted for middle elision. */
+    shownRange?: {
+        start: number;
+        end: number;
+    };
+    /** Head/tail line ranges shown when direction === "middle". */
+    headRange?: {
+        start: number;
+        end: number;
+    };
+    tailRange?: {
+        start: number;
+        end: number;
+    };
+    /** Bytes elided from the middle. */
+    elidedBytes?: number;
+    /** Lines elided from the middle. */
+    elidedLines?: number;
+    /** Artifact ID if full output was saved */
+    artifactId?: string;
+    /** Next offset for pagination (head truncation only) */
+    nextOffset?: number;
+}
+/**
+ * Source resolution info for the output.
+ */
+export type SourceMeta = {
+    type: "path";
+    value: string;
+} | {
+    type: "url";
+    value: string;
+} | {
+    type: "internal";
+    value: string;
+};
+/**
+ * Limit-specific notices.
+ */
+export interface LimitsMeta {
+    matchLimit?: {
+        reached: number;
+        suggestion: number;
+    };
+    resultLimit?: {
+        reached: number;
+        suggestion: number;
+    };
+    headLimit?: {
+        reached: number;
+        suggestion: number;
+    };
+    columnTruncated?: {
+        maxColumn: number;
+    };
+}
+/**
+ * Structured metadata for tool outputs.
+ */
+export interface OutputMeta {
+    truncation?: TruncationMeta;
+    source?: SourceMeta;
+    limits?: LimitsMeta;
+}
+export interface TruncationOptions {
+    direction: "head" | "tail" | "middle";
+    startLine?: number;
+    totalFileLines?: number;
+    artifactId?: string;
+}
+export interface TruncationSummaryOptions {
+    direction: "head" | "tail" | "middle";
+    startLine?: number;
+    totalFileLines?: number;
+}
+export interface TruncationTextOptions {
+    direction: "head" | "tail" | "middle";
+    totalLines?: number;
+    totalBytes?: number;
+    maxBytes?: number;
+}
+/**
+ * Fluent builder for OutputMeta.
+ *
+ * @example
+ * ```ts
+ * details.meta = outputMeta()
+ *   .truncation(truncation, { direction: "head" })
+ *   .matchLimit(limitReached ? effectiveLimit : 0)
+ *   .columnTruncated(linesTruncated ? DEFAULT_MAX_COLUMN : 0)
+ *   .get();
+ * ```
+ */
+export declare class OutputMetaBuilder {
+    #private;
+    /** Add truncation info from TruncationResult. No-op if not truncated. */
+    truncation(result: TruncationResult, options: TruncationOptions): this;
+    /** Add truncation info from OutputSummary. No-op if not truncated. */
+    truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this;
+    /** Add truncation info from truncated output text. No-op if truncation not detected. */
+    truncationFromText(text: string, options: TruncationTextOptions): this;
+    /** Add match limit notice. No-op if reached <= 0. */
+    matchLimit(reached: number, suggestion?: number): this;
+    /** Add limit notices in one call. */
+    limits(limits: {
+        matchLimit?: number;
+        resultLimit?: number;
+        headLimit?: number;
+        columnMax?: number;
+    }): this;
+    /** Add result limit notice. No-op if reached <= 0. */
+    resultLimit(reached: number, suggestion?: number): this;
+    /** Add limit notice for head truncation. No-op if reached <= 0. */
+    headLimit(reached: number, suggestion?: number): this;
+    /** Add column truncation notice. No-op if maxColumn <= 0. */
+    columnTruncated(maxColumn: number): this;
+    /** Add source path info. */
+    sourcePath(value: string): this;
+    /** Add source URL info. */
+    sourceUrl(value: string): this;
+    /** Add internal URL source info (skill://, agent://, artifact://). */
+    sourceInternal(value: string): this;
+    /** Get the built OutputMeta, or undefined if empty. */
+    get(): OutputMeta | undefined;
+}
+/** Create a new OutputMetaBuilder. */
+export declare function outputMeta(): OutputMetaBuilder;
+export declare function formatFullOutputReference(artifactId: string): string;
+export declare function formatTruncationMetaNotice(truncation: TruncationMeta): string;
+/**
+ * Format notices from OutputMeta for LLM consumption.
+ * Returns empty string if no notices needed.
+ */
+export declare function formatOutputNotice(meta: OutputMeta | undefined): string;
+/**
+ * Resolve the per-line column cap from session settings. Shared by streaming
+ * executors (bash/python/ssh/eval via OutputSink) and the `read` tool's
+ * line-buffer post-processing, so one setting controls both surfaces.
+ */
+export declare function resolveOutputMaxColumns(s: Settings | undefined): number;