@assuredloop/orca-bot-kit 0.1.0 → 0.2.0

package/src/restart.js

@@ -0,0 +1,192 @@
+// `obk restart`: the one command in the kit that closes a tab.
+//
+// Everything else only adds. Closing a tab takes the user's screen away and
+// Orca's resume record with it, so `up` never does it (PRD 6.5: restarts are
+// avoided, not banned, and one happens when the user asks for it).
+//
+// When they do ask, the session has to come back as itself. The book holds the
+// conversation each session is running (ADR 0002), so a restart is: close the
+// tab the book names, then let `up` open a new one and resume that
+// conversation. Nothing else about it is new.
+//
+// Safe is the whole of it, and it is three rules:
+//
+//   1. Only a tab the book itself names. Bot Father's ops tab, and anything
+//      else open in a bot's project, belongs to the user (PRD 6.2).
+//   2. Never a tab whose conversation the kit could not name again. A live tab
+//      with no session id in the book is refused before anything is touched:
+//      the close would be the end of that conversation.
+//   3. One tab at a time, by its own handle. Orca's `--worktree <sel> --all`
+//      ends every tab of a project and is never called from anywhere in the kit.
+//
+// And two things about timing, both of which cost a session when they are got
+// wrong. Everything that can refuse has to refuse before the first close, which
+// means making the preparations `up` makes rather than leaving them to it. And
+// Orca answers a close before its own listing agrees, so the close has to be
+// seen to have landed before `up` is handed the tabs — `up` finding a tab it
+// was about to replace takes it for a session that is still running.
+
+import { realpathSync } from 'node:fs';
+import { setTimeout as pause } from 'node:timers/promises';
+
+import { bookFile, readBook } from './book.js';
+import { botDir, readBot } from './bot.js';
+import { closeTab, findProject, tabs } from './orca.js';
+import { botsNamed, bringUp, prepareBots, sessionsOf } from './up.js';
+
+/**
+ * Close the tabs of the bot's sessions, or of the one named, and bring them
+ * back. Returns `{ closed, ...what up answered }` — one entry per tab it
+ * closed, and then the whole of the run that opened them again.
+ */
+export async function restartSessions(bots, { bot: name, session: onlySession } = {}) {
+  // The same refusals `up` gives for a bot or a session that is not there, and
+  // given before Orca is asked for anything.
+  botsNamed(bots, name);
+  const home = realpathSync(botDir(bots, name));
+  const known = readBot(home, name);
+  const sessions = sessionsOf(known, onlySession);
+  // A paused bot or session has no tab to close and is not to be opened, so
+  // there is nothing here to restart.
+  if (known.paused === true) {
+    throw new Error(`${name} is paused, so there is nothing of it to restart and nothing was closed. Bring it back with obk unpause --bots ${bots} --bot ${name}.`);
+  }
+  if (onlySession !== undefined && sessions[0].paused === true) {
+    throw new Error(`${name} ${onlySession} is paused, so there is nothing of it to restart and nothing was closed. Bring it back with obk unpause --bots ${bots} --bot ${name} --session ${onlySession}.`);
+  }
+
+  // And the same preparations, made now rather than left to `up`, which makes
+  // them after the tabs would already be gone. A session the kit could not
+  // start again — a launch line it would refuse, rules that will not build, a
+  // hooks file it cannot write — is a session that keeps the tab it is in.
+  const prepared = prepareBots(bots, [name], onlySession);
+  if (prepared.running.length === 0) {
+    throw new Error(`${name} would not come up again as it is, so nothing was closed. ${prepared.rules[0].trouble}`);
+  }
+
+  const going = tabsToClose(bots, name, home, sessions.filter((session) => session.paused !== true));
+  const closed = await closeTabs(home, going, bots, name);
+  return { closed, ...(await bringUp(bots, { bot: name, session: onlySession })) };
+}
+
+/**
+ * The live tabs of these sessions, as `{ name, tab }`, once every one of them
+ * has been judged safe to close: a live tab whose conversation the book cannot
+ * name refuses the lot, before anything is touched. With `keepless`, a tab is
+ * closed whatever the book knows, for a caller that is ending the session on
+ * purpose.
+ */
+export function tabsToClose(bots, name, home, sessions, { keepless = false } = {}) {
+  const book = readBook(home);
+
+  // Orca is asked what the project holds only when it has one: a folder Orca
+  // knows nothing about is refused with `selector_not_found` rather than
+  // answered with an empty list (tech notes, section 1). A bot that has never
+  // been up has no tabs, which is the answer anyway.
+  const live = findProject(home) === undefined
+    ? new Map()
+    : new Map(tabs(home).map((tab) => [tab.tabId, tab]));
+
+  const going = [];
+  const refusals = [];
+  for (const session of sessions) {
+    const was = book.sessions[session.name];
+    const tab = typeof was?.tab === 'string' ? live.get(was.tab) : undefined;
+    // Nothing of this session's is open: there is nothing to close, and `up`
+    // brings it back the way it brings back a tab the user closed themselves.
+    if (tab === undefined) continue;
+    if (keepless || typeof was.session === 'string') going.push({ name: session.name, tab });
+    else refusals.push(cannotComeBack(bots, name, session.name, was));
+  }
+
+  // Every session is judged before one tab is closed: a fleet of two where one
+  // cannot come back is not a fleet to close the other half of.
+  if (refusals.length > 0) throw new Error(refusals.join('\n'));
+  return going;
+}
+
+/**
+ * Close the tabs `tabsToClose` gave, one at a time by their own handles, and
+ * wait until Orca's listing agrees they are gone. Returns one entry per tab.
+ */
+export async function closeTabs(home, going, bots, name) {
+  const closed = [];
+  for (const { name: session, tab } of going) {
+    try {
+      closeTab(tab.handle);
+    } catch (error) {
+      // A tab that would not close still holds its session, so nothing is
+      // opened after this: two harnesses on one conversation is worse than a
+      // restart that did not happen.
+      throw new Error(alsoClosed(error.message, closed, bots, name));
+    }
+    closed.push({ bot: name, name: session, tabId: tab.tabId, terminal: tab.handle });
+  }
+
+  await gone(home, closed, bots, name);
+  return closed;
+}
+
+/** How long Orca is given to stop listing a tab it has closed, and how often it is asked. */
+const SETTLED_MS = 5000;
+const ASK_MS = 100;
+
+/**
+ * Wait until Orca's own listing has caught up with the closes.
+ *
+ * `terminal close` answers before `terminal list` stops reporting the tab —
+ * seen live on a busy machine, which is why both system tests poll for it. What
+ * that costs here is the whole command: `up` lists the tabs, finds the one just
+ * closed, takes it for a session that is still running and only retitles it, so
+ * the run ends having reported a restart and ended a session.
+ *
+ * A listing that never catches up is not something the kit can put right, so it
+ * stops and says which tab it is waiting on. The conversation is in the book,
+ * which is the way back to it.
+ */
+async function gone(home, closed, bots, bot) {
+  // Nothing closed is nothing to wait for, and a bot that has never been up has
+  // no Orca project to ask: Orca refuses the listing (tech notes, section 1).
+  if (closed.length === 0) return;
+  const until = Date.now() + SETTLED_MS;
+  const ids = closed.map((tab) => tab.tabId);
+
+  for (;;) {
+    const there = new Set(tabs(home).map((tab) => tab.tabId));
+    const left = ids.filter((id) => there.has(id));
+    if (left.length === 0) return;
+
+    if (Date.now() >= until) {
+      const one = left.length === 1;
+      throw new Error(`Orca answered the close for ${one ? 'this tab' : 'these tabs'} and is still listing ${one ? 'it' : 'them'} ${SETTLED_MS / 1000} seconds later: ${left.join(', ')}. Nothing was opened in ${one ? 'its' : 'their'} place, because a tab that is on the way out is not a tab to start a harness in. The conversations are in the book: obk up --bots ${bots} --bot ${bot} brings them back once Orca has caught up.`);
+    }
+    await pause(ASK_MS);
+  }
+}
+
+/**
+ * A session the kit will not close a tab on: it is live, and the book does not
+ * say which conversation is in it — a Codex hooks file trusted too late is
+ * enough to leave the book like that (tech notes, section 3).
+ *
+ * The kit will not pick one either, so the way out is the user's: the ids it
+ * found and nobody claims are named, and the line to write is spelled out.
+ */
+function cannotComeBack(bots, bot, name, was) {
+  const unclaimed = Array.isArray(was.unclaimed) ? was.unclaimed : [];
+  return [
+    `${bot} ${name} is running in tab ${was.tab} and the book does not say which conversation that is, so closing the tab would be the end of it. Nothing was closed.`,
+    ...(unclaimed.length === 0
+      ? []
+      : [`These ran in this bot's folder and no session claims them: ${unclaimed.join(', ')}.`]),
+    `To settle it, write the id into ${bookFile(botDir(bots, bot))} under ${name} as  session: <id>  and run the command again.`,
+  ].join(' ');
+}
+
+/** What a failed close owes whoever is reading: the tabs that went before it. */
+function alsoClosed(why, closed, bots, bot) {
+  if (closed.length === 0) return why;
+
+  const one = closed.length === 1;
+  return `${why} ${closed.map((tab) => tab.name).join(', ')} ${one ? 'was' : 'were'} closed before it and nothing was opened in ${one ? 'its' : 'their'} place: obk up --bots ${bots} --bot ${bot} brings ${one ? 'it' : 'them'} back with ${one ? 'its' : 'their'} conversation.`;
+}

package/src/retire.js

@@ -0,0 +1,92 @@
+// `obk retire`: end a session, or a whole bot, on the user's word.
+//
+// Nothing is deleted that the user might want back. A retired session comes off
+// its bot's `bot.yaml`, and what the book knew about it moves to the book's
+// `retired` list, so the conversations it had are still accounted for (ADR
+// 0002). A retired bot moves, folder, book, charter and memory, out of `bots/`
+// into `retired/` beside it, where the kit no longer looks.
+//
+// What goes is what the kit made for it: its tabs, closed one at a time by
+// their own handles; its Orca project, after the tabs and never before; its
+// start-prompt files beside the bots folder; and, for a bot, the skill links
+// the kit made in its folder. A tab the book does not name is the user's, so a
+// bot whose project holds one is not retired until they have dealt with it.
+//
+// Closing a tab here ends the conversation in it on purpose, so unlike a
+// restart or a pause it does not wait for the book to know which one it was.
+// The mailbox Runs stay: Orca has no way to remove one (ADR 0008).
+
+import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import path from 'node:path';
+
+import { readBook, tabIdsIn, updateBook } from './book.js';
+import { botDir, dropSession, readBot } from './bot.js';
+import { deleteProject, findProject, tabs } from './orca.js';
+import { fleetMember } from './pause.js';
+import { closeTabs, tabsToClose } from './restart.js';
+import { unlinkSkills } from './skills.js';
+import { promptPath, sessionsOf } from './up.js';
+
+/** Where retired bots go: beside `bots/`, where nothing the kit runs looks. */
+export const retiredDir = (bots) => path.join(bots, 'retired');
+
+/**
+ * Retire the session `session` of the bot `bot`. Returns `{ bot, session, closed }`.
+ */
+export async function retireSession(bots, { bot, session }) {
+  const home = fleetMember(bots, bot, 'retire');
+  const sessions = sessionsOf(readBot(home, bot), session);
+
+  const closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot);
+  dropSession(bots, bot, session);
+
+  const at = new Date().toISOString();
+  await updateBook(home, (book) => {
+    const entry = book.sessions[session];
+    if (entry === undefined) return;
+    delete book.sessions[session];
+    book.retired = [...(Array.isArray(book.retired) ? book.retired : []), { name: session, ...entry, retired: at }];
+  });
+  rmSync(promptPath(bots, bot, session), { force: true });
+
+  return { bot, session, closed };
+}
+
+/**
+ * Retire the bot `bot`. Returns `{ bot, closed, project, moved }`: the tabs it
+ * closed, the Orca project it took away (if it had one) and where the bot is now.
+ */
+export async function retireBot(bots, { bot }) {
+  const home = fleetMember(bots, bot, 'retire');
+  const moved = path.join(retiredDir(bots), bot);
+  if (existsSync(moved)) {
+    throw new Error(`there is already something at ${moved}, and retire never writes over it. Move it aside, then retire ${bot} again.`);
+  }
+
+  const known = readBot(home, bot);
+  const project = findProject(home);
+  if (project !== undefined) {
+    const booked = tabIdsIn(readBook(home));
+    const theirs = tabs(home).filter((tab) => !booked.has(tab.tabId));
+    if (theirs.length > 0) {
+      throw new Error(`${bot}'s Orca project holds ${theirs.length === 1 ? 'a tab' : 'tabs'} the book does not name, so ${theirs.length === 1 ? 'it is' : 'they are'} not the kit's to close: ${theirs.map((tab) => tab.tabId).join(', ')}. Close ${theirs.length === 1 ? 'it' : 'them'} yourself, then retire ${bot} again. Nothing was done.`);
+    }
+  }
+
+  // Every session the book holds a tab for, whether or not bot.yaml still lists
+  // it: the same set the check above calls the kit's, so the project is not
+  // taken away with one of them still open. `closeTabs` waits until Orca agrees
+  // they are gone.
+  const booked = Object.keys(readBook(home).sessions).map((name) => ({ name }));
+  const closed = await closeTabs(home, tabsToClose(bots, bot, home, booked, { keepless: true }), bots, bot);
+  if (project !== undefined) deleteProject(project.id);
+
+  for (const name of new Set([...known.sessions, ...booked].map((session) => session.name))) {
+    rmSync(promptPath(bots, bot, name), { force: true });
+  }
+  unlinkSkills(home);
+  mkdirSync(retiredDir(bots), { recursive: true });
+  renameSync(botDir(bots, bot), moved);
+
+  return { bot, closed, ...(project === undefined ? {} : { project: project.id }), moved };
+}

package/src/roster.js

@@ -0,0 +1,71 @@
+// The fleet as facts (PRD 6.8): what each bot is, what each of its sessions is
+// set to, and what the book records about them.
+//
+// This is what Bot Father reads before it says anything about the fleet, and it
+// reads files and only files. It does not ask Orca, it changes nothing, and it
+// judges nothing: whether a bot is the right bot, what its charter comes to in
+// two lines, and which of its limits is the hard one are the reader's to say
+// (ADR 0006). What is wrong with the setup is a different question, and
+// `obk health` is the command that answers it.
+//
+// So a list here is the list as the user wrote it, unchecked. A skill named in
+// it that is nowhere on disk is still reported, because the fact is that the
+// bot's list names it.
+
+import path from 'node:path';
+
+import { botDir, botNames, readBot } from './bot.js';
+import { readBook } from './book.js';
+import { harnessOf } from './launch.js';
+import { listIn } from './rules.js';
+
+/** The bot's own file, which is where everything but the book comes from. */
+const BOT_YAML = 'bot.yaml';
+
+/**
+ * The fleet, or the one bot named, in the order `botNames` gives: one entry per
+ * bot, each holding what its `bot.yaml` says and what its book holds.
+ */
+export function readRoster(bots, { bot: only } = {}) {
+  const names = botNames(bots);
+  if (only !== undefined && !names.includes(only)) {
+    throw new Error(`there is no bot called ${only} in ${bots}. The bots there are: ${names.join(', ') || 'none'}.`);
+  }
+  return (only === undefined ? names : [only]).map((name) => card(bots, name));
+}
+
+/**
+ * One bot's entry. The settings come back as the session carries them, so a
+ * setting it does not carry is absent rather than guessed: the kit never
+ * invents a model or an effort, and not set means the harness's own.
+ *
+ * The one thing worked out rather than copied is the harness, because a session
+ * either names its own or runs on its bot's, and which of the two it is is not
+ * a fact about the fleet that anybody should have to derive twice.
+ */
+function card(bots, name) {
+  const home = botDir(bots, name);
+  const file = path.join(home, BOT_YAML);
+  const bot = readBot(home, name);
+  const book = readBook(home);
+
+  return {
+    bot: name,
+    home,
+    harness: bot.harness,
+    charter: bot.charter,
+    ...(bot.paused === true ? { paused: true } : {}),
+    rules: listIn(file, 'rules'),
+    skills: listIn(file, 'skills'),
+    orca: book.orca,
+    sessions: bot.sessions.map((session) => ({
+      ...session,
+      harness: harnessOf(session, bot.harness),
+      // What the kit knows about this session as a running thing, kept apart
+      // from what the user set: the tab it is in, the conversation it is
+      // having, the ones it had before, and anything in its folder that no
+      // session claims. Empty until it has been brought up.
+      book: book.sessions[session.name] ?? {},
+    })),
+  };
+}