moshcode 0.90.0 → 0.91.0

package/prd/README.md

@@ -27,4 +27,6 @@ Start one with `moshcode prd "<idea>"` (TUI: `/prd`).
 | [0009](0009-persistent-agent-runtime.md) | Keep the herd alive — a persistent runtime, semantic agent state, and one control surface for humans and agents | Accepted |
 | [0010](0010-cloud-settings-sync.md) | Sync the pit's settings to your moshcode.sh account | Draft |
 | [0011](0011-herd-agent-protocol.md) | Teach the herd the agent protocol — hooks-first state, a task ledger, and an A2A surface for local and remote agents | Draft |
+| [0012](0012-billing-baked-into-the-agent-cli.md) | Bake billing into the agent CLI — timer, clients, teams, rates, invoices, rails | Draft |
+| [0013](0013-persistent-ssh-workspaces.md) | Add persistent SSH workspaces for humans and agents | Draft |
 <!-- PRD-INDEX:END -->

package/src/cli-schema.mjs

@@ -207,6 +207,36 @@ export const CORE_CLI_COMMANDS = [
     seeAlso: ["herd", "ps"],
     note: "this brings back the shape — sessions, directories, engines. the processes are new; work that was in flight is not still running.",
   },
+  {
+    name: "ssh",
+    group: "runtime",
+    description: "persistent SSH workspaces — one connection, many clean commands",
+    synopsis: [
+      ["moshcode ssh", "targets, and whether each one is connected"],
+      ["moshcode ssh <name>", "an interactive shell over the shared connection"],
+      ["moshcode ssh exec <name> [flags] -- <command…>", "one command over it: stdout, stderr and exit status kept apart"],
+      ["moshcode ssh <verb> [args…]", "add, open, check, close, put, get, shell, bench"],
+    ],
+    verbs: "SSH_VERBS",
+    flags: [
+      ["--json", "machine-readable, on every verb that does not take the terminal", ""],
+      ["--persist <dur>", "how long the connection outlives its last client", "10m"],
+    ],
+    examples: [
+      ["moshcode ssh add dev deploy@example.com --cwd /srv/app", "a name for a box (or an alias from ~/.ssh/config)"],
+      ["moshcode ssh open dev", "authenticate once"],
+      ["moshcode ssh exec dev -- git status --short", "…then every command reuses it"],
+      ["moshcode ssh exec dev --json -- pnpm test", "exit code, stdout and stderr as one object"],
+      ["git diff | moshcode ssh exec dev --stdin -- git apply -", "a multi-file patch in one round trip"],
+      ["moshcode ssh dev", "a real shell on the same connection"],
+      ["moshcode ssh shell dev --name app", "a remote tmux shell that survives your laptop sleeping"],
+      ["moshcode ssh close dev", "hang up (or let --persist expire)"],
+    ],
+    seeAlso: ["herd", "shell"],
+    note: "nothing secret is stored: targets.json holds a host, a port and a directory, and OpenSSH keeps using your ~/.ssh, "
+      + "agent, known_hosts and ProxyJump exactly as it does at the prompt. `exec` gives every call a fresh command channel — "
+      + "no shell state carries between calls; `shell` is for the workflows that need it.",
+  },
   {
     name: "install",
     group: "engines",
@@ -1325,6 +1355,82 @@ export const HERD_VERBS = [
 // The business layer's verbs. Flatter than the herd's on purpose: these are
 // commands somebody types between other work, and a verb that needs a paragraph
 // to explain itself is a verb in the wrong place.
+export const SSH_VERBS = [
+  { name: "list", description: "every target, and whether its connection is up",
+    synopsis: [["moshcode ssh [list] [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "add", description: "name a box: user@host, or an alias from ~/.ssh/config",
+    synopsis: [["moshcode ssh add <name> <user@host|alias> [--port N] [--cwd PATH] [--persist 10m]", ""]],
+    flags: [
+      ["--port <n>", "ssh port, when ~/.ssh/config does not say", "22"],
+      ["--cwd <path>", "where exec and the interactive shell start", "the remote login directory"],
+      ["--persist <dur>", "how long the connection outlives its last client", "10m"],
+      ["--json", "machine-readable", ""],
+    ] },
+  { name: "remove", description: "forget a target (and close its connection)",
+    synopsis: [["moshcode ssh remove <name>", ""]] },
+  { name: "show", description: "one target in full, with its socket and state",
+    synopsis: [["moshcode ssh show <name> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "open", description: "authenticate once and keep the connection",
+    synopsis: [["moshcode ssh open <name> [--persist 10m] [--batch] [--json]", ""]],
+    flags: [
+      ["--persist <dur>", "how long it outlives its last client", "10m"],
+      ["--batch", "never prompt — fail instead (the default when stdin is not a terminal)", ""],
+      ["--json", "machine-readable; alreadyOpen says whether it was up", ""],
+    ] },
+  { name: "check", description: "is the connection up? (exit 0 yes, 1 no)",
+    synopsis: [["moshcode ssh check <name> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "close", description: "hang up, with ssh's own -O exit",
+    synopsis: [["moshcode ssh close <name> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "exec", description: "one command over the connection — no PTY, no shared shell state",
+    synopsis: [["moshcode ssh exec <name> [--cwd PATH] [--env K=V…] [--stdin] [--tty] [--timeout 2m] [--sh] [--json] -- <command…>", ""]],
+    flags: [
+      ["--cwd <path>", "run it here, this once", "the target's cwd"],
+      ["--env <K=V>", "an environment variable for this command only (repeatable)", ""],
+      ["--stdin", "forward this process's stdin, raw", ""],
+      ["--tty", "allocate a terminal (sudo, editors, anything that insists)", ""],
+      ["--timeout <dur>", "kill it after this long — exit 124", ""],
+      ["--sh", "the one argument is a shell snippet, pipes and all", ""],
+      ["--batch", "never prompt for auth — fail instead", ""],
+      ["--json", "{ ok, transportOk, code, signal, stdout, stderr, durationMs }", ""],
+    ],
+    examples: [
+      ["moshcode ssh exec dev -- git status --short", ""],
+      ["moshcode ssh exec dev --json -- grep -rn TODO src", "exit 1 is grep's answer, not a transport failure"],
+      ["moshcode ssh exec dev --sh 'git log --oneline | head -5'", "a pipeline, on purpose"],
+    ] },
+  { name: "put", description: "copy a file up over the connection, atomically",
+    synopsis: [["moshcode ssh put <name> <local> <remote> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "get", description: "copy a file down over the connection",
+    synopsis: [["moshcode ssh get <name> <remote> <local> [--json]", ""]],
+    flags: [["--json", "machine-readable", ""]] },
+  { name: "shell", description: "a persistent remote shell in tmux, and the verbs to drive it",
+    synopsis: [
+      ["moshcode ssh shell <name> --name <session>", "create or attach — Ctrl-b d leaves it running"],
+      ["moshcode ssh shell send <name>/<session> <text>", "type a line into it"],
+      ["moshcode ssh shell read <name>/<session> [--lines N]", "its screen, as text"],
+      ["moshcode ssh shell kill <name>/<session>", "end it"],
+      ["moshcode ssh shell list <name>", "every moshcode shell on the box"],
+    ],
+    flags: [
+      ["--name <session>", "which shell", "main"],
+      ["--lines <n>", "how much screen to read", "60"],
+      ["--json", "machine-readable", ""],
+    ],
+    examples: [
+      ["moshcode ssh shell dev --name app", ""],
+      ["moshcode ssh shell send dev/app \"pnpm dev\"", ""],
+      ["moshcode ssh shell read dev/app --lines 40", ""],
+    ] },
+  { name: "bench", description: "measure fresh connections against the shared one, on this host",
+    synopsis: [["moshcode ssh bench <name> [--n 20] [--json]", ""]],
+    flags: [["--n <runs>", "how many of each", "20"], ["--json", "machine-readable", ""]] },
+];
+
 export const TIMER_VERBS = [
   { name: "on", description: "start the clock", synopsis: [["moshcode timer on [client] [--task …] [--agents N|auto]", ""]] },
   { name: "off", description: "stop it and write the entry", synopsis: [["moshcode timer off [--note …]", ""]] },
@@ -1377,6 +1483,7 @@ export const PAYMENT_VERBS = [
 
 export const VERB_TABLES = {
   HERD_VERBS,
+  SSH_VERBS,
   TIMER_VERBS,
   CLIENT_VERBS,
   TEAM_VERBS,
@@ -1428,6 +1535,8 @@ export const PIT_COMMANDS = [
     description: "block until a session is blocked or done" },
   { name: "restore", args: "[--resume]", cli: "restore",
     description: "rebuild the herd's sessions after a reboot" },
+  { name: "ssh", args: "[name|verb] [args…]", cli: "ssh",
+    description: "persistent SSH workspaces — one connection, many clean commands" },
   { name: "tools", args: "[name] [args…]", cli: "tools",
     description: "list workflow tools, or run one" },
   { name: "trade", args: "<verb> [args…]", cli: "trade",

package/src/commands.mjs

@@ -22,6 +22,27 @@ import { capture, killSession, remoteStatus, sendPrompt } from "./herd.mjs";
 import { herdStart, isRemoteMember, roster, waitForMany, waitMember } from "./herd-cli.mjs";
 import { endTask, findTask, readTasks, startTask } from "./herd-tasks.mjs";
 import { shellInvocation } from "./shell.mjs";
+import {
+  checkMaster as sshCheckMaster, closeMaster as sshCloseMaster, exec as sshRun, get as sshGetFile,
+  openMaster as sshOpenMaster, parseSessionRef as sshParseSessionRef, parseTimeout as parseSshTimeout,
+  put as sshPutFile, resolveTarget as sshResolve,
+  shellKill as sshShellKillRemote, shellRead as sshShellReadRemote, shellSend as sshShellSendRemote,
+} from "./ssh.mjs";
+
+/** The registry entry for a named ssh target, or a moshscript error naming the verb. */
+function sshTarget(name, verb) {
+  if (!name) throw new Error(`moshscript: ${verb}(name) requires a target name`);
+  const found = sshResolve(String(name));
+  if (found.error) throw new Error(`moshscript: ${verb}: ${found.error.replace(/^ssh: /, "")}`);
+  return found.entry;
+}
+
+/** `dev/app` → the target entry and the session name, or a moshscript error. */
+function sshShellRef(ref, verb) {
+  const parsed = sshParseSessionRef(ref);
+  if (parsed.error) throw new Error(`moshscript: ${verb}: ${parsed.error.replace(/^ssh: /, "")}`);
+  return { found: sshTarget(parsed.name, verb), session: parsed.session };
+}
 import { captureSpec } from "./pty.mjs";
 import { identity, loginAuto, logout as forgetCreds } from "./auth.mjs";
 import { expandAlias, getAlias, loadAliases, removeAlias, setAlias } from "./aliases.mjs";
@@ -654,6 +675,148 @@ const COMMANDS = [
     },
   },
 
+  // SSH workspaces (PRD 0013 R49–R52). Value-returning for the herd's reason:
+  // a script that runs a command on a remote box wants its stdout back, and a
+  // cliVerb's { ok, code } cannot carry it. Each returns the same object the
+  // CLI prints under --json, so a script and a shell pipeline read one shape.
+  //
+  //   sshOpen("dev");
+  //   const r = sshExec("dev", ["git", "status", "--short"], { cwd: "/srv/app" });
+  //   if (!r.ok) say(r.stderr);
+  //   sshExec("dev", ["git", "apply", "-"], { stdin: patch });
+  //   sshClose("dev");
+  {
+    name: "sshOpen",
+    summary: "authenticate to a named ssh target once and keep the connection",
+    usage: "sshOpen(name, { persist })",
+    detail: "returns { ok, connected, alreadyOpen }; a live connection is left alone",
+    run(ctx, name, opts = {}) {
+      const found = sshTarget(name, "sshOpen");
+      if (ctx.dryRun) { ctx.out(`  🔌 sshOpen(${name}) → would open a master to ${found.target}`); return { ok: true, target: found.name, connected: true, dryRun: true }; }
+      const r = sshOpenMaster(found, { persist: opts.persist, batch: opts.batch });
+      ctx.out(r.ok ? `  🔌 sshOpen(${name}) → ${r.alreadyOpen ? "already connected" : "connected"}` : `  ✗ sshOpen(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshCheck",
+    summary: "is the connection to a target up?",
+    usage: "sshCheck(name)",
+    detail: "returns { connected, stale, pid }; never connects",
+    run(ctx, name) {
+      const found = sshTarget(name, "sshCheck");
+      if (ctx.dryRun) return { target: found.name, connected: false, dryRun: true };
+      const s = sshCheckMaster(found);
+      return { target: found.name, connected: s.connected, stale: s.stale, pid: s.pid ?? null };
+    },
+  },
+  {
+    name: "sshExec",
+    summary: "run one command over the shared connection and RETURN its result",
+    usage: "sshExec(name, [cmd, ...args], { cwd, env, stdin, timeout, sh })",
+    detail: "returns { ok, transportOk, code, signal, stdout, stderr, durationMs }; opens the connection if it is down. ok is the command's verdict, transportOk is ssh's",
+    run(ctx, name, argv, opts = {}) {
+      const found = sshTarget(name, "sshExec");
+      const command = Array.isArray(argv) ? argv.map(String) : [String(argv ?? "")].filter(Boolean);
+      if (!command.length) throw new Error("moshscript: sshExec(name, [command, ...args]) needs a command");
+      if (ctx.dryRun) {
+        ctx.out(`  ▶ sshExec(${name}) → would run on ${found.target}: ${command.join(" ")}`);
+        return { ok: true, transportOk: true, target: found.name, connected: true, code: 0, signal: null, stdout: "", stderr: "", durationMs: 0, dryRun: true };
+      }
+      ctx.out(`  ▶ sshExec(${name}) → ${command.join(" ").slice(0, 60)}${command.join(" ").length > 60 ? "…" : ""}`);
+      const timeoutMs = opts.timeout === undefined ? undefined
+        : (typeof opts.timeout === "number" ? opts.timeout : parseSshTimeout(opts.timeout));
+      const r = sshRun(found, command, {
+        cwd: opts.cwd, remoteEnv: opts.env || {}, stdin: opts.stdin, sh: Boolean(opts.sh), timeoutMs, persist: opts.persist, batch: opts.batch ?? true,
+      });
+      if (!r.transportOk) ctx.out(`  ✗ sshExec(${name}) → ${r.error}`);
+      else if (!r.ok) ctx.out(`  ✗ sshExec(${name}) exited ${r.signal || r.code}`);
+      return r;
+    },
+  },
+  {
+    name: "sshClose",
+    summary: "hang up a target's connection",
+    usage: "sshClose(name)",
+    detail: "returns { ok, closed, wasOpen }",
+    run(ctx, name) {
+      const found = sshTarget(name, "sshClose");
+      if (ctx.dryRun) { ctx.out(`  🔌 sshClose(${name}) → would send -O exit`); return { ok: true, target: found.name, closed: true, dryRun: true }; }
+      const r = sshCloseMaster(found);
+      ctx.out(r.ok ? `  🔌 sshClose(${name}) → ${r.wasOpen ? "closed" : "was not connected"}` : `  ✗ sshClose(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshPut",
+    summary: "copy a local file to a target, atomically",
+    usage: "sshPut(name, local, remote)",
+    detail: "returns { ok, remote }; scp to a temp path over the shared connection, then rename",
+    run(ctx, name, local, remote) {
+      const found = sshTarget(name, "sshPut");
+      if (!local || !remote) throw new Error("moshscript: sshPut(name, local, remote) needs both paths");
+      if (ctx.dryRun) { ctx.out(`  📤 sshPut(${name}) → would copy ${local} to ${remote}`); return { ok: true, target: found.name, dryRun: true }; }
+      const r = sshPutFile(found, String(local), String(remote));
+      ctx.out(r.ok ? `  📤 sshPut(${name}) → ${r.remote}` : `  ✗ sshPut(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshGet",
+    summary: "copy a file down from a target",
+    usage: "sshGet(name, remote, local)",
+    detail: "returns { ok, local }",
+    run(ctx, name, remote, local) {
+      const found = sshTarget(name, "sshGet");
+      if (!local || !remote) throw new Error("moshscript: sshGet(name, remote, local) needs both paths");
+      if (ctx.dryRun) { ctx.out(`  📥 sshGet(${name}) → would copy ${remote} to ${local}`); return { ok: true, target: found.name, dryRun: true }; }
+      const r = sshGetFile(found, String(remote), String(local));
+      ctx.out(r.ok ? `  📥 sshGet(${name}) → ${r.local}` : `  ✗ sshGet(${name}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshShellSend",
+    summary: "type a line into a persistent remote shell",
+    usage: 'sshShellSend("dev/app", text)',
+    detail: "returns { ok }; literal text then Enter, into the remote tmux session",
+    run(ctx, ref, ...words) {
+      const { found, session } = sshShellRef(ref, "sshShellSend");
+      const text = words.join(" ");
+      if (!text) throw new Error("moshscript: sshShellSend(ref, text) needs text");
+      if (ctx.dryRun) { ctx.out(`  💬 sshShellSend(${ref}) → would send: ${text}`); return { ok: true, dryRun: true }; }
+      const r = sshShellSendRemote(found, session, text);
+      if (!r.ok) ctx.out(`  ✗ sshShellSend(${ref}) → ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "sshShellRead",
+    summary: "the screen of a persistent remote shell, as a string",
+    usage: 'sshShellRead("dev/app", { lines })',
+    detail: "returns the text (empty on failure); the same capture-pane the CLI's read prints",
+    run(ctx, ref, opts = {}) {
+      const { found, session } = sshShellRef(ref, "sshShellRead");
+      if (ctx.dryRun) { ctx.out(`  📖 sshShellRead(${ref}) → would capture the pane`); return ""; }
+      const r = sshShellReadRemote(found, session, { lines: opts.lines });
+      if (!r.ok) { ctx.out(`  ✗ sshShellRead(${ref}) → ${r.error}`); return ""; }
+      return r.screen;
+    },
+  },
+  {
+    name: "sshShellKill",
+    summary: "end a persistent remote shell",
+    usage: 'sshShellKill("dev/app")',
+    detail: "returns { ok }",
+    run(ctx, ref) {
+      const { found, session } = sshShellRef(ref, "sshShellKill");
+      if (ctx.dryRun) { ctx.out(`  ☠ sshShellKill(${ref}) → would kill the session`); return { ok: true, dryRun: true }; }
+      const r = sshShellKillRemote(found, session);
+      if (!r.ok) ctx.out(`  ✗ sshShellKill(${ref}) → ${r.error}`);
+      return r;
+    },
+  },
+
   // CLI verbs — each is `moshcode <name> ...args`. This is the whole point:
   // scripting the CLI. Add a capability by adding a line here.
   //
@@ -695,6 +858,7 @@ const COMMANDS = [
   cliVerb("elevenlabs", "drive the ElevenLabs CLI (Eleven Agents, voices, TTS, dubbing)"),
   cliVerb("trade", "look up tickers, inspect markets, and preview/place Alpaca orders"),
   cliVerb("pwd", "print the current repo/location"),
+  cliVerb("ssh", "persistent SSH workspaces (moshcode ssh <verb>) — see sshExec/sshOpen for values"),
 
   // Research and feeds. The *Read() verbs above return the data; these are the
   // rendered CLI, for when a script wants the table on the operator's screen.