@assuredloop/orca-bot-kit 0.2.0 → 0.4.0

package/src/health.js

@@ -266,8 +266,8 @@ function inOrca(home, bot, setups) {
 /**
  * The conversations a harness has on record in this bot's folder that the book
  * does not name anywhere. The hook is how an id reaches the book, and when it
- * fails it fails quietly (ADR 0010), so this is where a stale book shows: the
- * harness's own record set beside it (ADR 0002).
+ * fails it fails quietly (ADR 0020), so this is where a stale book shows: the
+ * harness's own record set beside it (ADR 0012).
  */
 function offTheBook(home, bot, book) {
   const named = new Set();

package/src/hooks.js

@@ -1,4 +1,4 @@
-// The kit's own hook, in the bot's folder and nowhere else (ADR 0010).
+// The kit's own hook, in the bot's folder and nowhere else (ADR 0020).
 //
 // Both harnesses read a hooks file out of the folder a session starts in, and
 // every session starts at its bot home, so the bot folder is where the kit's
@@ -15,7 +15,7 @@ import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 
 import { leadsOutside } from './bot.js';
-import { shellWord } from './launch.js';
+import { ownCli, shellWord } from './launch.js';
 
 /** Where each harness reads a project's hooks, inside the bot home. */
 const HOOK_FILE = { claude: '.claude/settings.json', codex: '.codex/hooks.json' };
@@ -31,17 +31,16 @@ const EVENT = 'SessionStart';
 /** How long the harness gives the hook before it goes on without it. */
 const TIMEOUT = 10;
 
-/** The kit's own hook among whatever else the user keeps in the file. */
-const KIT_COMMAND = 'obk session record';
-
 /**
- * What the hook runs. `|| true` and a quiet stderr because a hook must never
- * disturb the session it fires in (ADR 0010): a kit that is not installed, or a
- * book that cannot be written, leaves the session alone and the health check
- * finds the stale book later.
+ * What the hook runs: the CLI that wrote it, by its own path, so the session
+ * reports to the kit that set it up and not to whatever `obk` PATH finds in the
+ * harness's shell (#220). `|| true` and a quiet stderr because a hook must never
+ * disturb the session it fires in (ADR 0020): a kit that is not there, or a book
+ * that cannot be written, leaves the session alone and the health check finds
+ * the stale book later.
  */
-export const hookCommand = (bots, bot) =>
-  `${KIT_COMMAND} --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
+export const hookCommand = (bots, bot, cli = ownCli()) =>
+  `${shellWord(cli)} session record --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
 
 /**
  * Make sure the bot at `home` has the kit's SessionStart hook for `harness`.
@@ -81,7 +80,7 @@ export function installHook(home, harness, { bots, bot }) {
  *
  * The same question `installHook` asks, without the writing. It matters more
  * than it looks: the hook is the whole of how the book learns which
- * conversation a session is running as (ADR 0002), and when it is not there
+ * conversation a session is running as (ADR 0012), and when it is not there
  * nothing else says so — the book simply stops being true.
  */
 export function hookTrouble(home, harness, { bots, bot }) {
@@ -95,7 +94,22 @@ export function hookTrouble(home, harness, { bots, bot }) {
   let settings;
   try {
     settings = readSettings(file);
-    wanted = { ...settings, hooks: withKitHook(settings.hooks, file, { type: 'command', command: hookCommand(bots, bot), timeout: TIMEOUT }) };
+    // The hook in the file is judged by what it runs, not by whether this is
+    // the install that wrote it. A bot made before the kit named itself by path
+    // runs the bare `obk`, and one another install wrote runs that install: both
+    // still reach a kit, and the next `obk up` writes this one's. So the line is
+    // checked against the program already in it, and only one that names a CLI
+    // that is not there any more is wrong — `|| true` would keep that quiet, and
+    // the book would stop being true with nothing to say why.
+    const running = kitProgramIn(settings);
+    if (running !== undefined && running !== BARE && !existsSync(running)) {
+      return {
+        where: file,
+        says: `${file} holds the kit's session hook, but it runs ${running}, which is not there any more. ${stale} obk up puts back one that runs the kit you have.`,
+      };
+    }
+    const program = running ?? ownCli();
+    wanted = { ...settings, hooks: withKitHook(settings.hooks, file, { type: 'command', command: hookCommand(bots, bot, program), timeout: TIMEOUT }) };
   } catch (error) {
     return { where: file, says: `${error.message} ${stale}` };
   }
@@ -110,7 +124,7 @@ export function hookTrouble(home, harness, { bots, bot }) {
 /**
  * What to say about a hooks file that a link takes out of the bot folder, or
  * undefined when it stays in. The kit writes its hook in the bot folder and
- * nowhere else (ADR 0010); through a link like that it would be writing the
+ * nowhere else (ADR 0020); through a link like that it would be writing the
  * user's own settings, so it does not, and says why.
  */
 function outside(home, file) {
@@ -169,14 +183,55 @@ function withKitHook(hooks, file, mine) {
 /**
  * The kit's own hook entry, wherever it sits and whatever sits beside it: a
  * command of exactly the shape `hookCommand` writes, for any bots folder and
- * bot, so an entry written before the folder moved is still the kit's. A line
- * of the user's that only mentions the command is theirs (PRD 6.5).
+ * bot, run by a kit — the bare `obk` a bot made before #220 still has, this
+ * install, or another — so an entry written before the folder moved or the kit
+ * changed is still the kit's, and is rewritten in place rather than joined by a
+ * second. A line of the user's that only mentions the command, or runs it with
+ * a program of their own, is theirs (PRD 6.5).
  */
-const isKitHook = (hook) => typeof hook?.command === 'string' && KIT_HOOK.test(hook.command);
+const isKitHook = (hook) => kitProgramOf(hook?.command) !== undefined;
 
 /** One word as `shellWord` writes it: bare, or single-quoted with `'\''` inside. */
 const WORD = String.raw`(?:[A-Za-z0-9,._+:@%/=-]+|'(?:[^']|'\\'')*')`;
-const KIT_HOOK = new RegExp(String.raw`^${KIT_COMMAND} --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+const KIT_HOOK = new RegExp(String.raw`^(${WORD}) session record --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+
+/** The program a bot made before the kit named itself by path runs. */
+const BARE = 'obk';
+
+/**
+ * Whether a program is a kit: the bare name, an install's `obk` wherever it
+ * lives, or a checkout's `src/cli.js` — the only two ways `ownCli` is reached.
+ */
+const isKitCli = (program) => path.basename(program) === BARE || program.endsWith('/src/cli.js');
+
+/** The program a hook command of the kit's runs, unquoted, or undefined for any other command. */
+function kitProgramOf(command) {
+  const found = typeof command === 'string' ? KIT_HOOK.exec(command) : null;
+  if (found === null) return undefined;
+  const program = unquoted(found[1]);
+  return isKitCli(program) ? program : undefined;
+}
+
+/**
+ * What the kit's hook in these settings runs, as a path or the bare name, or
+ * undefined when there is none. Read back out of its shell quoting, so it can be
+ * looked for on disk.
+ */
+function kitProgramIn(settings) {
+  for (const groups of Object.values(settings.hooks ?? {})) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      for (const hook of Array.isArray(group?.hooks) ? group.hooks : []) {
+        const program = kitProgramOf(hook?.command);
+        if (program !== undefined) return program;
+      }
+    }
+  }
+  return undefined;
+}
+
+/** A word as `shellWord` wrote it, read back to what it stands for. */
+const unquoted = (word) => (word.startsWith("'") ? word.slice(1, -1).replaceAll(`'\\''`, "'") : word);
 
 /**
  * What the file says, or nothing when there is no file yet. A file the kit

package/src/init.js

@@ -1,6 +1,6 @@
 // Creates the user's bots folder: their own git repo, seeded with the files the
 // kit reads, and Bot Father. The kit puts none of its own code in here — kit
-// skills are linked from the installed package (ADR 0004).
+// skills are linked from the installed package (ADR 0014).
 //
 // Seeding only ever adds what is missing. The user edits these files, by hand
 // or through Bot Father, so a re-run must never write over them.
@@ -15,7 +15,7 @@ import { RECORD, SKILL_DIRS } from './skills.js';
 
 /**
  * What the kit makes on this machine, and what the repo therefore does not
- * carry (ADR 0004, PRD 6.3).
+ * carry (ADR 0014, PRD 6.3).
  *
  * A bot's skills are symlinks into wherever the kit and the user's skill
  * sources are installed on the machine that made them, so a clone somewhere
@@ -126,7 +126,7 @@ const MANAGEMENT_SKILLS = ['obk-bot-building', 'obk-finops', 'obk-fleet-review',
 const BOT_FATHER_YAML = 'bots/bot-father/bot.yaml';
 
 /** The management session every Bot Father has: the tab you talk to it in. */
-const DAILY_SESSION = 'daily';
+export const DAILY_SESSION = 'daily';
 
 const seeds = (harness) => [
   ['.gitignore', GITIGNORE],

package/src/launch.js

@@ -1,7 +1,7 @@
 // What a session is started with: the one line typed into its tab, which brings
 // the harness up and carries the session's start prompt with it.
 //
-// The flag mapping is PRD 6.4 and ADR 0005, re-checked against the installed
+// The flag mapping is PRD 6.4 and ADR 0015, re-checked against the installed
 // CLIs (Claude Code 2.1.278, Codex 0.155.1). Every session is given its
 // approval level explicitly, so a user's own global harness defaults cannot
 // leak into a bot. The kit names no model: a session that sets none gets the
@@ -12,6 +12,7 @@
 
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 /** The approval levels, and what each one is called on each harness. */
 const APPROVAL = {
@@ -38,7 +39,7 @@ export const bypassFlags = (harness) => APPROVAL[harness]['dangerously-skip'];
 
 export const HARNESSES = Object.keys(APPROVAL);
 
-/** The level a session that names none runs at (ADR 0005). */
+/** The level a session that names none runs at (ADR 0015). */
 export const DEFAULT_APPROVAL = 'auto';
 
 /** A setting the user left out. An empty string is one too: it means the harness's own. */
@@ -49,7 +50,7 @@ export const harnessOf = (session, botHarness) => (set(session.harness) ? sessio
 
 /**
  * A session's name on Claude Code, which is also the address another Claude
- * session writes to (ADR 0008). It goes on the launch line as `-n`, and it is
+ * session writes to (ADR 0018). It goes on the launch line as `-n`, and it is
  * re-applied every time the session is started: a resume keeps the name by
  * itself (tech notes, section 2), and the kit does not depend on that.
  */
@@ -161,7 +162,7 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
 
   if (harness === 'claude') {
     // The name is the address other Claude sessions write to, so it goes on
-    // every launch line, a resume included (ADR 0008).
+    // every launch line, a resume included (ADR 0018).
     if (address !== undefined) words.push('-n', address);
     // The context window rides on the model name: `sonnet[1m]`.
     if (set(session.model)) words.push('--model', set(session.context) ? `${session.model}[${session.context}]` : session.model);
@@ -174,7 +175,7 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
     if (set(session.effort)) words.push('-c', `model_reasoning_effort=${session.effort}`);
     if (set(session.context)) words.push('-c', `model_context_window=${session.context}`);
     // In Codex's auto mode the sandbox lets it write in the folder it was
-    // started in, and nowhere else (ADR 0005), so a work dir outside the bot
+    // started in, and nowhere else (ADR 0015), so a work dir outside the bot
     // home has to be named.
     if (workDir !== undefined && !inside(home, workDir)) words.push('--add-dir', workDir);
   }
@@ -184,6 +185,7 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
     // starts — the shell's child — from anything the session starts later inside
     // the tab. `$$` is the shell's, and it is not quoted for that reason.
     `${SHELL_ENV}=$$`,
+    `${CLI_ENV}=${quoted(ownCli())}`,
     ...words.map(quoted),
     ...extraWords(session.extra_args),
     ...resumeWords(harness, resume),
@@ -274,3 +276,24 @@ const quoted = (word) => (/^[A-Za-z0-9,._+:@%/=-]+$/.test(word) ? word : `'${wor
 
 /** The same, for anything else of the kit's that has to build a shell line. */
 export const shellWord = quoted;
+
+/**
+ * The CLI that is running, by the path it was started by: the kit calls itself
+ * back with this, never with the bare name `obk`, because the bare name is
+ * whatever PATH says, and PATH is not the kit's to decide (#220). A user's
+ * install is started through npm's bin link, and the link is kept rather than
+ * resolved, so the path survives an upgrade of the package; a system test that
+ * runs a checkout's `src/cli.js` gets that checkout. What an environment
+ * variable claims is not asked: the kit says who it is from how it was started.
+ */
+export const ownCli = () => (process.argv[1] === undefined
+  // Nothing started as a script, as with `node -e`: the kit's own entry file.
+  ? fileURLToPath(new URL('./cli.js', import.meta.url))
+  : path.resolve(process.argv[1]));
+
+/**
+ * Where the launch line hands the session the CLI that started it, so a bot's
+ * own commands can call the same one. A plain variable, because a harness's
+ * shell keeps those where it rearranges PATH (#220).
+ */
+export const CLI_ENV = 'OBK_CLI';

package/src/message.js

@@ -1,4 +1,4 @@
-// `obk message`: one session writing to another (PRD 6.9, ADR 0008).
+// `obk message`: one session writing to another (PRD 6.9, ADR 0018).
 //
 // Two roads, and the bot never picks. Claude to Claude in the same approval
 // class is the harness's own messaging, which no command line can send for it —
@@ -20,8 +20,8 @@ import path from 'node:path';
 
 import { readBook } from './book.js';
 import { botDir, botNames, readBot } from './bot.js';
-import { harnessOf, reachesMail } from './launch.js';
-import { ackMailbox, postMessage, readMailbox, tabs, tuiInTab, typeIntoTab, useMailbox } from './orca.js';
+import { harnessOf, ownCli, reachesMail, shellWord } from './launch.js';
+import { ackMailbox, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, typeIntoTab, useMailbox } from './orca.js';
 
 /**
  * How much of a message travels as itself. Above this it is written to a file
@@ -147,7 +147,7 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
     return {
       ...answer,
       sent: false,
-      trouble: `${from.bot}/${from.session} has no mailbox of its own yet, so a reply would have nowhere to go. Bring it up first:  obk up --bots ${bots} --bot ${from.bot}`,
+      trouble: `${from.bot}/${from.session} has no mailbox of its own yet, so a reply would have nowhere to go. Bring it up first:  ${shellWord(ownCli())} up --bots ${shellWord(bots)} --bot ${shellWord(from.bot)}`,
     };
   }
 
@@ -173,7 +173,9 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
 /**
  * What is waiting for a session, and the reading of it.
  *
- * Orca fences a Run to one reader, so this binds before it reads. A read that
+ * Orca fences a Run to one reader, its coordinator. A session whose tab is live
+ * is bound to that tab and read as it; one whose tab is down is read as its
+ * Run's coordinator, and nothing is bound (issue #249). A read that
  * is not a peek acknowledges the batch it read: that is what makes the next
  * check bring the next one rather than the same again.
  */
@@ -192,10 +194,27 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
     };
   }
 
-  useMailbox(who.mailbox);
-  const found = readMailbox(who.mailbox, { peek });
+  // Read as the session's own tab, wherever this check was typed. Binding the
+  // tab that asked would hand it the session's mailbox, and Orca's notice for
+  // every message after (issue #228). A session with no live tab is read as
+  // whatever its mailbox is bound to, a closed tab included, and nothing is
+  // bound: the session's tab is bound again when it is back up (issue #249).
+  const live = who.tab === undefined ? undefined : tabs(who.home).find((tab) => tab.tabId === who.tab)?.handle;
+  if (live !== undefined) useMailbox(who.mailbox, live);
+  const handle = live ?? coordinatorOf(who.mailbox);
+  if (handle === undefined) {
+    return {
+      bots,
+      bot: who.bot,
+      session: who.session,
+      mailbox: who.mailbox,
+      messages: [],
+      trouble: `${who.bot}/${who.session} is not up, and its mailbox is bound to no tab, so there is nothing to read it as. Its mail waits until its tab is back: \`up\` brings it back, or \`unpause\` when it is paused.`,
+    };
+  }
+  const found = readMailbox(who.mailbox, { peek, handle });
   const messages = (found.messages ?? []).map((message) => asMessage(bots, message));
-  if (!peek && found.deliveryId !== undefined && messages.length > 0) ackMailbox(who.mailbox, found.deliveryId);
+  if (!peek && found.deliveryId !== undefined && messages.length > 0) ackMailbox(who.mailbox, found.deliveryId, handle);
 
   return { bots, bot: who.bot, session: who.session, mailbox: who.mailbox, read: !peek, messages };
 }
@@ -295,9 +314,10 @@ const stamp = () => new Date().toISOString().replaceAll(':', '-').replace('.', '
  *
  * Nothing in the mailbox reaches a running harness by itself, and a typed line
  * is taken as the next turn by a busy session rather than cutting into the one
- * it is having. A tab with no TUI in it is not typed into at all — there is
+ * it is having. A tab with no harness in it is not typed into at all — there is
  * nobody there to read it, and the message waits in the mailbox until the
- * session is up. A tab the book does not hold is never typed into on any road.
+ * session is up. Nor is one the kit cannot tell about. A tab the book does not
+ * hold is never typed into on any road.
  *
  * Nor is a tab with something on screen waiting to be answered. A line typed
  * into one of those is not a message: it is an answer to whatever question is
@@ -315,16 +335,15 @@ function nudge(to, from, subject) {
   if (to.tab === undefined) return { nudged: false };
 
   try {
-    const live = tabs(to.home).find((tab) => tab.tabId === to.tab);
-    if (live === undefined) return { nudged: false };
-
-    const tui = tuiInTab(live.handle, LOOK_MS);
-    if (!tui.running) return { nudged: false };
-    if (tui.blockedReason !== undefined) return { nudged: false, blocked: tui.blockedReason };
+    const found = tabToTypeInto(to.home, to.tab, LOOK_MS);
+    if (found.blocked !== undefined) return { nudged: false, blocked: found.blocked };
+    // A line that lands in a shell is run there, with the sender's subject in it.
+    if (found.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure };
+    if (found.handle === undefined) return { nudged: false };
 
     typeIntoTab(
-      live.handle,
-      `Fleet mail from ${from.bot}/${from.session}: ${subject}. Read it with  obk message check --bots ${to.bots} --bot ${to.bot} --session ${to.session}`,
+      found.handle,
+      `Fleet mail from ${from.bot}/${from.session}: ${subject}. Read it with  ${shellWord(ownCli())} message check --bots ${shellWord(to.bots)} --bot ${shellWord(to.bot)} --session ${shellWord(to.session)}`,
     );
     return { nudged: true };
   } catch (error) {
@@ -377,4 +396,4 @@ function whyNotReachable(bot, session, harness, held) {
 }
 
 const notUpYet = (who) =>
-  `${who.bot}/${who.session} has no mailbox yet: it has never been brought up. Start it and it gets one:  obk up --bots ${who.bots} --bot ${who.bot} --session ${who.session}`;
+  `${who.bot}/${who.session} has no mailbox yet: it has never been brought up. Start it and it gets one:  ${shellWord(ownCli())} up --bots ${shellWord(who.bots)} --bot ${shellWord(who.bot)} --session ${shellWord(who.session)}`;

package/src/orca-window.cjs

@@ -0,0 +1,21 @@
+// Run by Orca's own binary as plain Node, the way Orca's `bin/orca` runs its
+// CLI: `ELECTRON_RUN_AS_NODE=1 <Orca> orca-window.cjs <client> <projectId> <wait>`.
+//
+// It asks Orca's runtime, through Orca's own client, for `project.update` with
+// no changes on one project. That is the call that makes Orca's window read its
+// projects again, and Orca's CLI does not offer it (#224, ADR 0021). It exits 0
+// only when the runtime took the call; anything else is a non-zero exit, and
+// the kit reads every non-zero exit the same way.
+
+'use strict';
+
+const [client, projectId, wait] = process.argv.slice(2);
+
+process.exitCode = 1;
+const { RuntimeClient } = require(client);
+new RuntimeClient(undefined, Number(wait))
+  .call('project.update', { projectId, updates: {} })
+  .then((answer) => {
+    if (answer?.ok === true) process.exitCode = 0;
+  }, () => {})
+  .finally(() => process.exit());