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

package/lib/types/tools/shared/auto-generated-guard.dsh.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A-3 合并后的兼容转发层（second-impl-audit.md A-3）。
+ *
+ * 唯一实现在 `../omp/tools/auto-generated-guard.ts`（OMP 逐字移植 + T17-1
+ * Windows basename 修复）。原「简化重写」已删除：SimpleLRU、手搓 peekFile、
+ * 截断的三步整改文案、推送开关全部移除；开关语义改为 settings-pull
+ * （`edit.blockAutoGenerated`，三级回退 activeSettings → 全局 settings →
+ * schema 默认 true，refs settings-schema.ts:3230）。
+ */
+export { assertEditableFile, assertEditableFileContent, } from '../omp/tools/auto-generated-guard.ts';
+/**
+ * @deprecated 兼容旧推送式 API：守卫已改为 settings-pull（调用方传
+ * session.settings，未传时回退全局/默认），推送开关不再参与行为判定。
+ * 保留为 no-op 以兼容既有 import；src/index.ts 的调用点已删除。
+ */
+export declare function setBlockAutoGenerated(_enabled: boolean): void;

package/lib/types/tools/shared/browser-detect.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Browser executable detection for the read browser renderer — a thin,
+ * fully-injectable shell over the OMP probe family (`src/tools/omp/browser/launch.ts`).
+ *
+ * Two entry points share one candidate pipeline:
+ * - {@link probeBrowsers} — no caching; every call walks the candidate table.
+ *   Backs the settings-panel "探测浏览器" button via the host RPC, so a user
+ *   can re-probe after installing a browser.
+ * - {@link detectBrowser} — memoizes the first success as the renderer's
+ *   executable choice, so repeated reads do not re-stat the filesystem.
+ *
+ * Candidate kinds are annotated for display (`edge` / `chrome` / `chromium` /
+ * `cfr` / `env`); the renderer itself only needs the resolved path, so the
+ * detection result and the launch path never drift.
+ *
+ * Host-side only: this module imports node:fs, so it must never be reached
+ * from the browser client half (it isn't — the client imports the channel
+ * constants module, not this one).
+ * @module @xiaoso/dsh-tool-plus/browser-detect
+ */
+/** Browser family labels surfaced by the detection button. */
+export type BrowserKind = "edge" | "chrome" | "chromium" | "cfr" | "env";
+/** One detected browser executable. */
+export interface DetectedBrowser {
+    kind: BrowserKind;
+    name: string;
+    path: string;
+}
+/** Injectable environment; everything the probe touches comes through here. */
+export interface BrowserDetectEnv {
+    platform: NodeJS.Platform;
+    home: string;
+    which: (name: string) => string | null | undefined;
+    exists: (p: string) => boolean;
+    /** Directory listing for Chrome-for-Testing cache roots. */
+    readdir?: (p: string) => string[];
+    /** PUPPETEER_EXECUTABLE_PATH override (wins over the table). */
+    envPath?: string;
+    /** Chrome-for-Testing cache roots to scan (defaults to getPuppeteerDir()). */
+    cacheDirs?: readonly string[];
+}
+/** Default environment: the real platform/homedir/which/filesystem. */
+export declare function defaultBrowserDetectEnv(): BrowserDetectEnv;
+/** Detect every usable browser on the machine, best first. No caching. */
+export declare function probeBrowsers(env?: BrowserDetectEnv): DetectedBrowser[];
+/**
+ * Resolve the browser the renderer will launch (memoized). Mirrors
+ * {@link ensureChromiumExecutable} priority (PUPPETEER_EXECUTABLE_PATH →
+ * system table → Chrome-for-Testing cache) but keeps its own display
+ * metadata; returns undefined when no browser exists.
+ */
+export declare function detectBrowser(env?: BrowserDetectEnv): DetectedBrowser | undefined;
+/** Clear the memoized detection (re-probe on next call; test seam). */
+export declare function resetBrowserDetectionForTest(): void;

package/lib/types/tools/shared/browser-rpc-channel.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared RPC channel constants for the browser-detection round trip between
+ * the settings panel (client half) and the host. Both halves import this
+ * module so the channel/endpoint never drift.
+ *
+ * The channel rides the official `@deepseek-ai/dsh-client-connection` generic
+ * RPC transport (host registers with `ctx.connection.rpc.handle`; the client
+ * calls via `createWebConnectionRpc().call`). Channel names must match
+ * `/^\/[A-Za-z0-9._~-]+$/` and `/api` is reserved — `/tool-plus` is ours.
+ * @module @xiaoso/dsh-tool-plus/browser-rpc-channel
+ */
+/** Logical RPC channel registered by the host half of this plugin. */
+export declare const TOOL_PLUS_RPC_CHANNEL = "/tool-plus";
+/** Endpoint that probes the machine for usable browsers (probeBrowsers). */
+export declare const BROWSER_DETECT_ENDPOINT = "browser/detect";
+/** Endpoint that reports the rmSafe injection status (query = ensure + verify). */
+export declare const RM_SAFE_STATUS_ENDPOINT = "rmSafe/status";
+/** Payload of a browser/detect call (currently empty). */
+export interface BrowserDetectPayload {
+}
+/** One detected browser as surfaced over the wire. */
+export interface BrowserDetectItem {
+    kind: 'edge' | 'chrome' | 'chromium' | 'cfr' | 'env';
+    name: string;
+    path: string;
+}
+/** Successful browser/detect result. */
+export interface BrowserDetectValue {
+    found: BrowserDetectItem[];
+}
+/** rmSafe/status result (mirrors RmSafeStatus from bash/rm-safe-status). */
+export type RmSafeStatusValue = {
+    status: 'disabled';
+} | {
+    status: 'failed';
+    reason: 'snapshot-unavailable' | 'cli-missing' | 'snapshot-write-failed' | 'runtime-not-effective';
+} | {
+    status: 'injected';
+    runtime: 'function' | 'system' | 'unknown';
+};

package/lib/types/tools/shared/bun-ffi-shim.d.ts

@@ -0,0 +1,13 @@
+/**
+ * DSH named-import shim for `bun:ffi` (pi-utils stderr-guard / process-name).
+ * Both consumers degrade silently when dlopen is unavailable ("Never throws:
+ * bun:ffi unavailability ... degrades silently"), so this shim returns null.
+ */
+export declare const FFIType: Record<string, number>;
+export declare function dlopen(): null;
+export declare const ptr: () => number;
+/** FFI C-string view (pi-tui ttyid) — never populated since dlopen is null. */
+export declare class CString {
+    constructor(_ptr: number);
+    toString(): string;
+}

package/lib/types/tools/shared/bun-named-shim.d.ts

@@ -0,0 +1,42 @@
+import { GlobShim } from './bun-shim.ts';
+export { GlobShim as Glob } from './bun-shim.ts';
+/** Bun.YAML (pi-utils frontmatter) — yaml package under the hood. */
+export declare const YAML: {
+    parse: (s: string) => unknown;
+    stringify: (v: unknown) => string;
+};
+/** Bun build plugin hook (pi-utils module-timer) — inert under Node. */
+export declare function plugin(): void;
+/** Minimal Bun-shell result (pi-ai perplexity OAuth; never reached on non-macOS). */
+declare class BunShellResult {
+    get exitCode(): number;
+    text(): string;
+    quiet(): this;
+    nothrow(): this;
+    cwd(): this;
+}
+/** Bun shell template tag (Bun `$`). Perplexity's macOS defaults read only. */
+export declare function $(_strings: TemplateStringsArray, ..._expr: unknown[]): BunShellResult;
+/** HTTP cookie (pi-ai OAuth flows). */
+export declare class Cookie {
+    #private;
+    name: string;
+    value: string;
+    constructor(name: string, value: string, expires?: Date);
+    static parse(header: string): Cookie;
+    isExpired(): boolean;
+}
+/** Ordered cookie jar (Bun CookieMap surface used by pi-ai OAuth). */
+export declare class CookieMap implements Iterable<[string, string]> {
+    #private;
+    get size(): number;
+    set(name: string, value: string): void;
+    get(name: string): string | undefined;
+    delete(name: string): boolean;
+    has(name: string): boolean;
+    clear(): void;
+    [Symbol.iterator](): Iterator<[string, string]>;
+}
+export type Subprocess = unknown;
+export type Spawn = unknown;
+export type BunFile = GlobShim;

package/lib/types/tools/shared/bun-shim.d.ts

@@ -0,0 +1,138 @@
+export declare class BunFileShim {
+    readonly path: string;
+    constructor(p: string);
+    get size(): number;
+    get name(): string;
+    exists(): Promise<boolean>;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+    writer(): FileSinkShim;
+    /** Bun extension: stat the file (patched Node implementation). */
+    stat(): Promise<{
+        mtimeMs: number;
+        size: number;
+        isDirectory(): boolean;
+    }>;
+    /** Bun extension: delete the file. */
+    unlink(): Promise<void>;
+    /** Bun extension: write content to the file (overwrite). */
+    write(content: string | Uint8Array | Blob | ArrayBuffer): Promise<void>;
+    /** Bun extension: a sub-range view of the file. */
+    slice(start?: number, end?: number): BunFileShim;
+    stream(): ReadableStream<Uint8Array>;
+}
+/** Sub-range view of a file (Bun's `BunFile.slice`). */
+export declare class BunFileSliceShim extends BunFileShim {
+    #private;
+    constructor(filePath: string, start: number, end: number | undefined);
+    get size(): number;
+    text(): Promise<string>;
+    bytes(): Promise<Uint8Array>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Blob semantics: stream yields only the slice window. */
+    stream(): ReadableStream<Uint8Array>;
+}
+export declare class FileSinkShim {
+    #private;
+    constructor(filePath: string);
+    write(chunk: string | Uint8Array): void;
+    flush(): void;
+    end(): void;
+    close(): void;
+}
+export declare class GlobShim {
+    #private;
+    constructor(pattern: string);
+    scan(opts?: {
+        cwd?: string;
+        absolute?: boolean;
+        onlyFiles?: boolean;
+        dot?: boolean;
+    }): AsyncGenerator<string>;
+    match(input: string): boolean;
+}
+declare class CryptoHasherShim {
+    #private;
+    constructor(algorithm: string);
+    update(data: string | Uint8Array): this;
+    digest(encoding: 'hex' | 'base64' | 'buffer' | string): string | Buffer;
+}
+interface ImageStep {
+    op: 'resize' | 'png' | 'jpeg' | 'webp' | 'rotate' | 'flip' | 'blur' | 'sharpen';
+    args: unknown[];
+}
+export declare class BunImageShim {
+    #private;
+    constructor(bytes: Uint8Array | ArrayBuffer, steps?: readonly ImageStep[]);
+    metadata(): Promise<{
+        width: number;
+        height: number;
+        format?: string;
+        hasAlpha?: boolean;
+    }>;
+    resize(widthOrOpts?: number | {
+        width?: number;
+        height?: number;
+        quality?: number;
+    }, height?: number): BunImageShim;
+    /** Bun's resize() accepts { width, height, fit } — expose fit through to sharp. */
+    resizeWithFit(width: number, height: number, fit: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'): BunImageShim;
+    png(): BunImageShim;
+    jpeg(opts?: {
+        quality?: number;
+    }): BunImageShim;
+    webp(opts?: {
+        quality?: number;
+    }): BunImageShim;
+    rotate(): BunImageShim;
+    flip(flip: boolean): BunImageShim;
+    blur(radius: number): BunImageShim;
+    sharpen(radius?: number): BunImageShim;
+    bytes(): Promise<Uint8Array>;
+    toBase64(): Promise<string>;
+    write(destPath: string): Promise<number>;
+}
+type ArchiveMemberContent = string | Uint8Array | Blob;
+declare function archiveWrite(destPath: string, record: Record<string, ArchiveMemberContent>, opts?: {
+    compress?: 'gzip';
+}): Promise<void>;
+export declare function bunStripANSI(text: string): string;
+export interface BunShimSurface {
+    file(path: string): BunFileShim;
+    write(path: string, data: string | Uint8Array | Blob | ArrayBuffer): Promise<void>;
+    env: NodeJS.ProcessEnv;
+    which(command: string, options?: {
+        PATH?: string;
+        cwd?: string;
+    }): string | null;
+    sleep(ms: number): Promise<void>;
+    randomUUIDv7(): string;
+    stringWidth(s: string): number;
+    Glob: typeof GlobShim;
+    Archive: {
+        write: typeof archiveWrite;
+    };
+    FileSink: typeof FileSinkShim;
+    Image: typeof BunImageShim;
+    CryptoHasher: typeof CryptoHasherShim;
+    color(color: string, format?: string): string;
+    stripANSI(text: string): string;
+    JSON: {
+        parse(s: string): unknown;
+        stringify(v: unknown): string;
+    };
+    JSON5: {
+        parse(s: string): unknown;
+    };
+    Encoding: Record<string, never>;
+    native: undefined;
+    BunFile: typeof BunFileShim;
+    version: string;
+    hash: ((input: string | ArrayBuffer | Uint8Array, seed?: number | bigint) => number) & {
+        xxHash64(data: string | ArrayBuffer | Uint8Array, seed?: bigint): bigint;
+    };
+}
+export declare function installBunShim(): void;
+export {};

package/lib/types/tools/shared/bun-sqlite-shim.d.ts

@@ -0,0 +1,49 @@
+import type { StatementSync } from 'node:sqlite';
+/**
+ * Bindings bun:sqlite accepts. Includes `boolean` because the unmodified OMP
+ * write path passes booleans directly; the shim coerces them to `1`/`0` for
+ * node:sqlite, which rejects them.
+ */
+export type SQLQueryBindings = string | number | bigint | boolean | null | Uint8Array;
+/** Constructor options for {@link Database} — a superset of bun's surface. */
+export interface DatabaseOptions {
+    readonly?: boolean;
+    create?: boolean;
+    strict?: boolean;
+}
+/** Wrap a node `StatementSync` in Bun's `Statement` surface. */
+export declare class Statement<T = unknown, B extends unknown[] = unknown[]> {
+    #private;
+    constructor(s: StatementSync);
+    /** First result row as `T`, or `null` when the query returned no row. */
+    get(...params: B): T | null;
+    /** All result rows; node returns `[]` when there are none — normalise to that. */
+    all(...params: B): T[];
+    /** Execute a write statement; returns affected-row and insert info. */
+    run(...params: B): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /** Lazily iterate over result rows. */
+    iterate(...params: B): IterableIterator<T>;
+    /** Number of bind parameters in the prepared SQL. */
+    get paramsCount(): number;
+    /** Column names of the result set (for SELECT statements). */
+    get columnNames(): string[];
+    /** bun's `finalize()` — node closes statements with the database, so no-op. */
+    finalize(): void;
+}
+/** Wrap a node `DatabaseSync` in a bun `Database` surface. */
+export declare class Database {
+    private readonly s;
+    constructor(path: string, opts?: DatabaseOptions);
+    /** Compile a prepared statement. */
+    prepare<T = unknown, B extends unknown[] = unknown[]>(sql: string): Statement<T, B>;
+    /** Execute a SQL string directly (bun `db.run`); no result row set. */
+    run(sql: string): void;
+    /** Execute one or more SQL statements. */
+    exec(sql: string): void;
+    /** Run `fn` inside a BEGIN/COMMIT transaction, rolling back on throw. */
+    transaction<T extends (...args: any[]) => any>(fn: T): T;
+    close(): void;
+}

package/lib/types/tools/shared/fs-promises-shim.d.ts

@@ -0,0 +1,15 @@
+export * from 'fs/promises';
+/** Bun's `node:fs/promises` extension: `exists(path)` → `Promise<boolean>`.
+  * Bun swallows every stat error, not just ENOENT — ENAMETOOLONG on a 60k-char
+  * path also yields false (probe audit-probes/S15/s15-exists4.ts). */
+export declare function exists(path: string): Promise<boolean>;
+/**
+ * Augment the real `node:fs/promises` module type with Bun's `exists` so tsc
+ * (which resolves `node:*` builtins through `@types/node`, not via tsconfig
+ * `paths`) sees the extension on the bundled module too. At build time the
+ * tsdown alias replaces `node:fs/promises` with this shim; at typecheck time
+ * this augmentation covers the direct `node:fs/promises` imports.
+ */
+declare module 'node:fs/promises' {
+    function exists(path: string): Promise<boolean>;
+}

package/lib/types/tools/shared/image-bridge.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared image bridge (拍板#22, 2026-08-28) — the single DSH-facing seam
+ * through which the OMP engines (read's restored image path, fetch's URL
+ * image path) turn image bytes into model-visible content.
+ *
+ * DSH's content model has no inline base64 image block: an ImageBlock is
+ * exactly `{ type: 'image', attachment: ImageAttachmentRef }`
+ * (dsh-llm types). Every image entering the model therefore MUST pass
+ * through the host `attachments` service (saveImage → content-addressed
+ * normalized master → per-request variants). This module owns:
+ *
+ *  - the extension → media-type table (mirrors official dsh-tool-fs),
+ *  - the route vision-capability probe (omp flavor: unknown passes, explicit
+ *    non-image routes soft-refuse to a model-facing metadata text instead of
+ *    a thrown error — 用户拍板 2026-08-28),
+ *  - saveImage + AttachmentError → recoverable-message mapping (official
+ *    read_image's five-branch design, verbatim wording),
+ *  - the `<path>/<type>/<content>` envelope with originalDimensions
+ *    coordinate-multiplier advice (official formatImageReadOutput).
+ *
+ * The OMP layer never imports cordis/dsh packages: engines call these helpers
+ * through `ToolSession.getAttachments` and the exec context the adapter
+ * hands them, keeping the omp/ copies upstream-shaped.
+ */
+export type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** Normalized outcome of one attachment-store commit (official ref shape). */
+export interface SavedImageRef {
+    attachmentId: string;
+    mediaType: ImageMediaType;
+    bytes: number;
+    width: number;
+    height: number;
+    name?: string;
+    originalDimensions?: {
+        width: number;
+        height: number;
+    };
+}
+/** Minimal structural view of the host `attachments` service. */
+export interface AttachmentsService {
+    imageLimits?: {
+        maxImageBytes?: number;
+        maxMessageImageBytes?: number;
+        maxImagePixels?: number;
+        maxImageDimension?: number;
+        mediaTypes?: readonly string[];
+    };
+    saveImage?: (input: {
+        data: Uint8Array;
+        mediaType: string;
+        name?: string;
+    }) => Promise<unknown>;
+}
+/** Minimal structural view of the host `llm` service. */
+export interface LlmRouteService {
+    resolveModelInfo?: (provider: string, model: string, signal: AbortSignal) => Promise<{
+        inputModalities?: readonly string[];
+    }>;
+}
+/**
+ * Facade the DSH adapter builds over ctx.get('attachments')/ctx.get('llm')
+ * plus the calling route, handed to the engines via ToolSession.
+ */
+export interface ImageBridge {
+    attachments: AttachmentsService | undefined;
+    /** 'supported' = route declares image input; 'unsupported' = declares it does not; 'unknown' = not resolvable. */
+    routeImageSupport: () => Promise<'supported' | 'unsupported' | 'unknown'>;
+}
+export declare const IMAGE_EXTENSIONS: Readonly<Record<string, ImageMediaType>>;
+export declare function imageMediaTypeForExtension(ext: string): ImageMediaType | undefined;
+/** Admission byte cap: min(source cap, per-message cap) — official formula. */
+export declare function imageByteCap(bridge: ImageBridge, fallback?: number): number;
+/** Commit bytes to the attachment store, mapping AttachmentErrors to the
+ * official read_image recoverable messages. `displayPath` is only used for
+ * message rendering. Throws Error (not AttachmentError) for model consumption. */
+export declare function saveImageViaBridge(bridge: ImageBridge, input: {
+    data: Uint8Array;
+    mediaType: ImageMediaType;
+    name?: string;
+    displayPath: string;
+}): Promise<SavedImageRef>;
+/** Accept either the official branded ref or a plain object from a mock. */
+export declare function normalizeSavedImageRef(ref: unknown): SavedImageRef;
+export declare function formatImageEnvelope(displayPath: string, image: SavedImageRef): string;
+/** Content blocks for one committed image: envelope text + attachment block. */
+export declare function imageContentBlocks(displayPath: string, image: SavedImageRef): Array<{
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    attachment: SavedImageRef;
+}>;
+export declare function formatImageUnsupportedNote(displayPath: string, metadata: {
+    mimeType?: string;
+    width?: number;
+    height?: number;
+    bytes?: number;
+} | undefined, reason: string): string;

package/lib/types/tools/shared/omp-prompt.d.ts

@@ -0,0 +1,47 @@
+/**
+ * OMP prompt.md → DSH tool description 适配层（verbatim md 不动，适配在此）。
+ *
+ * OMP 的 prompts/tools/*.md 用 Handlebars 条件渲染，DSH 的 defineTool
+ * description 是静态字符串，这里提供：
+ * - `renderOmpPrompt`：完全委托 OMP 自家引擎（@oh-my-pi/pi-utils 的
+ *   prompt.render = 结构化 Handlebars 解析 + post-render format 后处理，
+ *   与上游 read.ts 渲染工具描述同一条管线）。按「移植绝不允许第二套实现」
+ *   （notebook T10-1 同类教训）：自写 regex 渲染器已删除——其全文懒匹配
+ *   会跨条件边界吞并并在真值分支残留孤立 `{{/if}}`（2026-08-28 tools:sdk
+ *   "malformed prompt variable" 事故根源）。strict:false → 未传变量按 falsy
+ *   取 else 分支；畸形模板 compile 期抛错（注册期 fail-loud）。
+ * - `sanitizeOmpPrompt`：按工具剔除 DSH 不适用的 OMP 提法（内部协议
+ *   artifact:// ssh:// memory:// xd://、browser、scout/Task 子代理、inspect_image），
+ *   全部剔除点记录在 step.md「提示词接入」节；md 源文件保持 verbatim 不变。
+ */
+export interface OmpPromptVars {
+    /** read 输出是否带 [PATH#TAG] hashline 锚点头（= edit.mode === 'hashline'） */
+    IS_HL_MODE?: boolean;
+    /** DSH 无 inspect_image 工具：read.md 图片条件句恒渲染 else 分支（引擎内部
+     *  #renderDescription 用），DSH 面再经 sanitizeReadPrompt 改写为附件提交语义
+     *  （拍板#22：图片经 attachments 入库，非 vision 路由降级 metadata 文本）。 */
+    INSPECT_IMAGE_ENABLED?: boolean;
+    /** DSH 无 OMP Task/scout 子代理，恒 false → 相关句在 sanitize 中整体剔除，无需变量 */
+    scoutAvailable?: boolean;
+}
+/** 渲染 {{#if KEY}}A{{else}}B{{/if}} 与 {{#if KEY}}A{{/if}}——委托 OMP 引擎
+ *  （@oh-my-pi/pi-utils prompt.render，strict:false：未传变量按 falsy 取 else
+ *  分支；畸形模板 compile 期抛错，注册期 fail-loud）。保留首尾 trim 对齐
+ *  既有调用点行为。 */
+export declare function renderOmpPrompt(text: string, vars: OmpPromptVars): string;
+/** grep.md：internal URLs 提法 + scout 句剔除。 */
+export declare function sanitizeGrepPrompt(text: string): string;
+/** glob.md：internal URL/memory:// 提法 + scout avoid 句剔除。 */
+export declare function sanitizeGlobPrompt(text: string): string;
+/** read.md：browser 提法剔除 + 图片句改为 DSH 实际行为（拍板#22 附件提交）+ internal URIs 段删除（{{#if}} 由 renderer 处理）。 */
+export declare function sanitizeReadPrompt(text: string): string;
+/** ast-edit.md：xd://resolve 预演确认协议已随内部路由删除；DSH 为预览后自动落盘（拍板#14）。 */
+export declare function sanitizeAstEditPrompt(text: string): string;
+/** ast-grep.md：scout 句剔除。 */
+export declare function sanitizeAstGrepPrompt(text: string): string;
+/** write.md / patch.md / apply-patch.md / replace.md / hashline prompt.md：无 DSH 不适用提法。 */
+export declare function sanitizeWritePrompt(text: string): string;
+export declare function sanitizePatchPrompt(text: string): string;
+export declare function sanitizeApplyPatchPrompt(text: string): string;
+export declare function sanitizeReplacePrompt(text: string): string;
+export declare function sanitizeHashlinePrompt(text: string): string;

package/lib/types/tools/shared/sandbox-policy.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Per-call sandbox policy resolution for DSH file mutations (方案A, 2026-08-27).
+ *
+ * Mirrors the official `@deepseek-ai/dsh-tool-fs` FsSandboxController semantics:
+ * the mounted `ctx.fs` reports `sandboxMode` (the capability fact — undefined
+ * means no confining backend, mutations go unfenced); when a confining backend
+ * is mounted, the shared `sandboxPolicy` service resolves the SESSION's
+ * standing mode + workspace root into the per-call policy that
+ * `ctx.fs.writeText` / `ctx.fs.editText` take as their final argument.
+ *
+ * Differences from the official controller (deliberate, adapter-scoped):
+ *  - No escalation advertisement: OMP-native tool schemas carry no
+ *    `sandbox_permissions`/`justification` fields, so nothing is advertised
+ *    and `FS_SANDBOX_DENIED` surfaces as the provider's own error text.
+ *  - Degradation instead of fail-fast: if `ctx.sandboxPolicy` is missing in a
+ *    composition (host builds always pair it with a confining `ctx.fs`; test
+ *    doubles may not), the policy resolves to `undefined` and the mutation
+ *    falls back to the deployment default — never crash registration.
+ */
+/** Minimal structural type of the policy object produced by `sandboxPolicy.resolve`.
+ * `mode` mirrors the host's closed `SandboxMode` vocabulary
+ * (read-only / workspace-write / danger-full-access) so the object is
+ * structurally assignable to `SandboxExecutionPolicy` without importing the
+ * host-internal type. */
+export type SandboxPolicyMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+export interface SandboxPolicyLike {
+    mode: SandboxPolicyMode;
+    /** Required: the host SandboxExecutionPolicy always carries the workspace
+     * root (session cwd, or the deployment fallback root). */
+    workspaceRoot: string;
+}
+/**
+ * Resolve the per-call mutation policy for the given exec context, or
+ * `undefined` when the mounted filesystem does not confine (or the policy
+ * service is unavailable). Pass the result as the final argument of
+ * `ctx.fs.writeText` / `ctx.fs.editText`.
+ */
+export declare function resolveSandboxPolicy(ctx: any, exec: any): SandboxPolicyLike | undefined;

package/lib/types/tools/shared/session-state.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OMP 引擎 session 级状态（跨工具调用保持）。
+ *
+ * OMP 的 read/write/edit 引擎把冲突注册表（ConflictHistory）、native 编辑存储
+ * （EditStore：hashline 快照 / 寄存器 / no-op 守卫）等挂在 ToolSession 对象上，
+ * 同一 agent 会话内跨工具调用共享。DSH 适配层
+ * 每次 execute 都新建 ToolSession，导致这些状态丢失（T11-2：read 注册的
+ * 冲突 id 在 write 时找不到）。本模块按 DSH Session 对象
+ * （exec.agent.session）持久化这些状态：WeakMap 键控，session 销毁自动
+ * 回收，无泄漏。
+ *
+ * 用法（适配层）：
+ *   1. execute 开始时 `attachOmpSessionState(session, exec?.agent?.session)`
+ *      把上次调用保存的状态挂到新建的 ToolSession 上；
+ *   2. execute 结束后 `persistOmpSessionState(exec?.agent?.session, session)`
+ *      把引擎惰性新建/更新的状态写回共享存储。
+ *
+ * 类型说明：read/write 各自 verbatim 拷贝了一份 conflict-detect.ts，两个
+ * ConflictHistory class 因 `#nextId` 私有字段互不兼容（名义类型）。本模块
+ * 只搬运状态、不调用其方法，故用 `unknown` 宽松承载，避免跨拷贝类型耦合。
+ */
+export interface OmpSessionState {
+    /** 冲突注册表（read 注册 / write 消费）。 */
+    conflictHistory?: unknown;
+    /**
+     * native 编辑存储 `EditStore`（read 锚点 / edit seen-lines 校验 / 锚点漂移恢复 /
+     * CUT-PUT 寄存器 / no-op 循环守卫；A-4 桥接，与 conflictHistory 对称：
+     * attach/persist round-trip）。
+     */
+    editStore?: unknown;
+}
+/** 取（或惰性建）某个 DSH session 的 OMP 状态。 */
+export declare function getOmpSessionState(sessionKey: object): OmpSessionState;
+/**
+ * 把共享状态挂到新建的 ToolSession 上（execute 开始时调用）。
+ * 无 sessionKey（无会话上下文）时跳过——状态不跨调用保持。
+ */
+export declare function attachOmpSessionState(session: {
+    conflictHistory?: unknown;
+    editStore?: unknown;
+}, sessionKey: object | undefined): void;
+/**
+ * 把 ToolSession 上引擎新建/更新的状态写回共享存储（execute 结束后调用）。
+ * OMP 引擎会惰性新建 ConflictHistory / EditStore 并赋到 session
+ * 对象上（如 read.ts 经 getFileSnapshotStore 挂快照库），必须回写才能被
+ * 下一次调用恢复。
+ */
+export declare function persistOmpSessionState(sessionKey: object | undefined, session: {
+    conflictHistory?: unknown;
+    editStore?: unknown;
+}): void;

package/lib/types/tools/shared/tool-errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Standardized error types for tool execution.
+ *
+ * Tools should throw these instead of returning error text.
+ * The agent loop catches and renders them appropriately.
+ */
+/**
+ * Base error for tool execution failures.
+ * Override render() for custom LLM-facing formatting.
+ */
+export declare class ToolError extends Error {
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+    /** Render error for LLM consumption. Override for custom formatting. */
+    render(): string;
+}
+/**
+ * Error thrown when a tool operation is aborted (e.g., via AbortSignal).
+ */
+export declare class ToolAbortError extends Error {
+    static readonly MESSAGE = "Operation aborted";
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Throw ToolAbortError if the signal is aborted.
+ * Use this instead of signal?.throwIfAborted() to get consistent error types.
+ */
+export declare function throwIfAborted(signal?: AbortSignal): void;
+/**
+ * Render an error for LLM consumption.
+ * Handles ToolError.render() and falls back to message/string.
+ */
+export declare function renderError(e: unknown): string;

package/lib/types/tools/shared/win-path-fixes.d.ts

@@ -0,0 +1,16 @@
+export type ProbeResult = 'exists' | 'missing' | 'unknown';
+/**
+ * probe 判定纯函数（供单测直接覆盖修正分支）。
+ *
+ * @param lstatOk lstat 是否成功
+ * @param openOk  open 验证是否成功（仅 needsOpenVerify 时有意义）
+ * @param needsOpenVerify 是否需要对含冒号的 Windows 路径做 open 验证
+ */
+export declare function resolveProbeResult(lstatOk: boolean, openOk: boolean, needsOpenVerify: boolean): ProbeResult;
+/** Windows NTFS ADS 感知的 probe：lstat 成功但 open 失败 → "missing"。 */
+export declare function probeLiteralPathExists(filePath: string, cwd: string): Promise<ProbeResult>;
+/** 字面优先于选择器拆分（修正版 probe）。 */
+export declare function splitPathAndSelPreferringLiteral(rawPath: string, cwd: string): Promise<{
+    path: string;
+    sel?: string;
+}>;