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

package/lib/types/tools/bash/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Plugin configuration, tool argument, and result DTO types for the ported
+ * Oh My Pi bash tool. The runtime `Config` schema lives in `index.ts`.
+ * @module @xiaoso/dsh-tool-plus/types
+ */
+/** Minimizer settings mirroring the native `MinimizerOptions` surface. */
+export interface MinimizerConfig {
+    enabled: boolean;
+    /** Restrict minimization to these filter names (empty = all). */
+    only: string[];
+    /** Exclude these filter names from minimization. */
+    except: string[];
+    /** Output capture budget in bytes; larger outputs pass through raw. */
+    maxCaptureBytes: number;
+}
+/**
+ * Runtime configuration schema for the plugin; declared in `index.ts`
+ * alongside `apply`. Every field is optional at the composition boundary and
+ * defaults inside `apply`; {@link ResolvedConfig} is the fully-defaulted form.
+ */
+export interface Config {
+    /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+    enableRunInBackground?: boolean;
+    /** Foreground commands exceeding this wall time are moved to the background (0 = never). */
+    autoBackgroundMs?: number;
+    /** Deadline applied when the model omits `timeoutMs`. */
+    defaultTimeoutMs?: number;
+    /** Upper clamp for explicit timeouts; `timeoutMs: 0` disables the deadline. */
+    maxTimeoutMs?: number;
+    /** Tail budget for live previews and background-job output reads. */
+    outputMaxBytes?: number;
+    /** OutputSink rolling tail window (bytes). */
+    outputSinkTailBytes?: number;
+    /** OutputSink head window (bytes) retained in addition to the tail. */
+    outputSinkHeadBytes?: number;
+    /** Output minimizer (native intelligent compression for git/npm/cargo/…). */
+    minimizer?: MinimizerConfig;
+    /** Block intercepted commands and suggest the dedicated dsh tool instead. */
+    interceptorEnabled?: boolean;
+    /** Harden the command environment for non-interactive use (pagers, prompts, color). */
+    nonInteractiveEnv?: boolean;
+    /** Capture the user's rc file (aliases, functions, options) into the session shell. */
+    snapshotEnabled?: boolean;
+    /** Redefine `rm` in the session shell to move into the system trash; the plugin config layer decides the default (rmSafe: true). */
+    rmSafe?: boolean;
+    /** Wrap every command in `bash -c '…'` for a full bash environment. */
+    useShellCommandWrapper?: boolean;
+}
+/** {@link Config} with every field resolved to its default. */
+export type ResolvedConfig = Required<Config>;
+/** Parsed tool arguments; execute validates value constraints absent from ParameterSchemaSpec. */
+export interface BashToolArgs {
+    command: string;
+    description: string;
+    timeoutMs?: number;
+    workdir?: string;
+    env?: Record<string, string>;
+    run_in_background?: boolean;
+}
+/** Minimizer facts surfaced with a foreground result. */
+export interface MinimizedOutputInfo {
+    filter: string;
+    inputBytes: number;
+    outputBytes: number;
+}
+/** One collected output stream (single merged stdout+stderr, like the native Shell). */
+export interface CollectedOutput {
+    text: string;
+    truncated: boolean;
+    /** Path of the spill file mirroring the full raw output stream, when one was created. */
+    spillPath?: string;
+    /** Path holding the pre-minimization original text, when the native minimizer rewrote the output. */
+    originalSpillPath?: string;
+    /** Stream counters carried for the truncation notice (OMP OutputSummary parity). */
+    totalLines?: number;
+    totalBytes?: number;
+    outputLines?: number;
+    outputBytes?: number;
+    elidedLines?: number;
+    elidedBytes?: number;
+}
+/** Foreground completion of one bash call. */
+export interface BashForegroundOutput {
+    kind: 'foreground';
+    /** Process exit code; null when the run was interrupted before exit. */
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+    /** The effective deadline in ms (null when the deadline was disabled). */
+    timeoutMs: number | null;
+    /** Wall-clock duration of the run. */
+    wallTimeMs: number;
+    /** The shell's working directory after the command (persists across calls). */
+    workingDir?: string;
+    /** Present when the native minimizer rewrote the output. */
+    minimized?: MinimizedOutputInfo;
+    /** True when the rmSafe injection failed: `rm` deletes permanently. */
+    rmSafeInjectionFailed?: boolean;
+    output: CollectedOutput;
+}
+/** Background acknowledgement: the call returned a managed job id. */
+export interface BashBackgroundOutput {
+    kind: 'background';
+    jobId: string;
+}
+/** The tool's canonical output DTO. */
+export type BashOutput = BashForegroundOutput | BashBackgroundOutput;

package/lib/types/tools/bash/which.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal PATH (+ PATHEXT on Windows) executable lookup — the plugin's single
+ * implementation of `Bun.which` semantics on the Node runtime.
+ *
+ * Two callers, one scanner: DSH code that must resolve executables the way OMP
+ * does (procmgr `resolveWindowsShell` for shell discovery, `REJECT_PROMPT_COMMAND`
+ * in non-interactive-env) calls `findOnPath` directly, and the bun-shim installs
+ * `Bun.which` on top of it — which is also how upstream pi-utils' `$which` lands
+ * here (@oh-my-pi/pi-utils src/which.ts:201 calls `Bun.which` on non-darwin).
+ * Single implementation — any new caller resolves executables through here,
+ * never hand-rolls a PATH walk.
+ * @module @xiaoso/dsh-tool-plus/bash/which
+ */
+/**
+ * Resolve `command` against PATH the way `Bun.which` would: absolute/relative
+ * candidates are returned as-is when they name an existing file; bare names
+ * are looked up in each PATH dir (appending PATHEXT extensions on win32, in
+ * order). Returns the first existing regular file, or `undefined`.
+ */
+export declare function findOnPath(command: string, env?: NodeJS.ProcessEnv): string | undefined;

package/lib/types/tools/bash/windows-shell.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Windows shell discovery, ported from oh-my-pi procmgr's `resolveWindowsShell`
+ * (refs/oh-my-pi/packages/utils/src/procmgr.ts:148-173) — adapted verbatim:
+ * `Bun.env` → injectable Node env (default `process.env`), and pi-utils
+ * `$which` → `findOnPath` (src/tools/bash/which.ts).
+ *
+ * Deliberately NOT ported from procmgr: buildSpawnEnv, shell prefix handling,
+ * direnv integration, and PI_SHELL_PREFIX — DSH has no shell-prefix seam;
+ * commands run inside the embedded brush shell or the resolved user shell.
+ * @module @xiaoso/dsh-tool-plus/bash/windows-shell
+ */
+/**
+ * Resolve the external shell to advertise on Windows.
+ *
+ * A host bash is OPTIONAL: bash tool commands always execute in the embedded
+ * brush-core shell. The resolved binary only serves the spawn-a-shell paths,
+ * so this prefers a real Git Bash when one exists and otherwise falls back to
+ * cmd.exe — it never fails.
+ *
+ * Search order:
+ * 1. Git for Windows install roots (machine + per-user installers)
+ * 2. scoop installs — scoop's git manifest sets GIT_INSTALL_ROOT and shims
+ *    sh.exe/git.exe but never bash.exe, so PATH lookup alone misses it
+ * 3. bash.exe on PATH (Cygwin, MSYS2, ...)
+ * 4. sh.exe on PATH (Git for Windows' sh.exe is bash; prefer a sibling
+ *    bash.exe when present)
+ * 5. cmd.exe from ComSpec
+ *
+ * Exported for tests; `env` overrides process.env-based discovery.
+ */
+export declare function resolveWindowsShell(env?: NodeJS.ProcessEnv): string;

package/lib/types/tools/bash/yield.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Cooperative yield utility for preventing Bun event-loop busy-wait.
+ *
+ * ## Root Cause
+ *
+ * Bun 1.3.x (JavaScriptCore) event loop busy-waits (spins in userspace)
+ * when the only pending work is an unresolved Promise — even if there are
+ * active I/O watchers (stdin, child process pipes, etc.).  The event loop
+ * continuously polls for microtask resolution instead of blocking in
+ * `epoll_wait`, consuming ~100% of a CPU core.
+ *
+ * This affects any `await` on a never-resolved Promise, including:
+ * - `Promise.withResolvers()` used for user input callbacks
+ * - `await proc.exited` for long-running child processes
+ * - Agent loop iterations waiting for the next tool call
+ *
+ * ## Fix
+ *
+ * A recurring `setInterval` keeps the event loop sleeping in `epoll_wait`.
+ * The `EventLoopKeepalive` class and `keepaliveWhile()` wrapper provide a
+ * clean way to install and clean up this keepalive timer.
+ *
+ * The older `yieldIfDue()` and `ExponentialYield` approaches (compensated
+ * sleep loops) are retained for the agent-loop hot-path where Promises
+ * resolve frequently and the keepalive alone is insufficient.
+ */
+export declare class EventLoopKeepalive {
+    #private;
+    [Symbol.dispose](): void;
+}
+/**
+ * Cooperative yield gate. Sleeps for at least {@link YieldGateOptions.sleepMs}
+ * but at most once every {@link YieldGateOptions.intervalMs}; hot-path callers
+ * invoke it freely and only the slow path actually sleeps.
+ *
+ * The clock and sleep are injectable so tests drive the gate logic without
+ * touching process-global `Date.now`/`scheduler.wait` — globals a concurrent
+ * test file can restore mid-run, which previously made the shared gate flake.
+ */
+export interface YieldGateOptions {
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    intervalMs?: number;
+    sleepMs?: number;
+}
+export declare class YieldGate {
+    #private;
+    constructor(opts?: YieldGateOptions);
+    yieldIfDue(signal?: AbortSignal): Promise<void>;
+}
+/**
+ * Yield to the Bun event loop, sleeping for at least 20 ms — but at most once
+ * every {@link YIELD_INTERVAL_MS} across all callers.
+ */
+export declare function yieldIfDue(): Promise<void>;
+export declare class ExponentialYield {
+    #private;
+    constructor(opts?: {
+        minMs?: number;
+        maxMs?: number;
+        multiplier?: number;
+    });
+    notifyActivity(): void;
+    sleep(signal?: AbortSignal): Promise<number>;
+    /**
+     * Race `racers` against an exponentially-backed-off cooperative yield.
+     * The losing sleep is cancelled as soon as a racer settles, so no stray
+     * timers keep the event loop alive past the racer's resolution.
+     */
+    race<T>(racers: Array<Promise<T>>): Promise<T>;
+}

package/lib/types/tools/edit/adapter/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * DSH edit tool — adapter that wires the verbatim OMP edit engine
+ * (`src/tools/omp/edit/`) into DSH's `defineTool` contract.
+ *
+ * This file is pure glue. All edit logic lives in `omp/` (copied verbatim);
+ * this adapter only:
+ *  - builds an OMP `ToolSession` from the DSH exec context + tool-plus config,
+ *  - picks the edit mode from the call shape (replace / patch / hashline /
+ *    apply_patch), exactly like OMP's `EditTool.mode` resolution,
+ *  - hands replace/apply_patch to the verbatim upstream dispatch layer
+ *    (`omp/edit/dispatch.ts`，A-7/A-8：resolveEditPath 路径纠错 +
+ *    executeSinglePathEntries / executeApplyPatchPerFile 聚合) and converts
+ *    the `AgentToolResult` back to a DSH tool result.
+ *
+ * LSP/ACP/TUI are absent in DSH (plan.md 拍板#5/#8): writethrough writes through
+ * ctx.fs, diagnostics are never produced, and no TUI rendering happens.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { WritethroughCallback } from '../../omp/tools/writethrough.ts';
+import type { RuntimeConfig } from '../../../config/settings.ts';
+/** OMP 原版按模式渲染的 edit 描述（prompts/tools/*.md verbatim + native hashline 描述）。 */
+export declare const EDIT_MODE_DESCRIPTIONS: {
+    readonly replace: string;
+    readonly patch: string;
+    readonly apply_patch: string;
+    readonly hashline: string;
+};
+/** File-write channel for DSH (方案A, 2026-08-27): every edit mode funnels
+ * through `ctx.fs` with the per-call sandbox policy resolved from the session
+ * (official tool-fs semantics). The OMP engines pass a `file` handle for
+ * patch/hashline modes — previously this adapter wrote through that handle
+ * (OMP node-fs direct write), bypassing the host's sandbox fence entirely,
+ * while replace mode went through `ctx.fs` WITHOUT the policy argument and
+ * was denied by the deployment fallback. Both defects are fixed here: the
+ * handle is ignored and the policy is always attached. */
+export declare function createWritethrough(ctx: Context, exec: any): WritethroughCallback;
+/** DSH edit 工具输出形状（output.schema 镜像）。 */
+export interface EditToolOutput {
+    text: string;
+}
+/**
+ * S-13：edit.fuzzyThreshold 解析——上游 settings 面原样放行显式 0/负值
+ * （0 = 接受任意置信度的最佳匹配，refs edit/index.ts:112 同款语义），仅
+ * undefined/非数值回退引擎默认 0.95。env 层（上游 PI_EDIT_FUZZY* 环境变量
+ * 串解析）有意不移植：DSH 无该环境变量面，面板字段是唯一入口。
+ */
+export declare function resolveFuzzyThreshold(raw: unknown): number;
+/** 完整执行链路（defineTool.execute 与单测共用，镜像 read 的 executeReadTool）。 */
+export declare function executeEditTool(exec: any, cfg: RuntimeConfig, args: any, ctx: Context | null): Promise<EditToolOutput>;
+/**
+ * Register the edit tool. Mode is resolved per call from the argument shape
+ * (matching OMP's mode dispatch):
+ *  - `input` present → hashline, or apply_patch when it starts with `***`
+ *  - `patch` present → unified-diff patch mode
+ *  - `edits` present (or old_string) → replace mode
+ */
+export declare function registerEdit(ctx: Context, getConfig: () => RuntimeConfig): () => void;

package/lib/types/tools/edit/adapter/tools/auto-generated-guard.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A-3 合并后的纯转发层（second-impl-audit.md A-3）。
+ *
+ * 唯一实现在 `src/tools/omp/tools/auto-generated-guard.ts`（OMP refs
+ * packages/coding-agent/src/tools/auto-generated-guard.ts 的逐字移植，
+ * 含 T17-1 Windows basename 修复）。本文件不再持有任何守卫逻辑，仅为
+ * 既有 import 路径（omp/edit/hashline/filesystem.ts 等历史引用与单测）
+ * 保留转发。
+ */
+export { assertEditableFile, assertEditableFileContent, } from "../../../omp/tools/auto-generated-guard.ts";

package/lib/types/tools/edit/adapter/tools/output-meta.d.ts

@@ -0,0 +1,34 @@
+/**
+ * DSH adapter for OMP `tools/output-meta.ts`.
+ *
+ * OMP attaches LSP diagnostics + output metadata to tool results. LSP
+ * diagnostics are cut (plan.md 拍板#5); the metadata *shape* is kept so
+ * engine code (`outputMeta().get()`) compiles unchanged.
+ */
+export interface TruncationMeta {
+    kind: 'head' | 'tail' | 'middle';
+    startLine?: number;
+    totalFileLines?: number;
+}
+export interface SourceMeta {
+    path?: string;
+    lines?: number;
+}
+export interface LimitsMeta {
+    maxBytes?: number;
+}
+export interface OutputMeta {
+    truncation?: TruncationMeta;
+    source?: SourceMeta;
+    limits?: LimitsMeta;
+}
+/** Fluent builder for OutputMeta. */
+export declare class OutputMetaBuilder {
+    #private;
+    truncation(value: TruncationMeta): this;
+    source(value: SourceMeta): this;
+    limits(value: LimitsMeta): this;
+    get(): OutputMeta;
+}
+/** Create a new OutputMeta builder. */
+export declare function outputMeta(): OutputMetaBuilder;

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

@@ -0,0 +1,21 @@
+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 (verbatim OMP).
+ */
+export declare function unwrapHashlineHeaderPath(targetPath: string): string;
+/** True when `targetPath` resolves inside the local sandbox (DSH: none). */
+export declare function targetsLocalSandbox(_session: ToolSession, _targetPath: string): boolean;
+/**
+ * Resolve a write/edit target to its absolute filesystem path (verbatim OMP
+ * resolution, minus local:// / vault:// schemes which DSH does not have).
+ */
+export declare function resolvePlanPath(session: ToolSession, targetPath: string): string;
+/**
+ * Plan mode hard-gate — deliberately a no-op in DSH (plan mode is a hint
+ * layer; official write/edit do not hard-block, plan.md §3 判定去掉).
+ */
+export declare function enforcePlanModeWrite(_session: ToolSession, _targetPath: string, _options?: {
+    move?: string;
+    op?: 'create' | 'update' | 'delete';
+}): void;

package/lib/types/tools/glob/adapter/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * DSH glob tool — adapter that wires the verbatim OMP glob engine
+ * (`src/tools/glob/adapter/omp/glob.ts`) into DSH's `defineTool` contract.
+ *
+ * This file is pure glue. All glob logic lives in `omp/` (copied verbatim);
+ * this adapter only:
+ *  - builds an OMP `ToolSession` from the DSH exec context + tool-plus config,
+ *  - constructs the verbatim `GlobTool` and calls its `execute`,
+ *  - converts the `AgentToolResult` back to a DSH tool result, appending the
+ *    OMP session-layer meta notice (`formatOutputNotice`, A-6) to the
+ *    model-visible text.
+ *
+ * plan.md 拍板：glob keeps OMP's native single-param style (`path` with a
+ * semicolon-delimited multi-target list). DSH `hidden`/`gitignore`/`limit`
+ * are surfaced verbatim as optional parameters.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AgentToolResult } from '@oh-my-pi/pi-agent-core';
+import type { RuntimeConfig } from '../../../config/settings.ts';
+export type { Settings } from '../../omp/config/settings.ts';
+export type { ToolSession } from '../../omp/sdk.ts';
+/** DSH glob 工具输出形状（output.schema 镜像）。 */
+export interface GlobToolOutput {
+    path: string;
+    text: string;
+    fileCount?: number;
+    truncated?: boolean;
+}
+/**
+ * 把 OMP AgentToolResult 转成 DSH glob 工具输出。
+ *
+ * 上游 session 层会把 `formatOutputNotice(details.meta)` 的限量/截断提示追加
+ * 进模型可见文本（wrapToolWithMetaNotice → appendOutputNotice，refs
+ * tools/output-meta.ts:586）；DSH 无 session 层，适配层在此补上（A-6），
+ * 否则 glob 超限截断对模型静默。
+ */
+export declare function toGlobToolResult(result: AgentToolResult<any>, args: any): GlobToolOutput;
+/**
+ * 完整执行链路（defineTool.execute 与单测共用）。
+ *
+ * `ctx` 参数与 read 的 executeReadTool 对齐（glob 引擎不需要 image bridge /
+ * session state，仅占位保持签名一致）。
+ */
+export declare function executeGlobTool(exec: any, cfg: RuntimeConfig, args: any, ctx: Context): Promise<GlobToolOutput>;
+/**
+ * Register the glob tool (OMP native `path` + optional `hidden`/`gitignore`/
+ * `limit` parameters).
+ */
+export declare function registerGlob(ctx: Context, getConfig: () => RuntimeConfig): void;
+export declare const applyGlob: typeof registerGlob;
+export declare const registerGlobTool: typeof registerGlob;
+export default registerGlob;

package/lib/types/tools/grep/adapter/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * DSH grep tool — adapter that wires the verbatim OMP grep engine
+ * (`src/tools/grep/adapter/omp/`) into DSH's `defineTool` contract.
+ *
+ * This file is pure glue. All grep logic lives in `omp/` (copied verbatim);
+ * this adapter only:
+ *  - builds an OMP `ToolSession` from the DSH exec context + tool-plus config,
+ *  - constructs the verbatim `GrepTool` and calls its `execute`,
+ *  - converts the `AgentToolResult` back to a DSH tool result, appending the
+ *    OMP session-layer meta notice (`formatOutputNotice`, A-6) to the
+ *    model-visible text.
+ *
+ * Parameters follow OMP's native style (`pattern` regex + `path` with inline
+ * `:N-M` selectors); the DSH tool exposes the same schema so nothing is lost.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AgentToolResult } from '@oh-my-pi/pi-agent-core';
+import type { RuntimeConfig } from '../../../config/settings.ts';
+export type { Settings } from '../../omp/config/settings.ts';
+export type { ToolSession } from '../../omp/sdk.ts';
+/** DSH grep 工具输出形状（output.schema 镜像）。 */
+export interface GrepToolOutput {
+    text: string;
+    matchCount?: number;
+    fileCount?: number;
+    files?: string[];
+    scopePath?: string;
+    truncated?: boolean;
+}
+/**
+ * 把 OMP AgentToolResult 转成 DSH grep 工具输出。
+ *
+ * 上游 session 层会把 `formatOutputNotice(details.meta)` 的限量/截断提示追加
+ * 进模型可见文本（wrapToolWithMetaNotice → appendOutputNotice，refs
+ * tools/output-meta.ts:586）；DSH 无 session 层，适配层在此补上（A-6），
+ * 否则 grep 的列宽截断/限量对模型静默。
+ */
+export declare function toGrepToolResult(result: AgentToolResult<any>): GrepToolOutput;
+/**
+ * 完整执行链路（defineTool.execute 与单测共用）。
+ *
+ * `ctx` 参数与 read 的 executeReadTool 对齐（grep 引擎不需要 image bridge /
+ * session state，仅占位保持签名一致）。
+ */
+export declare function executeGrepTool(exec: any, cfg: RuntimeConfig, args: any, ctx: Context): Promise<GrepToolOutput>;
+/**
+ * Register the grep tool (OMP-native `pattern` + `path` parameters; the `path`
+ * accepts an inline `:N-M` selector and may be a semicolon-delimited list).
+ */
+export declare function registerGrep(ctx: Context, getConfig: () => RuntimeConfig): void;
+export declare const applyGrep: typeof registerGrep;
+export declare const registerGrepTool: typeof registerGrep;
+export default registerGrep;

package/lib/types/tools/grep/adapter/match-path.d.ts

@@ -0,0 +1 @@
+export declare function matchAbsolutePath(matchPath: string, searchPath: string): string;

package/lib/types/tools/hashline/native/diff-preview.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Re-number a unified diff that uses the `+<lineNum>|content` /
+ * `-<lineNum>|content` / ` <lineNum>|content` line format into a compact
+ * current-file preview. Removed lines are counted for stats and post-edit
+ * offset tracking, but omitted from the preview. Added and context lines are
+ * anchored to their post-edit positions so a follow-up edit can reuse visible
+ * concrete lines directly. Long contiguous added runs are summarized with a
+ * `…` marker instead of echoing every inserted line.
+ *
+ * This is intentionally decoupled from the diff producer: anything that
+ * emits the `<sign><lineNum>|<content>` shape works.
+ *
+ * Migration note: the native engine has no equivalent export — its rendered
+ * `EditFileOutcome.text` already carries a compact preview, so DSH's
+ * `executeHashlineSingle` passes that text through untouched. This module is
+ * kept because `EditFileOutcome.diff` (and the diff/apply-patch engines) use
+ * the very same `<sign><lineNum>|<content>` shape, so the helper still has
+ * consumers. The algorithm is a **verbatim port** of the vendored
+ * `src/tools/hashline/engine/diff-preview.ts` (itself a verbatim port of the
+ * pre-18.0 TS engine), with the two option/result types inlined from that
+ * engine's `types.ts:147-160` so this file has no dependency on the deleted
+ * engine directory.
+ */
+/** Result of {@link buildCompactDiffPreview}. */
+export interface CompactDiffPreview {
+    preview: string;
+    addedLines: number;
+    removedLines: number;
+}
+/** Optional knobs for {@link buildCompactDiffPreview}. */
+export interface CompactDiffOptions {
+    /** Added lines kept on each side of a long added-run elision (default 2). */
+    maxAddedRunContext?: number;
+    /** Back-compat alias for {@link maxAddedRunContext}. */
+    maxUnchangedRun?: number;
+}
+export declare function buildCompactDiffPreview(diff: string, options?: CompactDiffOptions): CompactDiffPreview;

package/lib/types/tools/hashline/native/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * DSH adapter for the native (Rust) hashline engine.
+ *
+ * Upstream deleted the TypeScript `@oh-my-pi/hashline` package in 18.x and
+ * rewrote the engine as `crates/pi-edit/src/modes/hashline/*.rs`, exposed
+ * through `@oh-my-pi/pi-natives`. This module is the single seam DSH keeps
+ * against it, and it is a **verbatim port** of the two upstream TS files that
+ * replaced the old engine surface:
+ *
+ * - `refs/oh-my-pi/packages/coding-agent/src/tools/hashline-format.ts` (41L)
+ *   → the `HL_*` constants plus the format/hash helpers below.
+ * - `refs/oh-my-pi/packages/coding-agent/src/edit/store.ts` (19L)
+ *   → {@link getEditStore}.
+ *
+ * The multi-mode transport (`Patcher`/`Filesystem`/`Clipboard`/`InMemorySnapshotStore`)
+ * is gone on purpose: `EditSession.apply` owns staging, snapshot validation,
+ * `N*` block resolution, clipboard registers, the no-op loop guard, and the
+ * model-facing text. Hosts only supply an {@link EditPolicy} and a writer
+ * callback — see `./policy.ts` and `./writer.ts`.
+ *
+ * `tsconfig.json` aliases `@oh-my-pi/hashline` onto this module, so the DSH
+ * tools that only need the display/format helpers (read / write / grep /
+ * ast-edit / ast-grep / plan-mode-guard) import it directly.
+ */
+import { blockRangeAt, EditSession, EditStore, editAutoGeneratedMessage, editDescription, editDiffString, editGrammar, editInspect, hashlineCountOps, structuredPatchHunks } from "@oh-my-pi/pi-natives";
+import type { BlockRange, BlockRangeOptions, EditApplyOutcome, EditApplyRequest, EditDiffResult, EditFileOpIntent, EditFileOutcome, EditFilePreview, EditInspection, EditMatcherEntry, EditPolicy, EditPreviewBatch, EditVaultRoot, EditWriteRequest, EditWriteResponse } from "@oh-my-pi/pi-natives";
+import { buildCompactDiffPreview } from "./diff-preview.ts";
+import type { CompactDiffOptions, CompactDiffPreview } from "./diff-preview.ts";
+import { detectLineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize.ts";
+import type { BomResult, LineEnding } from "./normalize.ts";
+/** Opens the `[path#tag]` section header. */
+export declare const HL_FILE_PREFIX = "[";
+/** Closes the `[path#tag]` section header. */
+export declare const HL_FILE_SUFFIX = "]";
+/** Separates the path from the tag inside a section header. */
+export declare const HL_FILE_HASH_SEP = "#";
+/** Hex digits in a section tag. */
+export declare const HL_FILE_HASH_LENGTH = 4;
+/** `MV` op keyword. */
+export declare const HL_MOVE_KEYWORD = "MV";
+/** `REM` op keyword. */
+export declare const HL_REM_KEYWORD = "REM";
+/** Separates an op locator from its body. */
+export declare const HL_LINE_BODY_SEP = ":";
+/** `[path#TAG]` section header. */
+export declare function formatHashlineHeader(path: string, tag: string): string;
+/** `N:line` numbered display rows starting at `startLine` (default 1). */
+export declare function formatNumberedLines(text: string, startLine?: number): string;
+/**
+ * One `N:line` display row. Composed in TS rather than delegated: the native
+ * surface has no single-line formatter (`hashlineFormatNumberedLines` takes a
+ * whole text), and the JS join is byte-identical to the native row shape —
+ * upstream composes it the same way (hashline-format.ts:26-28).
+ */
+export declare function formatNumberedLine(lineNumber: number, line: string): string;
+/**
+ * Split `text` into addressable rows, dropping the empty row a trailing
+ * newline produces. Upstream hashline-format.ts:30-34; the native engine
+ * numbers the same way internally.
+ */
+export declare function splitAddressableFileLines(text: string): string[];
+/** Strip hashline display prefixes (`N:` / `+N:` …) from pasted rows. */
+export declare function stripHashlinePrefixes(lines: string[]): string[];
+/** 4-hex hashline content tag for `text`. */
+export declare function computeFileHash(text: string): string;
+/** Owner of the lazily created per-session store. */
+export interface EditStoreOwner {
+    editStore?: EditStore;
+}
+/**
+ * The session's store, created on first use (verbatim upstream
+ * `edit/store.ts:15-18`).
+ *
+ * One store per session carries the full-file snapshots that mint hashline
+ * tags, the `CUT`/`PUT` clipboard registers, and the byte-identical no-op loop
+ * guard — every {@link EditSession} the edit tool opens shares it, and the
+ * read/search/write tools mint their tags into it.
+ *
+ * DSH note: DSH rebuilds its `ToolSession` object on every tool call and
+ * round-trips the store through `shared/session-state.ts`, so the engine path
+ * reaches the store through `getFileSnapshotStore` in
+ * `src/tools/omp/edit/file-snapshot-store.ts`, which delegates here.
+ */
+export declare function getEditStore(session: EditStoreOwner): EditStore;
+/**
+ * Raised when the native engine rejects a payload.
+ *
+ * The Rust engine reports every rejection as an `isError` outcome carrying the
+ * model-facing text — mismatched tag, unseen anchor line, missing file, no-op
+ * escalation (upstream `edit/index.ts:495-497` returns it as a tool result).
+ * DSH's `edit` tool contract is throw-based (`toText` in
+ * `src/tools/edit/adapter/index.ts` throws when a result is `isError`), and
+ * DSH's per-file detail shape carries `displayErrorText` sourced from
+ * `MismatchError.displayMessage` (`details.ts`, `dispatch.ts`), so
+ * `executeHashlineSingle` re-raises the native text as this class. Both
+ * `message` and `displayMessage` are exactly the native text, so the model
+ * sees the teaching message unchanged.
+ *
+ * (Upstream's pre-18.0 `MismatchError` formatted its own richer diagnostic
+ * from structured fields; the native text already contains that diagnostic,
+ * hence the single-string shape.)
+ */
+export declare class MismatchError extends Error {
+    /** Model/TUI-facing text — always identical to {@link Error.message}. */
+    readonly displayMessage: string;
+    constructor(message: string);
+}
+export { blockRangeAt, buildCompactDiffPreview, detectLineEnding, EditStore, EditSession, editAutoGeneratedMessage, editDescription, editDiffString, editGrammar, editInspect, hashlineCountOps, normalizeToLF, restoreLineEndings, stripBom, structuredPatchHunks, };
+export type { BlockRange, BlockRangeOptions, BomResult, CompactDiffOptions, CompactDiffPreview, EditApplyOutcome, EditApplyRequest, EditDiffResult, EditFileOpIntent, EditFileOutcome, EditFilePreview, EditInspection, EditMatcherEntry, EditPolicy, EditPreviewBatch, EditVaultRoot, EditWriteRequest, EditWriteResponse, LineEnding, };

package/lib/types/tools/hashline/native/normalize.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Minimal text-shape normalization: line-ending detection / round-trip and
+ * BOM stripping. The edit engines use these to canonicalize text to LF before
+ * applying edits and to restore the original shape on write-back.
+ *
+ * Migration note: this is a **verbatim port** of the vendored
+ * `src/tools/hashline/engine/normalize.ts` (itself a verbatim port of the
+ * pre-18.0 TS engine). The Rust engine has no equivalent exports — it
+ * normalizes internally and never hands these primitives back to the host —
+ * but DSH's own edit paths (`omp/edit/normalize.ts`, which re-exports this
+ * module through the `@oh-my-pi/hashline` alias, plus `read`/`write`/`grep`
+ * snapshot recording) still need them. Kept here so the single hashline seam
+ * keeps its old export surface after the engine directory was deleted.
+ */
+export type LineEnding = "\r\n" | "\n";
+/** Detect the first line ending style in `content`. Defaults to LF when neither is present. */
+export declare function detectLineEnding(content: string): LineEnding;
+/** Normalize every line ending to LF. */
+export declare function normalizeToLF(text: string): string;
+/** Re-encode LF text with the requested line ending. */
+export declare function restoreLineEndings(text: string, ending: LineEnding): string;
+export interface BomResult {
+    /** Either the empty string or the BOM sequence (currently UTF-8 BOM). */
+    bom: string;
+    /** Text with any leading BOM removed. */
+    text: string;
+}
+/** Strip a UTF-8 BOM if present and return both the BOM and the trailing text. */
+export declare function stripBom(content: string): BomResult;