shmakk 1.2.1 → 1.2.2

package/README.md

@@ -170,6 +170,46 @@ The coordinator system enables complex, multi-step task execution with plan-firs
 - Secrets (`.env`, keys, tokens) are never sent to the AI
 - Workspace root is enforced — tools can't access files outside it
 
+## Remote SSH
+
+The agent can run commands and transfer files on remote hosts via SSH. Configure hosts in `.shmakk/hosts.json` (per-project) or `~/.config/shmakk/hosts.json` (global):
+
+```json
+{
+  "hosts": {
+    "devbox": {
+      "host": "marcus@192.168.1.100",
+      "port": 22,
+      "auto_approve": false,
+      "timeout_sec": 30
+    },
+    "staging": {
+      "host": "deploy@10.0.0.5",
+      "port": 2247
+    }
+  },
+  "allow_ssh_config": false,
+  "default_timeout_sec": 30
+}
+```
+
+| Tool | Description |
+|------|-------------|
+| `ssh_run` | Run a shell command on a remote host |
+| `ssh_push` | Copy a local workspace file to a remote host |
+| `ssh_pull` | Copy a remote file into the local workspace |
+
+SSH key auth via `~/.ssh` is assumed. For persistent connections (avoid re-auth on every call), add to `~/.ssh/config`:
+
+```
+Host *
+  ControlMaster auto
+  ControlPath ~/.ssh/controlmasters/%r@%h:%p
+  ControlPersist 600
+```
+
+Then `mkdir -p ~/.ssh/controlmasters` once.
+
 ## How it works
 
 shmakk wraps your shell in a PTY (pseudo-terminal). Every command that fails is checked against a deterministic correction engine (no LLM, no API call). If a correction matches and the fixed command succeeds, shmakk feeds the agent your **original input** (not the fixed command) so the agent can address your full intent — not just the typo. You can also give task instructions in natural language — shmakk uses tools to read files, write code, list directories, and run commands, all constrained to your workspace.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shmakk",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "AI-supervised terminal wrapper — command correction, tool-driven tasks, safety controls",
   "license": "MIT",
   "keywords": [

package/src/cli.js

@@ -300,6 +300,33 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   Tools: navigate, click, type, read_page, screenshot, evaluate, select,
   wait, scroll, close.
 
+═══════════════════════════════════════════════════════════════════════════
+  REMOTE HOSTS (SSH)
+═══════════════════════════════════════════════════════════════════════════
+
+  The agent can run commands on remote hosts and transfer files via SSH.
+  Configure hosts in .shmakk/hosts.json or ~/.config/shmakk/hosts.json:
+
+    {
+      "hosts": {
+        "devbox": {
+          "host": "user@192.168.1.100",
+          "port": 22,
+          "auto_approve": false,
+          "timeout_sec": 30
+        }
+      },
+      "allow_ssh_config": false,
+      "default_timeout_sec": 30
+    }
+
+  Agent tools: ssh_run (run command), ssh_push (upload), ssh_pull (download).
+  For persistent connections, use ControlMaster in ~/.ssh/config:
+    Host *
+      ControlMaster auto
+      ControlPath ~/.ssh/controlmasters/%r@%h:%p
+      ControlPersist 600
+
 `;
 
 module.exports = { parseArgs, HELP };

package/src/ssh.js

@@ -0,0 +1,255 @@
+// SSH remote execution and file transfer for shmakk.
+//
+// Hosts are defined in .shmakk/hosts.json (project-local) or
+// ~/.config/shmakk/hosts.json (global). If a host config has
+// allow_ssh_config: true, ~/.ssh/config Host entries are also
+// available as targets.
+//
+// Schema (hosts.json):
+//   {
+//     "hosts": {
+//       "devbox": {
+//         "host": "user@192.168.1.100",
+//         "port": 22,
+//         "auto_approve": false,
+//         "timeout_sec": 30
+//       }
+//     },
+//     "allow_ssh_config": false,
+//     "default_timeout_sec": 30
+//   }
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFile } = require('child_process');
+
+// ── Config loading ─────────────────────────────────────────────────────
+
+function loadHostConfig(workspaceRoot) {
+  const candidates = [];
+  // Project-local config
+  if (workspaceRoot) {
+    candidates.push(path.join(workspaceRoot, '.shmakk', 'hosts.json'));
+  }
+  // Global config
+  candidates.push(path.join(os.homedir(), '.config', 'shmakk', 'hosts.json'));
+
+  let merged = { hosts: {}, allow_ssh_config: false, default_timeout_sec: 30 };
+
+  for (const p of candidates) {
+    try {
+      const raw = fs.readFileSync(p, 'utf8');
+      const cfg = JSON.parse(raw);
+      if (cfg.hosts && typeof cfg.hosts === 'object') {
+        Object.assign(merged.hosts, cfg.hosts);
+      }
+      if (typeof cfg.allow_ssh_config === 'boolean') {
+        merged.allow_ssh_config = merged.allow_ssh_config || cfg.allow_ssh_config;
+      }
+      if (typeof cfg.default_timeout_sec === 'number') {
+        merged.default_timeout_sec = cfg.default_timeout_sec;
+      }
+    } catch {
+      // Missing or malformed — skip
+    }
+  }
+
+  // Optionally import ~/.ssh/config hosts
+  if (merged.allow_ssh_config) {
+    const sshConfigHosts = parseSSHConfig();
+    for (const [name, entry] of Object.entries(sshConfigHosts)) {
+      if (!merged.hosts[name]) {
+        merged.hosts[name] = entry;
+      }
+    }
+  }
+
+  return merged;
+}
+
+function parseSSHConfig() {
+  const configPath = path.join(os.homedir(), '.ssh', 'config');
+  const hosts = {};
+  try {
+    const content = fs.readFileSync(configPath, 'utf8');
+    const lines = content.split(/\r?\n/);
+    let currentHost = null;
+    let currentEntry = null;
+
+    for (const raw of lines) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+
+      const m = line.match(/^(\S+)\s+(.+)$/);
+      if (!m) continue;
+
+      const key = m[1].toLowerCase();
+      const value = m[2].trim();
+
+      if (key === 'host') {
+        // Save previous entry
+        if (currentHost && currentEntry) {
+          currentEntry._aliases = currentHost.split(/\s+/);
+          for (const alias of currentEntry._aliases) {
+            if (alias !== '*') hosts[alias] = currentEntry;
+          }
+        }
+        currentHost = value;
+        currentEntry = { host: null, port: 22, auto_approve: false, _from_ssh_config: true };
+      } else if (currentEntry) {
+        if (key === 'hostname') currentEntry.host = value;
+        else if (key === 'port') currentEntry.port = parseInt(value, 10) || 22;
+        else if (key === 'user') {
+          // Merge user into the host string
+          const h = currentEntry.host || value;
+          currentEntry.host = `${value}@${h.replace(/^[^@]+@/, '')}`;
+        }
+      }
+    }
+    // Save last entry
+    if (currentHost && currentEntry) {
+      currentEntry._aliases = currentHost.split(/\s+/);
+      for (const alias of currentEntry._aliases) {
+        if (alias !== '*') hosts[alias] = currentEntry;
+      }
+    }
+  } catch {
+    // No config or unreadable
+  }
+  return hosts;
+}
+
+function resolveHost(cfg, name) {
+  const entry = cfg.hosts[name];
+  if (!entry) return null;
+  if (!entry.host) return null;
+  return entry;
+}
+
+// ── SSH command builder ─────────────────────────────────────────────────
+
+function buildSSHArgs(entry, cmd) {
+  const args = ['ssh'];
+  if (entry.port && entry.port !== 22) {
+    args.push('-p', String(entry.port));
+  }
+  // Common options for non-interactive remote execution
+  args.push('-o', 'BatchMode=yes');
+  args.push('-o', 'StrictHostKeyChecking=accept-new');
+  args.push('-o', 'ConnectTimeout=10');
+  args.push(entry.host);
+  args.push(cmd);
+  return args;
+}
+
+function buildSCPArgs(entry, src, dest, direction) {
+  // direction: 'push' → local src → remote dest
+  //            'pull' → remote src → local dest
+  const args = ['scp'];
+  if (entry.port && entry.port !== 22) {
+    args.push('-P', String(entry.port));
+  }
+  args.push('-o', 'BatchMode=yes');
+  args.push('-o', 'StrictHostKeyChecking=accept-new');
+  args.push('-o', 'ConnectTimeout=10');
+
+  if (direction === 'push') {
+    args.push(src, `${entry.host}:${dest}`);
+  } else {
+    args.push(`${entry.host}:${src}`, dest);
+  }
+  return args;
+}
+
+// ── Execution ───────────────────────────────────────────────────────────
+
+function sshRun(entry, cmd, signal) {
+  const timeout = (entry.timeout_sec || 30) * 1000;
+  const args = buildSSHArgs(entry, cmd);
+
+  return new Promise((resolve) => {
+    const child = execFile('ssh', args, {
+      timeout,
+      maxBuffer: 4 * 1024 * 1024,
+    }, (err, stdout, stderr) => {
+      if (err) {
+        const msg = (stderr || '').toString().trim() || err.message;
+        // Distinguish known SSH errors
+        if (err.killed) {
+          resolve({ error: `SSH timed out after ${timeout / 1000}s`, exitCode: null, stderr: msg });
+        } else {
+          resolve({
+            error: `SSH failed (exit ${err.code}): ${msg}`,
+            exitCode: err.code,
+            stderr: msg,
+            stdout: (stdout || '').toString().trim(),
+          });
+        }
+        return;
+      }
+      resolve({
+        ok: true,
+        stdout: (stdout || '').toString().trim(),
+        stderr: (stderr || '').toString().trim(),
+      });
+    });
+
+    if (signal) {
+      const onAbort = () => { try { child.kill('SIGINT'); } catch {} };
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}
+
+function sshTransfer(entry, src, dest, direction, signal) {
+  const timeout = (entry.timeout_sec || 60) * 1000;
+  const args = buildSCPArgs(entry, src, dest, direction);
+
+  return new Promise((resolve) => {
+    const child = execFile('scp', args, {
+      timeout,
+      maxBuffer: 4 * 1024 * 1024,
+    }, (err, stdout, stderr) => {
+      if (err) {
+        const msg = (stderr || '').toString().trim() || err.message;
+        if (err.killed) {
+          resolve({ error: `SCP timed out after ${timeout / 1000}s`, stderr: msg });
+        } else {
+          resolve({
+            error: `SCP failed (exit ${err.code}): ${msg}`,
+            exitCode: err.code,
+            stderr: msg,
+          });
+        }
+        return;
+      }
+      resolve({ ok: true, stdout: (stdout || '').toString().trim() });
+    });
+
+    if (signal) {
+      const onAbort = () => { try { child.kill('SIGINT'); } catch {} };
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}
+
+// ── Host listing ────────────────────────────────────────────────────────
+
+function listHosts(cfg) {
+  return Object.entries(cfg.hosts).map(([name, entry]) => ({
+    name,
+    host: entry.host,
+    port: entry.port || 22,
+    auto_approve: !!entry.auto_approve,
+    from_ssh_config: !!entry._from_ssh_config,
+  }));
+}
+
+module.exports = {
+  loadHostConfig,
+  resolveHost,
+  sshRun,
+  sshTransfer,
+  listHosts,
+};

package/src/tools.js

@@ -14,6 +14,14 @@ const https = require('https');
 const http = require('http');
 const os = require('os');
 
+// Lazy-load SSH (optional — only required when ssh_* tools are called).
+let _ssh = null;
+function _getSSH(roots) {
+  if (_ssh) return _ssh;
+  try { _ssh = require('./ssh'); } catch (e) { return null; }
+  return _ssh;
+}
+
 // Lazy-load TTS (kokoro-js is an optional dep; only required when
 // tts_generate is actually called).
 let _ttsGenerate = null;
@@ -229,6 +237,44 @@ const TOOLS = [
       },
     },
   }},
+  { type: 'function', function: {
+    name: 'ssh_run',
+    description: 'Run a shell command on a pre-configured remote host via SSH. Hosts are defined in .shmakk/hosts.json or ~/.config/shmakk/hosts.json. Output is captured.',
+    parameters: {
+      type: 'object',
+      required: ['host', 'cmd'],
+      properties: {
+        host: { type: 'string', description: 'Host alias as defined in hosts.json (e.g. "devbox")' },
+        cmd: { type: 'string', description: 'Shell command to run on the remote host' },
+      },
+    },
+  }},
+  { type: 'function', function: {
+    name: 'ssh_push',
+    description: 'Copy a file from the local workspace to a remote host via SCP. Hosts are defined in .shmakk/hosts.json.',
+    parameters: {
+      type: 'object',
+      required: ['host', 'src', 'dest'],
+      properties: {
+        host: { type: 'string', description: 'Host alias as defined in hosts.json' },
+        src: { type: 'string', description: 'Local file path (relative to workspace or absolute)' },
+        dest: { type: 'string', description: 'Remote destination path (absolute on remote host)' },
+      },
+    },
+  }},
+  { type: 'function', function: {
+    name: 'ssh_pull',
+    description: 'Copy a file from a remote host to the local workspace via SCP. Hosts are defined in .shmakk/hosts.json.',
+    parameters: {
+      type: 'object',
+      required: ['host', 'src', 'dest'],
+      properties: {
+        host: { type: 'string', description: 'Host alias as defined in hosts.json' },
+        src: { type: 'string', description: 'Remote source path (absolute on remote host)' },
+        dest: { type: 'string', description: 'Local destination path (relative to workspace or absolute)' },
+      },
+    },
+  }},
 ];
 
 // Tool safety classification.
@@ -258,6 +304,7 @@ function classifyTool(name, args, mcpManager) {
   if (name === 'tts_generate') return 'safe';       // local-only, no network
   if (name === 'video_probe') return 'safe';        // read-only local metadata
   if (name === 'video_compose') return 'safe';      // local ffmpeg, reads only workspace files
+  if (name === 'ssh_run' || name === 'ssh_push' || name === 'ssh_pull') return 'unsafe';
   return 'uncertain';
 }
 
@@ -287,6 +334,9 @@ function describeTool(name, args, mcpManager) {
   if (name === 'tts_generate') return `tts_generate: "${(args.text || '').slice(0, 80)}" (voice: ${args.voice || 'af_heart'})`;
   if (name === 'video_probe') return `video_probe ${args.path || ''}`;
   if (name === 'video_compose') return `video_compose ${(args.segments || []).length} segments → ${args.outputPath || ''}`;
+  if (name === 'ssh_run') return `ssh_run ${args.host || ''}: ${(args.cmd || '').slice(0, 100)}`;
+  if (name === 'ssh_push') return `ssh_push ${args.src || ''} → ${args.host || ''}:${args.dest || ''}`;
+  if (name === 'ssh_pull') return `ssh_pull ${args.host || ''}:${args.src || ''} → ${args.dest || ''}`;
   return `${name} ${JSON.stringify(args).slice(0, 80)}`;
 }
 
@@ -767,6 +817,35 @@ async function dispatchTool(name, args, roots, confirmTool, signal, mcpManager)
     });
     return composeResult;
   }
+  if (name === 'ssh_run') {
+    const ssh = _getSSH(roots);
+    if (!ssh) return { error: 'SSH module not available' };
+    const cfg = ssh.loadHostConfig(roots[0]);
+    const entry = ssh.resolveHost(cfg, args.host);
+    if (!entry) return { error: 'host not configured: ' + args.host + '. Define it in .shmakk/hosts.json or ~/.config/shmakk/hosts.json' };
+    return await ssh.sshRun(entry, args.cmd, signal);
+  }
+  if (name === 'ssh_push') {
+    const ssh = _getSSH(roots);
+    if (!ssh) return { error: 'SSH module not available' };
+    const cfg = ssh.loadHostConfig(roots[0]);
+    const entry = ssh.resolveHost(cfg, args.host);
+    if (!entry) return { error: 'host not configured: ' + args.host };
+    const p = within(roots, args.src);
+    if (!p) return { error: 'src path outside workspace' };
+    if (!fs.existsSync(p)) return { error: 'src not found: ' + args.src };
+    return await ssh.sshTransfer(entry, p, args.dest, 'push', signal);
+  }
+  if (name === 'ssh_pull') {
+    const ssh = _getSSH(roots);
+    if (!ssh) return { error: 'SSH module not available' };
+    const cfg = ssh.loadHostConfig(roots[0]);
+    const entry = ssh.resolveHost(cfg, args.host);
+    if (!entry) return { error: 'host not configured: ' + args.host };
+    const p = within(roots, args.dest);
+    if (!p) return { error: 'dest path outside workspace' };
+    return await ssh.sshTransfer(entry, args.src, p, 'pull', signal);
+  }
   return { error: `unknown tool: ${name}` };
 }