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

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;

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

@@ -0,0 +1,98 @@
+import type { ToolSession } from "../../omp/sdk.ts";
+import type { EditPolicy } from "./index.ts";
+/** Optional overrides for {@link buildHashlineEditPolicy}. */
+export interface HashlinePolicyOptions {
+    /**
+     * The payload is a verbatim custom-format string rather than JSON
+     * (upstream sets this when the call arrived through the custom-tool wire).
+     * DSH never opens an argument stream — it hands `executeHashlineSingle` the
+     * parsed `{ input }` arguments — so this stays `false`.
+     */
+    rawInput?: boolean;
+}
+/**
+ * Canonicalize `cwd` for the engine policy.
+ *
+ * The Rust engine canonicalizes the paths it stores (`recordSnapshot`), but it
+ * uses `policy.cwd` verbatim for path resolution and for its containment check,
+ * and that check compares byte-wise (`path_policy.rs:429-431`). On Windows a
+ * workspace under `%TEMP%` reaches JS in 8.3 short form
+ * (`C:\Users\XIAOSO~1\...`) while the engine's canonical snapshot key is the
+ * long form (`C:\Users\xiaoso456\...`), so an un-normalized `cwd` makes
+ * `is_within` fail and tag path recovery silently skip — verified with
+ * `D:/tmp/hashline-probes/probe-d3-recovery.mts` (raw cwd →
+ * `File not found: a.ts`; canonical cwd → recovered onto `nested/a.ts`).
+ *
+ * `.native` is required: the JS `realpathSync` does NOT expand short names.
+ * A failure (missing directory, permissions) falls back to the input, matching
+ * `canonicalSnapshotKey`'s behaviour so both sides of the store agree on one
+ * spelling.
+ *
+ * The same byte-wise check also drives the plan-sandbox / vault-root
+ * decisions, so normalizing here is what keeps those from silently
+ * mis-evaluating on a short-name cwd. Parity measured this normalization as
+ * neutral for every other policy behaviour (7 scenarios, raw vs canonical).
+ */
+export declare function canonicalCwd(cwd: string): string;
+/**
+ * Build the engine policy for one `hashline` tool call.
+ *
+ * Field sources (all reads go through the DSH settings facade, which maps the
+ * OMP dotted keys onto the tool-plus config — `src/config/omp-settings.ts`):
+ *
+ * - `cwd`               — `session.cwd` through {@link canonicalCwd}: the
+ *                         engine resolves every authored path against it and
+ *                         runs its byte-wise containment check on it
+ *                         (upstream :563 passes the cwd verbatim; the
+ *                         normalization is a DSH-required fix for Windows
+ *                         short names — see {@link canonicalCwd}).
+ * - `mode`              — constant `"hashline"`: this adapter only serves the
+ *                         hashline entry point.
+ * - `allowFuzzy`        — `edit.fuzzyMatch`, default true
+ *                         (`edit/adapter/index.ts:210`).
+ * - `fuzzyThreshold`    — `edit.fuzzyThreshold`, default 0.95 (S-13 above).
+ * - `enforceSeenLines`  — `edit.enforceSeenLines`, schema default false
+ *                         (`src/config/omp-settings.ts:24/72`). **Passed
+ *                         explicitly and never left to a default**: the
+ *                         vendored TS `Patcher` defaulted this to `true`,
+ *                         while upstream/native resolve it from settings
+ *                         (default `false`). The old engine's stricter
+ *                         default therefore deliberately does not survive
+ *                         the migration; DSH follows the settings value
+ *                         (strict boolean, so a missing key reads as "off").
+ * - `blockAutoGenerated`— `edit.blockAutoGenerated`, schema default true
+ *                         (`omp-settings.ts:21/69`); `!== false` mirrors
+ *                         `shouldBlockAutoGeneratedFiles`'s default-on
+ *                         semantics in `omp/tools/auto-generated-guard.ts:297`.
+ * - `planActive`        — upstream reads `session.getPlanModeState()?.enabled`.
+ *                         DSH's plan mode is a hint layer with **no hard
+ *                         gate** (`edit/adapter/tools/plan-mode-guard.ts`
+ *                         documents `enforcePlanModeWrite` as a deliberate
+ *                         no-op), and no DSH session installs
+ *                         `getPlanModeState`, so this resolves to `false`.
+ * - `localSandboxRoot`  — upstream resolves the `local://` root. DSH has no
+ *                         `local://` write sandbox: the edit-path guard
+ *                         (`edit/adapter/tools/plan-mode-guard.ts`) hardcodes
+ *                         `targetsLocalSandbox → false` and documents plan
+ *                         mode as a hint layer, so `undefined` reproduces the
+ *                         old engine's `allowTagPathRecovery` exactly (cwd
+ *                         only). **If DSH ever wires a real sandbox root, it
+ *                         must go through {@link canonicalCwd} too** — the
+ *                         engine's containment check is byte-wise on
+ *                         `localSandboxRoot` just like on `cwd`.
+ *                         Consequence (D-3, awaiting the Lead's ruling): the
+ *                         vendored engine's `allowTagPathRecovery` override —
+ *                         which let a bare/mis-typed authored path rebind onto
+ *                         the file its snapshot tag uniquely names — has no
+ *                         counterpart here. The native engine now decides tag
+ *                         path recovery from `cwd` / `localSandboxRoot` /
+ *                         `vaultRoots` / `homeDir` alone, so a bare filename
+ *                         that needs rebinding fails with native's own error
+ *                         rather than silently landing on a recovered path.
+ * - `vaultRoots`        — upstream `isVaultEnabled() ? cachedVaultRoots() : …`.
+ *                         DSH has no `vault://` protocol → `undefined`.
+ * - `homeDir`           — `os.homedir()` (upstream :571); the engine uses it
+ *                         to recognise and refuse home-directory escapes.
+ * - `rawInput`          — see {@link HashlinePolicyOptions.rawInput}.
+ */
+export declare function buildHashlineEditPolicy(session: ToolSession, options?: HashlinePolicyOptions): EditPolicy;

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

@@ -0,0 +1,42 @@
+import type { ToolSession } from "../../omp/sdk.ts";
+import type { WritethroughCallback } from "../../omp/tools/writethrough.ts";
+import type { EditWriteRequest, EditWriteResponse } from "./index.ts";
+/** Wiring for {@link createHashlineWriter}. */
+export interface HashlineWriterOptions {
+    session: ToolSession;
+    /** DSH's sandbox-routed file-write channel. */
+    writethrough: WritethroughCallback;
+    signal?: AbortSignal;
+}
+/**
+ * The `writer` argument for `EditSession.apply`, carrying the landed-file
+ * record alongside the callback.
+ *
+ * The native callback signature carries a leading `error` (used by the
+ * streaming *preview* channel, never by write requests) — upstream ignores it
+ * the same way (`refs/.../edit/index.ts:576`).
+ */
+export interface HashlineWriter {
+    /** The error-first callback the engine invokes for every landed change. */
+    (error: Error | null, request: EditWriteRequest): Promise<EditWriteResponse>;
+    /**
+     * DSH display paths (`EditWriteRequest.displayPath` — the authored form,
+     * e.g. `a.ts`; for a move the *source*, which is the section that landed) of
+     * every file this apply actually wrote, in write order.
+     *
+     * The engine calls the writer once per file and aborts on the first throw,
+     * so after a rejected payload this holds exactly the sections that are on
+     * disk — the breadcrumb `executeHashlineSingle` re-attaches to the
+     * model-facing error (the old TS engine reported the same list from its
+     * prepared batch, `engine/patcher.ts:287-296` at v17.3.5).
+     */
+    readonly landedPaths: readonly string[];
+}
+/**
+ * Build the `writer` argument for `EditSession.apply`.
+ *
+ * The returned callable also exposes {@link HashlineWriter.landedPaths}; only a
+ * *successful* write is recorded, so a channel refusal on file #2 leaves just
+ * file #1 in the list.
+ */
+export declare function createHashlineWriter(options: HashlineWriterOptions): HashlineWriter;

package/lib/types/tools/omp/browser/launch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-CDP-message timeout applied to every puppeteer launch/connect. Set above
+ * the fetch tool timeout (30s) so the tool wall-clock is the canonical limit;
+ * this constant only catches genuinely stuck CDP sockets.
+ */
+export declare const BROWSER_PROTOCOL_TIMEOUT_MS = 60000;
+/**
+ * Resolve the Chromium executable the browser renderer will launch.
+ * `PUPPETEER_EXECUTABLE_PATH` always wins, then the system
+ * Chrome/Edge/Chromium candidate table (Windows and macOS check mere file
+ * existence; Linux additionally version-probes, see {@link isChromiumExecutable}).
+ * Returns undefined when nothing is found — puppeteer-core would fall back to
+ * its own bundled-Chromium search, which for this package means failure, so
+ * callers should treat undefined as "browser rendering unavailable".
+ *
+ * Unlike OMP upstream there is no Chrome-for-Testing download fallback: this
+ * plugin ships no browser installer, and the detection button only reports
+ * what is already on the machine.
+ */
+export declare function ensureChromiumExecutable(): Promise<string | undefined>;
+/** Reset the cached executable resolution (test seam). */
+export declare function resetChromiumExecutableForTest(): void;
+/** Exposes executable candidates for detection tests (OMP parity export). */
+export declare function systemChromiumCandidatesForTest(platform?: NodeJS.Platform, home?: string, which?: (name: string) => string | null | undefined): string[];
+/** Expose the Linux probe for tests (OMP parity export). */
+export declare function chromiumExecutableProbeForTest(executablePath: string): Promise<boolean>;
+/** Expose the executable-file check for tests. */
+export declare function isExecutableFileForTest(p: string): boolean;