moshcode 0.58.0 → 0.60.0

package/src/herd.mjs

@@ -142,6 +142,54 @@ export function forgetSession(name) {
   return true;
 }
 
+// ---------------------------------------------------------------------------
+// Remote members — the last thing a URL told us (PRD 0011 R11)
+// ---------------------------------------------------------------------------
+//
+// A remote member has no pane to capture and no pid to signal, so its state can
+// only come from a request. Requests are slow and the roster is drawn on every
+// pit start, so what `ps` reads is a *cache*: whatever the last call to that
+// remote observed, with the time it was observed at. The alternative — a roster
+// that opens N sockets before it prints a line — makes `moshcode ps` as fast as
+// the slowest agent someone registered, which is not a trade worth making for a
+// column that already says `authority: remote`.
+//
+// It lives here rather than in herd-remote.mjs so that herd-state.mjs can read
+// it without importing the module that makes network calls.
+
+const remoteFile = (name) => path.join(herdDir(), "remote", `${name}.json`);
+
+/** Record what a remote just told us. Best effort: a failed write loses a poll. */
+export function recordRemoteStatus(name, status = {}) {
+  try {
+    fs.mkdirSync(path.join(herdDir(), "remote"), { recursive: true, mode: 0o700 });
+    const file = remoteFile(name);
+    fs.writeFileSync(file, JSON.stringify({ ...status, at: status.at ?? Date.now() }), { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * The cached status of a remote member, or null when it has never answered.
+ *
+ * Deliberately un-expiring. A hook report has a TTL because a stale one would
+ * outrank a screen that could be read instead; there is nothing better to fall
+ * back to here, and "it was idle an hour ago" beats "unknown" as long as the
+ * age travels with it — which it does, in `--json` and in `herd remote list`.
+ */
+export function remoteStatus(name) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(remoteFile(name), "utf8"));
+    return raw && typeof raw === "object" ? raw : null;
+  } catch { return null; }
+}
+
+export function clearRemoteStatus(name) {
+  try { fs.rmSync(remoteFile(name), { force: true }); return true; }
+  catch { return false; }
+}
+
 // ---------------------------------------------------------------------------
 // Substrate detection
 // ---------------------------------------------------------------------------
@@ -226,10 +274,17 @@ export function tmux(args, { runner = spawnSync, env = process.env, encoding = "
  * (an inherited ANTHROPIC_API_KEY hijacks its stored login — see ENGINES), and
  * `-e KEY=` sets an empty value, which is not the same as unset.
  */
-export function sessionCommand({ bin, args = [], stripEnv = [], exec = true }) {
+export function sessionCommand({ bin, args = [], stripEnv = [], setEnv = {}, exec = true }) {
   const unset = stripEnv.flatMap((key) => ["-u", key]);
+  // Set through the same `env` prefix rather than tmux's `-e`, for two reasons:
+  // `-e` is a 3.2+ flag and the pty substrate has no equivalent at all, so one
+  // prefix is the only spelling both substrates can share.
+  const set = Object.entries(setEnv)
+    .filter(([key, value]) => key && value !== undefined && value !== null)
+    .map(([key, value]) => `${key}=${String(value)}`);
   const command = [bin, ...args].map(shQuote).join(" ");
-  const withEnv = unset.length ? `env ${unset.map(shQuote).join(" ")} ${command}` : command;
+  const prefix = [...unset, ...set];
+  const withEnv = prefix.length ? `env ${prefix.map(shQuote).join(" ")} ${command}` : command;
   // `exec` so the engine replaces the shell rather than sitting under it — one
   // less process between a signal and the thing meant to receive it. The pty
   // substrate passes exec:false because it needs the shell to outlive the
@@ -302,6 +357,24 @@ export function pidAlive(pid) {
  * never sees EOF and waits for input forever, which is what an idle agent
  * should do.
  */
+/**
+ * What every session knows about itself (PRD 0011 R2).
+ *
+ * A lifecycle hook fires inside the engine's own process tree and has to name
+ * the session it is reporting for. Nothing else in that tree knows the name, so
+ * the herd puts it there at launch. `MOSHCODE_HERD_DIR` rides along because a
+ * hook shells out to `moshcode herd report`, and a box whose herd lives
+ * somewhere non-default would otherwise have its reports written to the default
+ * directory nobody is reading.
+ *
+ * A hook fired outside a herd session sees neither, which is the signal to exit
+ * quietly — see `herdReport`. Hooks must never break an engine that is not in
+ * the herd.
+ */
+export function sessionEnv(name) {
+  return { MOSHCODE_HERD_NAME: name, MOSHCODE_HERD_DIR: herdDir() };
+}
+
 function ptyStart({ name, cwd, bin, args, stripEnv, env, spawner = spawn, runner = spawnSync, size = {} }) {
   ensureDir();
   const cols = Number(size.cols) || Number(env.COLUMNS) || process.stdout.columns || 80;
@@ -328,7 +401,7 @@ function ptyStart({ name, cwd, bin, args, stripEnv, env, spawner = spawn, runner
   // that a session which finishes on its own leaves proof it finished.
   const command = [
     `stty rows ${rows} cols ${cols} 2>/dev/null`,
-    sessionCommand({ bin, args, stripEnv, exec: false }),
+    sessionCommand({ bin, args, stripEnv, setEnv: sessionEnv(name), exec: false }),
     `printf '%s' "$?" > ${shQuote(exit)}`,
   ].join("; ");
   // Reuse ptySpec's flag knowledge rather than re-deriving it: util-linux and
@@ -347,7 +420,7 @@ function ptyStart({ name, cwd, bin, args, stripEnv, env, spawner = spawn, runner
       cwd,
       // Belt and braces with the stty above: some toolkits read COLUMNS/LINES
       // before they ever ask the terminal.
-      env: { ...env, COLUMNS: String(cols), LINES: String(rows), MOSHCODE_HERD_SESSION: name },
+      env: { ...env, COLUMNS: String(cols), LINES: String(rows), MOSHCODE_HERD_SESSION: name, ...sessionEnv(name) },
       stdio: [stdin, "ignore", "ignore"],
       detached: true,
     });
@@ -565,7 +638,7 @@ export function startSession({
   };
 
   if (substrate === "tmux") {
-    const command = sessionCommand({ bin, args, stripEnv });
+    const command = sessionCommand({ bin, args, stripEnv, setEnv: sessionEnv(name) });
     const started = tmux(tmuxStartPlan({ name, cwd, command }), { runner, env });
     if (!started.ok) {
       return { ok: false, error: new Error(started.stderr.trim() || started.error?.message || "tmux could not start the session") };
@@ -802,12 +875,21 @@ export function listSessions({ substrate = detectSubstrate(), runner = spawnSync
   const names = [...new Set([...live, ...Object.keys(manifest.sessions)])].sort();
   return names.map((name) => {
     const meta = manifest.sessions[name] || {};
-    const alive = live.has(name);
-    const exited = !alive ? null
+    // A remote member (PRD 0011 R11) has no pane and no pid — it is a URL. The
+    // substrate can only ever report it as absent, so liveness for those rows
+    // means "still registered", and whether the far end answers is a question
+    // for herd-remote.mjs's cache rather than for tmux.
+    const remote = meta.kind === "remote";
+    const alive = remote ? true : live.has(name);
+    const exited = remote ? false
+      : !alive ? null
       : panes ? Boolean(panes.get(name)?.dead)
       : sessionExited(name, { substrate, runner });
     return {
       name,
+      kind: meta.kind || "local",
+      url: meta.url || null,
+      remoteKind: meta.remoteKind || null,
       engine: meta.engine || "?",
       // Sessions started before herds existed have none. They belong to `main`
       // rather than to a group rendered as "undefined".

package/src/templates.mjs

@@ -41,6 +41,23 @@ function isOwnManifest(relative) {
 
 /* ------------------------------------------------------------------ listing */
 
+/**
+ * Template collections worth knowing about that this repo does not ship
+ * (PRD 0011 R15).
+ *
+ * A pointer rather than a copy, deliberately. `template install` already takes
+ * an `owner/repo`, so vendoring somebody else's templates would mean carrying
+ * their updates by hand forever — and pinning a stale copy of an SDK's starter
+ * kit is worse than not having one. What is missing is only that nobody knows
+ * the name to type, so the listing says it.
+ */
+export const TEMPLATE_POINTERS = [
+  {
+    spec: "digitalocean/gradient-adk-templates",
+    description: "DigitalOcean Gradient ADK — agent starters (A2A-capable; pairs with `moshcode install gradient`)",
+  },
+];
+
 /** The bundled templates, each with whatever its manifest says about it. */
 export async function listTemplates(dir = BUNDLED_DIR) {
   let entries;
@@ -347,19 +364,29 @@ export async function templateCommand(
     }
     const templates = await listTemplates();
     if (rest.includes("--json")) {
+      // The bundled list stays an array, because that is what it has always
+      // been and something is parsing it. Pointers are named separately rather
+      // than mixed in: `template install <name>` works for one and not the
+      // other, and a listing that hid that difference would be a listing that
+      // lies about what it can do.
       out(JSON.stringify(templates, null, 2));
       return 0;
     }
     if (!templates.length) {
       out("no templates bundled with this install");
-      return 0;
+    } else {
+      const width = Math.max(...templates.map((t) => t.name.length));
+      for (const { name, description } of templates) {
+        out(`  ${name.padEnd(width)}  ${description}`);
+      }
     }
-    const width = Math.max(...templates.map((t) => t.name.length));
-    for (const { name, description } of templates) {
-      out(`  ${name.padEnd(width)}  ${description}`);
+    out("");
+    out("elsewhere:");
+    for (const { spec, description } of TEMPLATE_POINTERS) {
+      out(`  ${spec}  ${description}`);
     }
     out("");
-    out("install one with: moshcode template install <name>");
+    out("install one with: moshcode template install <name|owner/repo|url>");
     return 0;
   }
 

package/src/tools.mjs

@@ -160,6 +160,49 @@ export const TOOLS = {
     },
     installHelp: "Go is required to install Alpaca; install Go, then retry `moshcode install alpaca`.",
   },
+  gradient: {
+    desc: "DigitalOcean Gradient ADK — build, run, deploy and evaluate agents (A2A-capable)",
+    bin: "gradient",
+    // The one tool here that is not a self-contained binary. gradient-adk is a
+    // Python package, and moshcode stays Node: the tool owns its runtime, the
+    // same way CoinPay owns Node 20. So the install spec checks for a Python
+    // the package can actually run on and NAMES the requirement when it is
+    // missing, rather than letting pip fail three screens later with a
+    // resolution error nobody reads. `--user` keeps it out of the system
+    // site-packages, which is also the only place a non-root install can go on
+    // a modern distro.
+    install: {
+      cmd: "sh",
+      args: [
+        "-c",
+        'python3 -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)" 2>/dev/null '
+        + '|| { echo "gradient-adk needs Python 3.10 or newer on PATH as python3 — install it, then re-run: moshcode install gradient" >&2; exit 1; }; '
+        + "python3 -m pip install --user --upgrade gradient-adk",
+      ],
+    },
+    installHelp: "gradient-adk is a Python package: it needs python3 (3.10+) and pip. moshcode does not install Python for you.",
+    // pip --user drops console scripts here, and appends nothing to PATH for
+    // the shell that ran the install — the same gap turso and kimi have.
+    binDirs: [path.join(homedir(), ".local", "bin")],
+    // How the ADK's dev server reads in the herd (PRD 0011 R15). `gradient
+    // agent run --dev` is uvicorn underneath, and its startup banner is a clear
+    // "I am up and waiting", which is `idle`.
+    //
+    // There is deliberately no `working` rule. uvicorn writes its access line
+    // when a request has FINISHED, so a screen showing one is a screen showing
+    // a server that is free again — a rule matching it would pin the tile to
+    // `working` from the first request until the line scrolled away, which is
+    // the exact kind of rot the sub-kinds and hooks exist to get away from. So
+    // the completed request counts as idle too, and it is right both times.
+    // Watching a *deployed* agent's state is what `herd remote add` is for.
+    state: {
+      idle: [
+        /\buvicorn running on\b/i,
+        /\bapplication startup complete\b/i,
+        /"(?:POST|GET|PUT) \/[^"]*" \d{3}\b/,
+      ],
+    },
+  },
   mcpjam: {
     desc: "MCPJam — test, debug, and validate MCP servers (health, OAuth, tool-surface diffs)",
     bin: "mcpjam",

package/src/tui.mjs

@@ -833,6 +833,7 @@ export async function tui() {
     // sessions run somewhere that outlives it.
     if (cmd === "herd") { await herdCommand(rest); continue; }
     if (cmd === "ps") { await herdCommand(["ps", ...rest]); continue; }
+    if (cmd === "cost" || cmd === "usage") { await herdCommand(["cost", ...rest]); continue; }
     if (cmd === "kill") { await herdCommand(["kill", ...rest]); continue; }
     if (cmd === "wait") { await herdCommand(["wait", ...rest]); continue; }
     if (cmd === "restore") { await herdCommand(["restore", ...rest]); continue; }