@ours.network/install 0.17.0 → 0.18.0-nightly.2

package/lib/extras.mjs

@@ -0,0 +1,351 @@
+// ours-install v3 — the four retained extras, re-pointed at the v3 arrangement.
+//
+// The v3 installer keeps harness plugins, ours-fleet, voice setup and the
+// copy-paste hand-off prompt; spec v3's silence about them was an oversight.
+//
+// The shared daemon belongs to the operator CLI. ours-mcp is only a per-session
+// stdio adapter with no unit, and these extra phases preserve that boundary.
+//
+// Pure, like target.mjs / plan.mjs / components.mjs: no I/O, no subprocess, no
+// terminal. Every function takes what was observed and returns a plan; the
+// orchestrator (a later PR) is what performs it.
+
+import { dirname, join, resolve } from 'node:path';
+import { pkgSpec } from './logic.mjs';
+
+const cfgPath = (stateDir) => join(resolve(stateDir), 'config.json');
+
+// -----------------------------------------------------------------------------
+// §5 — harness plugins
+// -----------------------------------------------------------------------------
+
+export const CLAUDE_MARKET = 'adapt-toolkit/ours-claude-marketplace';
+export const CODEX_MARKET = 'adapt-toolkit/ours-codex-marketplace';
+
+export const HARNESSES = [
+  { name: 'claude-code', label: 'Claude Code' },
+  { name: 'codex', label: 'Codex' },
+  { name: 'hermes', label: 'Hermes' },
+];
+
+/**
+ * SPEC §5 PROMISES SOMETHING TWO OF THE THREE REGISTRATIONS CANNOT DO.
+ *
+ * §5: "For any other state directory the installer registers the harness MCP
+ * entry with OURS_CONFIG=<state-dir>/config.json in its environment, so the pair
+ * travels together." planMcpAttachment already returns exactly that harnessEnv —
+ * and the orchestrator only PRINTS it. That is not an oversight to be fixed by
+ * wiring it up harder; none of the three registrations can carry a value:
+ *
+ *   Claude Code  the marketplace plugin's mcpServers.ours is command+args, with
+ *                no env key, and `claude plugin install` injects nothing per
+ *                install.
+ *   Codex        .mcp.json's env_vars is an allowlist of NAMES, not a value map
+ *                (pinned by packages/codex/test/plugin-package.test.mjs). The
+ *                value must already be in the ambient environment.
+ *   Hermes       renderConfigBlock is OUR writer, and now emits an `env:` block
+ *                carrying OURS_CONFIG — so for Hermes the pair is real.
+ *
+ * So §5's guarantee is ALREADY unmet today for every non-default state
+ * directory, silently: the harness attaches to ~/.ours while the operator was
+ * told the run targeted somewhere else. The shape is:
+ *
+ *   default state directory   today's behaviour, byte for byte.
+ *   Hermes, non-default       real: the pair is handed to ours-hermes-install's
+ *                             invocation and written into ~/.hermes/config.yaml
+ *                             as the ours server's own env block.
+ *   Claude / Codex, non-def   install the plugin (it is still the right plugin)
+ *                             and PRINT the exact line the operator must add.
+ *                             Never claim §5's guarantee in the screen text.
+ *
+ * Deliberately NOT done: registering a second, user-scoped `ours` MCP server via
+ * `claude mcp add --env`. Two `ours` servers in front of one harness, and which
+ * wins is not something anyone here has verified.
+ */
+export const HARNESS_ENV_SUPPORT = {
+  // 'applied' — the pair is genuinely carried into the registration.
+  // 'printed' — the operator is told the exact line and nothing is claimed.
+  'claude-code': 'printed',
+  codex: 'printed',
+  hermes: 'applied',
+};
+
+const manualSteps = {
+  'claude-code': (channel) => [
+    `/plugin marketplace add ${CLAUDE_MARKET}`,
+    '/plugin install ours',
+  ],
+  codex: (channel) => [
+    `codex plugin marketplace add ${CODEX_MARKET}`,
+    'codex plugin add ours@ours-codex-marketplace',
+    `npm i -g ${pkgSpec('codex', channel)}`,
+  ],
+  hermes: (channel) => [
+    `npm i -g ${pkgSpec('hermes', channel)}`,
+    'ours-hermes-install',
+  ],
+};
+
+const driveSteps = {
+  'claude-code': (channel) => [
+    ['claude', 'plugin', 'marketplace', 'add', CLAUDE_MARKET],
+    ['claude', 'plugin', 'install', 'ours@ours.network'],
+  ],
+  codex: (channel) => [
+    ['codex', 'plugin', 'marketplace', 'add', CODEX_MARKET],
+    ['codex', 'plugin', 'add', 'ours@ours-codex-marketplace'],
+    // Owner-mandated in v2 and kept: choosing the Codex plugin also installs the
+    // ours-codex live launcher, in the same step.
+    ['npm', 'i', '-g', pkgSpec('codex', channel)],
+  ],
+  // Hermes has no driven CLI: nothing here ever calls a `hermes` binary. Its
+  // plugin install is npm + ours-hermes-install, which writes ~/.hermes.
+  // --skip-daemon because in v3 the daemon is emphatically not ours-mcp's.
+  hermes: (channel) => [
+    ['npm', 'i', '-g', pkgSpec('hermes', channel)],
+    ['ours-hermes-install', '--skip-daemon'],
+  ],
+};
+
+/**
+ * One plan per harness the caller observed.
+ *
+ * `harnesses` is [{ name, status }] where status is classifyHarnessProbe's
+ * verdict ('ok' | 'alias' | 'unsafe' | 'absent'). Hermes is detected by its
+ * config directory rather than a CLI, which is the caller's business; this only
+ * consumes the verdict.
+ *
+ * The v2 golden rule is kept intact: 'alias' / 'unsafe' NEVER dead-end. A
+ * harness we cannot safely drive still gets its manual steps printed, so the
+ * plugin is still installable.
+ *
+ * `env` is what an invocation must carry, and it is EMPTY unless the harness can
+ * genuinely apply it. `envLine` is what the operator is told. `claimsPair` is
+ * false whenever the pair is only printed — the screen text renderer reads it so
+ * §5's guarantee cannot be claimed where it does not hold.
+ */
+export function planHarnessPlugins({
+  harnesses = [],
+  stateDir,
+  isDefaultStateDir,
+  channel = 'latest',
+  assumeYes = false,
+  answers = {},
+} = {}) {
+  const config = stateDir ? cfgPath(stateDir) : null;
+  return harnesses.map((h) => {
+    const name = String(h?.name ?? '');
+    const known = HARNESSES.find((k) => k.name === name);
+    const label = known?.label ?? name;
+    const status = String(h?.status ?? 'absent');
+    const support = HARNESS_ENV_SUPPORT[name] ?? 'printed';
+    const applies = !isDefaultStateDir && support === 'applied';
+
+    const base = {
+      name,
+      label,
+      status,
+      // Default state directory → today's behaviour, byte for byte: no env
+      // anywhere, nothing extra printed, nothing claimed.
+      envSupport: isDefaultStateDir ? 'none' : support,
+      env: applies ? { OURS_CONFIG: config } : {},
+      envLine: isDefaultStateDir || applies ? null : `export OURS_CONFIG=${config}`,
+      claimsPair: isDefaultStateDir ? true : applies,
+      manual: manualSteps[name] ? manualSteps[name](channel) : [],
+    };
+
+    if (!known) return { ...base, action: 'skip', reason: 'unknown harness' };
+    if (status === 'absent') return { ...base, action: 'skip', reason: 'not installed' };
+
+    const wanted = assumeYes ? true : answers[name] !== false;
+    if (!wanted) return { ...base, action: 'skip', reason: 'declined', offerOnRerun: true };
+
+    if (status === 'ok') return { ...base, action: 'drive', steps: driveSteps[name](channel) };
+    return {
+      ...base,
+      action: 'manual',
+      reason: status === 'alias' ? 'installed as an alias, not the real command' : 'found, but did not answer --version',
+    };
+  });
+}
+
+// -----------------------------------------------------------------------------
+// §5 — what the operator has to do BEFORE any of this works
+// -----------------------------------------------------------------------------
+
+/**
+ * The restart each harness needs before its new plugin is live.
+ *
+ * A CORRECTNESS PROBLEM WEARING A COSMETIC COSTUME. The ours MCP server is spawned
+ * BY the harness, once per session (`ours-mcp proxy` over stdio), so a harness that
+ * was already running when its plugin was installed has no ours tools and will not
+ * get them until it restarts. v3 said nothing at all about this: the screen read
+ * "Everything installed cleanly", the user went back to a running Claude Code,
+ * found no ours tools, and concluded the install had failed. The nightly installer
+ * prints these hints and v3 dropped them.
+ *
+ * Derived from what THIS RUN installed rather than from a registry — v3 already
+ * knows, and its own summary is a better source than a persisted file that can go
+ * stale against reality.
+ *
+ * The connectors are deliberately absent. The installer runs their
+ * `install-service` itself, so their new configuration is already applied; telling
+ * someone to restart something that was just restarted for them is noise, and noise
+ * in this list is what stops the real lines being read.
+ */
+export const HARNESS_RESTART = {
+  'claude-code': 'restart Claude Code',
+  codex: 'start a new Codex session (or `ours-codex`)',
+  hermes: 'run /reload-mcp in Hermes',
+};
+
+export function restartHints(summary = []) {
+  const live = (row) => row && (row.state === 'installed' || row.state === 'current');
+  const hints = [];
+  for (const [name, action] of Object.entries(HARNESS_RESTART)) {
+    const row = summary.find((r) => r.key === name);
+    if (live(row)) hints.push({ key: name, action });
+  }
+  // Nothing to restart if no harness got a plugin this run. The MCP server on its
+  // own changes nothing a running harness can see, so an "install the MCP server
+  // and restart everything" line would be advice with no reason behind it.
+  return hints;
+}
+
+// -----------------------------------------------------------------------------
+// ours-fleet — installed and staged, never started implicitly
+// -----------------------------------------------------------------------------
+
+export const fleetConfigPath = (home) => join(resolve(home), 'fleet.yaml');
+
+const yamlString = (value) => JSON.stringify(String(value));
+
+/** A conservative, useful first fleet: one coordinator, one watchdog, one loop. */
+export function defaultFleetConfig({ home, stateDir, isDefaultStateDir } = {}) {
+  const cwd = resolve(home);
+  const config = stateDir ? cfgPath(stateDir) : null;
+  const roleEnv = isDefaultStateDir || !config
+    ? ''
+    : `\n    env:\n      OURS_CONFIG: ${yamlString(config)}`;
+  return `# Generated by ours-install. Review this file before starting Fleet.\n`
+    + `defaults:\n`
+    + `  harness: codex\n`
+    + `  session: acp\n`
+    + `  permissions:\n`
+    + `    approval: allow\n`
+    + `    filesystem: workspace\n`
+    + `    unattended: wait\n`
+    + `  monitor:\n`
+    + `    mode: fleet\n\n`
+    + `roles:\n`
+    + `  FleetCoordinator:\n`
+    + `    identity: FleetCoordinator\n`
+    + `    cwd: ${yamlString(cwd)}\n`
+    + `    mission: Coordinate durable agent work, delegate bounded tasks, and report material outcomes.\n`
+    + `    bio: Fleet coordinator for this host; engage it to assign work or check agent status.\n`
+    + `    persona: |\n`
+    + `      Keep a concise durable worklog. Preserve user state, verify delegated results,\n`
+    + `      and escalate decisions that require new authority. Report material progress only.${roleEnv}\n\n`
+    + `watchdogs:\n`
+    + `  fleet-health:\n`
+    + `    coordinator: FleetCoordinator\n`
+    + `    watch: [FleetCoordinator]\n`
+    + `    harness: codex\n`
+    + `    session: acp\n`
+    + `    interval: 10m\n`
+    + `    timeout: 8m\n\n`
+    + `loops:\n`
+    + `  coordinator_health:\n`
+    + `    roles: [FleetCoordinator]\n`
+    + `    interval: 10m\n`
+    + `    initial_delay: 10m\n`
+    + `    enabled: true\n`
+    + `    prompt: |\n`
+    + `      Perform one bounded fleet health pass. Reconcile active work, specialist state,\n`
+    + `      declared blockers, and CI. Unstick only safe in-scope work. If nothing material\n`
+    + `      changed, complete silently.\n`;
+}
+
+export function planFleet({ home, stateDir, isDefaultStateDir, wanted = true, channel = 'latest' } = {}) {
+  const config = stateDir ? cfgPath(stateDir) : null;
+  const resolvedHome = home ?? (stateDir ? dirname(resolve(stateDir)) : null);
+  const path = resolvedHome ? fleetConfigPath(resolvedHome) : null;
+  const plan = {
+    key: 'fleet',
+    label: 'ours-fleet',
+    // FOLLOWS THE CHANNEL, and the correction matters more than it looks.
+    //
+    // This comment used to say the opposite — that ours-fleet lives in its own
+    // repo and publishes no nightly tag, so pkgSpec pinned it to @latest. That
+    // was true when v3 was written against `main` and it is FALSE here: fleet
+    // does publish a nightly dist-tag, and the nightly stack needs the fleet
+    // build carrying the SDK integration. A nightly installer that quietly
+    // installs stable fleet is precisely the split-brain deployment the channel
+    // exists to prevent — the same architecture boundary that made a mixed
+    // tg-connector fatal. lib/logic.mjs is the single source of that mapping and
+    // this defers to it rather than restating it.
+    install: ['npm', 'i', '-g', pkgSpec('fleet', channel)],
+    init: ['ours-fleet', 'init'],
+    configPath: path,
+    config: resolvedHome ? defaultFleetConfig({ home: resolvedHome, stateDir, isDefaultStateDir }) : null,
+    writes: path ? [path] : [],
+    roleEnv: isDefaultStateDir ? {} : { OURS_CONFIG: config },
+    instruction: isDefaultStateDir
+      ? `review ${path}, then run ours-fleet doctor and ours-fleet up when you are ready`
+      : `review ${path}; its coordinator is pinned to this daemon with OURS_CONFIG=${config}`,
+  };
+  return wanted ? { ...plan, action: 'install' } : { ...plan, action: 'skip', offerOnRerun: true };
+}
+
+// -----------------------------------------------------------------------------
+// the copy-paste hand-off prompt
+// -----------------------------------------------------------------------------
+
+/**
+ * buildHandoffPrompt is pure, renumbers automatically, and drops steps for
+ * components that were not installed. The default path needs no daemon preamble;
+ * a non-default path names the exact config so the assistant cannot guess.
+ */
+export function buildHandoffPromptV3({
+  identity = false,
+  fleet = false,
+  telegram = false,
+  stateDir = null,
+  isDefaultStateDir = true,
+} = {}) {
+  const steps = [];
+  if (identity) {
+    steps.push(
+      'Create my Ours human identity — this is me, the human; my agents act on\n'
+      + '   my behalf. Ask me what name others should see, then create it.',
+    );
+  }
+  if (fleet) {
+    steps.push(
+      'Review ~/fleet.yaml with me. It already contains a stopped FleetCoordinator,\n'
+      + '   a fleet-health watchdog, and a 10-minute coordinator health loop. Ask\n'
+      + '   before changing permissions or starting the fleet.',
+    );
+  }
+  if (telegram) {
+    steps.push(
+      'Finish my Telegram setup without exposing secrets: ask me for the bot name\n'
+      + '   and guide me through entering the @BotFather token locally. Register the\n'
+      + '   route, then start the connector only after I approve.',
+    );
+  }
+  if (steps.length === 0) return { text: '', empty: true };
+
+  const preamble = isDefaultStateDir || !stateDir
+    ? ''
+    : `My ours daemon uses the state directory ${resolve(stateDir)} (config\n${cfgPath(stateDir)}). When you configure anything for me — fleet roles,\nharness environments — set OURS_CONFIG to that path.\n\n`;
+
+  const numbered = steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
+  const text = preamble
+    + 'I just installed the ours.network stack. Please help me finish setup, one\n'
+    + 'step at a time, explaining as you go:\n\n'
+    + numbered + '\n\n'
+    + 'Do these in order, wait for my answers, and tell me if you need anything\n'
+    + "from me. Don't assume — ask.";
+  return { text, empty: false };
+}

package/lib/journal.mjs

@@ -0,0 +1,158 @@
+// ours-install v3 — the config journal.
+//
+// WHAT THIS IS FOR, IN ONE SENTENCE: v3 could write a config file describing a
+// daemon it then failed to bring up, print one warning line, and go on to say
+// "install complete".
+//
+// The nightly installer does not have that failure. It snapshots every config
+// file before touching it and restores the bytes when the plan does not complete
+// (lib/nightly-install.mjs `snap`/`rollbackSnapshots`), and it says precisely what
+// it could NOT undo. This is that behaviour, carried into v3's shape rather than
+// copied into it.
+//
+// THE LINE THIS DOES NOT CROSS. Package and plugin installs are NOT rolled back.
+// Not because it is hard, but because it is wrong: npm cannot be un-run
+// meaningfully, a newer package is not damage, and nightly draws the line in the
+// same place and says so. What gets restored is exactly the bytes of files this
+// installer rewrote. Everything else is REPORTED.
+//
+// SCOPE IS PER UNIT OF WORK, NOT PER RUN, and that is the one design decision
+// here worth reading twice. v3's rule is that a failed extra never undoes a
+// daemon that came up correctly (lib/orchestrate.mjs `attempt`), so a single
+// run-wide journal restored at the end would fight the architecture: a cowork
+// failure would roll back the daemon's own config. Instead each journal covers
+// ONE write and the step that makes its bytes true — write the connector config,
+// then install its service; if the service does not come up, the config goes
+// back. The pairing is the whole idea, and it is why `snapshot` and `restoreAll`
+// are on an object you hold for the length of one unit of work rather than
+// functions you call anywhere.
+
+import { ok, info, warn } from './ui.mjs';
+
+/**
+ * A journal for one unit of work.
+ *
+ * `effects.snapshot(path)` and `effects.restore(path, snapshot)` are the seam, so
+ * this is testable without a filesystem for the same reason everything else here
+ * is. On a dry run nothing was written, so nothing is snapshotted and nothing can
+ * be restored — the journal is inert rather than special-cased at each call site.
+ */
+export function configJournal(effects, { dryRun = false } = {}) {
+  const entries = [];
+  return {
+    get entries() { return entries.slice(); },
+
+    /**
+     * Record the current bytes of `path` BEFORE it is written. Idempotent per
+     * path: the FIRST snapshot is the one that survives, because that is the
+     * state the run started from. Snapshotting twice and keeping the second would
+     * "restore" to a value this run itself wrote.
+     */
+    snapshot(path) {
+      if (dryRun) return null;
+      if (entries.some((e) => e.path === path)) return entries.find((e) => e.path === path).snapshot;
+      const snapshot = effects.snapshot(path);
+      entries.push({ path, snapshot });
+      return snapshot;
+    },
+
+    /**
+     * Put every journalled file back, most recent first.
+     *
+     * A restore that itself fails is reported, never thrown: the caller is already
+     * on a failure path, and losing the original error to a second one would hide
+     * the thing that actually went wrong. The report says which files went back
+     * and which did not, so a partially recovered state is visible rather than
+     * implied.
+     */
+    restoreAll() {
+      const restored = [];
+      const failed = [];
+      for (const entry of entries.slice().reverse()) {
+        try {
+          effects.restore(entry.path, entry.snapshot);
+          // A write that RETURNED is not a file that HOLDS. Read the bytes back.
+          const mismatch = verifyRestored(effects, entry);
+          if (mismatch) failed.push({ path: entry.path, reason: mismatch });
+          else restored.push({ path: entry.path, existed: entry.snapshot?.exists !== false });
+        } catch (error) {
+          failed.push({ path: entry.path, reason: error instanceof Error ? error.message : String(error) });
+        }
+      }
+      entries.length = 0;
+      return { restored, failed };
+    },
+  };
+}
+
+/**
+ * Did the restore actually take? Returns null when it did, or the reason it did not.
+ *
+ * WHY THIS EXISTS. `restore` returning is evidence that a call completed, not that
+ * a file holds the bytes it was given. A full disk, a read-only mount, a rename
+ * that lands somewhere else, an editor holding the inode — each of those can let
+ * the write return and leave the old contents in place. Reporting on the call
+ * rather than on the state is how a rollback comes to LIE, and a rollback that
+ * lies is worse than one that admits it failed: the operator is told the machine
+ * is back where it was and stops looking.
+ *
+ * The read-back seam is `effects.snapshot`, the same one used to record the bytes
+ * in the first place — it already returns exactly the shape being compared, so
+ * this needs no second seam and no second notion of what a file's state is.
+ *
+ * Its own failure is a mismatch, not an exception: if the file cannot be read
+ * after being written, that is precisely the case this check exists to catch.
+ */
+function verifyRestored(effects, entry) {
+  const expected = entry.snapshot;
+  let actual;
+  try {
+    actual = effects.snapshot(entry.path);
+  } catch (error) {
+    return `restored, but the file could not be read back to confirm it (${error instanceof Error ? error.message : String(error)})`;
+  }
+  const shouldExist = expected?.exists !== false;
+  if (!shouldExist) {
+    return actual?.exists ? 'this run created it and the removal did not take — the file is still there' : null;
+  }
+  if (!actual?.exists) return 'the restore reported success but the file is not there';
+  if (actual.text !== expected.text) return 'the restore reported success but the bytes on disk are not the previous ones';
+  // Bytes first, permissions second: the contents are back either way, so this
+  // must not be reported as "could not restore the config".
+  if (expected.mode !== undefined && actual.mode !== undefined && actual.mode !== expected.mode) {
+    return `contents restored, but the permissions are ${fmtMode(actual.mode)} and were ${fmtMode(expected.mode)} — check them before re-running`;
+  }
+  return null;
+}
+
+const fmtMode = (mode) => `0${(mode & 0o777).toString(8).padStart(3, '0')}`;
+
+/**
+ * The report, and it is half the feature.
+ *
+ * A rollback nobody is told about is indistinguishable from a run that did
+ * nothing. Three separate facts, each stated plainly:
+ *
+ *   · which files were put back, and whether "back" meant deleting one this run
+ *     created — because "restored" and "removed the file we made" are different
+ *     things to read on a screen;
+ *   · which could not be put back, if any;
+ *   · that completed package installs were NOT rolled back. This last line is the
+ *     honest boundary, and it is nightly's wording rather than a new one.
+ */
+export function reportRollback(effects, outcome, { packagesInstalled = false } = {}) {
+  const { restored = [], failed = [] } = outcome ?? {};
+  if (restored.length === 0 && failed.length === 0) return false;
+  for (const item of restored) {
+    effects.out(item.existed
+      ? ok(`rolled back ${item.path} to its previous contents`)
+      : ok(`removed ${item.path} — this run created it and did not finish`));
+  }
+  for (const item of failed) {
+    effects.out(warn(`could NOT roll back ${item.path}: ${item.reason} — inspect it before re-running`));
+  }
+  if (packagesInstalled) {
+    effects.out(info('completed package installs were not rolled back — a newer package is not damage, and npm cannot be un-run'));
+  }
+  return true;
+}