dsh-ops 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this package are recorded here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.4] — Independently toggled components
+
+- Split the market bundle into shell (on), file (on), and background (off) rows with exported per-component titles, descriptions, icons and locales.
+- Publish five tools by default, nine with background enabled. Stop publishing duplicate foreground ops_run. Preserve the bash/PowerShell 7 routing and the object-root bash schema.
+- Own separate prompt sections for each component; visibility and shutdown withdraw only the matching guidance/tools. Do not append to AGENTS.md.
+- Share one ref-counted plugin-owned FastCtx connection for file/background. Drain in-flight calls and attempt to kill only remembered owned jobs when background stops; report cleanup failures.
+- Replace the unconditional bundle pwshPath override with a runtime-only official config lifecycle overlay; shell OFF recomputes the executor's current owning raw config without persisting changes.
+- Document release-age version selection and the limits of token savings. No host/vendor implementation, old regression suite, or Actions changes.
+
 ## [0.2.3] — Strict-argument guidance and display metadata
 
 - Add one routing-section reminder: `ops_* arguments are strict: pass only declared fields.` Keep FastCtx's portable schema subset and runtime guards unchanged.

package/PROVENANCE.md

@@ -3,6 +3,30 @@
 What this repository is, where its parts came from, what was verified, and what
 was not.
 
+## 0.2.4 Component lifecycle
+
+Three exported subpath plugins replace the single bundle row: shell/file on by
+default, background off. Each owns its registrations and system-prompt section;
+file and background lease one plugin-owned MCP connection scoped to the Cordis root.
+No global host registry or service methods are replaced. Foreground ops_run is no
+longer published. Background shutdown drains tracked calls, attempts to kill only
+remembered job IDs, then releases its connection lease; disconnect can still lose
+ownership, so cleanup is not guaranteed for unknown durable jobs.
+
+The unconditional pwsh-sandbox patch is removed. Shell mounts an internal/config
+waterfall hook targeted at the official pwsh-sandbox row, then uses public
+Fiber.update(rawConfig, true) to apply/revoke the temporary path via the official
+config lifecycle (noSave). Removing the hook recomputes from the latest owning raw
+config, not a stale saved copy. It does not mutate a service/config reference, write
+profile files, change OS defaults or cancel existing host shell processes. An
+isolated real Cordis/ToolRuntime inspection verified independent tool/prompt
+withdrawal, permission-gated commands, shared-client leases, and config restoration
+with a stand-in executor. Real desktop marketplace toggles and the real sandbox
+executor require user validation; no model requests/old suites were run.
+
+Default schema bytes drop from 10,700 (0.2.3 ten tools) to 7,685 (five tools).
+This is a byte metric, not a tokenizer or proof of lower whole-task usage.
+
 ## 0.2.3 Prompt and display update
 
 Add one model-facing sentence in `lib/policy.js`: `ops_* arguments are strict:

package/README.en.md

@@ -41,10 +41,12 @@ dsh plugin --profile dsh-tui add dsh-ops
 Update by repeating the npx install command, or official `add dsh-ops@latest`.
 Reload/restart as the application requests; replacing loaded code may require restart.
 
-The current version is `0.2.3`: it reminds the model to pass only declared `ops_*`
-fields and updates the display title, descriptions, and icon. It retains the 0.2.2
-bash parameter schema fix. Runtime dependencies remain pinned to `0.2.1`; their
-original release record is in [docs/release-0.2.1.md](docs/release-0.2.1.md).
+Version `0.2.4` adds three independently toggled components and retains the bash
+object-root schema fix and custom icon. Runtime dependencies remain at `0.2.1` and
+install automatically. Desktop pnpm's 24-hour release-age policy may show new metadata
+but select an older package for a bare name: specify `dsh-ops@0.2.4` from the official
+npm registry, confirm the installed version, then fully quit/restart. See the original
+[payload release record](docs/release-0.2.1.md).
 
 ```console
 npx --yes dsh-ops@latest status --profile desktop
@@ -56,11 +58,32 @@ also remove profile dependency references. Runtime files are package dependencie
 not a new shared provisioned directory. System shells, other profiles and package
 manager caches are never manually deleted. Clean legacy provisioned files separately
 with `npx --yes dsh-ops@latest uninstall --yes`; `~/.fastctx/` is kept unless
-`--purge-fastctx` is explicit. Unload/downgrade does not prove durable jobs stopped.
+`--purge-fastctx` is explicit. Background OFF drains in-flight calls and attempts to
+kill only jobs remembered by this component on its current connection; failures warn.
+Lost ownership after disconnect and permission downgrade do not guarantee termination.
+
+## Components and prompts
+
+| Component | Default | Capability |
+| --- | --- | --- |
+| dsh-ops-bash & powershell 7 | On | Prefer ops_bash for general commands; bundled PowerShell 7 for Windows-native work |
+| dsh-ops-file | On | Rust batch reads, search, path discovery and replacement |
+| dsh-ops-background | Off | Scientific simulations, model training and other long-running tasks |
+
+Each row owns its tools and runtime prompt section; OFF withdraws both. Nothing is
+appended to AGENTS.md. Shell ON adds a runtime-only configuration overlay for the
+stock pwsh-sandbox path; OFF recomputes its latest owning raw configuration via the
+official lifecycle, without writing profile files. It does not change the OS default
+terminal or cancel already-running host commands. File/background share one owned
+FastCtx connection; turning one off does not stop the other. Default tool count is
+five; duplicate ops_run is no longer published. Reduced fixed schema cost is not a
+promise of lower task-total tokens. Minimal's complete persona excludes extra sections;
+PTC invokes the tools through its generated SDK with unchanged permission checks.
 
 ## Configuration and tools
 
-Edit the dsh-ops row's `config` in the DSH configuration editor. Unknown keys fail.
+Edit the corresponding dsh-ops/shell, dsh-ops/file or dsh-ops/background row's config.
+Unknown keys fail; normal component enablement is available in the marketplace.
 
 ```yaml
 config:
@@ -75,8 +98,8 @@ config:
   # bashPath: 'C:\tools\bash.exe'
 ```
 
-`enableShellTools` controls the FastCtx command/job group; `publishBashTool` controls
-bash. Both additionally require authoritative session `danger-full-access`; bash
+`enableShellTools` controls the background component's four run/job tools; file never
+publishes commands. `publishBashTool` controls bash. Both additionally require authoritative session `danger-full-access`; bash
 also requires the host subprocess service. `promptPolicy` controls compact routing;
 `extraGuidance` appends text. RPC wait timeout does not prove server termination.
 `required` fails activation on unavailable runtime. Explicit binary/bash paths are
@@ -90,7 +113,6 @@ authoritative. `shellPolicy: deny-host-shell` blocks `deniedHostTools` (default
 | ops_glob | Multiple path patterns and exclusions | No command gate¹ |
 | ops_replace | Mechanical cross-file replacement; host edit for precise edits | No command gate¹ |
 | ops_bash | Preferred general bash executor | Required |
-| ops_run | Bounded bash result | Required |
 | ops_run_background | Start background jobs | Required |
 | ops_job_output / ops_job_list / ops_job_kill | Operate on this session's owned jobs | Required |
 | Host pwsh | Bundled PowerShell 7 Windows-native operations | Host policy |

package/README.md

@@ -40,7 +40,7 @@ dsh plugin --profile dsh-tui add dsh-ops
 
 **更新**：重新运行相同的 `npx --yes dsh-ops@latest install --profile ...`，或用官方 CLI `add dsh-ops@latest`。按应用提示重载；替换已加载代码时重启应用。
 
-当前 npm 版本为 `0.2.3`：提示词提醒 `ops_*` 只传声明字段，标题统一为 `dsh-ops`，并更新中英文介绍和图标；保留 `0.2.2` 的 bash schema 修复，三个运行包仍使用 `0.2.1`。原始载荷发布记录见 [docs/release-0.2.1.md](docs/release-0.2.1.md)。
+当前版本 `0.2.4` 支持三个独立组件；bash 参数 schema 修复和自定义图标保留。三个二进制依赖继续使用 `0.2.1`，它们会自动安装，不影响主插件版本。新发布版本可能受桌面 pnpm 的 24 小时安全冷却策略影响：如果市场分析版号与安装结果不一致，指定 `dsh-ops@0.2.4` 并选择 npm 官方源，确认实际版本后完全退出并重启。原始载荷记录见 [docs/release-0.2.1.md](docs/release-0.2.1.md)。
 
 **卸载与查看状态**：
 
@@ -51,14 +51,29 @@ npx --yes dsh-ops@latest uninstall --profile desktop
 
 把 `desktop` 换成 `web` 或 `tui` 即可。也可在市场卸载，或执行官方 `dsh plugin --profile ... remove dsh-ops`。二进制随 profile 的插件依赖管理；卸载移除依赖引用，不误删系统 shell、其它 profile 的副本或包管理器共享缓存。
 
-旧版显式 provision 的 `<DSH_HOME>/dsh-ops/` 文件需单独清理：`npx --yes dsh-ops@latest uninstall --yes`。默认不删 `~/.fastctx/` 持久状态；需要时显式加 `--purge-fastctx`。卸载/降权不保证已经启动的持久后台任务终止，先处理自己的任务。
+旧版显式 provision 的 `<DSH_HOME>/dsh-ops/` 文件需单独清理：`npx --yes dsh-ops@latest uninstall --yes`。默认不删 `~/.fastctx/` 持久状态；需要时显式加 `--purge-fastctx`。关闭后台组件会等待已发出的调用，然后尝试终止该组件当前连接记住的自有任务；失败会告警。断线丢失归属的旧任务及单纯降权不保证终止，先处理自己的任务。
+
+## 组件开关与提示词
+
+官方市场显示三个组件，分别启停，首次安装默认开启前两个：
+
+| 组件 | 介绍 | 默认 | 发布的工具 |
+| --- | --- | --- | --- |
+| `dsh-ops-bash & powershell 7` | 将默认终端改为bash，以及bash覆盖不到时提供powershell7 | 开 | `ops_bash`；宿主 `pwsh` 使用随包 PowerShell 7 |
+| `dsh-ops-file` | 更快、更高性能、输出更精简更省token的rust文件检索 | 开 | 四个文件工具 |
+| `dsh-ops-background` | 为科研仿真、模型训练及其他长进程后台任务提供托管 | 关 | 启动、输出、列出、终止后台任务 |
+
+“默认终端改为 bash”指模型提示优先使用 `ops_bash`，**不修改系统默认终端、PATH 或宿主原有 shell 工具名称**。Shell 组件开时，通过官方配置生命周期临时指定 `pwsh-sandbox` 的 PowerShell 7 路径；关时按执行器最新原配置恢复，不写 profile 配置。执行器配置切换不代表取消已在运行的宿主命令。
+
+提示词注册为独立运行时段，**不写 AGENTS.md**：Shell 关就撤销 bash/pwsh 路由；文件关就撤销检索说明；后台关就不发布后台工具及自有 job 指导。文件与后台共享一个插件拥有的 FastCtx 连接，关闭其中一个不关闭另一个。默认仅新增五个工具，不发布重复前台 `ops_run`。这些改变减少固定声明成本，**不保证任意任务总 token 降低**。极简预设会覆盖附加 system sections；PTC 模式经 SDK 调用底层工具，权限门不变。
 
 ## 配置方式与工具列表
 
-在 DSH 的配置编辑器中找到 `dsh-ops` 行，调整 `config` 后保存；未知配置键会点名报错。主要默认值：
+在 DSH 的配置编辑器中找到对应的 `dsh-ops/shell`、`dsh-ops/file` 或 `dsh-ops/background` 行，调整 `config` 后保存；未知配置键会点名报错。也可直接在市场切换组件。主要配置：
 
 ```yaml
 config:
+  # background component only; its market row is disabled by default
   enableShellTools: true
   publishBashTool: true
   promptPolicy: true
@@ -70,9 +85,9 @@ config:
   # bashPath: 'C:\tools\bash.exe'
 ```
 
-- `enableShellTools`：部署开关，开启仍须会话 `danger-full-access` 才发布 FastCtx 命令/job 组。
+- `enableShellTools`：后台组件的部署开关，开启仍须会话 `danger-full-access` 才发布四个后台工具；文件组件不发布命令工具。
 - `publishBashTool`：是否发布 `ops_bash`，同样要求完全权限和宿主 subprocess 服务。
-- `promptPolicy`：是否注入紧凑三层路由说明；可用 `extraGuidance` 追加指导。
+- `promptPolicy`：是否注入该组件的运行时说明；可用 `extraGuidance` 追加指导。
 - `toolCallTimeoutMs`：FastCtx RPC 等待超时，不代表服务端工作已终止。
 - `required`：运行时不可用时是否拒绝激活。
 - `shellPolicy`：默认 `advise`；`deny-host-shell` 拒绝 `deniedHostTools` 列表中的宿主 shell（默认 `[pwsh, bash, pwsh_persistent]`）。这也会禁用第三层 pwsh，谨慎开启。
@@ -85,7 +100,6 @@ config:
 | `ops_glob` | 多模式找路径，支持排除 | 无命令权限门¹ |
 | `ops_replace` | 跨文件批量替换；精确编辑仍用宿主 edit | 无命令权限门¹ |
 | `ops_bash` | 优先的通用 bash 命令执行器 | 是 |
-| `ops_run` | 有界 bash 命令结果 | 是 |
 | `ops_run_background` | 启动后台任务 | 是 |
 | `ops_job_output` / `ops_job_list` / `ops_job_kill` | 查看、列出、停止当前会话启动的任务 | 是 |
 | 宿主 `pwsh` | 使用随包 PowerShell 7 的 Windows 原生操作 | 沿用宿主策略 |

package/README.zh.md

@@ -40,7 +40,7 @@ dsh plugin --profile dsh-tui add dsh-ops
 
 **更新**：重新运行相同的 `npx --yes dsh-ops@latest install --profile ...`，或用官方 CLI `add dsh-ops@latest`。按应用提示重载；替换已加载代码时重启应用。
 
-当前 npm 版本为 `0.2.3`：提示词提醒 `ops_*` 只传声明字段，标题统一为 `dsh-ops`，并更新中英文介绍和图标；保留 `0.2.2` 的 bash schema 修复，三个运行包仍使用 `0.2.1`。原始载荷发布记录见 [docs/release-0.2.1.md](docs/release-0.2.1.md)。
+当前版本 `0.2.4` 支持三个独立组件；bash 参数 schema 修复和自定义图标保留。三个二进制依赖继续使用 `0.2.1`，它们会自动安装，不影响主插件版本。新发布版本可能受桌面 pnpm 的 24 小时安全冷却策略影响：如果市场分析版号与安装结果不一致，指定 `dsh-ops@0.2.4` 并选择 npm 官方源，确认实际版本后完全退出并重启。原始载荷记录见 [docs/release-0.2.1.md](docs/release-0.2.1.md)。
 
 **卸载与查看状态**：
 
@@ -51,14 +51,29 @@ npx --yes dsh-ops@latest uninstall --profile desktop
 
 把 `desktop` 换成 `web` 或 `tui` 即可。也可在市场卸载，或执行官方 `dsh plugin --profile ... remove dsh-ops`。二进制随 profile 的插件依赖管理；卸载移除依赖引用，不误删系统 shell、其它 profile 的副本或包管理器共享缓存。
 
-旧版显式 provision 的 `<DSH_HOME>/dsh-ops/` 文件需单独清理：`npx --yes dsh-ops@latest uninstall --yes`。默认不删 `~/.fastctx/` 持久状态；需要时显式加 `--purge-fastctx`。卸载/降权不保证已经启动的持久后台任务终止，先处理自己的任务。
+旧版显式 provision 的 `<DSH_HOME>/dsh-ops/` 文件需单独清理：`npx --yes dsh-ops@latest uninstall --yes`。默认不删 `~/.fastctx/` 持久状态；需要时显式加 `--purge-fastctx`。关闭后台组件会等待已发出的调用，然后尝试终止该组件当前连接记住的自有任务；失败会告警。断线丢失归属的旧任务及单纯降权不保证终止，先处理自己的任务。
+
+## 组件开关与提示词
+
+官方市场显示三个组件，分别启停，首次安装默认开启前两个：
+
+| 组件 | 介绍 | 默认 | 发布的工具 |
+| --- | --- | --- | --- |
+| `dsh-ops-bash & powershell 7` | 将默认终端改为bash，以及bash覆盖不到时提供powershell7 | 开 | `ops_bash`；宿主 `pwsh` 使用随包 PowerShell 7 |
+| `dsh-ops-file` | 更快、更高性能、输出更精简更省token的rust文件检索 | 开 | 四个文件工具 |
+| `dsh-ops-background` | 为科研仿真、模型训练及其他长进程后台任务提供托管 | 关 | 启动、输出、列出、终止后台任务 |
+
+“默认终端改为 bash”指模型提示优先使用 `ops_bash`，**不修改系统默认终端、PATH 或宿主原有 shell 工具名称**。Shell 组件开时，通过官方配置生命周期临时指定 `pwsh-sandbox` 的 PowerShell 7 路径；关时按执行器最新原配置恢复，不写 profile 配置。执行器配置切换不代表取消已在运行的宿主命令。
+
+提示词注册为独立运行时段，**不写 AGENTS.md**：Shell 关就撤销 bash/pwsh 路由；文件关就撤销检索说明；后台关就不发布后台工具及自有 job 指导。文件与后台共享一个插件拥有的 FastCtx 连接，关闭其中一个不关闭另一个。默认仅新增五个工具，不发布重复前台 `ops_run`。这些改变减少固定声明成本，**不保证任意任务总 token 降低**。极简预设会覆盖附加 system sections；PTC 模式经 SDK 调用底层工具，权限门不变。
 
 ## 配置方式与工具列表
 
-在 DSH 的配置编辑器中找到 `dsh-ops` 行，调整 `config` 后保存；未知配置键会点名报错。主要默认值：
+在 DSH 的配置编辑器中找到对应的 `dsh-ops/shell`、`dsh-ops/file` 或 `dsh-ops/background` 行，调整 `config` 后保存；未知配置键会点名报错。也可直接在市场切换组件。主要配置：
 
 ```yaml
 config:
+  # background component only; its market row is disabled by default
   enableShellTools: true
   publishBashTool: true
   promptPolicy: true
@@ -70,9 +85,9 @@ config:
   # bashPath: 'C:\tools\bash.exe'
 ```
 
-- `enableShellTools`：部署开关，开启仍须会话 `danger-full-access` 才发布 FastCtx 命令/job 组。
+- `enableShellTools`：后台组件的部署开关，开启仍须会话 `danger-full-access` 才发布四个后台工具；文件组件不发布命令工具。
 - `publishBashTool`：是否发布 `ops_bash`，同样要求完全权限和宿主 subprocess 服务。
-- `promptPolicy`：是否注入紧凑三层路由说明；可用 `extraGuidance` 追加指导。
+- `promptPolicy`：是否注入该组件的运行时说明；可用 `extraGuidance` 追加指导。
 - `toolCallTimeoutMs`：FastCtx RPC 等待超时，不代表服务端工作已终止。
 - `required`：运行时不可用时是否拒绝激活。
 - `shellPolicy`：默认 `advise`；`deny-host-shell` 拒绝 `deniedHostTools` 列表中的宿主 shell（默认 `[pwsh, bash, pwsh_persistent]`）。这也会禁用第三层 pwsh，谨慎开启。
@@ -85,7 +100,6 @@ config:
 | `ops_glob` | 多模式找路径，支持排除 | 无命令权限门¹ |
 | `ops_replace` | 跨文件批量替换；精确编辑仍用宿主 edit | 无命令权限门¹ |
 | `ops_bash` | 优先的通用 bash 命令执行器 | 是 |
-| `ops_run` | 有界 bash 命令结果 | 是 |
 | `ops_run_background` | 启动后台任务 | 是 |
 | `ops_job_output` / `ops_job_list` / `ops_job_kill` | 查看、列出、停止当前会话启动的任务 | 是 |
 | 宿主 `pwsh` | 使用随包 PowerShell 7 的 Windows 原生操作 | 沿用宿主策略 |

package/cordis.patch.yml

@@ -1,160 +1,25 @@
-# ============================================================================
-# dsh-ops — DSH bundle patch
-# ============================================================================
-# This is the plugin's "mount declaration". DSH applies every bundle patch in
-# the profile's `dsh.profile.bundles` order at startup; this file inserts the
-# dsh-ops row into that tree.
-#
-# Install:
-#   dsh plugin --profile desktop add <path to this package>
-#   dsh plugin --profile web     add <path to this package>
-#
-# The row's config is validated by lib/config.js; every key below is optional
-# and the values shown are the defaults. An unknown key fails the plugin at load
-# rather than being ignored.
-# ----------------------------------------------------------------------------
-
+# Three independent market components; no unconditional host executor override.
+# Shell and file are enabled by default. Background is explicitly opt-in.
 - insert:
-    - id: dsh-ops
-      name: dsh-ops
+    - id: dsh-ops-shell
+      name: dsh-ops/shell
       config:
-        # Absolute path to the FastCtx executable. When set, the plugin hosts
-        # exactly this file and fails loud if it is unusable.
-        # binaryPath: 'C:\path\to\fastctx.exe'
-
-        # The FastCtx server's own name, used to attribute the server
-        # instructions this plugin publishes as a prompt section. The model
-        # never sees it: this plugin speaks MCP to the server it spawns itself
-        # and registers every tool under its own ops_<tool> name.
-        serverName: fastctx
-
-        # Deployment opt-in only. Command/job tools are published per session
-        # only when sandboxPolicy.resolve() reports danger-full-access.
-        enableShellTools: true
-
-        # Per-call deadline for one FastCtx tool call, in milliseconds.
-        toolCallTimeoutMs: 300000
-
-        # Fail plugin activation when the FastCtx server cannot start. Keep
-        # false so a missing runtime degrades to "prompt policy only" instead of
-        # taking the plugin down.
-        required: false
-
-        # 'advise'   — inject the prompt policy only.
-        # 'deny-host-shell' — additionally refuse the host shell tools below at
-        #                     the tools/pre-execute gate.
-        shellPolicy: advise
-
-        # Host tool names refused under 'deny-host-shell'.
-        deniedHostTools:
-          - pwsh
-          - bash
-          - pwsh_persistent
-
-        # Inject the repository-tooling prompt section.
         promptPolicy: true
-
-        # ---- L2: the plugin's own bash -------------------------------------
-        # Absolute path to the bash this plugin runs `ops_bash` through. When
-        # set, the plugin runs exactly this file and refuses the rung when it is
-        # unusable; leave it unset to search the plugin's own bundled copy
-        # first, then PATH, then the well-known Git for Windows locations.
-        # bashPath: 'C:\Program Files\Git\bin\bash.exe'
-
-        # Layer 2: preferred executor for general commands, pipelines and scripts.
-        # Requires a resolved bash, host subprocess and session full access.
         publishBashTool: true
-
-        # Fall back to a system-installed bash when the plugin carries no copy
-        # of its own. Set false to confine the bash rung to plugin-provided
-        # shells. (L3 needs no such switch: whether the host's pwsh row runs
-        # the plugin's own pwsh is decided by the executable's presence — see
-        # the L3 override below.)
+        shellPolicy: advise
         allowSystemShellFallback: true
-
-# ----------------------------------------------------------------------------
-# L3: run the host's pwsh tool on the plugin's own PowerShell 7.
-#
-# WHY ONE LINE IS ENOUGH. `pwsh-local`'s Config owns a `pwshPath` field
-# ("Explicit pwsh executable", packages/shell/pwsh-local/src/index.ts:71-77),
-# and `pwsh-sandbox` inherits it verbatim because it declares
-# `type Config = LocalConfig` (packages/shell/pwsh-sandbox/src/index.ts:40).
-# Pointing this row at the plugin's executable therefore gets the bundled pwsh
-# 7 under the host's sandbox, credential scrub, and output governance with no
-# custom executor and no patched internals.
-#
-# WHY IT CAN EVALUATE TO `undefined` — and that is the safe answer. The row's
-# `pwshPath` default is `undefined`, and `undefined` means "resolve a pwsh the
-# official way" (PowerShell 7 install, PATH, Windows PowerShell 5.1;
-# packages/shell/pwsh-local/src/resolve.ts:67-79). The expression keeps exactly
-# four guards:
-#
-#   1. the platform gate, matching the row's own `disabled` gate: this override
-#      is meaningless off Windows, where `pwsh-sandbox` is not mounted;
-#   2. an existence check over the SAME THREE PLACES, IN THE SAME ORDER, as the
-#      plugin's own probe in `lib/shells.js` (`PWSH_LAYOUT_ORDER`): first the
-#      provisioned store, `<DSH_HOME>/dsh-ops/shells/pwsh/<version>/bin/pwsh.exe`
-#      (what `dsh-ops provision-shells` installs, and the copy the plugin
-#      prefers), then `@dsh-ops/pwsh-<platform>-<arch>` with the shell at
-#      `bin/pwsh.exe` (a deployment that installed the platform package), then
-#      the vendored `vendor/pwsh/<platform>-<arch>/pwsh.exe` (a checkout that
-#      carries its own copy). Keeping the order identical is what makes the
-#      ladder's L3 and the host row the same fact rather than two guesses;
-#   3. a `lstat`-based usability test, so a Windows Store execution alias (a
-#      symlink whose target is not statable) counts, while a directory named
-#      `pwsh.exe` does not — the same rule `resolveShells` applies;
-#   4. a wrapping `try`/`catch` around the whole body, plus a `try` each for the
-#      store scan, the plugin-package resolution, and the platform-package
-#      resolution: an absent store, an unresolvable package, and a malformed
-#      manifest alike may not fail the boot. The store scan sits outside the
-#      plugin resolution on purpose — a provisioned copy is an absolute path
-#      under `DSH_HOME`, so a profile whose `baseUrl` cannot resolve `dsh-ops`
-#      still gets it rather than losing the rung.
-#
-# The store scan picks the greatest version name that holds the executable —
-# the identical comparison `provisionedShell` makes in `lib/shells.js`, which is
-# why it is one expression rather than a version list repeated here. The store's
-# root mirrors `dshHome` there too: `DSH_HOME` when the deployment names one,
-# `~/.dsh` otherwise.
-#
-# Until one of those three places actually carries the executable, the
-# expression yields `undefined` and the host row is left completely untouched.
-#
-# "Installed means used" is the point of the rung: a deployment that carries
-# the plugin's pwsh 7 wants the host's pwsh tool to run it, not the machine's.
-# A deployment that does NOT want this rewrite removes or edits this patch
-# entry in its OWN profile `cordis.patch.yml` — that layer applies after every
-# bundle layer (docs/user/develop/basic/publish.md:118-130), so it has the last
-# word. There is deliberately no plugin config key for it: a bundle patch is
-# evaluated before any dsh-ops row is mounted (the Loader defers a row's `!!js`
-# interpolation until that row's own injections are active), so a config key
-# could not reach this expression, and a key that pretends to is a ladder that
-# lies about the row it never changed.
-#
-# `!!js` SCOPE, VERIFIED IN THE VENDORED LOADER. The Loader evaluates these
-# expressions as `with (ctx) { return eval(expr) }`
-# (vendor/loader/src/config/utils.ts:5-9), so bare `baseUrl` (the owning config
-# tree's base URL) and `ctx` are both in scope — the same convention the shipped
-# bundle uses at packages/bundle/web-app/presets/cordis.patch.yml:147.
-# `dsh-ops` is a dependency of the profile, so
-# `createRequire(baseUrl).resolve('dsh-ops/package.json')` finds the package
-# whether it was installed as a link or from the registry.
-#
-# WHOLE-OBJECT REPLACEMENT — AUDITED, NOT ASSUMED. A patch replaces the target
-# row's ENTIRE `config` object rather than deep-merging it
-# (docs/user/develop/basic/publish.md:129), so every non-default field of the
-# target must be restated here. The base row this targets is
-# packages/bundle/base/cordis.patch.yml:241-243:
-#
-#     - id: pwsh-sandbox
-#       name: '@deepseek-ai/dsh-pwsh-sandbox'
-#       disabled: !!js process.platform !== 'win32'
-#
-# It declares NO `config` at all, and this patch writes only `config` (the
-# row's `name` and its platform `disabled` gate are untouched), so there is no
-# non-default field to restate and nothing is silently dropped. If the base row
-# ever gains one, it must be restated here.
-# ----------------------------------------------------------------------------
-- id: pwsh-sandbox
-  config:
-    pwshPath: !!js "(() => { if (process.platform !== 'win32') return undefined; try { const builtin = (name) => process.getBuiltinModule(name); const fs = builtin('node:fs'); const nodePath = builtin('node:path'); const win = process.platform + '-' + process.arch; const usable = (file) => { try { const stat = fs.lstatSync(file); return stat.isFile() || stat.isSymbolicLink(); } catch { return false; } }; const named = process.env.DSH_HOME; const home = typeof named === 'string' && named.trim() !== '' ? nodePath.resolve(named) : nodePath.join(builtin('node:os').homedir(), '.dsh'); const layouts = []; try { const store = nodePath.join(home, 'dsh-ops', 'shells', 'pwsh'); const versions = fs.readdirSync(store, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort().reverse(); for (const version of versions) layouts.push(nodePath.join(store, version, 'bin', 'pwsh.exe')); } catch {} try { const requires = builtin('node:module').createRequire(String(baseUrl).replace(/[^/]*$/, 'noop.json')); const dir = nodePath.dirname(requires.resolve('dsh-ops/package.json')); try { const pluginRequire = builtin('node:module').createRequire(nodePath.join(dir, 'package.json')); const pkg = nodePath.dirname(pluginRequire.resolve('@dsh-ops/pwsh-' + win + '/package.json')); layouts.push(nodePath.join(pkg, 'bin', 'pwsh.exe')); } catch {} layouts.push(nodePath.join(dir, 'vendor', 'pwsh', win, 'pwsh.exe')); } catch {} for (const candidate of layouts) { if (usable(candidate)) return candidate; } return undefined; } catch { return undefined; } })()"
+    - id: dsh-ops-file
+      name: dsh-ops/file
+      config:
+        promptPolicy: true
+        enableShellTools: false
+        required: false
+        toolCallTimeoutMs: 300000
+    - id: dsh-ops-background
+      name: dsh-ops/background
+      disabled: true
+      config:
+        promptPolicy: true
+        enableShellTools: true
+        required: false
+        toolCallTimeoutMs: 300000

package/docs/manual-validation.md

@@ -4,13 +4,17 @@
 
 ## 工具发布与提示词
 
-- `workspace-write`、`read-only`：目录只有四个 ops 文件工具；没有任何 `ops_run` / `ops_job_*`，提示词也不出现这些名字。
-- `danger-full-access` 且 `enableShellTools: true`：五个命令/job 工具一起出现。
-- `enableShellTools: false`、无 sandboxPolicy 服务、无会话：命令组不出现。
+- 组件列表恰为三个：shell/file 默认开启，background 默认关闭。分别核验组件名称、中文介绍、图标，以及实际版本。
+- `workspace-write`、`read-only`：只有开启的四个 ops 文件工具；没有 ops_bash/后台工具，提示词不广告不存在的命令。
+- `danger-full-access`：默认四个文件工具 + ops_bash；仅后台组件开且 enableShellTools=true 时增加四个后台工具。任何组合都不发布 ops_run。
+- 文件与后台共享一个 FastCtx；关文件仍能管理后台，关后台仍能读搜改，重开不积累注册。
+- `enableShellTools: false`、无 sandboxPolicy 服务、无会话：后台组不出现。
 - 同时开受限会话与完全权限会话：两者目录互不污染。受限子 agent 不继承祖先的命令组。
 - 同一会话切换受限 → 完全权限 → 受限：每次下一请求目录/提示词跟随变化，不重连 FastCtx；旧命令句柄不能继续调用。
 - 受限会话不发布 `ops_bash`；完全权限 + publishBashTool=true + bash 可解析 + subprocess 可用时出现，通用命令优先走它。FastCtx 缺失或 enableShellTools=false 时 bash 层仍独立可用。
-- 提示词仅一段 `dsh-ops:repository-tooling`：工具包 → bash → pwsh7；不混语法，不因 bash 报错切 PowerShell。Windows 原生操作才用 pwsh。没有旧 host-shell 段或 `mcp:fastctx`。
+- 提示词按组件分段 `dsh-ops:repository-tooling:{file,shell,background}`：开关只移除对应段；bash/pwsh 路由仅 shell 开时出现，后台关闭不出现后台指导。不写 AGENTS.md，没有旧 host-shell 段或 mcp:fastctx。
+- shell 开时宿主 pwsh-sandbox 采用随包 pwsh7，关时恢复最新宿主原配置；profile 文件不得被改动。开关期间用户更改执行器原配置后也应恢复新值。
+- 极简预设 complete persona 可排除附加提示；PTC 通过 SDK 使用同一工具层，权限/组件开关仍应生效。
 - publishBashTool=false 隐去 bash 这一层；bash 权限动态切换、受限子 agent 继承过滤和卸载清理一起验证。
 - `promptPolicy: false`：不发布路由提示词。
 - `deny-host-shell`：有无 ops 命令组都应拒绝配置的宿主 shell；若工具来自继承层，目录也应遮蔽。无可用执行器时不推荐不可调用的 ops 命令。
@@ -35,6 +39,7 @@
 - 完成/kill 后仍能读取自己已有 ID 的日志。
 - job_list status/limit/offset 是自己的分页，不暴露全局总数/offset；空列表明确为空。
 - 大全局 job 存储扫描不完整时必须报告 Partial，不冒充完整；原工具结果的 Complete/Partial 续页提示不能丢。
+- 关闭后台组件/卸载：等待已发调用，再尝试终止当前组件已知的自有 ID；不能杀别的会话或组件任务。清理失败有告警。断线后已丢归属的任务不保证终止。
 - 重连后不认领旧 ID；操作者可通过上游工具清理持久 job。权限降级不自动杀已运行任务，须操作者管理。
 
 ## 生命周期与边界
@@ -42,7 +47,7 @@
 - 服务端断线立即撤下工具与对应提示词项，恢复后重新出现。
 - 卸载后工具/提示词/限制全部消失；共享注册表方法未改写，外来同名工具仍可按自己的 scope 注册。
 - 未知配置键报错点名；required=true 的缺失/不可用二进制拒绝激活。
-- 取消/传输超时只表明停止等待，不把它误读为命令已停止。ops_run 的 timeout_ms 才是上游进程树超时。
+- 取消/传输超时只表明停止等待，不把它误读为命令已停止。ops_bash 的宿主执行器截止时间独立于 MCP 等待超时。
 
 ## 数字复核
 

package/docs/schema-current.json

@@ -38,11 +38,6 @@
       "bytes": 1511,
       "approximateTokens": 378
     },
-    {
-      "name": "ops_run",
-      "bytes": 751,
-      "approximateTokens": 188
-    },
     {
       "name": "ops_run_background",
       "bytes": 635,
@@ -50,28 +45,40 @@
     }
   ],
   "total": {
-    "bytes": 9739,
-    "approximateTokens": 2435
+    "bytes": 8988,
+    "approximateTokens": 2247
   },
   "fileOnly": {
     "bytes": 6724,
     "approximateTokens": 1681
   },
   "fileOnlyPrompt": {
-    "bytes": 527,
-    "approximateTokens": 132
+    "bytes": 498,
+    "approximateTokens": 125
   },
   "bashSchema": {
     "bytes": 961,
     "approximateTokens": 241
   },
+  "defaultWithBash": {
+    "bytes": 7685,
+    "approximateTokens": 1922
+  },
   "fullWithBash": {
-    "bytes": 10700,
-    "approximateTokens": 2675
+    "bytes": 9949,
+    "approximateTokens": 2488
+  },
+  "shellPrompt": {
+    "bytes": 492,
+    "approximateTokens": 123
+  },
+  "backgroundPrompt": {
+    "bytes": 269,
+    "approximateTokens": 68
   },
   "toolingPrompt": {
-    "bytes": 1110,
-    "approximateTokens": 278
+    "bytes": 878,
+    "approximateTokens": 220
   },
   "publishedServerInstructions": {
     "bytes": 0,

package/docs/schema-measurement.md

@@ -1,17 +1,37 @@
 # Schema measurement
 
-Manual measurement only; not CI, regression coverage, a tokenizer, or tool-use telemetry.
+Manual measurement only; not a tokenizer, CI, or proof of whole-task savings.
+Metric: compact UTF-8 JSON `{name,description,parameters}` bytes, tokens ≈ ceil(bytes/4).
+Runtime is FastCtx 0.2.6; only plugin publication/presentation changes.
 
-Baseline: plugin `dee3c57`, FastCtx 0.2.6, before presentation changes. Current: same runtime, plugin-only schema projections. Metric: sum of compact UTF-8 JSON `{name,description,parameters}` sizes, no whitespace formatting; tokens ≈ ceil(bytes/4).
+## 0.2.4 component surface
 
-| Surface | Baseline bytes | Current bytes | Reduction |
+| Enabled components | Tools | Schema bytes | Approximate tokens |
 | --- | ---: | ---: | ---: |
-| Nine FastCtx schemas (full-access session) | 18,889 | 9,739 | 48.4% |
-| Four file schemas | 12,807 | 6,724 | 47.5% |
-| Routing section (original full ladder vs compact three-layer table with strict-argument reminder) | 3,373 | 1,110 | 67.1% |
+| File only | 4 | 6,724 | 1,681 |
+| Shell + file (default, full access) | 5 | 7,685 | 1,922 |
+| Shell + file + background (full access) | 9 | 9,949 | 2,488 |
+| 0.2.3 full surface (historical) | 10 | 10,700 | 2,675 |
 
-Full-access FastCtx schema estimate: 4,723 → 2,435 tokens. The corrected object-root ops_bash schema adds 961 bytes (~241 tokens); full FastCtx+bash surface is 10,700 bytes (~2,675 tokens). Restricted file-only surface: about 1,681 tokens; its routing table is 527 bytes (~132 tokens). No server instructions are published (the original raw server instructions were 246 bytes); the old host-shell section is also removed. Baseline excludes ops_bash, so compare nine FastCtx tools like-for-like rather than treating restoration as a regression of those numbers. Total request savings depend on host presentation; these are not API usage/billing measurements.
+Default reduces plugin schema bytes by 28.2% versus 0.2.3. Background contributes
+2,264 bytes only when enabled; duplicate ops_run (751 bytes) is no longer published.
+The host tool declarations remain additive and are not included in this table.
+Restricted sessions have no ops_bash or background command tools.
 
-`ops_grep` went from 3,766 → 2,019 bytes; `ops_inspect_local_file` from 4,375 → 1,968. `ops_replace` is retained: schema cost cannot establish invocation frequency, and no usage-frequency measurement was collected.
+Prompt sections are component-owned and independently removed: file 498 bytes,
+shell 492 bytes, background 269 bytes. These sum when multiple components are on;
+`toolingPrompt` in the snapshot is the legacy combined CLI renderer, not the actual
+sum of separately registered sections. Minimal's complete persona can exclude them.
+No raw server instructions or old host-shell policy segment is published.
 
-Reproduce the current snapshot with `node scripts/measure-schemas.mjs docs/schema-current.json`. It only starts FastCtx, initializes, lists schemas, then closes it; it executes no tools. Keep the baseline unchanged; a different runtime schema requires an explicitly labeled comparison.
+## Historical comparison
+
+The unchanged baseline is dee3c57 before description compression: nine FastCtx
+schemas 18,889 bytes; four file schemas 12,807. File descriptions remain 6,724 bytes
+(47.5% reduction). ops_grep: 3,766 → 2,019; inspect: 4,375 → 1,968. These are plugin
+old/new comparisons, NOT official-host versus plugin comparisons.
+
+Reproduce with `node scripts/measure-schemas.mjs docs/schema-current.json`.
+It initializes and lists schemas without tool execution. Preserve baseline JSON.
+Actual request count, cache pricing, tool output and repeated history can outweigh
+fixed schema savings; no percentage here predicts task-total provider tokens.

package/dsh-plugin.json

@@ -3,7 +3,7 @@
   "manifestVersion": "0.15",
   "id": "dsh-ops.fastctx",
   "name": "dsh-ops",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "license": "MIT AND Apache-2.0",
   "facets": {
     "host": {
@@ -50,9 +50,19 @@
     ],
     "x-prompt-sections": [
       {
-        "name": "dsh-ops:repository-tooling",
+        "name": "dsh-ops:repository-tooling:file",
         "order": 3250,
-        "summary": "Compact tools-to-bash-to-PowerShell-7 routing; prefer bash except for Windows-native operations."
+        "summary": "File operations only; follows the file component visibility."
+      },
+      {
+        "name": "dsh-ops:repository-tooling:shell",
+        "order": 3251,
+        "summary": "Prefer bash, use bundled PowerShell 7 for Windows-native functionality; removed when shell component is off."
+      },
+      {
+        "name": "dsh-ops:repository-tooling:background",
+        "order": 3252,
+        "summary": "Owned background tasks only; absent by default."
       }
     ],
     "x-tool-namespaces": [
@@ -66,21 +76,39 @@
           "grep",
           "glob",
           "replace",
-          "run",
           "run_background",
           "job_output",
           "job_list",
           "job_kill"
         ],
-        "shellPermission": "enableShellTools AND per-session sandboxPolicy danger-full-access"
+        "shellPermission": "background component enabled AND enableShellTools AND per-session sandboxPolicy danger-full-access"
       },
       {
         "serverName": "dsh-ops",
         "transport": "in-process",
         "source": "the plugin's bash layer via host subprocess",
         "publicPrefix": "ops_",
-        "tools": ["bash"],
-        "shellPermission": "publishBashTool AND per-session sandboxPolicy danger-full-access"
+        "tools": [
+          "bash"
+        ],
+        "shellPermission": "shell component enabled AND publishBashTool AND per-session sandboxPolicy danger-full-access"
+      }
+    ],
+    "x-components": [
+      {
+        "id": "dsh-ops-shell",
+        "entry": "dsh-ops/shell",
+        "defaultEnabled": true
+      },
+      {
+        "id": "dsh-ops-file",
+        "entry": "dsh-ops/file",
+        "defaultEnabled": true
+      },
+      {
+        "id": "dsh-ops-background",
+        "entry": "dsh-ops/background",
+        "defaultEnabled": false
       }
     ]
   },

package/lib/components/background/index.js

@@ -0,0 +1,3 @@
+import { applyComponent } from "../../index.js"
+export const name = "dsh-ops-background"
+export function apply(ctx, config) { return applyComponent(ctx, config, "background") }

package/lib/components/background/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-ops-background",
+    "description": "Manage scientific simulations, model training, and other long-running background tasks."
+  }
+}

package/lib/components/background/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-ops-background",
+    "description": "为科研仿真、模型训练及其他长进程后台任务提供托管"
+  }
+}

package/lib/components/background/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "dsh-ops-background",
+  "description": "Manage scientific simulations, model training, and other long-running background tasks.",
+  "icon": "./icon.png",
+  "type": "module"
+}

package/lib/components/file/index.js

@@ -0,0 +1,3 @@
+import { applyComponent } from "../../index.js"
+export const name = "dsh-ops-file"
+export function apply(ctx, config) { return applyComponent(ctx, config, "file") }

package/lib/components/file/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-ops-file",
+    "description": "High-performance Rust file search with faster execution and compact output for token efficiency."
+  }
+}

package/lib/components/file/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-ops-file",
+    "description": "更快、更高性能、输出更精简更省token的rust文件检索"
+  }
+}

package/lib/components/file/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "dsh-ops-file",
+  "description": "High-performance Rust file search with faster execution and compact output for token efficiency.",
+  "icon": "./icon.png",
+  "type": "module"
+}

package/lib/components/shell/index.js

@@ -0,0 +1,3 @@
+import { applyComponent } from "../../index.js"
+export const name = "dsh-ops-bash & powershell 7"
+export function apply(ctx, config) { return applyComponent(ctx, config, "shell") }

package/lib/components/shell/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-ops-bash & powershell 7",
+    "description": "Prefer bash for general commands and provide PowerShell 7 when Windows-native functionality is needed."
+  }
+}

package/lib/components/shell/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-ops-bash & powershell 7",
+    "description": "将默认终端改为bash，以及bash覆盖不到时提供powershell7"
+  }
+}

package/lib/components/shell/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "dsh-ops-bash & powershell 7",
+  "description": "Prefer bash for general commands and provide PowerShell 7 when Windows-native functionality is needed.",
+  "icon": "./icon.png",
+  "type": "module"
+}

package/lib/index.js

@@ -1,9 +1,10 @@
 /** dsh-ops host half. Own registrations only; no @deepseek-ai value imports. */
 import { PACKAGE_ROOT, probeBinary, resolveBinary } from './binary.js'
 import { resolveConfig } from './config.js'
-import { SECTION_ORDERS, TOOLING_SECTION, hostShellRefusal, renderToolingPolicy } from './policy.js'
+import { SECTION_ORDERS, TOOLING_SECTION, BACKGROUND_TOOLS, FILE_TOOLS, BASH_TOOL, publicToolName, hostShellRefusal, renderToolingPolicy } from './policy.js'
 import { resolveShells } from './shells.js'
 import { mountSessionBash } from './session-shells.js'
+import { mountBundledPwsh } from './session-pwsh.js'
 import { FastCtxTools } from './tools.js'
 
 export const name = 'dsh-ops'
@@ -54,30 +55,34 @@ function installHostShellDenial(ctx, config) {
   }
 }
 
-async function mountServer(ctx, config, runtime) {
+async function mountServer(ctx, config, runtime, component) {
   if (!runtime) return
-  const surface = new FastCtxTools({ ctx, config, runtime, report: (message, level) => report(ctx, message, level) })
+  const background = component === 'background'
+  const surface = new FastCtxTools({ ctx, config, runtime,
+    fileTools: !background, commandTools: background ? BACKGROUND_TOOLS : [], shared: true,
+    report: (message, level) => report(ctx, message, level) })
   ctx.effect(() => () => surface.stop(), 'dsh-ops: fastctx server')
-  ctx.on('agent/created', ({ agent }) => surface.attachAgent(agent))
-  ctx.on('agent/disposed', ({ agent }) => surface.detachAgent(agent))
-  ctx.on('session/event', (session, event) => {
-    if (event.type === 'sandbox/mode') surface.refreshAgents(session)
-  })
-  // Authority may mount after the tools service or be hot-reloaded. Losing it
-  // immediately retires every command layer; it never falls back to env state.
-  surface.authorityAvailable = false
-  ctx.inject(['sandboxPolicy'], authorityCtx => {
-    surface.authorityAvailable = true
-    surface.refreshAgents()
-    authorityCtx.effect(() => () => {
-      surface.authorityAvailable = false
+  if (background) {
+    ctx.on('agent/created', ({ agent }) => surface.attachAgent(agent))
+    ctx.on('agent/disposed', ({ agent }) => surface.detachAgent(agent))
+    ctx.on('session/event', (_session, event) => {
+      if (event.type === 'sandbox/mode') surface.refreshAgents()
+    })
+    // Background command layers follow authoritative per-session permission.
+    surface.authorityAvailable = false
+    ctx.inject(['sandboxPolicy'], authorityCtx => {
+      surface.authorityAvailable = true
       surface.refreshAgents()
-    }, 'dsh-ops: permission authority')
-  })
-  for (const agent of ctx.get('agents')?.list?.() ?? []) surface.attachAgent(agent)
+      authorityCtx.effect(() => () => {
+        surface.authorityAvailable = false
+        surface.refreshAgents()
+      }, 'dsh-ops: permission authority')
+    })
+    for (const agent of ctx.get('agents')?.list?.() ?? []) surface.attachAgent(agent)
+  }
   try {
     const tools = await surface.start()
-    report(ctx, `dsh-ops: FastCtx ${runtime.version} ready; ${tools.length} file tools, session-authorized command layers.`, 'info')
+    report(ctx, `dsh-ops: FastCtx ${runtime.version} ready; ${component} component, ${tools.length} global tools.`, 'info')
   } catch (error) {
     report(ctx, `dsh-ops: FastCtx unavailable: ${error.message}`)
     if (config.required) throw error
@@ -85,24 +90,33 @@ async function mountServer(ctx, config, runtime) {
   }
 }
 
-export function apply(root, rawConfig) {
+export function applyComponent(root, rawConfig, component) {
   const config = resolveConfig(rawConfig)
-  const runtime = prepareRuntime(root, config)
-  const shells = resolveShells(config)
+  const runtime = component === 'shell' ? undefined : prepareRuntime(root, config)
+  const shells = component === 'shell' ? resolveShells(config) : undefined
+  const owned = component === 'shell' ? [BASH_TOOL, 'pwsh']
+    : component === 'file' ? FILE_TOOLS.map(publicToolName) : BACKGROUND_TOOLS.map(publicToolName)
+  if (component === 'file') owned.push('read_image')
   if (config.promptPolicy) root.inject(['systemPrompt'], ctx => {
     ctx.effect(() => ctx.systemPrompt.section({
-      name: TOOLING_SECTION,
-      order: SECTION_ORDERS[TOOLING_SECTION],
+      name: `${TOOLING_SECTION}:${component}`,
+      order: SECTION_ORDERS[TOOLING_SECTION] + (component === 'shell' ? 1 : component === 'background' ? 2 : 0),
       interpolate: false,
       text: context => renderToolingPolicy({
-        published: visibleTools(ctx, context.agent), pwsh7: shells.pwsh.available,
+        published: visibleTools(ctx, context.agent).filter(name => owned.includes(name)),
+        shellComponent: component === 'shell', pwsh7: shells?.pwsh.available ?? false,
         extraGuidance: config.extraGuidance,
       }),
-    }), 'dsh-ops: repository tooling')
-  })
-  root.inject(['tools'], ctx => {
-    mountSessionBash(ctx, config, shells)
-    if (config.shellPolicy === 'deny-host-shell') installHostShellDenial(ctx, config)
-    return mountServer(ctx, config, runtime)
+    }), `dsh-ops: ${component} tooling`)
   })
+  if (component === 'shell') {
+    mountBundledPwsh(root, shells)
+    root.inject(['tools'], ctx => {
+      mountSessionBash(ctx, config, shells)
+      if (config.shellPolicy === 'deny-host-shell') installHostShellDenial(ctx, config)
+    })
+  } else root.inject(['tools'], ctx => mountServer(ctx, config, runtime, component))
 }
+
+// Backward-compatible module entry. The bundle uses independently toggled rows.
+export function apply(root, rawConfig) { return applyComponent(root, rawConfig, 'file') }

package/lib/policy.js

@@ -5,7 +5,8 @@ export const HOST_SHELL_SECTION = 'dsh-ops:host-shell-policy'
 export const SECTION_ORDERS = Object.freeze({ [TOOLING_SECTION]: 3250 })
 export const TOOL_PREFIX = 'ops_'
 export const FILE_TOOLS = Object.freeze(['inspect_local_file', 'grep', 'glob', 'replace'])
-export const SHELL_TOOLS = Object.freeze(['run', 'run_background', 'job_output', 'job_list', 'job_kill'])
+export const BACKGROUND_TOOLS = Object.freeze(['run_background', 'job_output', 'job_list', 'job_kill'])
+export const SHELL_TOOLS = Object.freeze(['run', ...BACKGROUND_TOOLS])
 // The plugin's second layer executes POSIX commands; pwsh7 uses the host tool.
 export const IN_PROCESS_TOOLS = Object.freeze(['bash'])
 export function publicToolName(rawName) { return `${TOOL_PREFIX}${rawName}` }
@@ -23,17 +24,24 @@ export function ladderLevels({ published, pwsh = false }) {
 }
 
 /** A single compact table; absent tools never get advertised. */
-export function renderToolingPolicy({ published, enableShellTools, mounted, levels, pwsh7 = false, extraGuidance = '' }) {
+export function renderToolingPolicy({ published, enableShellTools, mounted, levels, pwsh7 = false, shellComponent = true, extraGuidance = '' }) {
   const names = new Set(published ?? (mounted || levels?.fastctx
     ? [...FILE_TOOLS, ...(enableShellTools ? SHELL_TOOLS : []), ...(levels?.bash ? IN_PROCESS_TOOLS : [])].map(publicToolName) : []))
   if (levels?.pwsh) names.add('pwsh')
-  if (!FILE_TOOLS.some(name => names.has(publicToolName(name))) && !names.has(BASH_TOOL)) return ''
-  const lines = ['# Repository operations: tools → bash → PowerShell 7', '', '| Task | Tool |', '| --- | --- |']
+  if (!shellComponent) names.delete('pwsh')
+  const hasFiles = FILE_TOOLS.some(name => names.has(publicToolName(name)))
+  const hasBash = names.has(BASH_TOOL)
+  const hasBackground = names.has(publicToolName('run_background'))
+  const hasPwsh = shellComponent && names.has('pwsh')
+  if (!hasFiles && !hasBash && !hasBackground && !hasPwsh) return ''
+  const heading = hasBash ? '# Shell routing: bash → PowerShell 7'
+    : hasFiles ? '# Repository file tools' : hasBackground ? '# Background task tools' : '# Windows-native shell'
+  const lines = [heading, '', '| Task | Tool |', '| --- | --- |']
   const row = (raw, task) => {
     if (names.has(publicToolName(raw))) lines.push(`| ${task} | ${publicToolName(raw)} |`)
   }
   row('inspect_local_file', 'Text / multiple ranges / encoding / PDF text / hex')
-  lines.push('| Images | read_image (host) |')
+  if (hasFiles && names.has('read_image')) lines.push('| Images | read_image (host) |')
   row('grep', 'Search contents')
   row('glob', 'Find paths')
   row('replace', 'Batch replacement; use host edit for precise edits')
@@ -41,10 +49,10 @@ export function renderToolingPolicy({ published, enableShellTools, mounted, leve
   if (names.has('pwsh')) lines.push(`| Windows-native cmdlets / registry / services only | pwsh (${pwsh7 || levels?.pwsh ? 'bundled PowerShell 7 via host' : 'host PowerShell'}) |`)
   row('run', 'Bounded bash command result (full access only)')
   if (names.has(publicToolName('run_background'))) {
-    lines.push(`| Background commands / owned jobs | ${SHELL_TOOLS.slice(1).map(publicToolName).join(', ')} |`)
+    lines.push(`| Background commands / owned jobs | ${BACKGROUND_TOOLS.map(publicToolName).filter(name => names.has(name)).join(', ')} |`)
   }
-  lines.push('', '- ops_* arguments are strict: pass only declared fields.',
-    '- Do not build shell command lines for file operations.',
+  lines.push('', '- ops_* arguments are strict: pass only declared fields.')
+  if (hasFiles) lines.push('- Use file tools for file operations; use count for totals and batch independent requests.',
     '- On a tool error, correct the arguments and retry; do not switch to a shell workaround.')
   if (names.has(BASH_TOOL)) lines.push('- Prefer bash for command execution. Use PowerShell only when Windows-native functionality is necessary; fix bash errors in bash, do not switch shells or mix their syntax.')
   if (names.has(publicToolName('run_background'))) lines.push('- Only operate on job IDs you started in this session.')

package/lib/runtime-pool.js

@@ -0,0 +1,42 @@
+/** One plugin-owned FastCtx connection shared by independently toggled components. */
+import { McpStdioClient } from './handshake.js'
+const pools = new WeakMap()
+export async function acquireRuntime(ctx, runtime, env) {
+  const root = ctx.root
+  let pool = pools.get(root)
+  if (!pool) { pool = { clients: new Map(), closing: Promise.resolve() }; pools.set(root, pool) }
+  await pool.closing
+  let entry = pool.clients.get(runtime.file)
+  if (!entry) {
+    const client = McpStdioClient.start({ file: runtime.file, args: ['serve', '--enable-shell'], env, timeoutMs: 60000 })
+    entry = { client, refs: 0, ready: undefined }
+    pool.clients.set(runtime.file, entry)
+    entry.ready = (async () => {
+      try {
+        const handshake = await client.initialize('dsh-ops-components')
+        const tools = await client.listTools()
+        return { client, handshake, tools }
+      } catch (error) {
+        if (pool.clients.get(runtime.file) === entry) pool.clients.delete(runtime.file)
+        await client.close()
+        throw error
+      }
+    })()
+    void client.exited.then(() => { if (pool.clients.get(runtime.file) === entry) pool.clients.delete(runtime.file) })
+  }
+  entry.refs += 1
+  let released = false
+  const release = async () => {
+    if (released) return
+    released = true
+    entry.refs -= 1
+    if (!entry.refs) {
+      if (pool.clients.get(runtime.file) === entry) pool.clients.delete(runtime.file)
+      const closing = pool.closing.then(() => entry.client.close())
+      pool.closing = closing.catch(() => {})
+      await closing
+    }
+  }
+  try { return { ...await entry.ready, release } }
+  catch (error) { await release(); throw error }
+}

package/lib/session-pwsh.js

@@ -0,0 +1,31 @@
+/** A reversible runtime-only config overlay; never edits profile files or services. */
+export function mountBundledPwsh(ctx, shells) {
+  if (!shells.pwsh.available || process.platform !== 'win32') return
+  ctx.inject(['loader'], loaderCtx => {
+    const loader = loaderCtx.get('loader')
+    const matches = entry => entry?.options?.id === 'pwsh-sandbox'
+      && entry.options.name === '@deepseek-ai/dsh-pwsh-sandbox'
+    const refresh = () => {
+      for (const entry of loader.entries()) {
+        if (matches(entry) && entry.fiber?.state === 2) {
+          // Public Fiber.update with noSave recomputes from the owner's latest
+          // raw config. No stored config, volatile reference, or method is changed.
+          entry.fiber.update(entry.options.config, true)
+        }
+      }
+    }
+    const unhook = loaderCtx.on('internal/config', function (_raw, next) {
+      const config = next()
+      if (!matches(this.entry) || this.parent?.fiber?.entry === this.entry) return config
+      return { ...config, pwshPath: shells.pwsh.file }
+    }, { global: true, prepend: true })
+    let stopped = false
+    loaderCtx.effect(() => () => {
+      if (stopped) return
+      stopped = true
+      unhook()
+      refresh()
+    }, 'dsh-ops: restore owning PowerShell executor config')
+    refresh()
+  })
+}

package/lib/tools.js

@@ -23,6 +23,8 @@ import { McpStdioClient } from './handshake.js'
 import { FILE_TOOLS, SHELL_TOOLS, publicToolName } from './policy.js'
 import { projectTool } from './presentation.js'
 import { cleanBackground, jobEntries, startedJob } from './jobs.js'
+import { acquireRuntime } from './runtime-pool.js'
+import { resolveShells } from './shells.js'
 
 /** Deadline for one connection attempt: spawn, initialize, and `tools/list`. */
 const CONNECT_TIMEOUT_MS = 60_000
@@ -216,10 +218,16 @@ export class FastCtxTools {
    * @param {{file: string, source: string, version: string}} options.runtime - the resolved FastCtx executable.
    * @param {(message: string, level?: string) => void} [options.report] - where asynchronous events are reported.
    */
-  constructor({ ctx, config, runtime, report }) {
+  constructor({ ctx, config, runtime, report, fileTools = true, commandTools = SHELL_TOOLS, shared = false }) {
     this.ctx = ctx
     this.config = config
     this.runtime = runtime
+    this.fileTools = fileTools
+    this.commandTools = commandTools
+    this.shared = shared
+    this.leases = new Map()
+    this.pendingCalls = new Set()
+    this.shuttingDown = false
     this.report = report ?? (() => {})
     /** The live connection, or undefined while the surface is down. */
     this.client = undefined
@@ -282,7 +290,7 @@ export class FastCtxTools {
     if (!entry?.ctx) return
     for (const dispose of entry.disposers) dispose()
     entry.disposers = []
-    if (this.stopped) return
+    if (this.stopped || this.shuttingDown) return
     if (!this.shellAllowed(agent.session)) {
       // A child must not inherit an authorized ancestor's command surface.
       const names = (this.ctx.get('tools')?.schemas(agent) ?? []).map(tool => tool.name)
@@ -293,8 +301,8 @@ export class FastCtxTools {
       }
       return
     }
-    const commandTools = this.tools.filter(tool => SHELL_TOOLS.includes(tool.name))
-    if (commandTools.length !== SHELL_TOOLS.length) return
+    const commandTools = this.tools.filter(tool => this.commandTools.includes(tool.name))
+    if (commandTools.length !== this.commandTools.length) return
     try {
       for (const tool of commandTools) {
         entry.disposers.push(entry.ctx.tools.register(toolDefinition({
@@ -367,6 +375,20 @@ export class FastCtxTools {
    * @returns {Promise<void>} resolves once the child is gone.
    */
   async stop() {
+    this.shuttingDown = true
+    this.refreshAgents()
+    // Drain launches before killing only this component's owned jobs. Closing
+    // FastCtx alone does not stop its durable supervisors.
+    await Promise.allSettled([...this.pendingCalls])
+    const cleanupClient = this.client
+    if (cleanupClient) {
+      for (const ids of this.ownedJobs.values()) for (const job_id of ids) {
+        try {
+          const result = await cleanupClient.callTool('job_kill', { job_id }, { timeoutMs: 15000 })
+          if (result?.isError) this.report(`dsh-ops: owned job ${job_id} could not be stopped during component shutdown.`, 'warn')
+        } catch (error) { this.report(`dsh-ops: owned job ${job_id} shutdown failed: ${messageOf(error)}`, 'warn') }
+      }
+    }
     this.stopped = true
     if (this.timer !== undefined) {
       clearTimeout(this.timer)
@@ -380,7 +402,14 @@ export class FastCtxTools {
     this.tools = []
     this.ownedJobs.clear()
     await Promise.all([...this.agents.keys()].map(agent => this.detachAgent(agent)))
-    if (client !== undefined) await client.close()
+    if (client !== undefined) await this.#release(client)
+  }
+
+  async #release(client) {
+    const lease = this.leases.get(client)
+    this.leases.delete(client)
+    if (lease) await lease.release()
+    else if (!this.shared) await client.close()
   }
 
   /**
@@ -388,7 +417,16 @@ export class FastCtxTools {
    * @returns {Promise<void>} resolves once the generation is live.
    */
   async #connect() {
-    const client = McpStdioClient.start({
+    let lease
+    if (this.shared) {
+      const env = childEnv()
+      const bash = resolveShells(this.config).bash
+      if (bash.available) env.FASTCTX_BASH = bash.file
+      lease = await acquireRuntime(this.ctx, this.runtime, env)
+      if (this.shuttingDown || this.stopped) { await lease.release(); throw new StoppedError() }
+      this.leases.set(lease.client, lease)
+    }
+    const client = lease?.client ?? McpStdioClient.start({
       file: this.runtime.file,
       args: serverArgs(this.config.enableShellTools),
       env: childEnv(),
@@ -401,9 +439,9 @@ export class FastCtxTools {
     // already replaced or abandoned.
     void client.exited.then(({ code, signal, error }) => this.#onExit(client, code, signal, error))
     try {
-      const handshake = await client.initialize('dsh-ops')
-      const tools = await client.listTools()
-      if (this.stopped || client !== this.client) throw new StoppedError()
+      const handshake = lease?.handshake ?? await client.initialize('dsh-ops')
+      const tools = lease?.tools ?? await client.listTools()
+      if (this.stopped || this.shuttingDown || client !== this.client) throw new StoppedError()
       this.ownedJobs.clear()
       this.#publish(tools)
       this.serverInfo = handshake?.serverInfo
@@ -411,7 +449,7 @@ export class FastCtxTools {
       this.serverInstructions = ''
       this.connectedAt = Date.now()
     } catch (error) {
-      await client.close()
+      await this.#release(client)
       if (this.client === client) this.client = undefined
       throw error
     }
@@ -426,7 +464,8 @@ export class FastCtxTools {
    * @returns {void}
    */
   #onExit(client, code, signal, error) {
-    if (this.stopped || client !== this.client) return
+    if (this.stopped || this.shuttingDown || client !== this.client) return
+    void this.#release(client)
     this.client = undefined
     this.ownedJobs.clear()
     this.tools = []
@@ -449,7 +488,7 @@ export class FastCtxTools {
   #scheduleReconnect() {
     // One pending timer at a time: a crash and a failed first connect can both
     // land here, and two loops would double every later attempt.
-    if (this.stopped || this.timer !== undefined) return
+    if (this.stopped || this.shuttingDown || this.timer !== undefined) return
     // A connection that stayed up long enough closed the previous outage.
     if (this.connectedAt !== undefined && Date.now() - this.connectedAt >= RECONNECT.maxDelayMs) {
       this.attempts = 0
@@ -486,12 +525,12 @@ export class FastCtxTools {
    * @returns {Promise<void>} resolves once this attempt settled.
    */
   async #reconnect() {
-    if (this.stopped) return
+    if (this.stopped || this.shuttingDown) return
     try {
       await this.#connect()
       this.report(`dsh-ops: ${this.#describe()} reconnected with ${this.names().length} tool(s).`)
     } catch (error) {
-      if (this.stopped) return
+      if (this.stopped || this.shuttingDown) return
       this.report(
         `dsh-ops: FastCtx reconnect attempt ${this.attempts}/${RECONNECT.maxAttempts} `
         + `failed (${messageOf(error)}).`,
@@ -521,7 +560,7 @@ export class FastCtxTools {
         throw new Error(`${this.#describe()} listed the tool "${String(tool?.name)}" more than once`)
       }
       seen.add(name)
-      if (!FILE_TOOLS.includes(tool.name)) continue
+      if (!this.fileTools || !FILE_TOOLS.includes(tool.name)) continue
       definitions.push(toolDefinition({
         tool,
         call: (args, exec) => this.#call(tool.name, args, exec),
@@ -556,7 +595,15 @@ export class FastCtxTools {
    * @param {{signal?: AbortSignal, agent?: {session?: object}}} [exec] - the host execution context.
    * @returns {Promise<{content: unknown[], structuredContent?: unknown}>} the canonical value.
    */
-  async #call(rawName, args, exec) {
+  #call(rawName, args, exec) {
+    if (this.shuttingDown || this.stopped) return Promise.reject(new Error('This dsh-ops component is shutting down.'))
+    const call = this.#callActive(rawName, args, exec)
+    this.pendingCalls.add(call)
+    void call.then(() => this.pendingCalls.delete(call), () => this.pendingCalls.delete(call))
+    return call
+  }
+
+  async #callActive(rawName, args, exec) {
     const label = publicToolName(rawName)
     const session = exec?.agent?.session
     if (SHELL_TOOLS.includes(rawName) && !this.shellAllowed(session)) {
@@ -569,6 +616,7 @@ export class FastCtxTools {
         throw new Error('This is an image; use host read_image.')
       }
     }
+    if (rawName === 'run_background') args = { ...args, cwd: args?.cwd ?? session?.header?.cwd }
     const client = this.client
     if (client === undefined) {
       // A dead server must be an immediate, explicit failure rather than a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ops",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "publishConfig": {
     "access": "public"
   },
@@ -39,7 +39,22 @@
       "default": "./lib/policy.js"
     },
     "./package.json": "./package.json",
-    "./locale/*.json": "./locale/*.json"
+    "./locale/*.json": "./locale/*.json",
+    "./shell": {
+      "default": "./lib/components/shell/index.js"
+    },
+    "./shell/package.json": "./lib/components/shell/package.json",
+    "./shell/locale/*.json": "./lib/components/shell/locale/*.json",
+    "./file": {
+      "default": "./lib/components/file/index.js"
+    },
+    "./file/package.json": "./lib/components/file/package.json",
+    "./file/locale/*.json": "./lib/components/file/locale/*.json",
+    "./background": {
+      "default": "./lib/components/background/index.js"
+    },
+    "./background/package.json": "./lib/components/background/package.json",
+    "./background/locale/*.json": "./lib/components/background/locale/*.json"
   },
   "bin": {
     "dsh-ops": "bin/dsh-ops.mjs"