@assuredloop/orca-bot-kit 0.25.2 → 0.25.4

package/src/retire.js

@@ -17,7 +17,9 @@
 //
 // 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 0030).
+// The mailbox Runs stay: Orca has no way to remove one (ADR 0035). What the
+// kit knows of mail sent to a session and not read with `obk message check`
+// is said, with who sent it, so it is not lost without a word (#509).
 
 import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
 import path from 'node:path';
@@ -29,6 +31,7 @@ import { shellWord } from './launch.js';
 import { fleetMember } from './pause.js';
 import { closeTabs, commandLine, tabsToClose } from './restart.js';
 import { unlinkSkills } from './skills.js';
+import { takeUnread } from './unread.js';
 import { promptPath, sessionsOf } from './up.js';
 
 /** Where retired bots go: beside `bots/`, where nothing the kit runs looks. */
@@ -38,7 +41,8 @@ export const retiredDir = (bots) => path.join(bots, 'retired');
  * Retire the session `session` of the bot `bot`, and first the temporary
  * sessions it made, and theirs (#464, ADR 0033). Returns `{ bot, session,
  * closed, retiredWith }`, and `promptsLeft` when its prompt file could not be
- * removed. `retiredWith` holds one `{ bot, session, maker, closed }` for each
+ * removed, and `unread: { count, from }` when the kit knows of mail sent to it
+ * that it did not read with `obk message check` (#509). `retiredWith` holds one `{ bot, session, maker, closed }` for each
  * session that went with it, deepest first, with its own `promptsLeft`.
  */
 export async function retireSession(bots, { bot, session }) {
@@ -73,8 +77,9 @@ export async function retireSession(bots, { bot, session }) {
     throw error;
   }
   const left = removePrompts([promptPath(bots, bot, session)]);
+  const unread = takeUnread(home, session);
 
-  return { bot, session, closed, retiredWith, ...left };
+  return { bot, session, closed, retiredWith, ...left, ...(unread === undefined ? {} : { unread }) };
 }
 
 /**
@@ -85,14 +90,29 @@ function goneBefore(session, retiredWith) {
   const names = retiredWith.map((gone) => `${gone.bot}/${gone.session}, a temporary session of ${gone.maker}'s`);
   const left = retiredWith.flatMap((gone) => gone.promptsLeft ?? [])
     .map(({ file, reason }) => ` ${file} could not be removed (${reason}), and nothing reads it. Remove it with  rm ${shellWord(file)}`);
-  return `Retired along with ${session} before that, and still retired: ${names.join('; ')}.${left.join('')}`;
+  // Their hint of unread mail went with them, so this is the only place it is
+  // said (#509 review).
+  const unread = retiredWith.flatMap((gone) => (gone.unread === undefined ? [] : [` ${unreadWords(gone.unread, `${gone.bot}/${gone.session}`)}`]));
+  return `Retired along with ${session} before that, and still retired: ${names.join('; ')}.${unread.join('')}${left.join('')}`;
 }
 
+/**
+ * The mail a retired session did not read, as far as the kit knows (#509): the
+ * kit cannot see a read made with Orca's own check, so it says only this.
+ */
+export const unreadWords = (unread, who) =>
+  `${unread.count} ${unread.count === 1 ? 'message' : 'messages'} sent to ${who} ${unread.count === 1 ? 'was' : 'were'} not read with obk message check, from ${andList(unread.from)}.`;
+
+/** `a`, `a and b`, `a, b and c`. */
+const andList = (items) => (items.length <= 1 ? items.join('') : `${items.slice(0, -1).join(', ')} and ${items.at(-1)}`);
+
 /**
  * Retire the bot `bot`. Returns `{ bot, closed, project, windowReloaded, moved }`:
  * the tabs it closed, the Orca project it took away (if it had one), whether
  * Orca's window was reloaded after that, and where the bot is now; and
- * `promptsLeft` when a prompt file could not be removed.
+ * `promptsLeft` when a prompt file could not be removed, and `unread: [{
+ * session, count, from }]` for its sessions with mail the kit knows was not
+ * read with `obk message check` (#509).
  * When Orca does not confirm the project gone, it returns `{ bot, closed,
  * project, trouble }` instead, and the bot is left where it was.
  */
@@ -142,11 +162,16 @@ export async function retireBot(bots, { bot }) {
 
   const names = new Set([...known.sessions, ...booked].map((session) => session.name));
   const left = removePrompts([...names].map((name) => promptPath(bots, bot, name)));
+  // Before the folder moves: the hint is filed under the bot home's real path.
+  const unread = [...names].flatMap((name) => {
+    const taken = takeUnread(home, name);
+    return taken === undefined ? [] : [{ session: name, ...taken }];
+  });
   unlinkSkills(home);
   mkdirSync(retiredDir(bots), { recursive: true });
   renameSync(botDir(bots, bot), moved);
 
-  return { bot, closed, ...(project === undefined ? {} : { project: project.id, windowReloaded }), moved, ...left };
+  return { bot, closed, ...(project === undefined ? {} : { project: project.id, windowReloaded }), moved, ...left, ...(unread.length === 0 ? {} : { unread }) };
 }
 
 /**

package/src/unread.js

@@ -0,0 +1,160 @@
+// The kit's hint of the fleet mail it sent and that is not read yet (#509, ADR 0035).
+//
+// The mailbox is the record of a message; this is not. It is what the kit
+// itself knows: a send writes one file for the message, `obk message check`
+// takes out what it read, and a retire says what is left. A Claude session's
+// turn-end hook reads it first, so a session with no mail asks Orca nothing,
+// and asks Orca before it tells, so a stale entry tells nothing.
+//
+// It sits in the system temp folder because a sender inside Codex's sandbox
+// may write there and nowhere outside its own bot (#350). So it is private:
+// every folder the kit makes here is 0700, every file 0600, and a file holds
+// who sent the message and its subject, never its body. A temp clean-up loses
+// it, and loses no mail: the message still waits in the mailbox.
+//
+// One file for each message, `<session folder>/<message id>.json`, so senders
+// writing at once never write the same file; a `<message id>.told` beside it
+// once the session's hook told it, so it is told once; and a `<message
+// id>.read` once `obk message check` read it, so a send whose answer came back
+// after that read does not leave an entry for read mail (#509 review).
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Where the hint lives. */
+export const unreadRoot = () => path.join(os.tmpdir(), 'obk-unread');
+
+/** One session's folder: its bot home, by its real path, and its name. */
+function sessionDir(home, session) {
+  let real = home;
+  try {
+    real = realpathSync(home);
+  } catch {
+    // A home that is gone is named as it was given.
+  }
+  return path.join(unreadRoot(), encodeURIComponent(real), encodeURIComponent(session));
+}
+
+/** How long a read mark is kept for a send still waiting on Orca's answer. */
+const READ_MARK_MS = 60 * 60 * 1000;
+
+/** A message id as a file name: Orca's ids are plain, and anything else is made plain. */
+const fileOf = (id) => encodeURIComponent(String(id));
+
+/**
+ * Note one message sent to `session` of the bot at `home`: `{ id, from, subject,
+ * at }`. Quiet whatever happens: the message is sent either way.
+ */
+export function noteUnread(home, session, { id, from, subject, at }) {
+  if (id === undefined) return;
+  try {
+    const dir = sessionDir(home, session);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = path.join(dir, `${fileOf(id)}.json`);
+    // Written aside, then put in place whole: a reader never takes half a file.
+    writeFileSync(`${file}.${process.pid}.writing`, `${JSON.stringify({ id, from, subject, at })}\n`, { mode: 0o600 });
+    renameSync(`${file}.${process.pid}.writing`, file);
+    // Read already, while the send waited for Orca's answer: the entry is
+    // written first and taken out here, and a check writes its mark before it
+    // takes an entry out, so in either order no entry is left.
+    const read = path.join(dir, `${fileOf(id)}.read`);
+    if (existsSync(read)) {
+      rmSync(file, { force: true });
+      rmSync(read, { force: true });
+    }
+  } catch {
+    // Nothing: the hint is lost, the mail is not.
+  }
+}
+
+/**
+ * What the hint holds for `session`: `[{ id, from, subject, at, told }]`,
+ * oldest first. An entry that cannot be read is left out. A folder that is not
+ * there is no mail; one that cannot be read throws, for the caller to stay
+ * quiet about.
+ */
+export function unreadOf(home, session) {
+  const dir = sessionDir(home, session);
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+  const told = new Set(names.filter((name) => name.endsWith('.told')).map((name) => name.slice(0, -'.told'.length)));
+  return names
+    .filter((name) => name.endsWith('.json'))
+    .flatMap((name) => {
+      try {
+        const entry = JSON.parse(readFileSync(path.join(dir, name), 'utf8'));
+        if (entry === null || typeof entry !== 'object' || typeof entry.from !== 'string' || typeof entry.subject !== 'string') return [];
+        return [{ id: entry.id, from: entry.from, subject: entry.subject, at: entry.at, told: told.has(name.slice(0, -'.json'.length)) }];
+      } catch {
+        return [];
+      }
+    })
+    .sort((a, b) => String(a.at).localeCompare(String(b.at)));
+}
+
+/**
+ * Mark these messages told. Throws when a mark cannot be written: a hook that
+ * cannot remember it told must not tell, or it would tell again.
+ */
+export function markTold(home, session, ids) {
+  const dir = sessionDir(home, session);
+  for (const id of ids) writeFileSync(path.join(dir, `${fileOf(id)}.told`), '', { mode: 0o600 });
+}
+
+/**
+ * Take these messages out: they were read. Each gets a read mark first, for a
+ * send still waiting on Orca's answer (see `noteUnread`); marks older than an
+ * hour are cleared here, since no send waits that long. Quiet whatever happens.
+ */
+export function forgetUnread(home, session, ids) {
+  const dir = sessionDir(home, session);
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    for (const name of readdirSync(dir).filter((one) => one.endsWith('.read'))) {
+      if (Date.now() - statSync(path.join(dir, name)).mtimeMs > READ_MARK_MS) rmSync(path.join(dir, name), { force: true });
+    }
+  } catch {
+    // Nothing: a mark that stays is a few bytes in the temp folder.
+  }
+  for (const id of ids) {
+    try {
+      writeFileSync(path.join(dir, `${fileOf(id)}.read`), '', { mode: 0o600 });
+    } catch {
+      // Nothing: the entry is still taken out below.
+    }
+    for (const end of ['.json', '.told']) {
+      try {
+        rmSync(path.join(dir, `${fileOf(id)}${end}`), { force: true });
+      } catch {
+        // Nothing: a stale entry tells nothing, since the hook asks Orca first.
+      }
+    }
+  }
+}
+
+/**
+ * What the hint holds for a session that is going, as a retire says it:
+ * `{ count, from: [<bot>/<session>, …] }`, or undefined when nothing; and the
+ * session's folder is removed. Quiet whatever happens.
+ */
+export function takeUnread(home, session) {
+  let entries = [];
+  try {
+    entries = unreadOf(home, session);
+  } catch {
+    // Unreadable: nothing can be said of it.
+  }
+  try {
+    rmSync(sessionDir(home, session), { recursive: true, force: true });
+  } catch {
+    // Nothing: it is in the temp folder, and holds no body.
+  }
+  if (entries.length === 0) return undefined;
+  return { count: entries.length, from: [...new Set(entries.map((entry) => entry.from))] };
+}

package/src/up.js

@@ -14,7 +14,7 @@ import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from
 import { installHook } from './hooks.js';
 import { writePermissions } from './permissions.js';
 import { addressOf, harnessOf, isAddressOf, isShortPrompt, launchCommand, mailboxStep, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
-import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, screenRows, shellInTab, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
+import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, runMissing, screenRows, shellInTab, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
 import { TAB_ENV } from './record.js';
 import { buildAgents, rulesStamp } from './rules.js';
 import { linkSkills } from './skills.js';
@@ -648,7 +648,8 @@ async function writeAddress(home, session, address) {
  * a restart (tech notes, section 1). Orca offers no way to delete one, so this
  * makes one for a session whose book names none, and otherwise binds the one
  * the book names to this tab: after a restart, or a closed tab brought back,
- * it would stay with the tab that is gone (review of PR #248, finding 1).
+ * it would stay with the tab that is gone (review of PR #248, finding 1). A
+ * Run the book names and this Orca does not have at all is replaced (#508).
  *
  * Only inside an Orca tab. Asked from anywhere else, Orca picks a terminal
  * itself, and seen live that was not the asker's (tech notes, section 1), so
@@ -705,20 +706,34 @@ async function mailboxInTurn(home, botName, sessionName, who) {
       if (error.code === TIMED_OUT) {
         throw new Error(`${error.message}\n${who}'s mailbox ${held} may now be bound to this tab, or may still be bound where it was: Orca did not say which.`);
       }
-      throw new Error(`${error.message}\n${who}'s mailbox ${held} is unchanged: it is still bound to ${boundTo(held)}.`);
+      // A Run this Orca has never had, as when the book was written on another
+      // machine, can never be bound, so every start would fail the same way.
+      // It is replaced as a session with none would be given one (#508).
+      if (!runMissing(held, STEP_WAIT)) {
+        throw new Error(`${error.message}\n${who}'s mailbox ${held} is unchanged: it is still bound to ${boundTo(held)}.`);
+      }
+      return newMailbox(home, botName, sessionName, who, here, held);
     }
     return { bot: botName, session: sessionName, mailbox: held, change: 'bound' };
   }
+  return newMailbox(home, botName, sessionName, who, here);
+}
 
+/**
+ * Make a mailbox in this tab and write it into the book, for a session whose
+ * book names none, or names `stale`, a Run this Orca does not have.
+ */
+async function newMailbox(home, botName, sessionName, who, here, stale) {
   // Made outside the book's lock, which is held for one read and one write
   // (book.js).
   let made;
   try {
     made = makeMailbox(who, STEP_WAIT);
   } catch (error) {
+    const written = stale === undefined ? 'none is written down' : `the book still names ${stale}, which this Orca does not have`;
     const left = error.code === TIMED_OUT
-      ? `None is written down for ${who}; a Run Orca made after the kit stopped waiting is left unused.`
-      : `No mailbox was made for ${who}, and none is written down.`;
+      ? `For ${who}, ${written}; a Run Orca made after the kit stopped waiting is left unused.`
+      : `No mailbox was made for ${who}, and ${written}.`;
     throw new Error(`${error.message}\n${left} It gets one the next time the kit starts it.`);
   }
 
@@ -734,10 +749,11 @@ async function mailboxInTurn(home, botName, sessionName, who) {
         movedTo = now.tab ?? 'none';
         return undefined;
       }
-      // Under the lock, and only if the book still has none: two runs at once
-      // would each have made one, and a session with two mailboxes is a session
-      // half its mail never reaches. The loser's Run is left unused.
-      if (typeof now.mailbox !== 'string') now.mailbox = made;
+      // Under the lock, and only if the book still has none, or still the
+      // stale one: two runs at once would each have made one, and a session
+      // with two mailboxes is a session half its mail never reaches. The
+      // loser's Run is left unused.
+      if (typeof now.mailbox !== 'string' || now.mailbox === stale) now.mailbox = made;
       kept = now.mailbox;
       current.sessions[sessionName] = now;
       return undefined;
@@ -750,8 +766,13 @@ async function mailboxInTurn(home, botName, sessionName, who) {
   }
   // One terminal holds one Run, so making the loser took this tab off the one
   // the book kept. It goes back.
-  if (kept !== made) useMailbox(kept, undefined, STEP_WAIT);
-  return { bot: botName, session: sessionName, mailbox: kept, change: kept === made ? 'made' : 'bound' };
+  if (kept !== made) {
+    useMailbox(kept, undefined, STEP_WAIT);
+    return { bot: botName, session: sessionName, mailbox: kept, change: 'bound' };
+  }
+  return stale === undefined
+    ? { bot: botName, session: sessionName, mailbox: made, change: 'made' }
+    : { bot: botName, session: sessionName, mailbox: made, change: 'replaced', replaced: stale };
 }
 
 /**