wisp-agents 0.15.0 → 0.17.0

package/server/machines/bootstrap.js

@@ -0,0 +1,56 @@
+// The script that starts wisp on a machine over `ssh … sh -s` and reports each step back.
+
+import { shq } from '../util.js';
+
+// What runs on the machine. Sent on stdin, so the login shell there (bash, zsh, fish…) only ever
+// sees `sh -s`. Steps come back as `@@wisp step <id> <run|done> <detail>`, `@@wisp fail <id>
+// <message>`, and finally `@@wisp ready <version> <pid>`; then `cat` holds the session (and the
+// tunnel) open until this side lets go.
+export function bootstrapScript({ port, command, apiVersion }) {
+  return String.raw`say() { printf '@@wisp %s\n' "$*"; }
+PORT=__PORT__
+API=__API__
+CMD=__CMD__
+cd "$HOME" 2>/dev/null # npx would resolve wisp-agents from a package.json in the current folder
+say step ssh done "$(uname -sn 2>/dev/null)"
+# A non-interactive SSH shell skips the profile that puts node (Homebrew, nvm, Volta…) on PATH.
+SH=$SHELL; [ -n "$SH" ] || SH=/bin/sh
+LP=$("$SH" -lc 'printf "%s" "$PATH"' </dev/null 2>/dev/null) && [ -n "$LP" ] && PATH="$LP:$PATH"
+NVM_BIN=
+for d in "$HOME"/.nvm/versions/node/*/bin; do [ -x "$d/node" ] && NVM_BIN=$d; done
+[ -n "$NVM_BIN" ] && PATH="$NVM_BIN:$PATH"
+PATH="$PATH:$HOME/.local/bin:$HOME/.volta/bin:$HOME/.npm-global/bin:/opt/homebrew/bin:/usr/local/bin"
+export PATH
+if ! command -v node >/dev/null 2>&1; then say fail node "Node.js isn't installed there (or isn't on PATH)."; exit 0; fi
+NV=$(node -v 2>/dev/null)
+if ! node -e 'process.exit(+process.versions.node.split(".")[0] >= 20 ? 0 : 1)' 2>/dev/null; then say fail node "Node $NV is too old: wisp needs 20 or newer."; exit 0; fi
+say step node done "$NV"
+health() { node -e 'fetch("http://127.0.0.1:" + process.argv[1] + "/api/health", { signal: AbortSignal.timeout(2500) }).then((r) => r.json().catch(() => ({ name: "other" }))).then((j) => console.log([j.name, j.version, j.apiVersion, j.pid].join(" ")), () => process.exit(1))' "$PORT" 2>/dev/null; }
+H=$(health)
+if [ -n "$H" ]; then
+  set -- $H
+  if [ "$1" != wisp ]; then say fail wisp "Port $PORT is used by another program there. Pick another port under Advanced."; exit 0; fi
+  if [ "$3" != "$API" ]; then say stale "$4"; say fail wisp "wisp $2 is already running there and speaks an older API. Restart it to update."; exit 0; fi
+  say step wisp done "already running · $2"
+else
+  LOG=$WISP_HOME; [ -n "$LOG" ] || LOG=$HOME/.wisp
+  mkdir -p "$LOG"; LOG=$LOG/machine.log
+  say step wisp run "starting $CMD"
+  npm_config_omit=optional nohup sh -c "exec $CMD --no-open --port $PORT" >"$LOG" 2>&1 </dev/null &
+  PID=$!
+  i=0
+  until H=$(health) && [ -n "$H" ]; do
+    if ! kill -0 "$PID" 2>/dev/null; then say fail wisp "wisp stopped while starting: $(tail -n 4 "$LOG" | tr '\n' ' ')"; exit 0; fi
+    i=$((i+1)); if [ "$i" -ge 330 ]; then say fail wisp "wisp didn't answer within 5 minutes: $(tail -n 4 "$LOG" | tr '\n' ' ')"; exit 0; fi
+    sleep 1
+  done
+  set -- $H
+  say step wisp done "started · $2"
+fi
+say ready "$2" "$4"
+exec cat >/dev/null
+`
+    .replace('__PORT__', String(port))
+    .replace('__API__', String(apiVersion))
+    .replace('__CMD__', shq(command));
+}

package/server/machines/hosts.js

@@ -0,0 +1,127 @@
+// Hosts this computer already knows how to reach (~/.ssh/config, known_hosts, Tailscale), and
+// what a failed `ssh` most likely needs. Pure reads: nothing here connects anywhere.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from '../proc.js';
+
+// user@host, host, host:port-less alias, [v6]. Never an option: `-oProxyCommand=…` would run code.
+export const TARGET = /^(?!-)[\w.%+-]+(@[\w.%:[\]-]+)?$/;
+
+// What a failed `ssh` most likely needs, from its stderr.
+export function sshHint(stderr, target) {
+  const e = String(stderr || '');
+  if (/Permission denied|Too many authentication failures|publickey/i.test(e))
+    return { text: 'SSH asked for a password or a key wisp can’t use. wisp signs in with keys only: copy yours over once, or load it into ssh-agent.', command: `ssh-copy-id ${target}` };
+  if (/Host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED/i.test(e)) return { text: 'The machine’s host key changed since you last connected. Check it in a terminal before trusting it again.', command: `ssh ${target}` };
+  if (/Could not resolve hostname|Name or service not known|nodename nor servname/i.test(e)) return { text: 'That name doesn’t resolve. Use user@host, an IP address, or a Host from ~/.ssh/config.' };
+  if (/Connection refused/i.test(e)) return { text: 'Nothing accepts SSH there. Turn on its SSH server (Remote Login on macOS, sshd on Linux).' };
+  if (/timed out|No route to host|Network is unreachable|Connection closed|Broken pipe/i.test(e)) return { text: 'Can’t reach that machine right now. Check the network or VPN.' };
+  if (/Address already in use|forwarding failed/i.test(e)) return { text: 'The local end of the tunnel was taken. Connect again to pick another port.' };
+  return null;
+}
+
+// Hosts from ~/.ssh/config (and the files it Includes), for the "SSH host" suggestions.
+export function sshHosts(file = path.join(os.homedir(), '.ssh', 'config'), seen = new Set()) {
+  if (seen.has(file) || seen.size > 20) return [];
+  seen.add(file);
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return [];
+  }
+  const hosts = [];
+  let current = []; // one Host line may name several hosts; what follows applies to each
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    const [key, ...rest] = line.split(/\s+/);
+    const value = rest.join(' ');
+    if (/^include$/i.test(key)) {
+      for (const pat of value.split(/\s+/)) {
+        const abs = path.resolve(path.join(os.homedir(), '.ssh'), pat.replace(/^~(?=\/)/, os.homedir()));
+        const dir = path.dirname(abs);
+        const re = new RegExp(`^${path.basename(abs).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`);
+        let names = [];
+        try {
+          names = fs.readdirSync(dir).filter((n) => re.test(n));
+        } catch {}
+        for (const n of names) hosts.push(...sshHosts(path.join(dir, n), seen));
+      }
+    } else if (/^host$/i.test(key)) {
+      current = value
+        .split(/\s+/)
+        .filter((h) => h && !/[*?!]/.test(h))
+        .map((host) => ({ host, hostname: '', user: '' }));
+      hosts.push(...current);
+    } else if (/^hostname$/i.test(key)) for (const h of current) h.hostname = value;
+    else if (/^user$/i.test(key)) for (const h of current) h.user = value;
+  }
+  const uniq = new Map(hosts.map((h) => [h.host, h]));
+  return [...uniq.values()];
+}
+
+// Code hosts you push to, not computers to run agents on.
+const FORGE = /(^|\.)(github\.com|gitlab\.com|bitbucket\.org|ssh\.dev\.azure\.com|vs-ssh\.visualstudio\.com|heroku\.com|codeberg\.org|sr\.ht)$/i;
+
+// Hosts you've already SSHed to, from ~/.ssh/known_hosts. Hashed entries and ones on a
+// non-default port ([host]:2222, which a bare target can't express) are skipped.
+export function knownHosts(file = path.join(os.homedir(), '.ssh', 'known_hosts')) {
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return [];
+  }
+  const out = new Map();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || line.startsWith('@') || line.startsWith('|')) continue;
+    const names = line.split(/\s+/)[0].split(',').filter((n) => n && !n.startsWith('[') && !/[*?!]/.test(n));
+    // "devbox,10.0.0.5": the name, with the address as a detail.
+    const host = names.find((n) => !/^[\d.]+$|:/.test(n)) || names[0];
+    if (!host || FORGE.test(host) || /^(localhost|127\.|::1$)/.test(host) || !TARGET.test(host)) continue;
+    if (!out.has(host)) out.set(host, { host, hostname: names.find((n) => n !== host) || '' });
+  }
+  return [...out.values()];
+}
+
+const TAILSCALE_BINS = ['tailscale', '/Applications/Tailscale.app/Contents/MacOS/Tailscale'];
+
+// Peers on your tailnet, from `tailscale status --json`. Phones and tablets don't run agents.
+export function tailscalePeers({ bin = process.env.WISP_TAILSCALE, timeout = 3_000 } = {}) {
+  const bins = bin ? [bin] : TAILSCALE_BINS;
+  const run = (i) =>
+    new Promise((resolve) => {
+      if (i >= bins.length) return resolve([]);
+      execFile(bins[i], ['status', '--json'], { timeout, maxBuffer: 8 << 20 }, (err, stdout) => {
+        if (err) return resolve(err.code === 'ENOENT' ? run(i + 1) : []);
+        try {
+          const peers = Object.values(JSON.parse(stdout).Peer || {});
+          resolve(
+            peers
+              .filter((p) => !/^(ios|android|tvos)$/i.test(p.OS || ''))
+              .map((p) => ({ host: (p.DNSName || '').replace(/\.$/, '') || p.TailscaleIPs?.[0] || '', name: p.HostName || '', os: p.OS || '', online: !!p.Online }))
+              .filter((p) => p.host && TARGET.test(p.host)),
+          );
+        } catch {
+          resolve([]);
+        }
+      });
+    });
+  return run(0);
+}
+
+// Every host this computer already knows how to reach, for "Found on this computer" in Machines.
+// One entry per target: ~/.ssh/config first (your own names), then the tailnet, then known_hosts.
+export async function discoverHosts({ sshDir = path.join(os.homedir(), '.ssh'), tailscale } = {}) {
+  const out = new Map();
+  const put = (x) => {
+    if (x.target && !out.has(x.target)) out.set(x.target, x);
+  };
+  for (const h of sshHosts(path.join(sshDir, 'config'))) put({ target: h.host, name: h.host, source: 'ssh-config', detail: [h.user, h.hostname].filter(Boolean).join('@') });
+  for (const p of await tailscalePeers(tailscale)) put({ target: p.host, name: p.name || p.host.split('.')[0], source: 'tailscale', detail: [p.os, p.online ? 'online' : 'offline'].filter(Boolean).join(' · '), online: p.online });
+  for (const h of knownHosts(path.join(sshDir, 'known_hosts'))) put({ target: h.host, name: /^[\d.]+$/.test(h.host) ? h.host : h.host.split('.')[0], source: 'known-hosts', detail: h.hostname });
+  return [...out.values()].sort((a, b) => (b.online === false ? 0 : 1) - (a.online === false ? 0 : 1));
+}

package/server/machines.js

@@ -15,14 +15,15 @@ import { EventEmitter } from 'node:events';
 import fs from 'node:fs';
 import http from 'node:http';
 import net from 'node:net';
-import os from 'node:os';
-import path from 'node:path';
 import readline from 'node:readline';
 import { randomBytes } from 'node:crypto';
-import { spawn, execFile, killTree } from './proc.js';
+import { spawn, killTree } from './proc.js';
 import { newer } from './update.js';
+import { bootstrapScript } from './machines/bootstrap.js';
+import { sshHint, sshHosts, knownHosts, tailscalePeers, discoverHosts, TARGET } from './machines/hosts.js';
+import { bad, DEFAULT_PORT, shq } from './util.js';
 
-export const DEFAULT_PORT = 4477;
+export { DEFAULT_PORT };
 const READY_TIMEOUT_MS = 6 * 60_000; // the first `npx` download can take a while
 const RETRY_MS = [2_000, 5_000, 15_000, 30_000, 60_000];
 const LIST_TIMEOUT_MS = 5_000;
@@ -36,8 +37,7 @@ export const STEPS = [
 ];
 
 const sshBin = () => process.env.WISP_SSH || 'ssh';
-export const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
-const bad = (msg, status = 400) => Object.assign(new Error(msg), { status });
+export { shq, bootstrapScript, sshHint, sshHosts, knownHosts, tailscalePeers, discoverHosts };
 
 // Session ids: <remote id>@<machine id> here. Local ids never contain '@'.
 export const qualify = (id, mid) => (id ? `${id}@${mid}` : id);
@@ -50,179 +50,9 @@ export function splitId(id) {
 // custom start command decides what runs there.
 export const updateTo = (local, remote, command) => (!command && remote && newer(local, remote) ? local : null);
 
-// What runs on the machine. Sent on stdin, so the login shell there (bash, zsh, fish…) only ever
-// sees `sh -s`. Steps come back as `@@wisp step <id> <run|done> <detail>`, `@@wisp fail <id>
-// <message>`, and finally `@@wisp ready <version> <pid>`; then `cat` holds the session (and the
-// tunnel) open until this side lets go.
-export function bootstrapScript({ port, command, apiVersion }) {
-  return String.raw`say() { printf '@@wisp %s\n' "$*"; }
-PORT=__PORT__
-API=__API__
-CMD=__CMD__
-cd "$HOME" 2>/dev/null # npx would resolve wisp-agents from a package.json in the current folder
-say step ssh done "$(uname -sn 2>/dev/null)"
-# A non-interactive SSH shell skips the profile that puts node (Homebrew, nvm, Volta…) on PATH.
-SH=$SHELL; [ -n "$SH" ] || SH=/bin/sh
-LP=$("$SH" -lc 'printf "%s" "$PATH"' </dev/null 2>/dev/null) && [ -n "$LP" ] && PATH="$LP:$PATH"
-NVM_BIN=
-for d in "$HOME"/.nvm/versions/node/*/bin; do [ -x "$d/node" ] && NVM_BIN=$d; done
-[ -n "$NVM_BIN" ] && PATH="$NVM_BIN:$PATH"
-PATH="$PATH:$HOME/.local/bin:$HOME/.volta/bin:$HOME/.npm-global/bin:/opt/homebrew/bin:/usr/local/bin"
-export PATH
-if ! command -v node >/dev/null 2>&1; then say fail node "Node.js isn't installed there (or isn't on PATH)."; exit 0; fi
-NV=$(node -v 2>/dev/null)
-if ! node -e 'process.exit(+process.versions.node.split(".")[0] >= 20 ? 0 : 1)' 2>/dev/null; then say fail node "Node $NV is too old: wisp needs 20 or newer."; exit 0; fi
-say step node done "$NV"
-health() { node -e 'fetch("http://127.0.0.1:" + process.argv[1] + "/api/health", { signal: AbortSignal.timeout(2500) }).then((r) => r.json().catch(() => ({ name: "other" }))).then((j) => console.log([j.name, j.version, j.apiVersion, j.pid].join(" ")), () => process.exit(1))' "$PORT" 2>/dev/null; }
-H=$(health)
-if [ -n "$H" ]; then
-  set -- $H
-  if [ "$1" != wisp ]; then say fail wisp "Port $PORT is used by another program there. Pick another port under Advanced."; exit 0; fi
-  if [ "$3" != "$API" ]; then say stale "$4"; say fail wisp "wisp $2 is already running there and speaks an older API. Restart it to update."; exit 0; fi
-  say step wisp done "already running · $2"
-else
-  LOG=$WISP_HOME; [ -n "$LOG" ] || LOG=$HOME/.wisp
-  mkdir -p "$LOG"; LOG=$LOG/machine.log
-  say step wisp run "starting $CMD"
-  npm_config_omit=optional nohup sh -c "exec $CMD --no-open --port $PORT" >"$LOG" 2>&1 </dev/null &
-  PID=$!
-  i=0
-  until H=$(health) && [ -n "$H" ]; do
-    if ! kill -0 "$PID" 2>/dev/null; then say fail wisp "wisp stopped while starting: $(tail -n 4 "$LOG" | tr '\n' ' ')"; exit 0; fi
-    i=$((i+1)); if [ "$i" -ge 330 ]; then say fail wisp "wisp didn't answer within 5 minutes: $(tail -n 4 "$LOG" | tr '\n' ' ')"; exit 0; fi
-    sleep 1
-  done
-  set -- $H
-  say step wisp done "started · $2"
-fi
-say ready "$2" "$4"
-exec cat >/dev/null
-`
-    .replace('__PORT__', String(port))
-    .replace('__API__', String(apiVersion))
-    .replace('__CMD__', shq(command));
-}
-
-// What a failed `ssh` most likely needs, from its stderr.
-export function sshHint(stderr, target) {
-  const e = String(stderr || '');
-  if (/Permission denied|Too many authentication failures|publickey/i.test(e))
-    return { text: 'SSH asked for a password or a key wisp can’t use. wisp signs in with keys only: copy yours over once, or load it into ssh-agent.', command: `ssh-copy-id ${target}` };
-  if (/Host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED/i.test(e)) return { text: 'The machine’s host key changed since you last connected. Check it in a terminal before trusting it again.', command: `ssh ${target}` };
-  if (/Could not resolve hostname|Name or service not known|nodename nor servname/i.test(e)) return { text: 'That name doesn’t resolve. Use user@host, an IP address, or a Host from ~/.ssh/config.' };
-  if (/Connection refused/i.test(e)) return { text: 'Nothing accepts SSH there. Turn on its SSH server (Remote Login on macOS, sshd on Linux).' };
-  if (/timed out|No route to host|Network is unreachable|Connection closed|Broken pipe/i.test(e)) return { text: 'Can’t reach that machine right now. Check the network or VPN.' };
-  if (/Address already in use|forwarding failed/i.test(e)) return { text: 'The local end of the tunnel was taken. Connect again to pick another port.' };
-  return null;
-}
-
-// Hosts from ~/.ssh/config (and the files it Includes), for the "SSH host" suggestions.
-export function sshHosts(file = path.join(os.homedir(), '.ssh', 'config'), seen = new Set()) {
-  if (seen.has(file) || seen.size > 20) return [];
-  seen.add(file);
-  let text = '';
-  try {
-    text = fs.readFileSync(file, 'utf8');
-  } catch {
-    return [];
-  }
-  const hosts = [];
-  let current = []; // one Host line may name several hosts; what follows applies to each
-  for (const raw of text.split(/\r?\n/)) {
-    const line = raw.trim();
-    const [key, ...rest] = line.split(/\s+/);
-    const value = rest.join(' ');
-    if (/^include$/i.test(key)) {
-      for (const pat of value.split(/\s+/)) {
-        const abs = path.resolve(path.join(os.homedir(), '.ssh'), pat.replace(/^~(?=\/)/, os.homedir()));
-        const dir = path.dirname(abs);
-        const re = new RegExp(`^${path.basename(abs).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`);
-        let names = [];
-        try {
-          names = fs.readdirSync(dir).filter((n) => re.test(n));
-        } catch {}
-        for (const n of names) hosts.push(...sshHosts(path.join(dir, n), seen));
-      }
-    } else if (/^host$/i.test(key)) {
-      current = value
-        .split(/\s+/)
-        .filter((h) => h && !/[*?!]/.test(h))
-        .map((host) => ({ host, hostname: '', user: '' }));
-      hosts.push(...current);
-    } else if (/^hostname$/i.test(key)) for (const h of current) h.hostname = value;
-    else if (/^user$/i.test(key)) for (const h of current) h.user = value;
-  }
-  const uniq = new Map(hosts.map((h) => [h.host, h]));
-  return [...uniq.values()];
-}
-
 // What the UI needs of a machine's harness list.
 const remoteAgent = ({ id, name, available, version, models, efforts, delegates }) => ({ id, name, available, version, models, efforts, delegates });
 
-// Code hosts you push to, not computers to run agents on.
-const FORGE = /(^|\.)(github\.com|gitlab\.com|bitbucket\.org|ssh\.dev\.azure\.com|vs-ssh\.visualstudio\.com|heroku\.com|codeberg\.org|sr\.ht)$/i;
-
-// Hosts you've already SSHed to, from ~/.ssh/known_hosts. Hashed entries and ones on a
-// non-default port ([host]:2222, which a bare target can't express) are skipped.
-export function knownHosts(file = path.join(os.homedir(), '.ssh', 'known_hosts')) {
-  let text = '';
-  try {
-    text = fs.readFileSync(file, 'utf8');
-  } catch {
-    return [];
-  }
-  const out = new Map();
-  for (const raw of text.split(/\r?\n/)) {
-    const line = raw.trim();
-    if (!line || line.startsWith('#') || line.startsWith('@') || line.startsWith('|')) continue;
-    const names = line.split(/\s+/)[0].split(',').filter((n) => n && !n.startsWith('[') && !/[*?!]/.test(n));
-    // "devbox,10.0.0.5": the name, with the address as a detail.
-    const host = names.find((n) => !/^[\d.]+$|:/.test(n)) || names[0];
-    if (!host || FORGE.test(host) || /^(localhost|127\.|::1$)/.test(host) || !TARGET.test(host)) continue;
-    if (!out.has(host)) out.set(host, { host, hostname: names.find((n) => n !== host) || '' });
-  }
-  return [...out.values()];
-}
-
-const TAILSCALE_BINS = ['tailscale', '/Applications/Tailscale.app/Contents/MacOS/Tailscale'];
-
-// Peers on your tailnet, from `tailscale status --json`. Phones and tablets don't run agents.
-export function tailscalePeers({ bin = process.env.WISP_TAILSCALE, timeout = 3_000 } = {}) {
-  const bins = bin ? [bin] : TAILSCALE_BINS;
-  const run = (i) =>
-    new Promise((resolve) => {
-      if (i >= bins.length) return resolve([]);
-      execFile(bins[i], ['status', '--json'], { timeout, maxBuffer: 8 << 20 }, (err, stdout) => {
-        if (err) return resolve(err.code === 'ENOENT' ? run(i + 1) : []);
-        try {
-          const peers = Object.values(JSON.parse(stdout).Peer || {});
-          resolve(
-            peers
-              .filter((p) => !/^(ios|android|tvos)$/i.test(p.OS || ''))
-              .map((p) => ({ host: (p.DNSName || '').replace(/\.$/, '') || p.TailscaleIPs?.[0] || '', name: p.HostName || '', os: p.OS || '', online: !!p.Online }))
-              .filter((p) => p.host && TARGET.test(p.host)),
-          );
-        } catch {
-          resolve([]);
-        }
-      });
-    });
-  return run(0);
-}
-
-// Every host this computer already knows how to reach, for "Found on this computer" in Machines.
-// One entry per target: ~/.ssh/config first (your own names), then the tailnet, then known_hosts.
-export async function discoverHosts({ sshDir = path.join(os.homedir(), '.ssh'), tailscale } = {}) {
-  const out = new Map();
-  const put = (x) => {
-    if (x.target && !out.has(x.target)) out.set(x.target, x);
-  };
-  for (const h of sshHosts(path.join(sshDir, 'config'))) put({ target: h.host, name: h.host, source: 'ssh-config', detail: [h.user, h.hostname].filter(Boolean).join('@') });
-  for (const p of await tailscalePeers(tailscale)) put({ target: p.host, name: p.name || p.host.split('.')[0], source: 'tailscale', detail: [p.os, p.online ? 'online' : 'offline'].filter(Boolean).join(' · '), online: p.online });
-  for (const h of knownHosts(path.join(sshDir, 'known_hosts'))) put({ target: h.host, name: /^[\d.]+$/.test(h.host) ? h.host : h.host.split('.')[0], source: 'known-hosts', detail: h.hostname });
-  return [...out.values()].sort((a, b) => (b.online === false ? 0 : 1) - (a.online === false ? 0 : 1));
-}
-
 const freePort = () =>
   new Promise((resolve, reject) => {
     const s = net.createServer().once('error', reject);
@@ -240,8 +70,6 @@ const readAll = (res) =>
     res.on('error', reject);
   });
 
-// user@host, host, host:port-less alias, [v6]. Never an option: `-oProxyCommand=…` would run code.
-const TARGET = /^(?!-)[\w.%+-]+(@[\w.%:[\]-]+)?$/;
 
 export class Machines extends EventEmitter {
   // onEvent(event, data): a session event from a machine, ids already rewritten.
@@ -572,7 +400,7 @@ export class Machines extends EventEmitter {
   #request(m, c, method, p, { body, headers = {}, timeout = 120_000 } = {}) {
     return new Promise((resolve, reject) => {
       const req = http.request({ host: '127.0.0.1', port: c.localPort, path: `/api${p}`, method, headers: { ...headers, host: `127.0.0.1:${m.port}` }, timeout }, resolve);
-      req.on('timeout', () => req.destroy(Object.assign(new Error(`${m.name} didn’t answer in time.`), { status: 504 })));
+      req.on('timeout', () => req.destroy(bad(`${m.name} didn’t answer in time.`, 504)));
       req.on('error', (err) => reject(Object.assign(err, { status: err.status || 502 })));
       if (body && typeof body.pipe === 'function') body.pipe(req);
       else req.end(body);

package/server/mcp-ask.js

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
-// Minimal stdio MCP server exposing `ask_user`, injected into every agent wisp launches.
+// Minimal stdio MCP server exposing `ask_user`, `wisp_stats`, `wisp_sessions` and `wisp_session`, injected into every agent wisp launches.
 // The call is relayed to the wisp server, which surfaces it in the queue and blocks
 // (by polling) until the user answers — so the agent keeps its full context.
 // With a team (WISP_TEAM), it also offers `delegate` and `subagent_results`: tasks for the
 // subagents the user picked, which wisp runs as child sessions while this call waits.
+// With WISP_APPROVE, it offers `approve`: the harness's permission prompt (Claude's
+// --permission-prompt-tool), answered by the user in wisp.
+// `wisp_stats` is read-only: tool counts, spend and success rate across the user's wisp sessions.
+// `wisp_sessions` and `wisp_session` are read-only too: list the user's other tasks and read one's
+// reports, e.g. a task the user mentioned in the prompt.
 
 import readline from 'node:readline';
 
-const { WISP_URL, WISP_TOKEN, WISP_SESSION } = process.env;
+const { WISP_URL, WISP_TOKEN, WISP_SESSION, WISP_APPROVE } = process.env;
 let TEAM = [];
 try {
   TEAM = JSON.parse(process.env.WISP_TEAM || '[]');
@@ -30,6 +35,83 @@ const TOOL = {
   },
 };
 
+// Claude's permission-prompt contract: { tool_name, input, tool_use_id } in, a JSON
+// { behavior: 'allow', updatedInput } or { behavior: 'deny', message } back as text.
+const APPROVE = {
+  name: 'approve',
+  description: 'Internal: wisp asks the user to approve a tool call your permissions do not allow on their own. Never call this yourself.',
+  inputSchema: {
+    type: 'object',
+    properties: { tool_name: { type: 'string' }, input: { type: 'object' }, tool_use_id: { type: 'string' } },
+    required: ['tool_name'],
+  },
+};
+
+const STATS = {
+  name: 'wisp_stats',
+  description:
+    'Read-only stats about the user\'s past wisp tasks: how many tool calls each kind of action made (run = shell, read, edit, ' +
+    'search, web, agent, tool = other MCP tools, ask), broken down by harness, project and day, plus turns, cost, tokens and ' +
+    'success rate. Use when the user asks about their wisp usage, which tools or harnesses their tasks use, or what tasks cost.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      days: { type: 'number', description: 'How many days back, 1–365. Default 30.' },
+      agent: { type: 'string', description: 'Only this harness, e.g. claude, codex, opencode.' },
+      project: { type: 'string', description: 'Only this project (name or id); "current" = the project of this task.' },
+    },
+  },
+};
+
+const SESSIONS = {
+  name: 'wisp_sessions',
+  description:
+    'List the user\'s other wisp tasks, newest first: id, title, state (running | waiting | review | done), harness, project, ' +
+    'last update and a one-line summary. Read-only. Use it to find a task the user refers to; read one with wisp_session.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Only tasks whose title or summary has all these words.' },
+      state: { type: 'string', description: 'Comma-separated, e.g. "running,waiting".' },
+      project: { type: 'string', description: 'Only this project (name or id); "current" = the project of this task.' },
+      archived: { type: 'boolean', description: 'Include archived tasks. Default false.' },
+      limit: { type: 'number', description: 'Default 20, at most 100.' },
+    },
+  },
+};
+
+const SESSION = {
+  name: 'wisp_session',
+  description:
+    'Read another wisp task by id: its title, state, harness, folder and branch, every request the user made in it, and a ' +
+    'turn\'s report as markdown (summary, diffs, tests, next steps). Read-only. Use it when the prompt mentions a wisp task ' +
+    '("@Title (wisp task <id>)") or the user asks what another task did.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      id: { type: 'string', description: 'The task id.' },
+      turn: { type: 'number', description: 'Which turn\'s report, 1 = first. Default: the latest.' },
+    },
+    required: ['id'],
+  },
+};
+
+async function sessions(args = {}) {
+  const q = new URLSearchParams(Object.entries(args).filter(([, v]) => v !== undefined && v !== '').map(([k, v]) => [k, String(v)]));
+  return (await call(`/api/internal/sessions/${WISP_SESSION}?${q}`)).text;
+}
+
+async function session({ id, turn } = {}) {
+  if (!id) throw new Error('id is required');
+  const q = new URLSearchParams({ of: String(id), ...(turn !== undefined && { turn: String(turn) }) });
+  return (await call(`/api/internal/session/${WISP_SESSION}?${q}`)).text;
+}
+
+async function stats({ days, agent, project } = {}) {
+  const q = new URLSearchParams(Object.entries({ days, agent, project }).filter(([, v]) => v !== undefined && v !== ''));
+  return (await call(`/api/internal/stats/${WISP_SESSION}?${q}`)).text;
+}
+
 const roster = TEAM.map((m) => `- ${m.name}${m.count > 1 ? ` ×${m.count} (parallel copies ${m.copies.join(', ')})` : ''}: ${[m.agent, m.model || 'default model', m.effort && `${m.effort} thinking`].filter(Boolean).join(' · ')}${m.use ? ` — use for: ${m.use}` : ''}`).join('\n');
 const TEAM_TOOLS = [
   {
@@ -104,8 +186,8 @@ async function call(path, body) {
   return res.json();
 }
 
-async function askUser(args) {
-  const { id } = await call(`/api/internal/ask`, { session: WISP_SESSION, ...args });
+// Poll a question until it's answered ({ answer, … }) or cancelled (null).
+async function waitFor(id) {
   for (;;) {
     await sleep(1500);
     let r;
@@ -114,11 +196,24 @@ async function askUser(args) {
     } catch {
       continue; // wisp restarting — keep waiting
     }
-    if (r.answer !== undefined) return r.answer;
+    if (r.answer !== undefined) return r;
     if (r.cancelled) return null;
   }
 }
 
+async function askUser(args) {
+  const { id } = await call(`/api/internal/ask`, { session: WISP_SESSION, ...args });
+  return (await waitFor(id))?.answer ?? null;
+}
+
+async function approve({ tool_name: tool, input = {} }) {
+  let r = await call(`/api/internal/approve`, { session: WISP_SESSION, tool, input });
+  if (r.id) r = await waitFor(r.id);
+  if (r?.decision === 'allow') return { behavior: 'allow', updatedInput: input };
+  if (!r) return { behavior: 'deny', message: 'The user did not answer (the request was cancelled). Do not retry it; carry on without it and say what was skipped.' };
+  return { behavior: 'deny', message: r.message ? `The user denied this and said: ${r.message}` : 'The user denied this. Do not retry it; carry on without it or ask how to proceed.' };
+}
+
 readline.createInterface({ input: process.stdin }).on('line', async (line) => {
   let msg;
   try {
@@ -133,11 +228,19 @@ readline.createInterface({ input: process.stdin }).on('line', async (line) => {
     if (method === 'initialize') {
       send({ id, result: { protocolVersion: params?.protocolVersion || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'wisp', version: '0.1.0' } } });
     } else if (method === 'tools/list') {
-      send({ id, result: { tools: TEAM.length ? [TOOL, ...TEAM_TOOLS] : [TOOL] } });
+      send({ id, result: { tools: [TOOL, STATS, SESSIONS, SESSION, ...(WISP_APPROVE ? [APPROVE] : []), ...(TEAM.length ? TEAM_TOOLS : [])] } });
     } else if (method === 'tools/call' && params?.name === 'ask_user') {
       const answer = await askUser(params.arguments || {});
       const text = answer === null ? 'The user did not answer (the question was cancelled). Use your best judgment and note the assumption.' : `The user answered: ${answer}`;
       send({ id, result: { content: [{ type: 'text', text }] } });
+    } else if (method === 'tools/call' && WISP_APPROVE && params?.name === 'approve') {
+      send({ id, result: { content: [{ type: 'text', text: JSON.stringify(await approve(params.arguments || {})) }] } });
+    } else if (method === 'tools/call' && params?.name === 'wisp_stats') {
+      send({ id, result: { content: [{ type: 'text', text: await stats(params.arguments || {}) }] } });
+    } else if (method === 'tools/call' && params?.name === 'wisp_sessions') {
+      send({ id, result: { content: [{ type: 'text', text: await sessions(params.arguments || {}) }] } });
+    } else if (method === 'tools/call' && params?.name === 'wisp_session') {
+      send({ id, result: { content: [{ type: 'text', text: await session(params.arguments || {}) }] } });
     } else if (method === 'tools/call' && TEAM.length && params?.name === 'delegate') {
       send({ id, result: { content: [{ type: 'text', text: await delegate(params.arguments || {}) }] } });
     } else if (method === 'tools/call' && TEAM.length && params?.name === 'subagent_results') {
@@ -149,7 +252,9 @@ readline.createInterface({ input: process.stdin }).on('line', async (line) => {
       send({ id, error: { code: -32601, message: `Method not found: ${method}` } });
     }
   } catch (err) {
-    const what = params?.name === 'ask_user' ? 'wisp could not reach the user' : 'wisp';
-    send({ id, result: { isError: true, content: [{ type: 'text', text: `${what}: ${err.message}` }] } });
+    const what = params?.name === 'ask_user' || params?.name === 'approve' ? 'wisp could not reach the user' : 'wisp';
+    // A permission prompt that errors would leave the harness guessing: deny, and say why.
+    if (params?.name === 'approve') send({ id, result: { content: [{ type: 'text', text: JSON.stringify({ behavior: 'deny', message: `${what}: ${err.message}` }) }] } });
+    else send({ id, result: { isError: true, content: [{ type: 'text', text: `${what}: ${err.message}` }] } });
   }
 });

package/server/mcp-wisp.js

@@ -5,10 +5,9 @@
 //   claude mcp add wisp -- npx -y wisp-agents mcp
 
 import readline from 'node:readline';
-import fs from 'node:fs';
 import { WispClient } from './client.js';
+import { VERSION } from './util.js';
 
-const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const AGENTS = ['auto', 'claude', 'codex', 'opencode', 'cursor', 'antigravity', 'grok'];
 const DEFAULT_WAIT_S = 240; // stay under typical MCP client tool-call timeouts; call wisp_wait again for more
 
@@ -66,8 +65,21 @@ const TOOLS = [
     name: 'wisp_reply',
     description:
       'Send a follow-up to a session; it resumes the same agent conversation. If the agent is waiting on a question, this answers it. ' +
-      'A follow-up sent while it runs interrupts it (queue=true waits for the run to finish instead). mode switches the session’s mode from this follow-up on.',
-    inputSchema: { type: 'object', properties: { id: { type: 'string' }, text: { type: 'string' }, queue: { type: 'boolean' }, mode: { type: 'string', enum: ['plan', 'edits', 'auto'] } }, required: ['id', 'text'] },
+      'A follow-up sent while it runs interrupts it (queue=true waits for the run to finish instead). mode switches the session’s mode from this follow-up on. ' +
+      'agent / model / effort switch the harness, model or thinking level from this follow-up on (see wisp_agents); a new harness is handed the conversation so far.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        text: { type: 'string' },
+        queue: { type: 'boolean' },
+        mode: { type: 'string', enum: ['plan', 'edits', 'auto'] },
+        agent: { type: 'string', description: 'Harness id, e.g. claude, codex, opencode' },
+        model: { type: 'string', description: 'Model id for that harness; empty for its default' },
+        effort: { type: 'string', description: 'Thinking level; empty for the default' },
+      },
+      required: ['id', 'text'],
+    },
   },
   {
     name: 'wisp_stop',
@@ -118,7 +130,7 @@ async function callTool(name, a = {}) {
       return waitFor(a.id);
     case 'wisp_reply': {
       if (!a.text?.trim()) throw new Error('text is required');
-      const r = await c.reply(a.id, a.text.trim(), { queue: a.queue, mode: a.mode });
+      const r = await c.reply(a.id, a.text.trim(), { queue: a.queue, mode: a.mode, agent: a.agent, model: a.model, effort: a.effort });
       return r.answered ? 'Answered the agent’s question; it is continuing.' : r.interrupted ? 'Interrupted the run; it resumes with your message.' : r.queued ? 'Queued; it goes out when the current run finishes.' : 'Sent; the agent is working on it.';
     }
     case 'wisp_stop':