@assuredloop/orca-bot-kit 0.26.1 → 0.27.0

package/src/health.js

@@ -18,22 +18,23 @@
 // is, the one thing to go and look at, and a sentence naming it — so that
 // somebody who cannot read code knows what was found and where.
 
-import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 
 import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
 import { botDir, botNames, botsDir, readBot, tempRoles, unknownKeys } from './bot.js';
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
-import { APPROVALS, bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
+import { APPROVALS, bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, sessionTrouble, SHELL_ENV, shellWord, workDirOf } from './launch.js';
 import { frontOfTab, orcaDefaultArgs, projects, runMissing, tabs, wordsOfProcess } from './orca.js';
 import { permissionsTrouble } from './permissions.js';
+import { processesIn } from './processes.js';
 import { TAB_ENV } from './record.js';
 import { agentsTrouble, rulesStamp } from './rules.js';
 import { settingsInUse } from './settings.js';
 import { skillsTrouble } from './skills.js';
 import { readSources, sourcesDir } from './sources.js';
-import { BOT_FATHER, botsNamed, promptPath } from './up.js';
+import { BOT_FATHER, botsNamed, oldPromptPath, promptPath } from './up.js';
 
 /**
  * Everything wrong with the setup at `bots`, in one list: what Orca's own
@@ -141,6 +142,9 @@ function leftBeside(bots) {
     try {
       for (const session of readBot(botDir(bots, name), name).sessions) {
         owned.add(promptPath(bots, name, session.name));
+        // Where a live session's prompt was before #534: nothing reads it once
+        // the session starts again, and its retire removes it.
+        owned.add(oldPromptPath(bots, name, session.name));
       }
     } catch {
       known = false;
@@ -148,8 +152,7 @@ function leftBeside(bots) {
   }
 
   if (known) {
-    for (const file of namesIn(`${bots}.prompts`)) {
-      const at = path.join(`${bots}.prompts`, file);
+    for (const at of promptFilesIn(`${bots}.prompts`)) {
       if (owned.has(at)) continue;
       found.push(finding('leftover', at, `${at} is a start prompt the kit wrote beside your bots folder, and no session of any bot answers to it now. Nothing reads it.`));
     }
@@ -196,9 +199,48 @@ function aboutBot(bots, name, setups, sessions) {
     ...permissionsTrouble(home, bot).map(said('config')),
     ...skillsTrouble(bots, home, bot).map(said('skill')),
     ...inOrca(bots, home, bot, setups, sessions),
+    ...leftRunning(home, bot),
   ];
 }
 
+/**
+ * What still runs in the work dir of a retired session (#537): a retire stops
+ * it, so this is one from before that, or one a retire could not stop. The
+ * book keeps a retired session's work dir; a temporary session retired before
+ * it did worked in `work/<name>`, where `obk temp make` puts it. A work dir a
+ * session in bot.yaml still uses is that session's, and not looked at, by its
+ * real path, so a link to it is not taken for a retired one (review of PR #543).
+ */
+function leftRunning(home, bot) {
+  let book;
+  try {
+    book = readBook(home);
+  } catch {
+    // A book that cannot be read is said where the book is read.
+    return [];
+  }
+  const real = (dir) => (dir === undefined ? undefined : realpathOf(dir));
+  const live = new Set(bot.sessions.map((session) => real(workDirOf(session, home))));
+  const dirs = [];
+  const seen = new Set();
+  for (const entry of Array.isArray(book.retired) ? book.retired : []) {
+    const named = typeof entry?.work_dir === 'string' && entry.work_dir !== '' ? entry.work_dir : undefined;
+    const dir = workDirOf({ work_dir: named ?? (entry?.temporary === undefined ? undefined : `work/${entry.name}`) }, home);
+    // One that is not there holds nothing.
+    const at = real(dir);
+    if (at === undefined || live.has(at) || seen.has(at)) continue;
+    seen.add(at);
+    dirs.push({ session: entry.name, dir });
+  }
+  if (dirs.length === 0) return [];
+
+  const read = processesIn(dirs);
+  if (read.unreadable !== undefined) {
+    return [finding('process', bookFile(home), `The kit cannot tell whether anything still runs in the work dirs of ${bot.name}'s retired sessions: ${read.unreadable}.`, bot.name)];
+  }
+  return read.running.map((one) => finding('process', one.dir, `pid ${one.pid} still runs in the work dir of ${bot.name}/${one.session}, which was retired: ${one.command}. Nothing of the kit's stops it now. If it is not wanted, stop it yourself:  kill ${one.pid}`, bot.name));
+}
+
 /** A session the kit would refuse to start, in the words `up` refuses it with. */
 function sessionSettings(home, bot) {
   const file = path.join(home, 'bot.yaml');
@@ -461,6 +503,21 @@ function recordIn(home, bot) {
 }
 
 /** What a directory holds, and nothing at all when there is no directory. */
+/**
+ * The files in the kit's folder of start prompts: in each bot's own folder
+ * there (#534), and flat in the folder itself, where they were before.
+ */
+function promptFilesIn(dir) {
+  return namesIn(dir).flatMap((name) => {
+    const at = path.join(dir, name);
+    try {
+      return statSync(at).isDirectory() ? namesIn(at).map((file) => path.join(at, file)) : [at];
+    } catch {
+      return [];
+    }
+  });
+}
+
 function namesIn(dir) {
   try {
     return readdirSync(dir);

package/src/hooks.js

@@ -58,36 +58,7 @@ export const sentCommand = (bots, bot, cli = ownCli()) =>
   `${shellWord(cli)} session sent --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
 
 /**
- * Claude Code's third kit hook: at each turn end, it tells the session once
- * about fleet mail the kit sent it that is still unread (#509, ADR 0035).
- * Claude Code only: on Codex a new hook entry puts every session on "Hooks
- * need review", and that waits for #511. It asks Orca only when the kit's hint
- * holds mail for the session, and gives Orca at most ten seconds of its thirty.
- */
-const MAIL_EVENT = 'Stop';
-const MAIL_TIMEOUT = 30;
-
-/** What the mail hook runs, by the kit's own path, as `hookCommand` does. */
-export const mailCommand = (bots, bot, cli = ownCli()) =>
-  `${shellWord(cli)} session mail --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
-
-/**
- * Codex's second kit hook: after each command its shell tool ran, outside
- * Codex's sandbox, it decides the mail nudges a send in that command could not
- * (#350, ADR 0034). Codex only, since only Codex runs its commands where `ps`
- * does not start. It types into another session's tab, which takes Orca a few
- * seconds a nudge, so it is given longer than the others.
- */
-const NUDGE_EVENT = 'PostToolUse';
-const NUDGE_MATCHER = 'Bash';
-const NUDGE_TIMEOUT = 30;
-
-/** What the nudge hook runs, by the kit's own path, as `hookCommand` does. */
-export const nudgeCommand = (bots, bot, cli = ownCli()) =>
-  `${shellWord(cli)} session nudge --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
-
-/**
- * Codex's third kit hook: at each turn end, the session's thread is named after
+ * Codex's second kit hook: at each turn end, the session's thread is named after
  * its bot and session, so its tab says which it is (#480). Async, so the turn
  * ends without waiting on it: it waits for the session to be idle, up to 30 s,
  * then types and confirms. A naming took 73 s live, each character waiting on
@@ -123,7 +94,9 @@ export function installHook(home, harness, { bots, bot }) {
   // longer asks about is taken out, and a hook of the user's beside the kit's
   // stays where they put it.
   const started = withKitHook(settings.hooks, file, mine);
-  const wanted = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, started) };
+  // The Claude Code mail hook and the Codex nudge hook went with the kit's
+  // typed line (#555), so an entry of either is taken out.
+  const wanted = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, withoutHooks(started, [KIT_MAIL, KIT_NUDGE])) };
 
   // Compared as documents, not as text: how the user laid their file out is
   // theirs, and a run that changes nothing writes nothing.
@@ -171,9 +144,8 @@ export function hookTrouble(home, harness, { bots, bot }) {
     const program = running ?? ownCli();
     wanted = { ...settings, hooks: withKitHook(settings.hooks, file, { type: 'command', command: hookCommand(bots, bot, program), timeout: TIMEOUT }) };
     // The harness's other hooks are each judged on their own: the session hook
-    // may be right while the warning after a native message (ADR 0032), the
-    // nudge a Codex sender left (ADR 0034), or the naming of a Codex thread
-    // (#480) is missing.
+    // may be right while the warning after a native message (ADR 0032) or the
+    // naming of a Codex thread (#480) is missing.
     if (isDeepStrictEqual(settings, wanted)) {
       for (const tool of toolHooksOf(harness, bots, bot)) {
         const toolRunning = programIn(settings, tool.pattern);
@@ -267,24 +239,15 @@ function withKitHook(hooks, file, mine) {
 
 /** Each harness's kit hooks beside its session hook, as `toolHookOf` gives each. */
 const toolHooksOf = (harness, bots, bot, cli = ownCli()) =>
-  (harness === 'claude' ? ['sent', 'mail'] : ['nudge', 'name']).map((kind) => toolHookOf(kind, bots, bot, cli));
+  (harness === 'claude' ? ['sent'] : ['name']).map((kind) => toolHookOf(kind, bots, bot, cli));
 
 /**
  * One of the kit's hooks beside its session hook: Claude Code's after a native
- * `SendMessage` (`sent`, ADR 0032), Codex's after its shell tool (`nudge`,
- * ADR 0034), and Codex's at a turn end (`name`, #480). The entry, where it
- * goes, how the kit knows its own, and what is lost without it.
+ * `SendMessage` (`sent`, ADR 0032), and Codex's at a turn end (`name`, #480).
+ * The entry, where it goes, how the kit knows its own, and what is lost
+ * without it.
  */
 function toolHookOf(kind, bots, bot, cli = ownCli()) {
-  if (kind === 'mail') {
-    return {
-      kind,
-      event: MAIL_EVENT,
-      pattern: KIT_MAIL,
-      mine: { type: 'command', command: mailCommand(bots, bot, cli), timeout: MAIL_TIMEOUT },
-      missing: 'a Claude session busy when fleet mail came is never told about it at the end of its turn, and nothing is typed into its tab either (#509)',
-    };
-  }
   if (kind === 'name') {
     return {
       kind,
@@ -294,26 +257,34 @@ function toolHookOf(kind, bots, bot, cli = ownCli()) {
       missing: "a Codex session's thread is never named after its bot and session, and its tab shows a topic Codex made up instead (#480)",
     };
   }
-  if (kind === 'sent') {
-    return {
-      kind,
-      event: SENT_EVENT,
-      matcher: SENT_MATCHER,
-      pattern: KIT_SENT,
-      mine: { type: 'command', command: sentCommand(bots, bot, cli), timeout: TIMEOUT },
-      missing: 'a session is never warned when its native message goes outside this bots folder (ADR 0032)',
-    };
-  }
   return {
     kind,
-    event: NUDGE_EVENT,
-    matcher: NUDGE_MATCHER,
-    pattern: KIT_NUDGE,
-    mine: { type: 'command', command: nudgeCommand(bots, bot, cli), timeout: NUDGE_TIMEOUT },
-    missing: "mail a session sends from inside Codex's sandbox never tells a receiver the kit could not see from there, such as a Claude session busy with a command (ADR 0034)",
+    event: SENT_EVENT,
+    matcher: SENT_MATCHER,
+    pattern: KIT_SENT,
+    mine: { type: 'command', command: sentCommand(bots, bot, cli), timeout: TIMEOUT },
+    missing: 'a session is never warned when its native message goes outside this bots folder (ADR 0032)',
   };
 }
 
+/**
+ * The hooks without the kit's entries of these patterns, the hooks it no
+ * longer writes, and everything else as the user left it. A group the kit
+ * empties goes, and an event left with no groups goes with it.
+ */
+function withoutHooks(hooks, patterns) {
+  return Object.fromEntries(Object.entries(hooks).flatMap(([event, groups]) => {
+    if (!Array.isArray(groups)) return [[event, groups]];
+    const kept = groups.flatMap((group) => {
+      if (!Array.isArray(group?.hooks)) return [group];
+      const entries = group.hooks.filter((hook) => patterns.every((pattern) => programOf(hook?.command, pattern) === undefined));
+      if (entries.length === group.hooks.length) return [group];
+      return entries.length === 0 ? [] : [{ ...group, hooks: entries }];
+    });
+    return kept.length === 0 ? [] : [[event, kept]];
+  }));
+}
+
 /**
  * The hooks with the kit's tool hook in a group of its event matched to its
  * tool (or with no matcher, for one that has none), and everything else as the
@@ -380,6 +351,7 @@ const isKitHook = (hook) => kitProgramOf(hook?.command) !== undefined;
 const WORD = String.raw`(?:[A-Za-z0-9,._+:@%/=-]+|'(?:[^']|'\\'')*')`;
 const KIT_HOOK = new RegExp(String.raw`^(${WORD}) session record --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_SENT = new RegExp(String.raw`^(${WORD}) session sent --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
+/** The hooks the kit wrote before #555, and takes out. */
 const KIT_NUDGE = new RegExp(String.raw`^(${WORD}) session nudge --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_MAIL = new RegExp(String.raw`^(${WORD}) session mail --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
 const KIT_NAME = new RegExp(String.raw`^(${WORD}) session name --bots ${WORD} --bot ${WORD} 2>/dev/null \|\| true$`);
@@ -390,7 +362,7 @@ const KIT_NAME = new RegExp(String.raw`^(${WORD}) session name --bots ${WORD} --
  * (#506). One that runs some other program, even another `obk`, is not.
  */
 export const runsThisKit = (hook, cli = ownCli()) =>
-  hook?.type === 'command' && [KIT_HOOK, KIT_SENT, KIT_NUDGE, KIT_NAME].some((pattern) => programOf(hook.command, pattern) === cli);
+  hook?.type === 'command' && [KIT_HOOK, KIT_SENT, KIT_NAME].some((pattern) => programOf(hook.command, pattern) === cli);
 
 /** The program a bot made before the kit named itself by path runs. */
 const BARE = 'obk';

package/src/launch.js

@@ -76,7 +76,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 0035). It goes on the launch line as `-n`, and it is
+ * session writes to (ADR 0042). 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.
  *
@@ -231,7 +231,7 @@ const where = (session) => (set(session.name) ? `session ${session.name}` : 'thi
  * send would land on that list and answer it. A prompt given as an argument is
  * held by the harness until it is ready for it (tech notes, section 1).
  */
-export function launchCommand(session, { harness, home, workDir, prompt, promptFile: fromFile, resume, address }) {
+export function launchCommand(session, { harness, home, workDir, prompt, promptFile: fromFile, resume, address, kit }) {
   const trouble = sessionTrouble(session, harness, home);
   if (trouble !== undefined) throw new Error(trouble);
 
@@ -249,7 +249,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 0035).
+    // every launch line, a resume included (ADR 0042).
     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);
@@ -265,6 +265,10 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
     // 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);
+    // And the kit's own folders for this bot beside the bots folder: its long
+    // message bodies, its start prompts and its locks (#534). The bot's, and no
+    // other bot's: a session never gets to write another bot's mail.
+    if (kit !== undefined) for (const folder of Object.values(kit)) words.push('--add-dir', folder);
   }
 
   return [
@@ -339,6 +343,19 @@ const resumeWords = (harness, resume) => {
   return harness === 'claude' ? ['--resume', quoted(resume)] : [quoted(resume)];
 };
 
+/**
+ * The kit's own folders for one bot, beside the bots folder: `messages` for
+ * the bodies of its long fleet mail, `prompts` for its sessions' start
+ * prompts, `locks` for its book's and its sessions' turns. Each is a folder of
+ * the bot's own, so that a Codex session, whose sandbox writes only where its
+ * launch line says, can be given its bot's and no other's (#534).
+ */
+export const kitFolders = (bots, bot) => ({
+  messages: path.join(`${bots}.messages`, bot),
+  prompts: path.join(`${bots}.prompts`, bot),
+  locks: path.join(`${bots}.locks`, bot),
+});
+
 /** Whether `target` is the folder at `home` or something inside it. */
 const inside = (home, target) => target === home || target.startsWith(home + path.sep);