moshcode 0.24.0

package/src/integrations.mjs

@@ -0,0 +1,265 @@
+// `/mcp` and `/skill` command flows, shared by the TUI and the CLI. Each parses
+// a canonical spec, plans the per-engine fan-out, runs it, and prints a
+// per-engine summary. See prd/0003.
+import { ENGINES, isInstalled } from "./engines.mjs";
+import {
+  MCP_ENGINES, deriveName, isRemoteTarget, planMcpAdd, runMcpAdd,
+} from "./mcp.mjs";
+import {
+  SKILL_ENGINES, planSkillInstall, runSkillInstall, skillName,
+} from "./skills.mjs";
+import { catalogList, resolveCatalog } from "./mcp-catalog.mjs";
+import { MCP_VERBS, SKILL_VERBS } from "./cli-schema.mjs";
+import { acid, ash, bone, ok, err, info } from "./ui.mjs";
+
+function splitKV(pair) {
+  const i = String(pair).indexOf("=");
+  return i === -1 ? [String(pair), ""] : [pair.slice(0, i), pair.slice(i + 1)];
+}
+
+function headerName(header) {
+  const i = String(header).indexOf(":");
+  return i === -1 ? null : String(header).slice(0, i).trim();
+}
+
+function flagValue(rest, index, flag) {
+  const value = rest[index + 1];
+  if (value === undefined || value === "--" || String(value).startsWith("-")) {
+    return { error: `${flag} requires a value` };
+  }
+  return { value };
+}
+
+/** Parse `/mcp` tokens (after the `mcp` word) into { list } | { spec } | { error }. */
+export function parseMcp(tokens) {
+  const verb = tokens[0];
+  if (!verb || verb === "list") return { list: true, json: tokens.slice(1).includes("--json") };
+  if (verb === "catalog") return { showCatalog: true };
+  const verbSchema = MCP_VERBS.find(({ name }) => name === verb);
+  if (!verbSchema?.acceptsServerSpec) {
+    const choices = MCP_VERBS.map(({ name }) => name);
+    return { error: `unknown mcp verb "${verb}" — try ${choices.slice(0, -1).join(", ")}, or ${choices.at(-1)}` };
+  }
+
+  const rest = tokens.slice(1);
+  let name, transport, cmdParts = null;
+  const env = [], headers = [], positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const t = rest[i];
+    if (t === "--") { cmdParts = rest.slice(i + 1); break; }
+    else if (t === "--name") {
+      const next = flagValue(rest, i, t);
+      if (next.error) return next;
+      name = next.value; i++;
+    }
+    else if (t === "-t" || t === "--transport") {
+      const next = flagValue(rest, i, t);
+      if (next.error) return next;
+      transport = next.value; i++;
+    }
+    else if (t === "-e" || t === "--env") {
+      const next = flagValue(rest, i, t);
+      if (next.error) return next;
+      env.push(splitKV(next.value)); i++;
+    }
+    else if (t === "-H" || t === "--header") {
+      const next = flagValue(rest, i, t);
+      if (next.error) return next;
+      headers.push(next.value); i++;
+    }
+    else positional.push(t);
+  }
+
+  if (verb === "add") name = name || positional.shift();
+  let target, args = [];
+  if (cmdParts) { target = cmdParts[0]; args = cmdParts.slice(1); }
+  else { target = positional[0]; args = positional.slice(1); }
+
+  // A bare known name is enough: `mcp add porkbun` fills the command in from
+  // the catalog. Only when nothing else was given — an explicit target always
+  // wins, so the catalog can never override what was actually typed.
+  let catalog = null;
+  if (!target) {
+    catalog = resolveCatalog(name) || resolveCatalog(positional[0]);
+    if (catalog) {
+      name = name || catalog.key;
+      target = catalog.target;
+      args = catalog.args;
+    }
+  }
+
+  // A token still starting with `-` at this point was never consumed as a flag,
+  // so it is a typo or an engine-native flag moshcode does not take (`-s user`).
+  // Left alone it becomes the server NAME or its command and gets spliced
+  // straight into every engine's own `mcp add` argv. Everything after `--` is
+  // the user's command line and is deliberately not second-guessed.
+  const stray = [name, cmdParts ? null : target]
+    .find((t) => typeof t === "string" && t.startsWith("-"));
+  if (stray) {
+    return {
+      error: `unknown mcp flag "${stray}" — mcp takes --name, -t/--transport, -e/--env, and -H/--header; put a command's own flags after --`,
+    };
+  }
+
+  if (verb === "install" && !name) {
+    if (target && isRemoteTarget(target)) name = deriveName(target);
+    else return { error: "a stdio command server needs an explicit --name" };
+  }
+  if (!name) return { error: "missing server name" };
+  if (!target) return { error: "missing server URL or command" };
+  if (env.some(([key]) => String(key).trim() === "")) {
+    return { error: "mcp --env requires a non-empty key" };
+  }
+  if (headers.some((header) => headerName(header) === null)) {
+    return { error: "mcp --header requires a Name: Value header" };
+  }
+  if (headers.some((header) => headerName(header) === "")) {
+    return { error: "mcp --header requires a non-empty header name" };
+  }
+  return {
+    spec: { name, target, args, transport, env, headers },
+    ...(catalog ? { catalog } : {}),
+  };
+}
+
+const DOT = { installed: acid("●"), missing: ash("○") };
+function line(key, statusText) { return `   ${bone(key.padEnd(9))} ${statusText}`; }
+
+function integrationTargetStatus(supportedKeys, { installedSet } = {}) {
+  const supported = new Set(supportedKeys);
+  const keys = [...supportedKeys, ...Object.keys(ENGINES).filter((key) => !supported.has(key))];
+  return keys.map((key) => ({
+    name: key,
+    binary: ENGINES[key].bin,
+    installed: installedSet ? installedSet.has(key) : isInstalled(ENGINES[key].bin, ENGINES[key].binDirs),
+    supported: supported.has(key),
+  }));
+}
+
+/** MCP capability and install status for every engine. */
+export function mcpTargetStatus(options) {
+  return integrationTargetStatus(MCP_ENGINES, options);
+}
+
+/** Skills capability and install status for every engine. */
+export function skillTargetStatus(options) {
+  return integrationTargetStatus(SKILL_ENGINES, options);
+}
+
+/** Print the known-server catalog. */
+export function printMcpCatalog() {
+  console.log(bone("  known mcp servers") + ash("  — register one with ") + acid("/mcp add <name>"));
+  console.log(catalogList());
+}
+
+/** Print the MCP support matrix + install status. */
+export function printMcpTargets(json = false) {
+  const targets = mcpTargetStatus();
+  if (json) { console.log(JSON.stringify(targets, null, 2)); return; }
+  console.log(bone("  mcp") + ash("  — register a server everywhere with ") + acid("/mcp install <url>"));
+  for (const target of targets) {
+    const dot = target.supported && target.installed ? DOT.installed : DOT.missing;
+    // "no MCP support" would be a claim about the engine; what this column
+    // actually knows is whether moshcode can register a server there. Kimi runs
+    // MCP servers perfectly well and simply has no command to add one from a
+    // script — the fan-out states each engine's own reason when you run it.
+    console.log(`   ${dot} ${bone(target.name.padEnd(9))} ${ash(target.supported ? "mcp add supported" : "no mcp add command")}`);
+  }
+}
+
+/** Print the skills support matrix + install status. */
+export function printSkillTargets(json = false) {
+  const targets = skillTargetStatus();
+  if (json) { console.log(JSON.stringify(targets, null, 2)); return; }
+  console.log(bone("  skills") + ash("  — install a skill everywhere with ") + acid("/skill install <git-url>"));
+  for (const target of targets) {
+    const dot = target.supported && target.installed ? DOT.installed : DOT.missing;
+    console.log(`   ${dot} ${bone(target.name.padEnd(9))} ${ash(target.supported ? "skills supported" : "no skills primitive")}`);
+  }
+}
+
+function summarize(results) {
+  for (const r of results) {
+    if (r.status === "added" || r.status === "installed") console.log(line(r.key, ok(r.status)));
+    else if (r.status === "failed") console.log(line(r.key, err(`failed${r.code != null ? ` (code ${r.code})` : r.signal ? ` (${r.signal})` : ""}`)));
+    else if (r.status === "not-installed") console.log(line(r.key, ash("not installed — /install " + r.key)));
+    else console.log(line(r.key, ash(`skipped — ${r.reason}`)));
+  }
+}
+
+/**
+ * Did any engine we actually ran come back failed?
+ *
+ * Only "failed" counts. An engine that is skipped ("no MCP support") or absent
+ * ("not installed") was never attempted, and the summary already prints both in
+ * grey rather than red — treating them as failures would make `mcp add` exit
+ * non-zero on a perfectly good box that simply does not have all six engines.
+ * This is the rule `upgrade` already applies to its own fan-out, which counts
+ * `!r.ok` over the engines it ran and exits 1 if any of them failed.
+ */
+const anyFailed = (results) => results.some((r) => r.status === "failed");
+
+/** Run `/mcp …`. `tokens` are the words after `mcp`. `run`/`installedSet` are injectable for tests. */
+export async function mcpCommand(tokens, { run, installedSet } = {}) {
+  const parsed = parseMcp(tokens);
+  if (parsed.list) { printMcpTargets(parsed.json); return 0; }
+  if (parsed.showCatalog) { printMcpCatalog(); return 0; }
+  if (parsed.error) { console.log(err(parsed.error)); return 1; }
+
+  const { spec } = parsed;
+  console.log(info(`registering ${bone(spec.name)} → ${ash(spec.target)} across MCP engines…`));
+  const results = await runMcpAdd(planMcpAdd(spec, { installedSet }), run ? { run } : {});
+  summarize(results);
+  // Credentials are named, never registered: an API key copied into five
+  // engines' config files is five places to leak it from and five to rotate.
+  const missing = (parsed.catalog?.env || []).filter((k) => !process.env[k]);
+  if (missing.length) {
+    console.log(ash(`  note: ${spec.name} needs ${missing.join(" and ")} in the environment.`));
+    if (parsed.catalog?.note) console.log(ash(`        ${parsed.catalog.note}`));
+    if (parsed.catalog?.docs) console.log(ash(`        ${parsed.catalog.docs}`));
+  }
+  if (spec.headers.length || /^https?:/i.test(spec.target)) {
+    console.log(ash("  note: OAuth/HTTP servers may still need per-engine auth (e.g. `opencode mcp auth`, `codex mcp login`)."));
+  }
+  return anyFailed(results) ? 1 : 0;
+}
+
+/** Run `/skill …`. `tokens` are the words after `skill`. `run`/`installedSet` are injectable for tests. */
+export async function skillCommand(tokens, { run, installedSet } = {}) {
+  const verb = tokens[0];
+  if (!verb || verb === "list") { printSkillTargets(tokens.slice(1).includes("--json")); return 0; }
+  if (verb !== "install") {
+    console.log(err(`unknown skill verb "${verb}" — try ${SKILL_VERBS.map(({ name }) => name).join(" or ")}`));
+    return 1;
+  }
+
+  const rest = tokens.slice(1);
+  let name, source;
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--name") {
+      const next = flagValue(rest, i, rest[i]);
+      if (next.error) { console.log(err(next.error)); return 1; }
+      name = next.value;
+      i++;
+    }
+    else if (!source) source = rest[i];
+  }
+  // A source still starting with `-` was never consumed as a flag, so it is a
+  // typo or an engine-native flag moshcode does not take (`-s user`). Left
+  // alone it becomes the skill SOURCE and is spliced straight into every
+  // engine's own argv — `gemini skills install -s --scope user`, and a
+  // `git clone --depth 1 -s <dest>` where `-s` (`--shared`) makes git read the
+  // destination as the repository — while the URL the user actually typed is
+  // dropped on the floor. Same guard `mcp` already applies to its own spec.
+  if (source?.startsWith("-")) {
+    console.log(err(`unknown skill flag "${source}" — skill install takes --name; a source that really starts with "-" must be written as ./${source}`));
+    return 1;
+  }
+  if (!source) { console.log(err("usage: /skill install <git-url|path> [--name <name>]")); return 1; }
+
+  const spec = { source, name: skillName(source, name) };
+  console.log(info(`installing skill ${bone(spec.name)} → ${ash(source)} across skills engines…`));
+  const results = await runSkillInstall(planSkillInstall(spec, { installedSet }), run ? { run } : {});
+  summarize(results);
+  return anyFailed(results) ? 1 : 0;
+}

package/src/mcp-catalog.mjs

@@ -0,0 +1,50 @@
+// Known MCP servers, so a name is enough: `moshcode mcp add porkbun` instead of
+// remembering an npx invocation and its package scope.
+//
+// This is a convenience layer, not a gate — `mcp add <name> -- <cmd> …` still
+// takes anything. An entry here only means "we know the canonical way to run
+// this one".
+//
+// `env` lists the variables the server needs to do real work. They are NOT
+// baked into the registration: an API key belongs in the environment (or a
+// secrets manager), not copied into five engines' config files. They are
+// printed as a reminder instead.
+
+export const MCP_CATALOG = {
+  porkbun: {
+    target: "npx",
+    args: ["-y", "@porkbunllc/mcp-server"],
+    desc: "Porkbun — domains, DNS records, SSL, email forwarding",
+    // Linked as the official MCP server from Porkbun's own API documentation,
+    // though the source lives on an individual's account rather than a Porkbun
+    // org — worth knowing before handing it DNS-write credentials.
+    docs: "https://porkbun.com/api/json/v3/documentation",
+    env: ["PORKBUN_API_KEY", "PORKBUN_SECRET_API_KEY"],
+    // The doc tools work with no credentials at all, so it is worth trying
+    // before deciding whether to trust it with keys.
+    note: "API access is off by default and must be enabled per-domain; the docs tools work without keys",
+  },
+};
+
+/** Resolve a catalog name to a spec fragment, or null. Own properties only. */
+export function resolveCatalog(token) {
+  if (!token) return null;
+  const key = String(token).trim().toLowerCase();
+  // MCP_CATALOG is a plain object literal, so `constructor` and friends would
+  // otherwise resolve to something off Object.prototype with no target.
+  if (!Object.hasOwn(MCP_CATALOG, key)) return null;
+  const entry = MCP_CATALOG[key];
+  return { key, ...entry, args: [...(entry.args || [])] };
+}
+
+/** Names, for help text and error messages. */
+export function catalogNames() {
+  return Object.keys(MCP_CATALOG);
+}
+
+/** One line per known server, for `mcp catalog`. */
+export function catalogList() {
+  return Object.entries(MCP_CATALOG)
+    .map(([key, e]) => `  ${key.padEnd(10)} ${e.desc}`)
+    .join("\n");
+}

package/src/mcp.mjs

@@ -0,0 +1,155 @@
+// Register MCP (Model Context Protocol) servers across every engine that
+// supports them, from one canonical definition. MoshCode drives each engine's
+// own `mcp add` so the engine owns its config format. See prd/0003.
+import { ENGINES, isInstalled, ranOk, runCmd } from "./engines.mjs";
+import { isIP } from "node:net";
+
+// Coding engines that can register MCP servers. Aider has no MCP support.
+export const MCP_ENGINES = ["claude", "gemini", "codex", "opencode", "privacycode"];
+
+/** Is this target a remote server URL (vs a local stdio command)? */
+export function isRemoteTarget(target) {
+  return /^https?:\/\//i.test(String(target));
+}
+
+// Second-level labels that are part of a multi-part public suffix rather than a
+// name, as in co.uk / com.au / co.za. Dropping only the TLD would leave these.
+const SUFFIX_LABELS = ["co", "com", "net", "org", "gov", "edu", "ac"];
+
+/** Derive a sane server name from a remote URL's host (e.g. mcp.sentry.dev → sentry). */
+export function deriveName(target) {
+  const sanitize = (s) => String(s).toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "");
+  try {
+    const hostname = new URL(target).hostname;
+    const ipHost = hostname.replace(/^\[|\]$/g, "");
+    if (isIP(ipHost)) {
+      const ipName = ipHost.replace(/[.:]+/g, "-").replace(/^-+|-+$/g, "");
+      return sanitize(`ip-${ipName}`);
+    }
+    const labels = hostname.split(".").filter(Boolean);
+    let withoutTld = labels.slice(0, -1); // drop the TLD
+    // ...and the generic label of a multi-part suffix, as long as a real name
+    // still precedes it (a bare "co.uk" host has nothing better to offer).
+    if (withoutTld.length > 1 && SUFFIX_LABELS.includes(withoutTld[withoutTld.length - 1])) {
+      withoutTld = withoutTld.slice(0, -1);
+    }
+    const meaningful = withoutTld.filter((l) => !["mcp", "www", "api", "app"].includes(l));
+    const pick = meaningful[meaningful.length - 1] || withoutTld[withoutTld.length - 1] || labels[0];
+    return sanitize(pick) || "server";
+  } catch {
+    return "server";
+  }
+}
+
+/** Convert a `"Key: Value"` header into OpenCode's `Key=Value` form. */
+function headerToEq(header) {
+  const i = String(header).indexOf(":");
+  return i === -1 ? String(header) : `${header.slice(0, i).trim()}=${header.slice(i + 1).trim()}`;
+}
+
+/**
+ * Build one engine's native `mcp add` argv for a canonical server spec, or a
+ * skip reason when the engine can't express it.
+ *
+ * spec: { name, target, args?, transport?, env?: [[k,v]], headers?: ["Key: Value"] }
+ * `target` is a URL (remote) or a stdio command; `args` are stdio command args.
+ * Returns { argv } or { skip }.
+ */
+export function mcpAddArgs(key, spec) {
+  const { name, target, args = [], env = [], headers = [] } = spec;
+  const remote = isRemoteTarget(target);
+  const transport = spec.transport || (remote ? "http" : "stdio");
+
+  switch (key) {
+    case "claude": {
+      const argv = ["mcp", "add", "-s", "user"];
+      if (remote) argv.push("-t", transport);
+      for (const [k, v] of env) argv.push("-e", `${k}=${v}`);
+      for (const h of headers) argv.push("-H", h);
+      argv.push(name);
+      if (remote) argv.push(target);
+      else argv.push("--", target, ...args);
+      return { argv };
+    }
+    case "gemini": {
+      const argv = ["mcp", "add", "-s", "user"];
+      if (remote) argv.push("-t", transport);
+      for (const [k, v] of env) argv.push("-e", `${k}=${v}`);
+      for (const h of headers) argv.push("-H", h);
+      argv.push(name);
+      if (remote) argv.push(target);
+      else argv.push(target, ...args);
+      return { argv };
+    }
+    case "kimi":
+      // Kimi Code runs MCP servers, but nothing registers one from a script: it
+      // reads ~/.kimi-code/mcp.json, edited by hand or through the in-session
+      // /mcp-config picker. (The deprecated Python kimi-cli did have `kimi mcp
+      // add`; Kimi Code dropped the subcommand.) MoshCode drives each engine's
+      // own CLI rather than writing its config file, so this is a stated skip —
+      // and a more useful one than the blanket "no MCP support", which would
+      // read as "kimi cannot do MCP at all".
+      return { skip: "no scriptable `mcp add` — add it in kimi with /mcp-config, or in ~/.kimi-code/mcp.json" };
+    case "codex": {
+      if (headers.length) {
+        return { skip: "Codex supports only a bearer-token env var, not literal headers" };
+      }
+      const argv = ["mcp", "add", name];
+      for (const [k, v] of env) argv.push("--env", `${k}=${v}`);
+      if (remote) argv.push("--url", target);
+      else argv.push("--", target, ...args);
+      return { argv };
+    }
+    // privacycode is opencode-derived, so it shares opencode's `mcp add` surface
+    // — including the "remote servers only, non-interactively" limitation.
+    case "opencode":
+    case "privacycode": {
+      if (!remote) {
+        return { skip: `${key === "privacycode" ? "privacycode" : "OpenCode"} CLI adds only remote (--url) servers non-interactively` };
+      }
+      const argv = ["mcp", "add", name, "--url", target];
+      for (const [k, v] of env) argv.push("--env", `${k}=${v}`);
+      for (const h of headers) argv.push("--header", headerToEq(h));
+      return { argv };
+    }
+    default:
+      return { skip: "no MCP support" };
+  }
+}
+
+/**
+ * Plan the fan-out: one entry per engine with its native argv or skip reason,
+ * annotated with install status. Pure + testable.
+ *
+ * Every engine, not just MCP_ENGINES — R6 requires an engine that cannot
+ * express the server to be skipped *with a stated reason*, and the PRD's own
+ * UX example ends on `· aider  skipped — no MCP support`. Mapping MCP_ENGINES
+ * dropped those engines before they reached the summary, so the fan-out
+ * reported five rows where /mcp list reports six. MCP_ENGINES stays the
+ * capability set (it is what the matrix splits "supported" on); it is only the
+ * iteration that widens. Supported engines keep their existing order.
+ */
+export function planMcpAdd(spec, { installedSet } = {}) {
+  const rest = Object.keys(ENGINES).filter((key) => !MCP_ENGINES.includes(key));
+  return [...MCP_ENGINES, ...rest].map((key) => {
+    const bin = ENGINES[key].bin;
+    const installed = installedSet ? installedSet.has(key) : isInstalled(bin, ENGINES[key].binDirs);
+    return { key, bin, installed, ...mcpAddArgs(key, spec) };
+  });
+}
+
+/**
+ * Execute a plan: run each installed, non-skipped engine's `mcp add`. Returns
+ * results [{ key, status: "added"|"skipped"|"failed"|"not-installed", reason? }].
+ * `run` is injectable for tests; defaults to the real spawner.
+ */
+export async function runMcpAdd(plan, { run = runCmd } = {}) {
+  const results = [];
+  for (const item of plan) {
+    if (item.skip) { results.push({ key: item.key, status: "skipped", reason: item.skip }); continue; }
+    if (!item.installed) { results.push({ key: item.key, status: "not-installed" }); continue; }
+    const r = await run(item.bin, item.argv);
+    results.push({ key: item.key, status: ranOk(r) ? "added" : "failed", code: r.code, signal: r.signal ?? null });
+  }
+  return results;
+}

package/src/mirror.mjs

@@ -0,0 +1,187 @@
+// Live session mirror — the CLI half of `/sessions` on app.moshcode.sh.
+//
+// While the pit is open, everything moshcode prints is tee'd to the app so you
+// can watch this machine from a browser, and commands typed there are handed
+// back to the prompt as if you'd typed them. It is deliberately best-effort:
+// every network call is swallowed, because a flaky link must never take down
+// the terminal you're actually working in.
+//
+// What it can't see: once an engine takes the terminal (`/agents claude`), the
+// child writes straight to the tty on its own fd — those bytes never pass
+// through this process. The mirror shows the hand-off, not the engine's screen.
+import os from "node:os";
+import { loadCreds } from "./auth.mjs";
+
+const FLUSH_MS = 150;      // batch writes so a busy render is one request, not fifty
+const MAX_BUFFER = 16000;  // flush early once a batch gets big
+
+export function createMirror({
+  version = "",
+  cwd = process.cwd(),
+  fetchImpl = fetch,
+  credentials = loadCreds(),
+} = {}) {
+  const creds = credentials;
+  let sessionId = null;
+  let stopped = false;
+  let pending = "";
+  let flushTimer = null;
+  let engine = null;
+  let engineDirty = false;
+  // The parked long-poll, so stop() can cut it loose instead of leaving the
+  // process alive for up to a full poll window after the pit closes.
+  let poll = null;
+  const onCommand = new Set();
+
+  const api = (creds?.api || "https://app.moshcode.sh").replace(/\/+$/, "");
+  const headers = { "content-type": "application/json", authorization: `Bearer ${creds?.token}` };
+
+  const post = async (path, body, opts = {}) => {
+    try {
+      const r = await fetchImpl(`${api}${path}`, { method: "POST", headers, body: JSON.stringify(body), ...opts });
+      return r.ok ? await r.json().catch(() => ({})) : null;
+    } catch { return null; }
+  };
+
+  // The browser runs a real terminal emulator over this stream, so it has to
+  // know how wide the tty on this end is — otherwise every line wraps at the
+  // wrong column and anything that redraws in place lands crooked.
+  //
+  // Piped output (CI, `mosh | tee`) has no size at all, and half a size is no
+  // use to an emulator, so send nothing rather than nulls: the app keeps
+  // whatever it already had and the page falls back to filling its box.
+  const size = () => {
+    const { columns, rows } = process.stdout;
+    return columns && rows ? { cols: columns, rows } : {};
+  };
+
+  async function flush() {
+    flushTimer = null;
+    if (!sessionId || (!pending && !engineDirty)) return;
+    const chunk = pending;
+    pending = "";
+    engineDirty = false;
+    await post(`/api/sessions/${sessionId}/output`, { chunk, engine, ...size() });
+  }
+
+  function schedule() {
+    if (flushTimer || stopped) return;
+    flushTimer = setTimeout(flush, FLUSH_MS);
+    flushTimer.unref?.(); // never hold the process open on account of the mirror
+  }
+
+  /** Tee a chunk of terminal output to the app. */
+  function write(text) {
+    if (!sessionId || stopped || !text) return;
+    pending += text;
+    if (pending.length >= MAX_BUFFER) { clearTimeout(flushTimer); flushTimer = null; flush(); }
+    else schedule();
+  }
+
+  /** Note which engine owns the terminal right now (null = back in the pit). */
+  function setEngine(name) {
+    const next = name || null;
+    if (next === engine) return;
+    engine = next;
+    engineDirty = true;
+    schedule();
+  }
+
+  // Dragging a window edge fires `resize` continuously, so settle first and
+  // send one empty post carrying the final geometry.
+  let resizeTimer = null;
+  function onResize() {
+    if (stopped || !sessionId) return;
+    clearTimeout(resizeTimer);
+    resizeTimer = setTimeout(() => {
+      resizeTimer = null;
+      post(`/api/sessions/${sessionId}/output`, { chunk: "", engine, ...size() });
+    }, 120);
+    resizeTimer.unref?.();
+  }
+
+  // Long-poll for commands typed on the web. One request parks on the server
+  // until something is queued, so a command lands in well under a second
+  // without us hammering the API.
+  async function pump() {
+    while (!stopped && sessionId) {
+      let got = null;
+      try {
+        poll = new AbortController();
+        const r = await fetchImpl(`${api}/api/sessions/${sessionId}/commands`, { headers, signal: poll.signal });
+        got = r.ok ? await r.json() : null;
+      } catch { /* network blip or stop() aborting us — handled below */ }
+      if (stopped) return;
+      if (!got) { await sleep(5000); continue; }
+      for (const c of got.commands || []) {
+        for (const fn of onCommand) { try { fn(c.body); } catch { /* handler's problem */ } }
+        post(`/api/sessions/${sessionId}/commands/${c.id}`, {});
+      }
+    }
+  }
+
+  return {
+    get id() { return sessionId; },
+    get url() { return sessionId ? `${api}/sessions/${sessionId}` : null; },
+    /** Register with the app. Resolves false when not logged in or unreachable. */
+    async start() {
+      if (!creds?.token) return false;
+      const r = await post("/api/sessions", {
+        name: `mosh @ ${os.hostname()}`,
+        host: os.hostname(),
+        version,
+        cwd,
+        ...size(),
+      });
+      if (!r?.id) return false;
+      sessionId = r.id;
+      // A resize carries no output of its own, so nudge a flush: the new
+      // geometry rides the next post and the watching browser reshapes with us
+      // instead of waiting for whatever gets printed next.
+      process.stdout.on("resize", onResize);
+      pump();
+      return true;
+    },
+    write,
+    setEngine,
+    /** Subscribe to commands sent from the web. Returns an unsubscribe fn. */
+    onCommand(fn) { onCommand.add(fn); return () => onCommand.delete(fn); },
+    async stop() {
+      if (!sessionId || stopped) return;
+      stopped = true;
+      clearTimeout(flushTimer);
+      clearTimeout(resizeTimer);
+      flushTimer = null;
+      resizeTimer = null;
+      process.stdout.off?.("resize", onResize);
+      try { poll?.abort(); } catch { /* already gone */ }
+      // Flush whatever is left before saying goodbye, so the last thing you
+      // did is visible in the mirror rather than lost with the process.
+      if (pending) {
+        const chunk = pending;
+        pending = "";
+        await post(`/api/sessions/${sessionId}/output`, { chunk, engine, ...size() });
+      }
+      await post(`/api/sessions/${sessionId}/end`, {});
+    },
+  };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Tee process stdout/stderr into `sink` while leaving the real terminal
+ * untouched. Returns a restore fn.
+ */
+export function teeOutput(sink) {
+  const targets = [process.stdout, process.stderr];
+  const originals = targets.map((s) => s.write.bind(s));
+  targets.forEach((stream, i) => {
+    stream.write = (chunk, enc, cb) => {
+      try { sink(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8")); }
+      catch { /* mirroring must never break printing */ }
+      return originals[i](chunk, enc, cb);
+    };
+  });
+  return () => targets.forEach((stream, i) => { stream.write = originals[i]; });
+}