@saadnvd1/agent-os 0.3.794 → 0.3.807

package/scripts/update-run.mjs

@@ -1,25 +1,38 @@
 #!/usr/bin/env node
 // Runs one update, started detached by the server so it survives the restart.
-// Runs scripts/redeploy, follows its "::phase <name>" lines into the state
-// file the server and the browser read, and writes how it ended.
+// Backs the database up, runs scripts/redeploy, follows its "::phase" and
+// "::stage" lines into the state file the server and the browser read, then
+// checks the restarted server and, when it isn't healthy, rolls back.
 //   AGENTOS_UPDATE_STATE  the state file (JSON, written atomically)
 //   AGENTOS_RESTART       the restart command; none means "built, restart it yourself"
+//   AGENTOS_UPDATE_TO     the commit to update to (default: the remote's head)
+//   AGENTOS_UPDATE_DB     the database to back up first, into AGENTOS_UPDATE_BACKUPS
+//   AGENTOS_UPDATE_VERIFY=0  skip the health check (tests)
 //   AGENTOS_UPDATE_REDEPLOY  the script to run (tests); default scripts/redeploy
-import { spawn } from "node:child_process";
+//   AGENTOS_UPDATE_ROOT   the checkout (tests); default this script's
+// Outcomes: done, built, build_failed (live server untouched), rolled_back,
+// broken (the rollback didn't come up either).
+import { execFileSync, spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
+import { verifyServer } from "./lib/update-verify.mjs";
 
-const file = process.env.AGENTOS_UPDATE_STATE;
+const env = process.env;
+const file = env.AGENTOS_UPDATE_STATE;
 if (!file) {
   console.error("AGENTOS_UPDATE_STATE is not set");
   process.exit(2);
 }
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const root =
+  env.AGENTOS_UPDATE_ROOT ||
+  path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const script =
-  process.env.AGENTOS_UPDATE_REDEPLOY || path.join(root, "scripts/redeploy");
+  env.AGENTOS_UPDATE_REDEPLOY || path.join(root, "scripts/redeploy");
 const PHASES = new Set(["pulling", "installing", "building", "restarting"]);
+const STAGES = ["pulled", "deps_swapped", "build_swapped"];
+const KEEP_BACKUPS = 3;
 
 function read() {
   try {
@@ -29,7 +42,7 @@ function read() {
   }
 }
 function write(patch) {
-  const run = { ...(read() ?? {}), ...patch };
+  const run = { ...(read() ?? {}), ...patch, updatedAt: Date.now() };
   const tmp = `${file}.${process.pid}.tmp`;
   fs.writeFileSync(tmp, JSON.stringify(run));
   fs.renameSync(tmp, file);
@@ -40,43 +53,172 @@ const keep = (line) => {
   tail.push(line);
   if (tail.length > 30) tail.shift();
 };
+const say = (line) => {
+  keep(line);
+  console.log(line);
+};
 
-const child = spawn("bash", [script], {
-  cwd: root,
-  env: process.env,
-  stdio: ["ignore", "pipe", "pipe"],
-});
-for (const stream of [child.stdout, child.stderr]) {
-  readline.createInterface({ input: stream }).on("line", (line) => {
-    const m = /^::phase (\w+)$/.exec(line);
-    if (m && PHASES.has(m[1])) return write({ phase: m[1] });
-    keep(line);
-    console.log(line);
-  });
-}
-child.on("error", (error) =>
+const finish = (phase, outcome, error) =>
   write({
-    phase: "failed",
+    phase,
+    outcome,
     finishedAt: Date.now(),
-    error: error.message,
     log: tail,
-  })
-);
-child.on("close", (code) => {
-  // The server may have marked this done already when it came back up.
-  const phase = read()?.phase;
-  if (code === 0) {
-    write({
-      phase: process.env.AGENTOS_RESTART ? "done" : "built",
-      finishedAt: Date.now(),
-      log: tail,
+    ...(error ? { error } : {}),
+  });
+
+/** Runs redeploy with args; resolves its exit code and the furthest stage. */
+function redeploy(args) {
+  return new Promise((resolve) => {
+    let stage = null;
+    const child = spawn("bash", [script, ...args], {
+      cwd: root,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
     });
-  } else if (phase !== "done") {
-    write({
-      phase: "failed",
-      finishedAt: Date.now(),
-      error: `The update failed (exit ${code}). The running server was not changed unless it says otherwise below.`,
-      log: tail,
+    for (const stream of [child.stdout, child.stderr]) {
+      readline.createInterface({ input: stream }).on("line", (line) => {
+        const p = /^::phase (\w+)$/.exec(line);
+        if (p && PHASES.has(p[1])) return write({ phase: p[1] });
+        const s = /^::stage (\w+)$/.exec(line);
+        if (s && STAGES.includes(s[1])) {
+          stage = s[1];
+          return write({ stage });
+        }
+        say(line);
+      });
+    }
+    child.on("error", (error) => {
+      say(error.message);
+      resolve({ code: -1, stage });
     });
+    child.on("close", (code) => resolve({ code: code ?? -1, stage }));
+  });
+}
+
+async function backup() {
+  const db = env.AGENTOS_UPDATE_DB;
+  const dir = env.AGENTOS_UPDATE_BACKUPS;
+  if (!db || !dir || !fs.existsSync(db)) return;
+  write({ phase: "backing_up" });
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").slice(0, 15);
+  const from = String(read()?.from ?? "").slice(0, 7) || "unknown";
+  const out = path.join(dir, `agent-os-${stamp}-update-${from}.db`);
+  // Loaded from this checkout before the install swaps node_modules.
+  const { default: Sqlite } = await import(
+    path.join(root, "node_modules/better-sqlite3/lib/index.js")
+  );
+  const src = new Sqlite(db, { readonly: true, fileMustExist: true });
+  try {
+    // The online backup copies pages between the server's writes.
+    await src.backup(out);
+  } finally {
+    src.close();
+  }
+  fs.chmodSync(out, 0o600);
+  say(`Backed up the database to ${path.basename(out)}`);
+  const old = fs
+    .readdirSync(dir)
+    .filter((f) => /^agent-os-\d{8}T\d{6}-update-\w+\.db$/.test(f))
+    .sort()
+    .slice(0, -KEEP_BACKUPS);
+  for (const f of old) fs.rmSync(path.join(dir, f), { force: true });
+}
+
+const head = () => {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { cwd: root })
+      .toString()
+      .trim();
+  } catch {
+    return null;
+  }
+};
+
+/** A pull that never got built in is undone, so source and build agree. */
+function resetSource(from) {
+  if (!from || head() === from) return;
+  try {
+    execFileSync("git", ["reset", "-q", "--keep", from], { cwd: root });
+    say(`Put the source back to ${from.slice(0, 7)}.`);
+  } catch (error) {
+    say(
+      `Couldn't put the source back to ${from.slice(0, 7)}: ${error.message}`
+    );
+  }
+}
+
+async function main() {
+  const heartbeat = setInterval(() => write({}), 15_000);
+  write({ pid: process.pid });
+  const from = read()?.from || head();
+  try {
+    try {
+      await backup();
+    } catch (error) {
+      return finish(
+        "failed",
+        "build_failed",
+        `Couldn't back up the database first, so nothing was changed: ${error.message}`
+      );
+    }
+
+    const up = await redeploy([]);
+    const swapped = up.stage === "build_swapped";
+    if (up.code !== 0 && !swapped) {
+      if (up.stage) resetSource(from);
+      return finish(
+        "failed",
+        "build_failed",
+        `The update failed (exit ${up.code}). The running server was not changed.`
+      );
+    }
+    if (!env.AGENTOS_RESTART) return finish("built", "done");
+
+    let why = up.code === 0 ? null : "it didn't come back after the restart";
+    if (!why && env.AGENTOS_UPDATE_VERIFY !== "0") {
+      write({ phase: "verifying" });
+      const ok = await verifyServer({
+        port: env.PORT || "3011",
+        expect: env.AGENTOS_UPDATE_TO || head(),
+        env,
+      });
+      if (!ok.ok) why = ok.why;
+    }
+    if (!why) return finish("done", "done");
+
+    say(`The new version isn't healthy: ${why}. Rolling back.`);
+    write({ phase: "rolling_back", error: why });
+    const back = await redeploy(
+      from ? ["--rollback", "--to", from] : ["--rollback"]
+    );
+    let backOk = back.code === 0;
+    if (backOk && env.AGENTOS_UPDATE_VERIFY !== "0") {
+      const ok = await verifyServer({
+        port: env.PORT || "3011",
+        expect: from,
+        env,
+      });
+      if (!ok.ok) {
+        backOk = false;
+        say(`The rolled-back version isn't healthy either: ${ok.why}`);
+      }
+    }
+    return backOk
+      ? finish(
+          "rolled_back",
+          "rolled_back",
+          `The new version wasn't healthy (${why}), so AgentOS went back to the previous one.`
+        )
+      : finish(
+          "failed",
+          "broken",
+          `The new version wasn't healthy (${why}) and rolling back didn't work either. See the update log; scripts/redeploy --rollback puts the previous build back.`
+        );
+  } finally {
+    clearInterval(heartbeat);
   }
-});
+}
+
+main().catch((error) => finish("failed", "build_failed", error.message));

package/scripts/update-run.test.ts

@@ -1,5 +1,7 @@
-import { execFile } from "child_process";
+import { execFile, execFileSync } from "child_process";
 import fs from "fs";
+import http from "http";
+import type { AddressInfo } from "net";
 import path from "path";
 import { promisify } from "util";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -18,7 +20,11 @@ beforeEach(() => {
 });
 afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
 
-const go = async (script: string, restart?: string) => {
+const go = async (
+  script: string,
+  restart?: string,
+  extra: Record<string, string> = {}
+) => {
   const redeploy = path.join(dir, "redeploy");
   fs.writeFileSync(redeploy, `#!/usr/bin/env bash\n${script}\n`, {
     mode: 0o755,
@@ -27,7 +33,14 @@ const go = async (script: string, restart?: string) => {
     ...process.env,
     AGENTOS_UPDATE_STATE: path.join(dir, "state.json"),
     AGENTOS_UPDATE_REDEPLOY: redeploy,
+    // Never the real checkout: a failed run resets the source.
+    AGENTOS_UPDATE_ROOT: dir,
+    AGENTOS_UPDATE_VERIFY: "0",
   };
+  delete env.AGENTOS_UPDATE_DB;
+  delete env.AGENTOS_UPDATE_TO;
+  delete env.PORT;
+  Object.assign(env, extra);
   if (restart) env.AGENTOS_RESTART = restart;
   else delete env.AGENTOS_RESTART;
   await exec(process.execPath, [runner], { env }).catch(() => {});
@@ -62,3 +75,196 @@ describe("scripts/update-run.mjs", () => {
     expect(s.log.at(-1)).toBe("line50");
   });
 });
+
+// A stand-in for the restarted server: its build comes from a file the fake
+// redeploy writes, and its startedAt can be made to change (a crash loop).
+async function fakeServer(opts: { restarts?: boolean } = {}) {
+  let n = 0;
+  const server = http.createServer((req, res) => {
+    const build = fs.readFileSync(path.join(dir, "build"), "utf8").trim();
+    res.setHeader("content-type", "application/json");
+    if (req.url === "/api/updates/health")
+      return res.end(
+        JSON.stringify({
+          ok: true,
+          build,
+          startedAt: opts.restarts ? `s${n++}` : "s",
+          migrations: { known: 3, applied: 3 },
+        })
+      );
+    res.end("{}");
+  });
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  return {
+    port: String((server.address() as AddressInfo).port),
+    close: () => new Promise((r) => server.close(r)),
+  };
+}
+
+const verifying = (port: string, to: string): Record<string, string> => ({
+  AGENTOS_UPDATE_VERIFY: "1",
+  AGENTOS_UPDATE_TO: to,
+  PORT: port,
+  AGENTOS_VERIFY_UP_MS: "300",
+  AGENTOS_VERIFY_EVERY_MS: "20",
+  AGENTOS_VERIFY_CHECKS: "2",
+});
+
+// Updates to "new"; a rollback writes "a" (the run's from) as the build.
+const REDEPLOY = `
+if [ "$1" = --rollback ]; then
+  echo "$*" > "${"$"}AGENTOS_UPDATE_ROOT/rolled"
+  [ -f "${"$"}AGENTOS_UPDATE_ROOT/rollback-works" ] && echo a > "${"$"}AGENTOS_UPDATE_ROOT/build"
+  echo "::stage build_swapped"
+  exit 0
+fi
+echo "::stage build_swapped"
+cat "${"$"}AGENTOS_UPDATE_ROOT/next-build" > "${"$"}AGENTOS_UPDATE_ROOT/build"
+`;
+
+describe("scripts/update-run.mjs checks the new server", () => {
+  const rolled = () =>
+    fs.existsSync(path.join(dir, "rolled"))
+      ? fs.readFileSync(path.join(dir, "rolled"), "utf8").trim()
+      : null;
+
+  it("a healthy server on the new build finishes done", async () => {
+    fs.writeFileSync(path.join(dir, "next-build"), "new");
+    const srv = await fakeServer();
+    try {
+      const s = await go(REDEPLOY, "x", verifying(srv.port, "new"));
+      expect(s).toMatchObject({ phase: "done", outcome: "done" });
+      expect(rolled()).toBeNull();
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("a server on the wrong build is rolled back to where it was", async () => {
+    fs.writeFileSync(path.join(dir, "next-build"), "stale");
+    fs.writeFileSync(path.join(dir, "rollback-works"), "");
+    const srv = await fakeServer();
+    try {
+      const s = await go(REDEPLOY, "x", verifying(srv.port, "new"));
+      expect(s).toMatchObject({ phase: "rolled_back", outcome: "rolled_back" });
+      expect(s.error).toContain("stale");
+      expect(rolled()).toBe("--rollback --to a");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("a crash loop (startedAt changing) is rolled back, and ends broken when the old build loops too", async () => {
+    fs.writeFileSync(path.join(dir, "next-build"), "new");
+    fs.writeFileSync(path.join(dir, "rollback-works"), "");
+    const srv = await fakeServer({ restarts: true });
+    try {
+      const s = await go(REDEPLOY, "x", {
+        ...verifying(srv.port, "new"),
+      });
+      expect(s.outcome).toBe("broken");
+      expect(s.error).toContain("crash loop");
+      expect(rolled()).toBe("--rollback --to a");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("when the rollback doesn't come up either, it ends broken", async () => {
+    fs.writeFileSync(path.join(dir, "next-build"), "stale");
+    const srv = await fakeServer();
+    try {
+      const s = await go(REDEPLOY, "x", verifying(srv.port, "new"));
+      expect(s).toMatchObject({ phase: "failed", outcome: "broken" });
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("a server that never came back after the restart is rolled back", async () => {
+    fs.writeFileSync(path.join(dir, "rollback-works"), "");
+    const s = await go(
+      'if [ "$1" = --rollback ]; then echo "$*" > "$AGENTOS_UPDATE_ROOT/rolled"; exit 0; fi\necho "::stage build_swapped"\nexit 1',
+      "x"
+    );
+    expect(s).toMatchObject({ phase: "rolled_back", outcome: "rolled_back" });
+    expect(rolled()).toBe("--rollback --to a");
+  });
+});
+
+describe("scripts/update-run.mjs before the swap", () => {
+  const git = (...args: string[]) =>
+    execFileSync("git", args, { cwd: dir, encoding: "utf8" }).trim();
+
+  it("a failed build after the pull puts the source back and records build_failed", async () => {
+    git("init", "-q");
+    git(
+      "-c",
+      "user.email=t@t",
+      "-c",
+      "user.name=t",
+      "commit",
+      "-q",
+      "--allow-empty",
+      "-m",
+      "one"
+    );
+    const from = git("rev-parse", "HEAD");
+    git(
+      "-c",
+      "user.email=t@t",
+      "-c",
+      "user.name=t",
+      "commit",
+      "-q",
+      "--allow-empty",
+      "-m",
+      "two"
+    );
+    fs.writeFileSync(
+      path.join(dir, "state.json"),
+      JSON.stringify({ id: "r1", phase: "starting", from })
+    );
+    const s = await go('echo "::stage pulled"\nexit 1', "x");
+    expect(s).toMatchObject({ phase: "failed", outcome: "build_failed" });
+    expect(git("rev-parse", "HEAD")).toBe(from);
+    expect(s.stage).toBe("pulled");
+  });
+
+  it("a failure before the pull leaves the source alone", async () => {
+    const s = await go("exit 1", "x");
+    expect(s.outcome).toBe("build_failed");
+    expect(s.log.join("\n")).not.toContain("Put the source back");
+  });
+
+  it("backs the database up first and keeps the last three", async () => {
+    fs.symlinkSync(
+      path.resolve(__dirname, "../node_modules"),
+      path.join(dir, "node_modules")
+    );
+    const { default: Sqlite } = await import("better-sqlite3");
+    const db = new Sqlite(path.join(dir, "live.db"));
+    db.exec("CREATE TABLE t (x); INSERT INTO t VALUES (42)");
+    db.close();
+    const backups = path.join(dir, "backups");
+    fs.mkdirSync(backups);
+    for (const d of ["20200101T000000", "20200102T000000", "20200103T000000"])
+      fs.writeFileSync(path.join(backups, `agent-os-${d}-update-a.db`), "");
+    const s = await go("echo ok", undefined, {
+      AGENTOS_UPDATE_DB: path.join(dir, "live.db"),
+      AGENTOS_UPDATE_BACKUPS: backups,
+    });
+    expect(s.phase).toBe("built");
+    const files = fs.readdirSync(backups).sort();
+    expect(files).toHaveLength(3);
+    const copy = new Sqlite(path.join(backups, files[2]), { readonly: true });
+    expect(copy.prepare("SELECT x FROM t").get()).toEqual({ x: 42 });
+    copy.close();
+  });
+
+  it("writes its pid and a heartbeat", async () => {
+    const s = await go("echo ok");
+    expect(s.pid).toBeTypeOf("number");
+    expect(s.updatedAt).toBeTypeOf("number");
+  });
+});

package/server.ts

@@ -500,8 +500,9 @@ app.prepare().then(async () => {
   startWaitWatcher();
   // Schedules tick here, once a minute, and nowhere else.
   if (schedulesEnabled(process.env)) startScheduler(realDeps);
-  // Looking for a newer version, and running an update only when one is
-  // asked for (the banner, Settings > Updates).
+  // Looking for a newer version, and running an update when one is asked
+  // for (the banner, Settings > Updates) or, with automatic updates on, once
+  // everything has been idle (lib/updates/auto.ts).
   try {
     reconcileUpdateRun();
   } catch (error) {

package/stores/chatJump.ts

@@ -1,14 +1,10 @@
 import { hrefWithSession } from "@/lib/session-url";
+import { go } from "@/components/Chat/session-link";
 import { bookmarksUiActions } from "@/stores/bookmarksUi";
 
 // Opens a chat by its address, then takes it to one message (bookmarks and
 // search both end here). The chat takes the jump once it is on screen.
 export function openChatAt(sessionId: string, itemId: string): void {
-  window.history.pushState(
-    null,
-    "",
-    hrefWithSession(location.href, { id: sessionId })
-  );
-  window.dispatchEvent(new PopStateEvent("popstate"));
+  go(hrefWithSession(location.href, { id: sessionId }), sessionId);
   bookmarksUiActions.jump(sessionId, itemId);
 }

package/stores/chatPositions.ts

@@ -0,0 +1,65 @@
+import { proxy } from "valtio";
+import type { ChatView } from "@/lib/chat-views/types";
+import type { Position } from "@/lib/nav/position";
+
+// A place asked for and not taken this soon is stale.
+const TARGET_MS = 10_000;
+
+// When each chat was last opened, apart from `views` so that a reader moving
+// through a chat doesn't redraw everything that lists chats by recency.
+export const chatOpened = proxy<Record<string, number>>({});
+
+const noteOpened = (v: ChatView) => {
+  if (chatOpened[v.sessionId] !== v.viewedAt)
+    chatOpened[v.sessionId] = v.viewedAt;
+};
+
+// What the page knows of where each chat was last read (the server's copy,
+// kept current as the reader moves), a place a history entry asks a chat to
+// open at, and the chats to open at their latest message.
+export const chatPositions = proxy<{
+  views: Record<string, ChatView>;
+  loaded: boolean;
+  target: { sessionId: string; pos: Position; at: number } | null;
+  latest: string[];
+}>({ views: {}, loaded: false, target: null, latest: [] });
+
+export const chatPositionsActions = {
+  // The server's list; what this page wrote since is newer and stays.
+  hydrate: (list: ChatView[]) => {
+    for (const v of list) {
+      const mine = chatPositions.views[v.sessionId];
+      if (!mine || mine.viewedAt < v.viewedAt)
+        chatPositions.views[v.sessionId] = v;
+      noteOpened(chatPositions.views[v.sessionId]);
+    }
+    chatPositions.loaded = true;
+  },
+  // The list couldn't be had: chats open at their latest, as they used to.
+  giveUp: () => {
+    chatPositions.loaded = true;
+  },
+  record: (view: ChatView) => {
+    chatPositions.views[view.sessionId] = view;
+    noteOpened(view);
+  },
+  setTarget: (sessionId: string, pos: Position) => {
+    chatPositions.target = { sessionId, pos, at: Date.now() };
+  },
+  takeTarget: (sessionId: string): Position | null => {
+    const t = chatPositions.target;
+    if (!t || t.sessionId !== sessionId) return null;
+    chatPositions.target = null;
+    return Date.now() - t.at < TARGET_MS ? t.pos : null;
+  },
+  wantLatest: (sessionId: string) => {
+    if (!chatPositions.latest.includes(sessionId))
+      chatPositions.latest.push(sessionId);
+  },
+  takeLatest: (sessionId: string): boolean => {
+    const at = chatPositions.latest.indexOf(sessionId);
+    if (at === -1) return false;
+    chatPositions.latest.splice(at, 1);
+    return true;
+  },
+};

package/stores/navHistory.ts

@@ -0,0 +1,98 @@
+import { proxy } from "valtio";
+import { HistoryWriter, navStateOf } from "@/lib/nav/history-writer";
+import {
+  emptyMirror,
+  moveTo,
+  renameIn,
+  visit,
+  type Mirror,
+} from "@/lib/nav/history-mirror";
+import type { Position } from "@/lib/nav/position";
+
+const KEY = "agentos-nav-history";
+
+function load(): Mirror {
+  try {
+    const raw = JSON.parse(sessionStorage.getItem(KEY) ?? "null");
+    if (raw && Array.isArray(raw.entries) && typeof raw.current === "number")
+      return raw;
+  } catch {
+    // Unavailable or corrupt: start over.
+  }
+  return emptyMirror();
+}
+
+const noHistory = typeof window === "undefined";
+// Made on first use in the browser.
+let writer: HistoryWriter | null = null;
+const w = () => (writer ??= new HistoryWriter(window.history));
+
+// The entries this tab made, for the back button's menu and for knowing
+// whether there is anywhere to go. Kept in sessionStorage across a reload.
+export const navHistory = proxy<Mirror>(noHistory ? emptyMirror() : load());
+
+function set(next: Mirror) {
+  navHistory.entries = next.entries;
+  navHistory.current = next.current;
+  try {
+    sessionStorage.setItem(KEY, JSON.stringify(next));
+  } catch {
+    // The menu is lost on reload; history itself is not.
+  }
+}
+
+const snapshot = (): Mirror => ({
+  entries: navHistory.entries.map((e) => ({ ...e })),
+  current: navHistory.current,
+});
+
+export const navHistoryActions = {
+  /** A new entry for a chat switch or a bookmark. */
+  push: (href: string, sessionId: string | null, name: string) => {
+    const s = w().push(href, sessionId);
+    set(
+      visit(
+        snapshot(),
+        { index: s.index, sessionId: sessionId ?? "", name },
+        "push"
+      )
+    );
+  },
+  /** The same entry at another address, or the first sight of this one. */
+  replace: (href: string, sessionId: string | null, name: string) => {
+    const s = w().replace(href, sessionId);
+    set(
+      visit(
+        snapshot(),
+        { index: s.index, sessionId: sessionId ?? "", name },
+        "replace"
+      )
+    );
+  },
+  /** Where the reader is in the chat, for the entry they're on. */
+  setPosition: (sessionId: string, pos: Position) =>
+    w().setPosition(sessionId, pos),
+  flush: () => w().flush(),
+  /** Back or forward landed on an entry: where it was made, if known. */
+  popped: () => {
+    const s = w().current();
+    if (s) set(moveTo(snapshot(), s.index));
+    return s;
+  },
+  rename: (sessionId: string, name: string) =>
+    set(renameIn(snapshot(), sessionId, name)),
+  back: () => {
+    w().flush();
+    window.history.back();
+  },
+  forward: () => {
+    w().flush();
+    window.history.forward();
+  },
+  /** The menu's pick: any entry, by index. */
+  goTo: (index: number) => {
+    w().flush();
+    window.history.go(index - navHistory.current);
+  },
+  currentState: () => (noHistory ? null : navStateOf(window.history.state)),
+};