@elinpf/dsh-ops-tool-ssh 0.1.0

package/README.i18n.yaml

@@ -0,0 +1,4 @@
+title: "@elinpf/dsh-ops-tool-ssh"
+description:
+  zh: "ssh 工具 — 解析 ssh 访问档案,经 ctx.shell 在远程主机执行命令"
+  en: "ssh tool — resolves ssh access profiles and runs commands on remote hosts via ctx.shell"

package/README.md

@@ -0,0 +1,37 @@
+# @elinpf/dsh-ops-tool-ssh
+
+The `ssh` tool for DeepSeek Harness ops mode — runs a command on a remote host over SSH, using a registered ssh access profile (key, port, user@host injected automatically).
+
+## What it does
+
+A consumer of the ops-access credential seam: the model calls `ssh` with a profile name and a command; the plugin resolves the profile through `opsAccess` and runs the command via `ctx.shell`. `BatchMode=yes` makes anything that would prompt fail fast, and `StrictHostKeyChecking=accept-new` trusts a host key on first contact while refusing changed ones. Use `list_access` to see available host names.
+
+- The remote command is passed as ONE single-quoted argument — pipes, redirects, `&&`, `;` and `$()` all execute on the REMOTE host; the local shell never splits the line (an unquoted `&&` chain once came one auth failure short of deleting control-plane manifests locally, 2026-08-27 near-miss).
+- Only the key path gets a per-call credential token; user@host and port stay inline. The display command (model-visible, logged) keeps tokens — only the executed command carries real values.
+- Signal deaths (null exitCode) are normalized to exitCode -1, with the cause surfaced in `error`.
+
+## Design
+
+This package is deliberately thin. All shared machinery — result shape `{ exitCode, stdout, stderr, command, error? }`, output schema, render, and the resolve-per-call execute template (30 s default timeout) — lives in `@elinpf/dsh-ops-shell-tool`. A consumer tool only supplies four identity pieces: tool name, resolved credential kind, profile-arg name, and `buildCommand`. The ops-access seam is resolved per call through `ctx.get('opsAccess')`, never a static inject (the preset mounts the group concurrently — a static inject deadlocks the loader).
+
+- `src/index.ts` — the plugin (function plugin: `name`/`inject`/`Config`/`apply`, no default export). Registration goes through `ctx.effect`, so fiber disposal/HMR unloads the tool.
+- `src/types.ts` — pure types (no runtime values).
+- `src/invariant.ts` — invariant companion; no runtime invariant (stateless tool, owns no session events), registers package ownership only.
+
+## Configuration
+
+```yaml
+- id: ops-tool-ssh
+  name: '@elinpf/dsh-ops-tool-ssh'
+  timeoutMs: 30000            # per-call shell timeout (ms)
+  connectTimeoutSeconds: 10   # ssh -o ConnectTimeout (TCP handshake wait)
+```
+
+## Testing
+
+```sh
+npm run build
+npx vitest run
+```
+
+Tests mount the plugin against a mock context (`tests/harness.ts`) that captures tool registrations, shell resolve/run calls, and effect disposers — covering command assembly, quoting, credential tokens, error fallbacks, render purity, and HMR unload.

package/README.zh.md

@@ -0,0 +1,37 @@
+# @elinpf/dsh-ops-tool-ssh
+
+DeepSeek Harness 运维模式的 `ssh` 工具 — 使用已注册的 ssh 访问档案在远程主机上执行命令(密钥路径、端口、user@host 自动注入)。
+
+## 功能
+
+ops-access 凭据缝隙的消费方:模型用档案名加命令调用 `ssh`,插件经 `opsAccess` 解析档案,再经 `ctx.shell` 执行。`BatchMode=yes` 让任何需要交互的场景快速失败;`StrictHostKeyChecking=accept-new` 首次连接信任主机密钥、密钥变更则拒绝。可用 `list_access` 查看可选主机名。
+
+- 远程命令作为**一个**单引号参数整体传出 — 管道、重定向、`&&`、`;`、`$()` 全部在远程主机执行,本地 shell 绝不切分这行命令(2026-08-27 险情:一条未加引号的 `&&` 链差一次认证失败就在本地删掉了控制面清单)。
+- 只有密钥路径换成按次生成的凭据 token;user@host 和端口保持内联。展示命令(模型可见、入日志)只含 token — 真正执行的命令才带真实值。
+- 信号死亡(exitCode 为 null)归一化为 -1,原因写入 `error` 字段。
+
+## 设计
+
+本包刻意保持单薄。所有共享机制 — 结果形状 `{ exitCode, stdout, stderr, command, error? }`、输出 schema、render、按次解析的执行模板(默认 30s 超时)— 都在 `@elinpf/dsh-ops-shell-tool`。消费方工具只提供四个身份要素:工具名、凭据 kind、档案参数名、`buildCommand`。ops-access 缝隙每次调用经 `ctx.get('opsAccess')` 现取,绝不用静态 inject(preset 并发挂载同组插件,静态 inject 会让加载器死锁)。
+
+- `src/index.ts` — 插件本体(函数式插件:`name`/`inject`/`Config`/`apply`,无默认导出)。注册走 `ctx.effect`,fiber 销毁/HMR 时工具随之卸载。
+- `src/types.ts` — 纯类型(无任何运行时值)。
+- `src/invariant.ts` — invariant 伴随插件;无运行时 invariant(工具无状态,不拥有 session 事件),仅登记包的归属。
+
+## 配置
+
+```yaml
+- id: ops-tool-ssh
+  name: '@elinpf/dsh-ops-tool-ssh'
+  timeoutMs: 30000            # 单次调用的 shell 超时(毫秒)
+  connectTimeoutSeconds: 10   # ssh -o ConnectTimeout(TCP 握手等待)
+```
+
+## 测试
+
+```sh
+npm run build
+npx vitest run
+```
+
+测试用 mock 上下文(`tests/harness.ts`)挂载插件,捕获工具注册、shell resolve/run 调用和 effect disposer — 覆盖命令拼装、引号、凭据 token、错误兜底、render 纯函数性和 HMR 卸载。

package/cordis.patch.yml

@@ -0,0 +1 @@
+[]

package/lib/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Ops ssh tool consumer.
+ *
+ * The `ssh` tool: resolves an `ssh` profile through the ops-access seam and
+ * runs a remote command via ctx.shell, injecting the profile's key path,
+ * port, and user@host. The remote command is shell-quoted as ONE argument —
+ * the local shell must never split it: an unquoted && chain once came one
+ * auth failure short of deleting control-plane manifests remotely while
+ * `restoring` them on the LOCAL machine (2026-08-27 near-miss). All shared
+ * machinery (result shape, output schema, render, execute template) lives
+ * in @elinpf/dsh-ops-shell-tool.
+ *
+ * @module @elinpf/dsh-ops-tool-ssh
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { SshToolConfig } from './types';
+export type { SshToolConfig } from './types';
+export declare const name = "ops-tool-ssh";
+export declare const inject: string[];
+export declare const Config: z<Schemastery.ObjectS<{
+    /** Per-call shell timeout for ssh runs (ms). */
+    timeoutMs: z<number, number>;
+    /** ssh -o ConnectTimeout value (seconds) — how long to wait for the TCP handshake. */
+    connectTimeoutSeconds: z<number, number>;
+}>, Schemastery.ObjectT<{
+    /** Per-call shell timeout for ssh runs (ms). */
+    timeoutMs: z<number, number>;
+    /** ssh -o ConnectTimeout value (seconds) — how long to wait for the TCP handshake. */
+    connectTimeoutSeconds: z<number, number>;
+}>>;
+export declare function apply(ctx: Context, config: SshToolConfig): void;

package/lib/index.js

@@ -0,0 +1,55 @@
+/**
+ * Ops ssh tool consumer.
+ *
+ * The `ssh` tool: resolves an `ssh` profile through the ops-access seam and
+ * runs a remote command via ctx.shell, injecting the profile's key path,
+ * port, and user@host. The remote command is shell-quoted as ONE argument —
+ * the local shell must never split it: an unquoted && chain once came one
+ * auth failure short of deleting control-plane manifests remotely while
+ * `restoring` them on the LOCAL machine (2026-08-27 near-miss). All shared
+ * machinery (result shape, output schema, render, execute template) lives
+ * in @elinpf/dsh-ops-shell-tool.
+ *
+ * @module @elinpf/dsh-ops-tool-ssh
+ */
+import z from '@deepseek-ai/schemastery';
+import { registerProfiledShellTool, shellQuote } from '@elinpf/dsh-ops-shell-tool';
+// ── Plugin identity ───────────────────────────────────────────────────────────
+export const name = 'ops-tool-ssh';
+export const inject = ['shell', 'tools'];
+// ── Config ───────────────────────────────────────────────────────────────────
+export const Config = z.object({
+    /** Per-call shell timeout for ssh runs (ms). */
+    timeoutMs: z.number().default(30000),
+    /** ssh -o ConnectTimeout value (seconds) — how long to wait for the TCP handshake. */
+    connectTimeoutSeconds: z.number().default(10),
+});
+// ── Plugin apply ─────────────────────────────────────────────────────────────
+export function apply(ctx, config) {
+    registerProfiledShellTool(ctx, {
+        timeoutMs: config.timeoutMs,
+        name: 'ssh',
+        kind: 'ssh',
+        targetParam: 'host',
+        description: 'Run a command on a remote host over SSH, using a registered ssh access profile (key, port, user@host injected automatically). Non-interactive: BatchMode is on, so anything that would prompt fails fast. Use list_access to see available host names.',
+        targetParamDescription: 'SSH host profile name. Use list_access to see options.',
+        commandDescription: 'Command to run on the remote host, e.g. "systemctl status ceph-osd@3". The whole string is passed as ONE shell-quoted argument and run by the remote shell: pipes, redirects, &&, ; and $() all execute on the REMOTE host — nothing is interpreted locally.',
+        buildCommand(fields, command, ref) {
+            const { host, user, key, port } = fields;
+            // BatchMode: never prompt (password/passphrase) — fail fast instead.
+            // accept-new: trust a host key on first contact, refuse changed ones —
+            // ops hosts are reached by name from the registry, not typed by hand.
+            const opts = ['-o BatchMode=yes', `-o ConnectTimeout=${config.connectTimeoutSeconds}`, '-o StrictHostKeyChecking=accept-new'];
+            // Only the key path gets a credential token; user@host/port stay inline.
+            if (key !== undefined)
+                opts.push(`-i ${ref('key')}`);
+            if (port !== undefined)
+                opts.push(`-p ${port}`);
+            // The remote command goes out as ONE single-quoted argument: sshd
+            // re-runs it through the remote shell, where &&, pipes, redirects and
+            // $() all belong. Left unquoted, the LOCAL shell would split the line
+            // and run the later segments here as root (2026-08-27 near-miss).
+            return `ssh ${opts.join(' ')} ${user}@${host} ${shellQuote(command)}`;
+        },
+    });
+}

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-tool-ssh.
+ *
+ * @module @elinpf/dsh-ops-tool-ssh/invariant
+ */
+/** Cordis companion plugin name. */
+declare const name = "ops-tool-ssh-invariant";
+/** Service required before the companion can reserve package ownership. */
+declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+declare const apply: (ctx: any) => Promise<void>;
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,26 @@
+/**
+ * Invariant companion for @elinpf/dsh-ops-tool-ssh.
+ *
+ * @module @elinpf/dsh-ops-tool-ssh/invariant
+ */
+const PACKAGE_NAME = '@elinpf/dsh-ops-tool-ssh';
+/** Cordis companion plugin name. */
+const name = 'ops-tool-ssh-invariant';
+/** Service required before the companion can reserve package ownership. */
+const inject = ['invariants'];
+/**
+ * No runtime invariant: this tool is fully stateless — it owns no session
+ * event types and no durable shape. Every call resolves its profile fresh
+ * through the ops-access seam and delegates execution to ctx.shell; there is
+ * nothing folded from the log and nothing cached to keep consistent.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Context carrying the invariant service.
+ * @returns a promise resolving after registration.
+ */
+const apply = async (ctx) => {
+    ctx.invariants.register(PACKAGE_NAME, install);
+};
+export { apply, inject, name };

package/lib/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Type definitions for the ops-tool-ssh plugin.
+ *
+ * Types only — no runtime values live here.
+ *
+ * @module @elinpf/dsh-ops-tool-ssh
+ */
+/**
+ * Resolved plugin config (post-Config-schema defaults).
+ */
+export interface SshToolConfig {
+    /** Per-call shell timeout for ssh runs (ms). */
+    timeoutMs: number;
+    /** ssh -o ConnectTimeout value (seconds) — how long to wait for the TCP handshake. */
+    connectTimeoutSeconds: number;
+}

package/lib/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for the ops-tool-ssh plugin.
+ *
+ * Types only — no runtime values live here.
+ *
+ * @module @elinpf/dsh-ops-tool-ssh
+ */
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@elinpf/dsh-ops-tool-ssh",
+  "version": "0.1.0",
+  "description": "ssh tool consumer of the ops-access seam — resolves ssh profiles and runs commands via ctx.shell, injecting credential paths automatically.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@elinpf/dsh-ops-shell-tool": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-shell": "0.0.1-rc.5",
+    "@deepseek-ai/dsh-tools": "0.0.1-rc.1",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.11",
+    "@elinpf/dsh-ops-access": "0.1.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}