@elinpf/dsh-ops-shell-tool 0.1.7 → 0.2.0

package/README.md

@@ -10,6 +10,7 @@ A pure library (not a plugin) — the single home for the boilerplate every ops
 - **Resolve per call** — the profile is resolved through `ctx.get('opsAccess')` inside execute, never statically injected, never cached.
 - **Credential tokens** — `buildCommand` marks file-bearing fields with `ref(field)`, which mints a display token `<id@tier:field>`; the executed command carries the shell-quoted real value, while the displayed command and all captured stdout/stderr are scrubbed back to tokens. Credential paths never reach the model or the session event log.
 - **Honest kill reporting** — 30 s default timeout; a signal death normalizes to `exitCode: -1` with the cause (timeout / caller abort / signal name) spelled out in the `error` field, never a bare -1.
+- **Environment-failure translation** — when stderr matches a known local-environment signature (e.g. ssh's startup `Couldn't open /dev/null` — the sandbox/host made /dev/null unwritable, so the command never left the machine), the `error` field carries the diagnosis and remediation instead of letting the model suspect credentials/network/remote.
 - **stderr noise filtering** — consumer-declared regexes drop known-noise stderr lines (e.g. ceph keyring chatter) after scrubbing.
 - **`shellQuote`** — exported for consumers that must embed a whole remote command as one argument (ops-tool-ssh).
 
@@ -21,7 +22,7 @@ A pure library (not a plugin) — the single home for the boilerplate every ops
 
 ## Configuration
 
-None — the package has no plugin `Config`. All behavior is parameterized per consumer through `ProfiledShellToolSpec`: `name`, `kind`, `targetParam`, the three description strings, `buildCommand`, `timeoutMs` (default 30000), and `stderrNoise`.
+None — the package has no plugin `Config`. All behavior is parameterized per consumer through `ProfiledShellToolSpec`: `name`, `kind`, `targetParam`, the three description strings, `buildCommand`, `timeoutMs` (default 30000), `perCallTimeout` (adds a 1–600s `timeoutSec` call parameter), `rejectShellComposition` (rejects `;` `&&` `||` backticks `$()` and newlines with a teaching error — a single `|` pipe stays allowed), and `stderrNoise`.
 
 ## Testing
 

package/README.zh.md

@@ -10,6 +10,7 @@ ops-access 消费方工具共享的工厂：统一的 shell 结果形状 `{ exit
 - **按调用解析** — profile 在 execute 内通过 `ctx.get('opsAccess')` 解析，不做静态 inject，不缓存。
 - **凭据 token** — `buildCommand` 用 `ref(field)` 标记含文件的字段，生成展示 token `<id@tier:field>`；实际执行的命令携带 shell 转义后的真实值，而展示命令和捕获的 stdout/stderr 全部洗回 token。凭据路径永远不进入模型上下文或会话事件日志。
 - **诚实的 kill 报告** — 默认 30s 超时；信号死亡归一为 `exitCode: -1`，并在 `error` 字段写明原因（超时 / 调用方取消 / 信号名），绝不留一个光秃秃的 -1。
+- **环境故障翻译** — stderr 命中已知环境签名（如 ssh 启动期 `Couldn't open /dev/null`——沙箱/宿主机把 /dev/null 变不可写，命令根本没出门）时，`error` 字段追加定位结论与修复指引，避免模型误查凭证/网络/远端。
 - **stderr 噪音过滤** — 消费方声明的正则在清洗之后丢弃已知噪音行（如 ceph keyring 唠叨）。
 - **`shellQuote`** — 导出给需要把整条远端命令作为单个参数嵌入的消费方（ops-tool-ssh）。
 
@@ -21,7 +22,7 @@ ops-access 消费方工具共享的工厂：统一的 shell 结果形状 `{ exit
 
 ## 配置项
 
-无 —— 本包没有插件 `Config`。所有行为由消费方通过 `ProfiledShellToolSpec` 参数化：`name`、`kind`、`targetParam`、三段描述文案、`buildCommand`、`timeoutMs`（默认 30000）、`stderrNoise`。
+无 —— 本包没有插件 `Config`。所有行为由消费方通过 `ProfiledShellToolSpec` 参数化：`name`、`kind`、`targetParam`、三段描述文案、`buildCommand`、`timeoutMs`（默认 30000）、`perCallTimeout`（为工具增加 1–600 秒的 `timeoutSec` 调用参数）、`rejectShellComposition`（拒绝 `;` `&&` `||` 反引号 `$()` 与换行并给出教学式报错——单个 `|` 管道仍然允许）、`stderrNoise`。
 
 ## 测试方式
 

package/lib/index.d.ts

@@ -35,6 +35,14 @@ export type { CredentialRef, ProfiledShellToolSpec, ShellToolExec, ShellToolResu
  * command as ONE argument (ops-tool-ssh).
  */
 export declare function shellQuote(value: string): string;
+/**
+ * Reject a composed command with a teaching error. Returns the message when
+ * the command is rejected, undefined when it is clean. Names the operator
+ * and the exact failure it would have caused — the bare 'xxx: command not
+ * found' the shell would produce sends the model suspecting the cluster
+ * instead of its own command shape.
+ */
+export declare function shellCompositionError(toolName: string, command: string): string | undefined;
 /**
  * Register a profiled shell tool on `ctx.tools`, disposed with the plugin's
  * fiber. The caller's plugin must declare `inject = ['shell', 'tools']`.

package/lib/index.js

@@ -86,6 +86,44 @@ function dropNoiseLines(text, patterns) {
         return text;
     return text.split('\n').filter((line) => !patterns.some((p) => p.test(line))).join('\n');
 }
+/**
+ * Recognize a broken LOCAL execution environment from stderr and translate it
+ * into actionable guidance. The trigger signature is ssh's startup open of
+ * /dev/null (O_RDWR) being denied — the command never reached the network,
+ * so without this note the model burns steps suspecting the credential, the
+ * network, and the remote host (it did, 2026-09-10). The real causes are a
+ * clobbered /dev/null on the dsh host (a regular file where the char device
+ * should be — classic in badly-built containers) or a sandbox profile that
+ * made /dev/null read-only (old-kernel Landlock partial enforcement, or a
+ * custom runnerOverride). Neither is fixable from here — the fix is the
+ * host's.
+ */
+function diagnoseSandboxEnv(stderr) {
+    if (!stderr.includes('Couldn\'t open /dev/null'))
+        return undefined;
+    return 'local execution environment failure (NOT the credential, the network, or the remote host): a process on the dsh host could not open /dev/null read-write at startup. Check the host: `ls -la /dev/null` must be a `crw-rw-rw-` character device — if it is a regular file, recreate it: `rm -f /dev/null && mknod -m 666 /dev/null c 1 3`. If /dev/null is healthy, the execution sandbox made it read-only (old-kernel Landlock partial enforcement, or a custom sandbox runnerOverride) — fix the sandbox policy; retrying the command will not help.';
+}
+/**
+ * Shell composition operators that would split the model's command into a
+ * second LOCAL command without the tool's binary prefix and credentials.
+ * A single `|` is deliberately absent: piping the wrapped command's output
+ * to a local filter (get pods | grep Running) is a documented, useful case.
+ */
+const SHELL_COMPOSITION = /;|&&|\|\||`|\$\(|\r|\n/;
+/**
+ * Reject a composed command with a teaching error. Returns the message when
+ * the command is rejected, undefined when it is clean. Names the operator
+ * and the exact failure it would have caused — the bare 'xxx: command not
+ * found' the shell would produce sends the model suspecting the cluster
+ * instead of its own command shape.
+ */
+export function shellCompositionError(toolName, command) {
+    const m = SHELL_COMPOSITION.exec(command);
+    if (!m)
+        return undefined;
+    const op = m[0] === '\n' || m[0] === '\r' ? 'a newline' : `'${m[0]}'`;
+    return `the command contains ${op} — everything after it would run as a NEW local command WITHOUT the ${toolName} prefix and injected credentials, failing with a misleading 'xxx: command not found'. One call = one ${toolName} command: split this into separate tool calls. (A single | pipe is allowed — it filters the output locally.)`;
+}
 /** The shared output contract: schema + render, both pure. */
 const output = {
     schema: {
@@ -128,11 +166,32 @@ export function registerProfiledShellTool(ctx, spec) {
         parameters: {
             [spec.targetParam]: { type: 'string', required: true, description: spec.targetParamDescription },
             command: { type: 'string', required: true, description: spec.commandDescription },
+            ...(spec.perCallTimeout
+                ? { timeoutSec: { type: 'number', description: `Optional per-call timeout in seconds (default ${Math.round((spec.timeoutMs ?? 30000) / 1000)}, max 600). Use only for a command you KNOW is slow (e.g. listing a very large pool) — a longer wait does not fix a hung remote end.` } }
+                : {}),
         },
         output,
         async execute(args, exec) {
             let fullCommand = '';
             try {
+                // Reject shell composition before anything else — cheap, side-effect
+                // free, and the teaching message is most useful BEFORE the model has
+                // burned a credential resolve on a malformed call.
+                const command = args.command;
+                if (spec.rejectShellComposition) {
+                    const message = shellCompositionError(spec.name, command);
+                    if (message)
+                        return { error: message, exitCode: -1, stdout: '', stderr: message, command: '' };
+                }
+                // Per-call timeout override (opt-in via spec.perCallTimeout):
+                // 1s–600s, anything else falls back to the configured ceiling.
+                let timeoutMs = spec.timeoutMs ?? 30000;
+                if (spec.perCallTimeout) {
+                    const override = args.timeoutSec;
+                    if (typeof override === 'number' && Number.isFinite(override) && override >= 1 && override <= 600) {
+                        timeoutMs = Math.round(override * 1000);
+                    }
+                }
                 // Resolve the seam per call through ctx.get: the preset mounts the
                 // group concurrently, so 'opsAccess' must not be a static inject
                 // (deadlock risk against the definition row), and by tool-call time
@@ -150,8 +209,8 @@ export function registerProfiledShellTool(ctx, spec) {
                 // ref(); the display command (model-visible, logged) keeps the tokens,
                 // only the executed command carries the real values.
                 const tokens = createCredentialTokens(profile.name, profile.tier, profile.fields);
-                fullCommand = tokens.scrub(spec.buildCommand(profile.fields, args.command, tokens.ref));
-                const request = { command: tokens.executable(fullCommand), timeoutMs: spec.timeoutMs ?? 30000, signal: exec.signal };
+                fullCommand = tokens.scrub(spec.buildCommand(profile.fields, command, tokens.ref));
+                const request = { command: tokens.executable(fullCommand), timeoutMs, signal: exec.signal };
                 const resolved = ctx.shell.resolve(request);
                 const result = await ctx.shell.run(resolved);
                 // exitCode is null when the process died from a signal — normalize to
@@ -169,12 +228,15 @@ export function registerProfiledShellTool(ctx, spec) {
                         : result.exitCode === null
                             ? 'killed by signal ' + (result.signal ?? 'unknown') + ' — no normal exit code; the process was terminated externally (OOM killer, sandbox policy, or a deliberate kill).'
                             : undefined;
+                const stderrText = dropNoiseLines(tokens.scrub(result.stderr.text), spec.stderrNoise);
+                const envNote = diagnoseSandboxEnv(stderrText);
+                const errorNote = [killNote, envNote].filter(Boolean).join('\n');
                 return {
                     exitCode: result.exitCode ?? -1,
                     stdout: tokens.scrub(result.stdout.text),
-                    stderr: dropNoiseLines(tokens.scrub(result.stderr.text), spec.stderrNoise),
+                    stderr: stderrText,
                     command: fullCommand,
-                    ...(killNote !== undefined ? { error: killNote } : {}),
+                    ...(errorNote !== '' ? { error: errorNote } : {}),
                 };
             }
             catch (e) {

package/lib/types.d.ts

@@ -44,6 +44,26 @@ export interface ProfiledShellToolSpec {
      * kill note tells the model exactly which ceiling it hit.
      */
     timeoutMs?: number;
+    /**
+     * When true the tool gains an optional `timeoutSec` parameter (1–600s) so
+     * the model can extend the per-call ceiling for one known-slow command
+     * (e.g. `rados ls` on a large pool) instead of being hard-killed at the
+     * configured timeoutMs. Absent/0/out-of-range values fall back to
+     * timeoutMs.
+     */
+    perCallTimeout?: boolean;
+    /**
+     * When true, a command containing shell composition operators (`;`, `&&`,
+     * `||`, backticks, `$(`, newlines) is rejected with a teaching error
+     * BEFORE execution: everything after such an operator runs as a NEW local
+     * command without the tool's binary prefix and credentials, which the
+     * model reads as a mysterious 'get: command not found' and misattributes
+     * to the cluster (it did, repeatedly, 2026-09-10). A single `|` pipe is
+     * still allowed — it filters the wrapped command's output locally. Leave
+     * unset for tools whose command legitimately contains composition
+     * (ops-tool-ssh passes the whole string to the REMOTE shell).
+     */
+    rejectShellComposition?: boolean;
     /**
      * Known-noise stderr line patterns: any captured stderr line matching one
      * of these regexes is dropped from the result. For warnings the CLI prints

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elinpf/dsh-ops-shell-tool",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Shared factory for ops-access consumer tools: standard shell result shape, output schema, render, and the resolve-per-call execute template.",
   "type": "module",
   "main": "lib/index.js",
@@ -28,7 +28,7 @@
   ],
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@elinpf/dsh-ops-access": "^0.1.7",
+    "@elinpf/dsh-ops-access": "^0.2.0",
     "@deepseek-ai/dsh-shell": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.8"
   },
@@ -38,7 +38,7 @@
     "@deepseek-ai/dsh-tools": "0.0.1-rc.1",
     "typescript": "^5.4.0",
     "vitest": "^4.1.11",
-    "@elinpf/dsh-ops-access": "0.1.7"
+    "@elinpf/dsh-ops-access": "0.2.0"
   },
   "license": "MIT",
   "publishConfig": {