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

package/lib/types/client/web-connection-rpc.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Browser caller for the plugin's Connection RPC channel.
+ *
+ * The official `@deepseek-ai/dsh-client-connection/client` package ships the
+ * protocol primitives as types (`RpcFetch`, `ClientConnectionRpc`, `RpcResult`)
+ * and the `RpcId` brand, but its published `createWebConnectionRpc` factory is
+ * internal to the bundle — not re-exported. This module re-implements that
+ * factory against the same public wire contract (docs/api-gateway.md, the
+ * client `rpc.ts` source): a `POST {origin}/{channel}/{endpoint}` with a
+ * `client-request` JSON envelope, answered by a `server-response` envelope
+ * echoing the rpcId. Host-side registration uses the official
+ * `ctx.connection.rpc.handle` — this file only mirrors the caller half.
+ * @module @xiaoso/dsh-tool-plus/client/web-connection-rpc
+ */
+import type { ClientConnectionRpc, RpcFetch } from '@deepseek-ai/dsh-client-connection/client';
+/**
+ * Create the browser-backed generic RPC caller for the plugin's channel
+ * (the `/tool-plus` host registration). Wire-compatible with the official
+ * ClientConnectionRpc contract; only the transport override differs.
+ * @param doFetch - transport override; defaults to the page's global fetch.
+ */
+export declare function createWebConnectionRpc(doFetch?: RpcFetch): ClientConnectionRpc;

package/lib/types/config/fields.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tool-plus configuration single source of truth: every settable field across
+ * all ported tools (bash + read + write/edit guard), its kind, default value,
+ * UI copy keys, and its group/tool membership — plus the tool-tab map the
+ * settings page renders.
+ *
+ * This module is intentionally dependency-free (no host services): both the
+ * Host schema (`src/config/settings.ts`) and the browser settings UI
+ * (`src/client/*`) read from it, so a default or a field can never drift
+ * between the two planes. The only import is the locale key type, which is
+ * type-only and erased at build time.
+ * @module @xiaoso/dsh-tool-plus/config
+ */
+import type { BashPlusLocaleKey } from '../client/locales.ts';
+/** A scalar value a settings field can hold (mirrors the schema types). */
+export type ToolPlusFieldValue = number | boolean | string;
+/** Field control kinds the settings UI renders. */
+export type ToolPlusFieldKind = 'number' | 'boolean' | 'select' | 'action';
+/** One selectable option of a `select` field. */
+export interface ToolPlusSelectOption {
+    value: string;
+    labelKey: BashPlusLocaleKey;
+}
+/** Conditional visibility: show this field only while a condition field matches. */
+export interface ToolPlusFieldVisibility {
+    /** Show only while this boolean field is true (a master switch). */
+    requiresEnabled?: string;
+    /** Show only while this select field equals the value. */
+    requiresSelect?: {
+        field: string;
+        value: string;
+    };
+    /** Hide while this select field equals the value (e.g. hide head bytes in tail mode). */
+    hideWhenSelect?: {
+        field: string;
+        value: string;
+    };
+}
+/** One configurable field of the plugin's tools. */
+export interface ToolPlusField {
+    /** Settings namespace key (flat schema key). */
+    name: string;
+    /** Control kind the UI renders. */
+    kind: ToolPlusFieldKind;
+    /** Schema default; a cleared user field reverts to this value. */
+    default: ToolPlusFieldValue;
+    /** Locale keys for the control label and hint. */
+    labelKey: BashPlusLocaleKey;
+    hintKey: BashPlusLocaleKey;
+    /** Group id (a Bash subgroup or the whole-tool group); order = render order. */
+    group: string;
+    /** Owning tool tab. */
+    tool: ToolPlusToolId;
+    /** Options for `select` fields. */
+    options?: readonly ToolPlusSelectOption[];
+    /** Conditional visibility (master switches, strategy-dependent fields). */
+    visibility?: ToolPlusFieldVisibility;
+    /** Host RPC endpoint for `action` fields (channel-relative, e.g. `browser/detect`). */
+    actionKey?: string;
+}
+/** Tool tabs of the settings page; `fields: []` = no global settings. */
+export interface ToolPlusTab {
+    id: ToolPlusToolId;
+    labelKey: BashPlusLocaleKey;
+    /** Field names owned by this tool, in render order. */
+    fields: readonly string[];
+}
+/** Identifiers of every tool tab. */
+export type ToolPlusToolId = 'bash' | 'read' | 'writeEdit' | 'grep' | 'glob' | 'astGrep' | 'astEdit';
+/** Field group ids -> locale key of the group heading. */
+export declare const TOOL_PLUS_GROUP_LABELS: Record<string, BashPlusLocaleKey>;
+/**
+ * Every field of the plugin, in schema order. Defaults mirror
+ * `src/config/settings.ts` schema + `resolveConfig` — this table is the
+ * single source; settings.ts reads from here.
+ */
+export declare const TOOL_PLUS_FIELDS: readonly ToolPlusField[];
+/** Tool tabs in nav order; empty `fields` = no configurable settings. */
+export declare const TOOL_PLUS_TABS: readonly ToolPlusTab[];
+/** Look up one field definition by its schema key. */
+export declare function toolPlusField(name: string): ToolPlusField | undefined;
+/** Fields of one tool tab, in table order. */
+export declare function toolPlusFieldsOf(tool: ToolPlusToolId): readonly ToolPlusField[];
+/** Every schema key, for settings-schema parity tests. */
+export declare const TOOL_PLUS_FIELD_NAMES: readonly string[];

package/lib/types/config/omp-settings.d.ts

@@ -0,0 +1,21 @@
+/**
+ * tool-plus 统一 OMP 配置注册表（单一事实源）。
+ *
+ * 所有移植工具（read/write/edit/grep/glob/ast_edit/ast_grep）的 OMP settings
+ * 键集中定义在这里：
+ * - `OMP_DEFAULTS`：每个键的默认值，verbatim 取自 OMP `config/settings-schema.ts`
+ *   （refs/oh-my-pi/packages/coding-agent/src/config/settings-schema.ts，5880 行注册表），
+ *   引擎行为与上游一致。
+ * - `OMP_KEY_TO_FIELD`：OMP dotted key → DSH tool-plus 扁平配置字段（fields.ts）
+ *   的映射；未映射的键走默认值（如 LSP/web-search/autoqa 等 DSH 不暴露的
+ *   能力，默认值兜底即可，不会降级）。
+ *
+ * 各工具 adapter 的 `config/settings.ts` / `config/settings-schema.ts` 引用
+ * 本模块，消除多份重复定义。新增配置键只改这里 + fields.ts。
+ */
+/** OMP dotted key -> flat tool-plus config field (when present). */
+export declare const OMP_KEY_TO_FIELD: Record<string, string | undefined>;
+/**
+ * OMP schema 默认值（verbatim，来源见上）。键 = OMP settings-schema.ts 的注册键。
+ */
+export declare const OMP_DEFAULTS: Record<string, unknown>;

package/lib/types/config/settings.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Plugin-owned settings surface for the ported bash tool: the `bash-plus`
+ * namespace, a FLAT settings schema (OMP `bash*`-style scalar keys — the
+ * client scope writes scalar fields only), its defaults, the mapping onto the
+ * nested {@link RuntimeConfig} the runtime consumes, and the optional-settings
+ * consumer wiring. Keeping the whole config-export surface here lets the
+ * ported OMP runtime stay pristine — the entry only calls
+ * {@link installBashPlusSettings} and re-exports this module's `Config`.
+ * @module @xiaoso/dsh-tool-plus/settings
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { MinimizerConfig } from '../tools/bash/types.ts';
+/** Truncation strategy for background→foreground completion messages (OMP config parity). */
+export type OutputTruncateStrategy = 'bytes' | 'lines';
+/** Retention mode for a truncated completion message: head, tail, or middle (head+tail). */
+export type OutputRetentionMode = 'head' | 'tail' | 'middle';
+/** Byte-based retention settings; `middle` keeps head+tail, `head`/`tail` keep one window. */
+export interface ByteRetentionConfig {
+    mode: OutputRetentionMode;
+    headBytes: number;
+    tailBytes: number;
+}
+/** Reader-backend preference for URL reads (`providers.fetch` parity). */
+export type FetchReaderPreference = 'auto' | 'native' | 'trafilatura' | 'lynx' | 'parallel' | 'jina' | 'browser';
+/** Line-based retention settings, mirroring the byte-based structure. */
+export interface LineRetentionConfig {
+    mode: OutputRetentionMode;
+    headLines: number;
+    tailLines: number;
+}
+/**
+ * Background-job completion text truncation (mirrors the OMP `bashOutputTruncate*`
+ * family). Only the settled preview text is affected; streaming reads and the
+ * completion notice are untouched.
+ */
+export interface OutputTruncateConfig {
+    strategy: OutputTruncateStrategy;
+    /** Threshold (in `strategy` units) below which the text is kept intact. */
+    triggerBytes: number;
+    triggerLines: number;
+    bytes: ByteRetentionConfig;
+    lines: LineRetentionConfig;
+}
+/**
+ * The resolved runtime configuration, nested for the OMP runtime consumers.
+ * {@link RuntimeConfig} is built from the flat {@link Config} by
+ * {@link resolveConfig}; the OMP-ported runtime files never see the flat shape.
+ */
+export interface RuntimeConfig {
+    enableRunInBackground: boolean;
+    autoBackgroundMs: number;
+    defaultTimeoutMs: number;
+    maxTimeoutMs: number;
+    outputMaxBytes: number;
+    outputSinkTailBytes: number;
+    outputSinkHeadBytes: number;
+    minimizer: MinimizerConfig;
+    interceptorEnabled: boolean;
+    nonInteractiveEnv: boolean;
+    snapshotEnabled: boolean;
+    rmSafe: boolean;
+    useShellCommandWrapper: boolean;
+    maxBackgroundJobs: number;
+    outputTruncate: OutputTruncateConfig;
+    editBlockAutoGenerated: boolean;
+    editMode: string;
+    editFuzzyMatch: boolean;
+    editFuzzyThreshold: number;
+    editEnforceSeenLines: boolean;
+    readSummarizeEnabled: boolean;
+    readSummarizeProse: boolean;
+    readSummarizeMinBodyLines: number;
+    readSummarizeMinCommentLines: number;
+    readSummarizeMinTotalLines: number;
+    readSummarizeUnfoldUntil: number;
+    readSummarizeUnfoldLimit: number;
+    readDefaultLimit: number;
+    readLineNumbers: boolean;
+    readRenderMarkdown: boolean;
+    readConcurrentSafe: boolean;
+    grepContextBefore: number;
+    grepContextAfter: number;
+    grepCaseDefault: boolean;
+    grepGitignoreDefault: boolean;
+    globGitignoreDefault: boolean;
+    globHiddenDefault: boolean;
+    astGrepEnabled: boolean;
+    astEditEnabled: boolean;
+    fetchEnabled: boolean;
+    fetchMaxTimeoutSeconds: number;
+    fetchReader: FetchReaderPreference;
+    browserReaderEnabled: boolean;
+    imagesAutoResize: boolean;
+    imagesBlockImages: boolean;
+    imagesExcludeWebp: boolean;
+    imagesInputMaxBytes: number;
+    imagesResizeMaxSide: number;
+    imagesResizeMaxBytes: number;
+    imagesResizeMinSide: number;
+    imagesResizeJpegQuality: number;
+}
+/** Settings namespace of this plugin, served to the web Plugins page. */
+export declare const BASH_PLUS_SETTINGS_NS = "tool-plus";
+/** OMP-parity defaults for the completion-message truncation policy. */
+export declare const DEFAULT_OUTPUT_TRUNCATE: OutputTruncateConfig;
+/**
+ * Timing knobs (ms). DEFAULT_MAX_TIMEOUT_MS is OMP-parity (= upstream bash
+ * per-tool max 3600s); DEFAULT_TIMEOUT_MS was deliberately relaxed from
+ * 300_000 to 3_600_000 with the bash-plus settings card (763023e,
+ * 2026-08-19) — NOT OMP-parity (OMP bash default is 300s), compensated by
+ * auto-backgrounding after DEFAULT_AUTO_BACKGROUND_MS. By design there is no
+ * upstream `tools.maxTimeout` global-cap equivalent: maxTimeoutMs always
+ * applies. (second-impl-audit.md S-11 终局, 2026-08-29.)
+ */
+export declare const DEFAULT_TIMEOUT_MS = 3600000;
+export declare const DEFAULT_MAX_TIMEOUT_MS = 3600000;
+export declare const DEFAULT_AUTO_BACKGROUND_MS = 60000;
+export declare const DEFAULT_MAX_BACKGROUND_JOBS = 15;
+/**
+ * Plugin settings, one scalar key per option — every field is writable through
+ * the client `SettingsScope.set`/`unset`. Defaults live in the {@link Config}
+ * schema and in {@link resolveConfig}.
+ */
+export interface Config {
+    enableRunInBackground?: boolean;
+    autoBackgroundMs?: number;
+    defaultTimeoutMs?: number;
+    maxTimeoutMs?: number;
+    outputMaxBytes?: number;
+    outputSinkTailBytes?: number;
+    outputSinkHeadBytes?: number;
+    minimizerEnabled?: boolean;
+    interceptorEnabled?: boolean;
+    nonInteractiveEnv?: boolean;
+    snapshotEnabled?: boolean;
+    /** Redefine `rm` in the session shell to move into the system trash (default true). */
+    rmSafe?: boolean;
+    useShellCommandWrapper?: boolean;
+    maxBackgroundJobs?: number;
+    outputTruncateStrategy?: OutputTruncateStrategy;
+    outputTruncateTriggerBytes?: number;
+    outputTruncateTriggerLines?: number;
+    outputTruncateByteMode?: OutputRetentionMode;
+    outputTruncateByteHeadBytes?: number;
+    outputTruncateByteTailBytes?: number;
+    outputTruncateLineMode?: OutputRetentionMode;
+    outputTruncateLineHeadLines?: number;
+    outputTruncateLineTailLines?: number;
+    editBlockAutoGenerated?: boolean;
+    editMode?: 'replace' | 'patch' | 'hashline' | 'apply_patch';
+    editFuzzyMatch?: boolean;
+    editFuzzyThreshold?: number;
+    editEnforceSeenLines?: boolean;
+    readSummarizeEnabled?: boolean;
+    readSummarizeProse?: boolean;
+    readSummarizeMinBodyLines?: number;
+    readSummarizeMinCommentLines?: number;
+    readSummarizeMinTotalLines?: number;
+    readSummarizeUnfoldUntil?: number;
+    readSummarizeUnfoldLimit?: number;
+    readDefaultLimit?: number;
+    readLineNumbers?: boolean;
+    readRenderMarkdown?: boolean;
+    readConcurrentSafe?: boolean;
+    grepContextBefore?: number;
+    grepContextAfter?: number;
+    grepCaseDefault?: boolean;
+    grepGitignoreDefault?: boolean;
+    globGitignoreDefault?: boolean;
+    globHiddenDefault?: boolean;
+    astGrepEnabled?: boolean;
+    astEditEnabled?: boolean;
+    fetchEnabled?: boolean;
+    fetchMaxTimeoutSeconds?: number;
+    fetchReader?: FetchReaderPreference;
+    browserReaderEnabled?: boolean;
+    imagesAutoResize?: boolean;
+    imagesBlockImages?: boolean;
+    imagesExcludeWebp?: boolean;
+    imagesInputMaxBytes?: number;
+    imagesResizeMaxSide?: number;
+    imagesResizeMaxBytes?: number;
+    imagesResizeMinSide?: number;
+    imagesResizeJpegQuality?: number;
+}
+/**
+ * Runtime configuration schema for the plugin. The namespace resolves through
+ * this flat surface; {@link resolveConfig} maps it onto {@link RuntimeConfig}.
+ */
+export declare const Config: z<Config>;
+/**
+ * Resolve the flat settings (composition entry or the settings document) to
+ * the nested runtime config the ported OMP runtime consumes. A direct mount
+ * (`ctx.plugin`) skips the Loader's schema parse, so the `?? default` pass
+ * mirrors the schema; the settings namespace resolution rides the same path.
+ * @param config - flat settings, possibly partial and not schema-parsed.
+ * @returns the fully-defaulted nested runtime config.
+ */
+export declare function resolveConfig(config: Config): RuntimeConfig;
+/**
+ * Install the optional-settings consumer wiring for this plugin: while a
+ * settings provider is mounted, resolve through the `tool-plus` namespace
+ * (schema defaults → composition entry `base` → user document) and forward the
+ * scope to `onSource`; when none is mounted, keep the composition entry, so
+ * the tool keeps working exactly as composed. Mirrors the official bash-local
+ * pattern so a committed change applies without a reload.
+ * @param ctx - plugin context owning the wiring.
+ * @param entry - composition entry config declared by the caller.
+ * @param onSource - receives a thunk of the currently authoritative runtime config.
+ */
+export declare function installBashPlusSettings(ctx: Context, entry: Config, onSource: (current: () => RuntimeConfig) => void): void;

package/lib/types/config/truncate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Config-driven output truncation for background→foreground completion text.
+ * Provenance (second-impl-audit.md S-1, 2026-08-29): the truncation
+ * primitives (truncateHead/Middle/Tail, TruncationResult) are OMP 17.3.5
+ * verbatim, imported directly from `../omp/session/streaming-output.ts`;
+ * the composition layer below (trigger threshold + retention mode + notice
+ * format) is a plugin-specific design shipped with the bash-plus settings
+ * card (763023e, 2026-08-19) — `applyConfiguredTruncation` has no
+ * counterpart in refs/oh-my-pi 17.3.5, so the old "ported verbatim from the
+ * OMP bash-runtime" claim was unverifiable and has been dropped.
+ * @module @xiaoso/dsh-tool-plus/truncate
+ */
+import type { OutputTruncateConfig } from './settings.ts';
+/** Line count of `text` (newline count + 1), matching the OMP helper. */
+export declare function countTextLines(text: string): number;
+/**
+ * Truncate a background job's completion text per the configured strategy
+ * (bytes/lines), trigger threshold, and retention mode (head/tail/middle) —
+ * ported from the OMP bash-runtime `applyConfiguredTruncation`. Returns the
+ * text unchanged when it does not exceed the trigger threshold; otherwise
+ * appends a notice describing the truncation.
+ * @param text - the completion text to truncate.
+ * @param fullOutputPath - optional path to the full output, appended to the notice.
+ * @param truncate - the resolved truncation policy.
+ * @returns the (possibly truncated) completion text.
+ */
+export declare function applyConfiguredTruncation(text: string, fullOutputPath: string | undefined, truncate: OutputTruncateConfig): string;

package/lib/types/host/browser-probe-rpc.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Host half of the tool-plus RPC channel: registers the `/tool-plus` logical
+ * channel on the official Connection transport and answers
+ * `browser/detect` (probe the machine for usable browsers) and
+ * `rmSafe/status` (query = ensure + verify the rmSafe injection). The
+ * settings panel (client half) calls these through
+ * `createWebConnectionRpc().call(...)` — the documented public RPC surface
+ * of `@deepseek-ai/dsh-client-connection`, not a private plugin hook.
+ *
+ * Trust policy is `loopback`: the probe only reports local filesystem paths,
+ * so it must never be reachable from a non-loopback host. Registration is
+ * best-effort — if `connection` is missing (non-web deployments) or the
+ * channel is already taken, the endpoints are simply unavailable and the
+ * panel shows "Unavailable".
+ * @module @xiaoso/dsh-tool-plus/host/browser-probe-rpc
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Install-time dependencies: live config reads (hot-reload safe). */
+export interface ToolPlusRpcDeps {
+    /** Whether rmSafe is currently enabled (resolved config). */
+    getRmSafe: () => boolean;
+}
+/**
+ * Install the tool-plus RPC endpoints. Returns a disposer that removes
+ * the registration (call it from the plugin's `ctx.effect` teardown).
+ * Never throws for "unavailable" — the return value tells the caller whether
+ * the channel is actually live.
+ */
+export declare function installBrowserProbeRpc(ctx: Context, deps: ToolPlusRpcDeps): () => Promise<void> | void;

package/lib/types/index.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type Config } from './config/settings.ts';
+export declare const name = "tool-plus";
+export declare const inject: string[];
+export { Config } from './config/settings.ts';
+export declare function apply(ctx: Context, config?: Config): void;

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

@@ -0,0 +1,26 @@
+/**
+ * DSH ast_edit tool — adapter that wires the verbatim OMP AST edit engine
+ * (`src/tools/ast-edit/adapter/omp/ast-edit.ts`) into DSH's `defineTool` contract.
+ *
+ * This file is pure glue. All edit logic lives in `omp/` (copied verbatim from
+ * OMP `tools/ast-edit.ts`); this adapter only:
+ *  - builds an OMP `ToolSession` from the DSH exec context + tool-plus config,
+ *  - constructs the verbatim `AstEditTool` and calls its `execute`,
+ *  - converts the `AgentToolResult` back to a DSH tool result.
+ *
+ * Parameter shape is OMP-native (`ops[{pat,out}]` + `paths[]`), mirroring
+ * `tools/ast-edit.ts` verbatim (plan.md 拍板#11 keeps this shape). No TUI/ACP
+ * rendering happens in DSH; the model-facing `result.text` is surfaced directly.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RuntimeConfig } from '../../../config/settings.ts';
+export type { ToolSession } from './sdk.ts';
+/**
+ * Register the ast_edit tool. Argument shape matches OMP verbatim:
+ * `ops` is a non-empty array of `{ pat, out }` rewrite rules, and `paths` is a
+ * non-empty array of files, directories, globs, or internal URLs.
+ */
+export declare function registerAstEdit(ctx: Context, getConfig: () => RuntimeConfig): () => void;
+export declare const applyAstEdit: typeof registerAstEdit;
+export declare const registerAstEditTool: typeof registerAstEdit;
+export default registerAstEdit;

package/lib/types/tools/ast-edit/adapter/sdk.d.ts

@@ -0,0 +1,49 @@
+/**
+ * DSH adapter for OMP's `sdk.ts` — the `ToolSession` interface the ast_edit
+ * engine consumes.
+ *
+ * ast_edit reuses the read engine's tool-scope resolver (`resolveToolSearchScope`
+ * from `src/tools/read/adapter/omp/path-utils.ts`) and the native edit store
+ * (`getFileSnapshotStore` from `src/tools/omp/edit/file-snapshot-store.ts`), so this
+ * session facade only declares the members those engines actually touch. DSH
+ * supplies the session adapter (`src/tools/ast-edit/adapter/index.ts`); the
+ * resolve/apply queue, local:// router, skills, and snapshot store are DSH-side
+ * and optional (absent → preview-apply resolution is inert, matching read).
+ */
+import type { Settings } from '../../omp/config/settings.ts';
+import type { Skill } from '../../omp/extensibility/skills.ts';
+import type { AgentToolResult } from '@oh-my-pi/pi-agent-core';
+import type { Model } from '@oh-my-pi/pi-ai';
+/** Tool-choice queue for staged resolution previews (DSH: never present). */
+export interface ToolChoiceQueueLike {
+    registerPendingInvoker: (id: string, toolName: string, invoker: ResolveInvoker) => void;
+    removePendingInvoker: (id: string) => void;
+}
+/** Staged resolution invocation runner (DSH: never present). */
+export type ResolveInvoker = (invocation: unknown) => Promise<AgentToolResult<unknown>>;
+/**
+ * Minimal ToolSession surface used by the OMP ast_edit engine (verbatim member
+ * shapes). DSH provides a session adapter implementing this interface.
+ */
+export interface ToolSession {
+    /** Current working directory */
+    cwd: string;
+    /** Whether an edit-capable tool is available (controls hashline output) */
+    hasEditTool?: boolean;
+    /** Session settings (read keys and edit keys; DSH maps them onto tool-plus config). */
+    settings: Settings;
+    /** Active model string for edit-mode resolution (optional in DSH). */
+    getActiveModelString?: () => string | undefined;
+    /** Active model object (optional in DSH). */
+    getActiveModel?: () => Model | undefined;
+    /** Native edit store (created lazily by the engine; hashline snapshots). */
+    editStore?: import('../../hashline/native/index.ts').EditStore;
+    /** Local protocol options (DSH has no local:// sandbox — optional). */
+    localProtocolOptions?: import('../../omp/internal-urls/index.ts').LocalProtocolOptions;
+    /** Pre-loaded skills (DSH: none). */
+    skills?: readonly Skill[];
+    /** Tool-choice queue (resolution devices; DSH: adapter-installed, captures the apply). */
+    getToolChoiceQueue?: () => ToolChoiceQueueLike | undefined;
+    /** Captured preview-apply invoker (DSH resolve channel, plan.md 拍板#14). */
+    pendingInvoker?: () => Promise<AgentToolResult<unknown>>;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * DSH ast_grep tool — adapter that wires the verbatim OMP AST grep engine
+ * (`src/tools/ast-grep/adapter/omp/ast-grep.ts`) into DSH's `defineTool`
+ * contract.
+ *
+ * This file is pure glue. All search logic lives in `omp/` (copied verbatim
+ * from OMP `tools/ast-grep.ts`); this adapter only:
+ *  - builds an OMP `ToolSession` from the DSH exec context + tool-plus config,
+ *  - constructs the verbatim `AstGrepTool` and calls its `execute`,
+ *  - converts the `AgentToolResult` back to a DSH tool result.
+ *
+ * ast_grep is a READ-ONLY query: it matches AST patterns and returns hashline
+ * headers + line-numbered matches. There is no preview or apply step.
+ *
+ * Parameter shape is OMP-native (`pat` + optional `path`/`skip`), mirroring
+ * `tools/ast-grep.ts` verbatim. No TUI/ACP rendering happens in DSH; the
+ * model-facing `result.text` is surfaced directly.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RuntimeConfig } from '../../../config/settings.ts';
+export type { ToolSession } from './sdk.ts';
+/**
+ * Register the ast_grep tool. Argument shape matches OMP verbatim:
+ * `pat` is a required AST pattern; `path` optionally selects files,
+ * directories, globs, or internal URLs (semicolon-delimited list); `skip`
+ * optionally skips the first N matches.
+ */
+export declare function registerAstGrep(ctx: Context, getConfig: () => RuntimeConfig): () => void;
+export declare const applyAstGrep: typeof registerAstGrep;
+export declare const registerAstGrepTool: typeof registerAstGrep;
+export default registerAstGrep;

package/lib/types/tools/ast-grep/adapter/sdk.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DSH adapter for OMP's `sdk.ts` — the `ToolSession` interface the ast_grep
+ * engine consumes.
+ *
+ * ast_grep is a read-only AST search tool. It reuses the read engine's tool
+ * scope resolver (`resolveToolSearchScope` from
+ * `src/tools/read/adapter/omp/path-utils.ts`), the native edit store
+ * (`recordFileSnapshot`/`recordSeenLinesFromBody` from
+ * `src/tools/omp/edit/file-snapshot-store.ts`), and the display-mode
+ * resolver (`resolveFileDisplayMode`), so this session facade declares exactly
+ * those members. DSH supplies the session adapter
+ * (`src/tools/ast-grep/adapter/index.ts`); the local:// router, skills, and
+ * snapshot store are DSH-side and optional (absent → read-scope resolution and
+ * hashline recording are inert, matching read). `getSessionSpawns` feeds the
+ * scout-spawnability hint in the tool description (`isScoutSpawnable`); when
+ * absent DSH defaults to unrestricted (`"*"`).
+ */
+import type { Settings } from '../../omp/config/settings.ts';
+import type { Skill } from '../../omp/extensibility/skills.ts';
+import type { Model } from '@oh-my-pi/pi-ai';
+/**
+ * Minimal ToolSession surface used by the OMP ast_grep engine (verbatim member
+ * shapes). DSH provides a session adapter implementing this interface.
+ */
+export interface ToolSession {
+    /** Current working directory */
+    cwd: string;
+    /** Whether an edit-capable tool is available (suppresses hashline output) */
+    hasEditTool?: boolean;
+    /** Session settings (read keys and task keys; DSH maps them onto tool-plus config). */
+    settings: Settings;
+    /** Active model string for edit-mode resolution (optional in DSH). */
+    getActiveModelString?: () => string | undefined;
+    /** Active model object (optional in DSH). */
+    getActiveModel?: () => Model | undefined;
+    /** Native edit store (created lazily by the engine; hashline snapshots). */
+    editStore?: import('../../hashline/native/index.ts').EditStore;
+    /** Local protocol options (DSH has no local:// sandbox — optional). */
+    localProtocolOptions?: import('../../omp/internal-urls/index.ts').LocalProtocolOptions;
+    /** Pre-loaded skills (DSH: none). */
+    skills?: readonly Skill[];
+    /** Session subagent-spawn policy string, used for the scout hint (optional in DSH). */
+    getSessionSpawns?: () => string | null | undefined;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Spill-file lifecycle for the bash tool, adapted from OMP's session artifact
+ * seam (`session.allocateOutputArtifact("bash")` + `saveBashOriginalArtifact`)
+ * to the plain Node filesystem: spill files live under `<tmpdir>/dsh-bash-spill/`,
+ * one unique file per call, written losslessly by the executor's OutputSink
+ * `artifactPath` mirror. A best-effort sweep removes files older than 24h
+ * (including the legacy flat `dsh-bash-*.log` naming from before this module),
+ * so orphaned captures do not accumulate across restarts.
+ * @module @xiaoso/dsh-tool-plus/bash/adapter/spill
+ */
+/** Directory holding all bash spill files. */
+export declare function spillDir(): string;
+/**
+ * Allocate one unique spill file path for a call. The directory is created on
+ * first use; allocation failure (read-only tmp, exotic sandbox) returns
+ * `undefined` and the caller simply runs without a spill mirror.
+ */
+export declare function allocateSpillFile(): string | undefined;
+/**
+ * Allocate one unique file for a minimizer original capture (upstream
+ * `saveBashOriginalArtifact`). Same failure semantics as {@link allocateSpillFile}.
+ */
+export declare function allocateOriginalFile(): string | undefined;
+/**
+ * Write pre-minimization original text to a fresh file.
+ * Returns the path, or `undefined` when the write failed.
+ */
+export declare function saveOriginalText(text: string): string | undefined;
+/**
+ * Best-effort sweep of orphaned spill files: everything under the spill dir
+ * plus the legacy flat `tmpdir/dsh-bash-*.log` files older than 24h. Never
+ * throws; returns the number of files removed.
+ */
+export declare function sweepStaleSpillFiles(now?: number): number;

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

@@ -0,0 +1,40 @@
+/**
+ * Background-job adaptation for the `ctx.jobs` seam: one managed job runs its
+ * command on its OWN `:async:` Shell (never the session's persistent shell),
+ * so background work never blocks the foreground session. The registry owns
+ * identity, lifecycle state, and completion notices (`dsh-tool-jobs` injects
+ * them); this module owns the execution resources and their hooks.
+ * @module @xiaoso/dsh-tool-plus/background
+ */
+import type { JobHooks } from '@deepseek-ai/dsh-jobs';
+import type { BashForegroundOutput, ResolvedConfig } from './types.ts';
+export interface ManagedBashJob {
+    /** Hooks handed to `ctx.jobs.start`'s `run()`. */
+    hooks: JobHooks;
+    /**
+     * The run's completion in tool-result terms. Foreground callers that
+     * auto-background and then finish within the wait window resolve this to
+     * return a foreground result; the registry's `done` maps it to an outcome.
+     */
+    completion: Promise<BashForegroundOutput>;
+}
+/** Options for {@link startBashJob}. */
+export interface StartBashJobOptions {
+    /** Session id prefix for the job's shell key (`<sessionId>:async:<nonce>`). */
+    sessionId: string;
+    command: string;
+    cwd: string;
+    /** Effective deadline in ms; `undefined`/0 disables the job deadline. */
+    timeoutMs: number | undefined;
+    /** Command-scoped environment (already merged with dshEnv). */
+    env: Record<string, string> | undefined;
+    config: ResolvedConfig;
+}
+/**
+ * Start one managed background bash job. The producer owns a per-job
+ * `AbortController` (cancellation kills only this job's shell), a bounded
+ * preview tail, and a consuming delta cursor for `readOutput`.
+ * @param options - job identity and execution parameters.
+ * @returns the registry hooks plus the tool-result completion promise.
+ */
+export declare function startBashJob(options: StartBashJobOptions): ManagedBashJob;