@elinpf/dsh-ops-shell-tool 0.2.1 → 0.4.0

package/README.md

@@ -12,6 +12,8 @@ A pure library (not a plugin) — the single home for the boilerplate every ops
 - **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.
+- **Per-call tier declaration** — every profiled tool carries an optional `tier: 'ro'|'rw'` parameter: omit = decided by the grant (rw when granted); `'ro'` = deliberate downgrade under an rw grant (declare it for pure queries); `'rw'` = require the write tier, failing loudly with request_access guidance when the session holds no grant. Forwarded to `opsAccess.resolve` as `AccessRequest`.
+- **Session sandbox policy passthrough** — when the mounted shell executor confines (`ctx.shell.sandboxMode` defined), the factory resolves the CALLING session's policy via `ctx.get('sandboxPolicy')` (agent's `session` forwarded) and attaches it to the shell request — mirroring tool-bash. Without it the executor falls back to the deployment policy, whose workspace root is the dsh process cwd: for a systemd service that is `/`, so bwrap bind-mounts `/` over its own `/dev` tmpfs (ssh dies with `Couldn't open /dev/null`) and workspace-write silently degrades into the whole container root being writable. A confining executor without the sandboxPolicy service fails loudly instead of running under the wrong root.
 - **`shellQuote`** — exported for consumers that must embed a whole remote command as one argument (ops-tool-ssh).
 
 ## Design notes

package/lib/index.d.ts

@@ -27,7 +27,7 @@
  * @module @elinpf/dsh-ops-shell-tool
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { ProfiledShellToolSpec } from './types.js';
+import type { ProfiledShellToolSpec, ShellToolResult } from './types.js';
 export type { CredentialRef, ProfiledShellToolSpec, ShellToolExec, ShellToolResult } from './types.js';
 /**
  * Single-quote a value for safe shell embedding. Used for ref-token
@@ -43,6 +43,38 @@ export declare function shellQuote(value: string): string;
  * instead of its own command shape.
  */
 export declare function shellCompositionError(toolName: string, command: string): string | undefined;
+/** The shared output contract: schema + render, both pure. Exported so non-shell tools (e.g. ops-tool-prometheus, which speaks HTTP but keeps the suite-standard result shape) can reuse it instead of copying. */
+export declare const shellToolOutput: {
+    readonly schema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly exitCode: {
+                readonly type: "number";
+                readonly required: true;
+            };
+            readonly stdout: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly stderr: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly command: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly error: {
+                readonly type: "string";
+            };
+        };
+    };
+    readonly render: (_args: unknown, value: ShellToolResult) => {
+        type: "text";
+        text: string;
+    }[];
+};
 /**
  * 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

@@ -124,8 +124,8 @@ export function shellCompositionError(toolName, command) {
     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 = {
+/** The shared output contract: schema + render, both pure. Exported so non-shell tools (e.g. ops-tool-prometheus, which speaks HTTP but keeps the suite-standard result shape) can reuse it instead of copying. */
+export const shellToolOutput = {
     schema: {
         type: 'object',
         additionalProperties: false,
@@ -166,11 +166,16 @@ export function registerProfiledShellTool(ctx, spec) {
         parameters: {
             [spec.targetParam]: { type: 'string', required: true, description: spec.targetParamDescription },
             command: { type: 'string', required: true, description: spec.commandDescription },
+            tier: {
+                type: 'string',
+                enum: ['ro', 'rw'],
+                description: 'Credential tier for THIS call. Omit = decided by the grant (rw when granted, else ro). "ro" = deliberate downgrade: use the read-only credential even while holding an rw grant — declare it for pure queries so you always know which power you are exercising. "rw" = require the write tier; without a session grant this fails loudly and points at request_access instead of silently reading.',
+            },
             ...(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,
+        output: shellToolOutput,
         async execute(args, exec) {
             let fullCommand = '';
             try {
@@ -204,13 +209,35 @@ export function registerProfiledShellTool(ctx, spec) {
                 }
                 // Pass the caller agent through so the access gate (if mounted) can
                 // key grants on the session id. Without a gate this arg is inert.
-                const profile = await opsAccess.resolve(spec.kind, args[spec.targetParam], exec.agent);
+                // An explicit tier arg is the per-call declaration: 'ro' downgrades
+                // deliberately even under an rw grant; 'rw' fails loudly when the
+                // session holds no grant (see core's resolve / the gate's broker).
+                const tierArg = args.tier === 'ro' || args.tier === 'rw' ? args.tier : undefined;
+                const profile = await opsAccess.resolve(spec.kind, args[spec.targetParam], exec.agent, tierArg ? { tier: tierArg } : undefined);
                 // Mint per-call credential tokens: buildCommand marks file fields via
                 // 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, command, tokens.ref));
-                const request = { command: tokens.executable(fullCommand), timeoutMs, signal: exec.signal };
+                // A confining executor (bash-sandbox) defaults a missing policy from
+                // the DEPLOYMENT, whose fallback workspace root is the dsh process
+                // cwd — '/' for a systemd service. bwrap then bind-mounts '/' over
+                // its own /dev tmpfs: ssh dies with "Couldn't open /dev/null", and
+                // worse, workspace-write degrades into the whole container root being
+                // writable. Mirror tool-bash: pass the calling session's resolved
+                // policy explicitly. Resolved per call via ctx.get, never cached —
+                // same discipline as the opsAccess lookup above.
+                let sandboxPolicy;
+                if (ctx.shell.sandboxMode !== undefined) {
+                    const policyService = ctx.get('sandboxPolicy');
+                    if (!policyService) {
+                        const message = `${spec.name}: the mounted shell executor confines commands but the sandboxPolicy service is unavailable — refusing to run under the deployment fallback policy (wrong sandbox root). Mount dsh-sandbox-policy alongside the executor.`;
+                        return { error: message, exitCode: -1, stdout: '', stderr: message, command: '' };
+                    }
+                    const session = exec.agent?.session;
+                    sandboxPolicy = policyService.resolve(session !== undefined ? { session } : {});
+                }
+                const request = { command: tokens.executable(fullCommand), timeoutMs, signal: exec.signal, ...(sandboxPolicy !== undefined ? { sandboxPolicy } : {}) };
                 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

package/lib/types.d.ts

@@ -86,9 +86,14 @@ export type CredentialRef = (field: string) => string;
  * dsh's ToolRunContext: `signal` (required there, optional here for tests)
  * and the optional caller `agent`, whose `id` is the session the access gate
  * keys grants on. The factory passes `agent` straight through to resolve —
- * consumers stay identity-only and need no changes.
+ * consumers stay identity-only and need no changes. The agent's `session`
+ * (opaque here) is forwarded to the sandboxPolicy service so a confining
+ * shell executor sandboxes against the CALLING session's workspace, not the
+ * deployment fallback root.
  */
 export interface ShellToolExec {
     signal?: ShellExecRequest['signal'];
-    agent?: AccessAgent;
+    agent?: AccessAgent & {
+        session?: unknown;
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elinpf/dsh-ops-shell-tool",
-  "version": "0.2.1",
+  "version": "0.4.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.2.1",
+    "@elinpf/dsh-ops-access": "^0.4.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.2.1"
+    "@elinpf/dsh-ops-access": "0.4.0"
   },
   "license": "MIT",
   "publishConfig": {