dsh-ops 0.2.3 → 0.2.5-beta.1

package/docs/auto-compact.md

@@ -0,0 +1,102 @@
+# 上下文自动压缩 / Automatic context compaction
+
+## 界面位置
+
+本地开发版在 **插件列表 → dsh-ops → 包含的组件** 中新增第四项「上下文自动压缩」
+（`dsh-ops-auto-compact` / `@dsh-ops/auto-compact`）。使用它旁边的配置入口进入设置，
+不是全局设置中的独立页面。新组件默认启用；原有 background 仍默认停用。
+`0.2.5-beta.1` 是待发布测试版候选；正式版 npm 0.2.4 不含此功能。是否发布以 registry 为准。
+
+| 配置 | 默认 | 范围 |
+| --- | --- | --- |
+| `thresholdPercent` | 50 | 1–99，整数 |
+| `cooldownSeconds` | 120 | 30–3600，整数 |
+| `timeoutSeconds` | 120 | 10–600，整数 |
+
+设置调用现有宿主表单的 revision-fenced mutate，保存到当前 profile 的
+`cordis.patch.yml`，可恢复默认，不使用 localStorage。启用组件且当前客户端具有
+宿主设置权限时才可保存；停用组件不伪装成可配置。修改即时影响下一次判定，
+不重挂载或中断正在运行的压缩；压缩已经开始时沿用当次捕获的截止时间。
+
+## 触发与安全
+
+- 使用与 Web 一致的 `contextPressure` 投影：`projectedTokens ?? pressureTokens`，
+  除以 `contextWindow`，四舍五入并上限 100。显示值 **严格高于** 阈值才满足条件；
+  等于 50% 不触发。无样本或容量、异常值时跳过，不猜模型容量。
+- 不按计时器轮询。正常 turn 进入 idle 时判定，热启用时检查已加载的 idle agent。
+  用户取消的 turn 不自动启动维护。长时间持续运行的 turn 不会在中途压缩；
+  原有宿主 pressure/overflow 自动策略保持不动。
+- 调用宿主 `/compact` 同一个 `compaction.compactNow(agent, signal)` 服务，不向
+  模型发送 `/compact` 文本，不增加模型可调用工具或额外提示词。
+- idle 状态本身不构成互斥：由宿主 runMaintenance admission 和 durable compaction
+  marker 执行真实串行化；busy 是正常竞态，跳过而非循环重试。
+- 一个组件实例同时只运行一个压缩，跨会话共享冷却期；不干扰宿主自己的压缩器。
+  同一 surface 在没有新内容/阈值改变时不重复尝试，自己的摘要替换也不会形成循环。
+  无可压缩历史、失败都受冷却和 surface 门禁控制；无定时后台重试。
+- commit/persistence 故障会暂停该会话的本组件自动压缩，直到重新加载组件。
+  应先检查会话状态，不直接重试。其它故障只记录固定脱敏消息。
+- deadline 是 AbortSignal 取消，不是强制销毁：依赖宿主/模型适配器响应 abort。
+  即使适配器延迟退出，本组件也不开放第二个任务；关闭组件会 abort 自己的压缩并
+  await allSettled，不调用 agent.cancel，不丢用户 inbox，不杀后台任务。
+- 摘要使用宿主配置的模型，可能产生调用费用；摘要会改变 model-visible surface，
+  原始历史/标记与持久化由宿主负责。压缩不是无损保证，不宣称百分比是未来 provider
+  请求的精确计费。文档与截图不能替代真实 Desktop 验收。
+
+## English
+
+The fourth component is in **Plugins → dsh-ops → Included components**. Its row
+configuration page uses the existing host forms, revision-fenced profile writes,
+and restore-default operations. The new component defaults to ON; background stays OFF.
+Only integer settings in the table above are accepted. This feature belongs to the
+0.2.5-beta.1 prerelease candidate, not npm 0.2.4. Check the registry for publication status.
+
+The policy matches the rounded Web context meter and requires a value strictly
+above the threshold. It calls the same public idle-maintenance service as `/compact`
+after a non-cancelled turn, never during active tools. Missing samples skip work.
+No model-callable tool, polling, invented model capacity, host policy mutation, or
+shared registry rewrite is involved. One owned operation, global cooldown,
+unchanged-surface suppression, abort/drain teardown, and commit/save-failure session
+suspension bound work. New user messages are queued by the host's maintenance seam.
+A timeout requests cooperative cancellation, not forced quiescence. Summarization
+may incur model cost and is not guaranteed lossless.
+
+## 内部分发
+
+宿主 Web module discovery 只接受 package-root row，不接受 `dsh-ops/*` 子入口。
+因此此组件是 `packages/auto-compact/` 内的伴随包，声明 file dependency 并通过
+`bundleDependencies` 随主包携带，无单独 npm 发布或安装要求。旧三入口不变，列表
+仍为四组件。宿主从所选 bundle 的 dependency closure 解析这个嵌套依赖。
+`npm pack` 后在隔离目录离线安装，已从主包锚点确认宿主入口/浏览器入口可解析；
+从 consumer 根直接 import 嵌套伴随包失败是预期的 npm 非提升布局，不假称根可解析。
+
+## 验证记录
+
+Target: DSH 0.2.0-rc.2. Runtime packages and vendored Rust are unchanged.
+
+```console
+node test/run.mjs auto-compact
+node --check packages/auto-compact/lib/client.js
+node --check packages/auto-compact/lib/index.js
+git diff --check
+```
+
+Targeted regressions cover schema rehydration with the real host library, real
+Cordis mounting/live update/unloading, strict bounds and occupancy, cancellation,
+serialization, no-op/self-replacement suppression, deadline/drain, errors and row
+registration. The compaction backend and browser rendering are test seams, not a
+real provider-backed Desktop E2E. Manual acceptance still required:
+
+1. Install a local development artifact in an isolated profile, reload the app,
+   confirm four components and this row's configuration control.
+2. Save 60%, reload page/app, confirm profile persistence; restore 50%.
+3. Grow a conversation past the threshold, confirm one compaction after idle;
+   inspect its durable marker and summary; queue input during compaction.
+4. Cancel a turn: no fresh automatic compaction. Disable during a summary: owned
+   abort/drain, no user/tool cancellation. Existing tools and background remain live.
+5. Missing model capacity, busy/manual compaction, provider failure and persistence
+   failure: no spin/no duplicate summary; inspect warnings and original session log.
+
+Full historical `npm run verify` is currently blocked by a pre-existing SVG-only
+icon expectation while the package intentionally ships PNG. Running the old suites
+also reveals earlier ladder/tool/metadata expectations incompatible with 0.2.4;
+no unrelated legacy migration is included in this change.

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.5-beta.1",
   "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,44 @@
           "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
+      },
+      {
+        "id": "dsh-ops-auto-compact",
+        "entry": "@dsh-ops/auto-compact",
+        "defaultEnabled": true
       }
     ]
   },

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/profile-install.js

@@ -50,7 +50,7 @@ export function profileCommand(operation, { profile, dshCli, dryRun = false }) {
   if (/\.cmd$/i.test(command)) {
     // cmd wrappers are Windows-owned launchers; reject shell metacharacters in caller-supplied paths.
     if (/["\r\n&|<>^%!]/.test(command)) throw new Error('Unsafe CLI path; use a path without cmd metacharacters.')
-    result = spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${command}" ${args.join(' ')}"`], { stdio: 'inherit', windowsHide: true })
+    result = spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${command}" ${args.join(' ')}"`], { stdio: 'inherit', windowsHide: true, windowsVerbatimArguments: true })
   } else result = spawnSync(command, [...prefix, ...args], { stdio: 'inherit', windowsHide: true })
   if (result.error) throw result.error
   if (result.status !== 0) return result.status ?? 1