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

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;

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

@@ -0,0 +1,102 @@
+import { type MinimizerOptions } from "@oh-my-pi/pi-natives";
+export interface ShellConfig {
+    shell: string;
+    args: string[];
+    env: Record<string, string>;
+    prefix: string | undefined;
+}
+export interface ShellMinimizerSettings {
+    enabled: boolean;
+    settingsPath: string | undefined;
+    only: string[];
+    except: string[];
+    maxCaptureBytes: number;
+    sourceOutlineLevel: "default" | "aggressive";
+    legacyFilters: boolean | undefined;
+}
+export declare function getShellConfig(): ShellConfig;
+export declare const DEFAULT_MINIMIZER_SETTINGS: ShellMinimizerSettings;
+export interface BashExecutorOptions {
+    cwd?: string;
+    /** Milliseconds before aborting the command; 0 disables the executor deadline. */
+    timeout?: number;
+    onChunk?: (chunk: string) => void;
+    chunkThrottleMs?: number;
+    signal?: AbortSignal;
+    /** Session key suffix to isolate shell sessions per agent */
+    sessionKey?: string;
+    /** Additional environment variables to inject */
+    env?: Record<string, string>;
+    /** Run through the configured user shell instead of brush parsing directly. */
+    useUserShell?: boolean;
+    /** Capture the user rc snapshot into the session shell (default true). */
+    snapshotEnabled?: boolean;
+    /** Redefine `rm` in the session shell to move into the system trash (default false). */
+    rmSafe?: boolean;
+    /** Apply non-interactive env hardening to the command environment (default true). */
+    nonInteractiveEnv?: boolean;
+    /** Enable intelligent output minimizer. Default true. */
+    minimizerEnabled?: boolean;
+    /** Minimizer settings (filters, capture budget). Defaults to {@link DEFAULT_MINIMIZER_SETTINGS}. */
+    minimizerSettings?: ShellMinimizerSettings;
+    /** Wrap the command in `bash -c '…'` before execution (full bash environment). */
+    useShellCommandWrapper?: boolean;
+    /** OutputSink tail rolling budget (bytes). Falls back to DEFAULT_MAX_BYTES (50KB). */
+    spillThreshold?: number;
+    /** OutputSink head window (bytes). Falls back to 20KB. */
+    headBytes?: number;
+    /**
+     * Mirror the full raw output stream to this file while it streams — the
+     * upstream `artifactPath` seam (`session.allocateOutputArtifact("bash")`).
+     * The mirror triggers exactly when the inline head+tail windows overflow,
+     * so a spill file exists whenever output was dropped. Lossless by default
+     * (`ARTIFACT_DEFAULT_MAX_BYTES = 0`).
+     */
+    artifactPath?: string;
+    /**
+     * Called when the native minimizer rewrote the output, with the original
+     * pre-minimization text (upstream `onMinimizedSave`). Return the path the
+     * text was saved to; it is surfaced as {@link BashResult.originalOutputPath}
+     * so the model can recover what the minimizer discarded.
+     */
+    onMinimizedSave?: (originalText: string) => string | undefined | Promise<string | undefined>;
+}
+export interface BashResult {
+    output: string;
+    exitCode: number | undefined;
+    cancelled: boolean;
+    /** True when the command was killed by its timeout deadline (not a user abort). */
+    timedOut?: boolean;
+    truncated: boolean;
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    /** Present when the native minimizer rewrote the output. */
+    minimized?: {
+        filter: string;
+        inputBytes: number;
+        outputBytes: number;
+    };
+    /** Path of the spill file mirroring the full raw stream, when one was created. */
+    spillPath?: string;
+    /** Path holding the pre-minimization original text, when {@link onMinimizedSave} saved one. */
+    originalOutputPath?: string;
+    /** Lines/bytes elided between the retained head and tail windows (middle elision). */
+    elidedLines?: number;
+    elidedBytes?: number;
+    workingDir?: string;
+    /** True when the rmSafe injection failed: `rm` stays the system command and deletes permanently. */
+    rmSafeInjectionFailed?: boolean;
+}
+/**
+ * Release every persistent shell owned by `sessionId` (foreground shells and
+ * retained `:async:` shells). Dropping the last reference SIGKILLs the native
+ * shell and its children via kill-on-drop; called on session shutdown/unbind.
+ */
+export declare function closeSessionShells(sessionId: string): void;
+/** Translate `ShellMinimizerSettings` into native `MinimizerOptions`, or `undefined` when disabled. */
+export declare function buildMinimizerOptions(group: ShellMinimizerSettings): MinimizerOptions | undefined;
+export declare function needsInteractiveShellArg(shell: string): boolean;
+export declare function ensureInteractiveShellArgs(shell: string, args: string[]): string[];
+export declare function executeBash(command: string, options?: BashExecutorOptions): Promise<BashResult>;

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

@@ -0,0 +1,33 @@
+export interface BashInterceptorRule {
+    pattern: string;
+    flags?: string;
+    tool: string;
+    message: string;
+    allowSubcommands?: string[];
+}
+/**
+ * 规则表对齐上游 refs/oh-my-pi/packages/coding-agent/src/config/settings-schema.ts:325-387（10 条）。
+ * 既有 6 条（read/grep/glob/edit×3）语义与消息文案保持不变；新增 echo/printf 重定向 → write（上游 :356-367）。
+ * hub 类 3 条（nohup/后台语法、dev/start 服务、--watch，上游 :368-386）按映射决策加入：
+ * pattern 逐字照抄；tool hub → bash（DSH 等价受管机制 = bash 工具 run_in_background:true，
+ * startBashJob → jobs 注册表 → job_output 读输出 / job_kill 停止）；文案改写为 run_in_background 引导。
+ * DSH 无 hub 的 stdin-send/restart/跨实例观察能力，属有意不移植。
+ * `bashInterceptor.patterns` 配置键不在本次范围，未引入。
+ */
+export declare const DEFAULT_BASH_INTERCEPTOR_RULES: BashInterceptorRule[];
+export interface InterceptionResult {
+    /** If true, the bash command should be blocked */
+    block: boolean;
+    /** Error message to return instead of executing */
+    message?: string;
+    /** Suggested tool to use instead */
+    suggestedTool?: string;
+}
+/**
+ * Check if a bash command should be intercepted.
+ *
+ * @param command The bash command to check
+ * @param availableTools Set of tool names that are available
+ * @returns InterceptionResult indicating if the command should be blocked
+ */
+export declare function checkBashInterception(command: string, availableTools: string[], rules?: BashInterceptorRule[], originalCommand?: string): InterceptionResult;