@assuredloop/orca-bot-kit 0.20.0 → 0.22.0

package/src/message.js

@@ -15,7 +15,8 @@
 // one line into the receiver's tab. Both harnesses queue a typed line while
 // they are busy, which is what PRD 6.9 means by queued and not interrupting.
 
-import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 import { MAILBOX_WAIT_MS, readBook, takeMailboxTurn } from './book.js';
@@ -172,7 +173,7 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
     id: message.id,
     thread: message.thread_id ?? thread,
     file: written.file,
-    ...nudge(to, from, subject),
+    ...nudge(to, from, subject, tab),
   };
 }
 
@@ -452,14 +453,14 @@ const stamp = () => new Date().toISOString().replaceAll(':', '-').replace('.', '
  * it is nobody sending to a session before its first screens are answered,
  * which is the caller's work either way.
  */
-function nudge(to, from, subject) {
+function nudge(to, from, subject, tab) {
   if (to.tab === undefined) return { nudged: false };
 
   try {
     const found = lookAt(to);
     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.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure, ...(found.psUnread ? leftForHook(to, from, subject, tab) : {}) };
     if (found.handle === undefined) return { nudged: false };
 
     const sent = typeIntoTab(
@@ -485,6 +486,82 @@ function nudge(to, from, subject) {
   }
 }
 
+/**
+ * The nudge a Codex sender could not decide, left for its own hook (#350, ADR
+ * 0034): `{ nudgeLeft: true }`, or nothing when it is not left.
+ *
+ * Inside Codex's sandbox `ps` does not start, and for a Claude receiver busy
+ * with a command Orca's runtime cannot see past it either. Codex runs its
+ * hooks outside the sandbox, and the kit's `PostToolUse` hook runs right after
+ * the command that made this send, in the same tab, where `ps` runs. So the
+ * send leaves the nudge where that hook looks, the system temp folder under the
+ * tab's id, which the sandbox lets it write and the hook reads. Only for a
+ * Codex session sending from its own tab, and only where `ps` could not read
+ * the receiver's tab: anywhere else no hook would see it, or would see no more
+ * than the send did.
+ */
+function leftForHook(to, from, subject, tab) {
+  if (tab === undefined || from.tab !== tab || from.harness !== 'codex') return {};
+  try {
+    const dir = leftDir(tab);
+    mkdirSync(dir, { recursive: true });
+    const left = { bots: to.bots, to: `${to.bot}/${to.session}`, from: `${from.bot}/${from.session}`, subject };
+    // Written under a name the hook does not take, then put in place whole: a
+    // hook running beside this send never takes a file still being written.
+    const name = path.join(dir, `${stamp()}.${process.pid}`);
+    writeFileSync(`${name}.writing`, `${JSON.stringify(left)}\n`);
+    renameSync(`${name}.writing`, `${name}.json`);
+    return { nudgeLeft: true };
+  } catch {
+    return {};
+  }
+}
+
+/** Where the nudges left from one tab wait for its hook. */
+const leftDir = (tab) => path.join(os.tmpdir(), 'obk-nudges', encodeURIComponent(tab));
+
+/**
+ * What the kit's Codex hook does after each shell command (#350): decide every
+ * nudge a send in this tab left, oldest first, with the gate the send uses, and
+ * type it or not. Each is taken out before it is looked at, so it is decided
+ * once, by one hook. Returns `{ to, subject, ...what the nudge came to }` for
+ * each, as the send's own answer says it.
+ */
+export function decideLeftNudges(tab) {
+  if (tab === undefined) return [];
+  const dir = leftDir(tab);
+  let names;
+  try {
+    names = readdirSync(dir).filter((name) => name.endsWith('.json')).sort();
+  } catch {
+    return [];
+  }
+  return names.flatMap((name) => {
+    const taking = path.join(dir, `${name}.taking`);
+    // Another hook took it first: it is that hook's to decide, and to remove.
+    try {
+      renameSync(path.join(dir, name), taking);
+    } catch {
+      return [];
+    }
+    let left;
+    try {
+      left = JSON.parse(readFileSync(taking, 'utf8'));
+    } catch {
+      return [];
+    } finally {
+      rmSync(taking, { force: true });
+    }
+    try {
+      const to = findSession(left.bots, left.to);
+      const from = findSession(left.bots, left.from);
+      return [{ to: left.to, subject: left.subject, ...nudge(to, from, left.subject) }];
+    } catch (error) {
+      return [{ to: left.to, subject: left.subject, nudged: false, nudgeTrouble: error.message }];
+    }
+  });
+}
+
 /** Orca's words about a line it did not see start a turn, or what its receipt says when it gives none. */
 function unseen(sent) {
   const warnings = Array.isArray(sent?.warnings) ? sent.warnings.filter((warning) => typeof warning === 'string') : [];

package/src/orca-reload.applescript

@@ -1,5 +1,5 @@
 -- Run by the kit as `osascript orca-reload.applescript <Orca.app path>`, after
--- a project was removed (#343, ADR 0031).
+-- a project was removed (#343, ADR 0034).
 --
 -- Orca's window keeps a removed project in its sidebar until the window is
 -- rebuilt (stablyai/orca#23224; once a release fixes it, this can go behind a

package/src/orca-runtime.cjs

@@ -2,7 +2,7 @@
 // CLI: `ELECTRON_RUN_AS_NODE=1 <Orca> orca-runtime.cjs <client> <method> <params> <wait>`.
 //
 // It makes one call to Orca's runtime, through Orca's own client, for a method
-// Orca's CLI does not offer (ADR 0031): `project.update`, which makes Orca's
+// Orca's CLI does not offer (ADR 0034): `project.update`, which makes Orca's
 // window read its projects again (#224), and `terminal.inspectProcess`, which
 // says who is in front of a tab where `ps` cannot (#298). `params` is JSON. It
 // prints the runtime's answer as JSON and exits 0 only when the runtime took

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0031). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0034). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -216,7 +216,7 @@ const CLIENT_KILL_MS = 3000;
  *
  * Orca's window re-reads only when its runtime says the projects changed, and
  * `setup-update` and `setup-delete` do not say so. `project.update` with no
- * changes does, and Orca's CLI does not offer it (ADR 0031). The caller prints
+ * changes does, and Orca's CLI does not offer it (ADR 0034). The caller prints
  * `RELOAD_LINE` either way. It does not take a removed project out of the
  * sidebar: `reloadWindow` does.
  */
@@ -227,7 +227,7 @@ export const tellWindow = (projectId) => askRuntime('project.update', { projectI
  * runtime's answer, or undefined when there is none to be had.
  *
  * It goes through Orca's own runtime client out of the installed app, run by
- * Orca's binary the way its `bin/orca` runs its CLI (ADR 0031). None of that is
+ * Orca's binary the way its `bin/orca` runs its CLI (ADR 0034). None of that is
  * Orca's published interface, so anything that goes wrong is a quiet
  * undefined: it never throws and is never tried twice.
  */
@@ -264,7 +264,7 @@ const RELOAD_KILL_MS = 5000;
 
 /**
  * Have Orca's window force-reload itself, after a project was removed: true
- * only when it did (#343, ADR 0031).
+ * only when it did (#343, ADR 0034).
  *
  * The window keeps a removed project in its sidebar until it is rebuilt, and
  * `tellWindow` only relabels the row "Unknown" (stablyai/orca#23224; once a
@@ -418,7 +418,7 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  * Whether the rows of a rendered screen hold a question of the harness's own.
  *
  * Every one seen is a numbered list of choices with the harness's pointer on
- * one (tech notes, section 1; ADR 0031). The same pointer starts the harness's
+ * one (tech notes, section 1; ADR 0034). The same pointer starts the harness's
  * input line and its echo of the user's past turns, and the input line is the
  * lowest of them whenever it is on screen, so only the lowest pointer row is
  * asked about: a question counts while it stands in the input line's place.
@@ -449,7 +449,8 @@ export function questionIn(rows) {
  * `{}` for a tab with no harness in it (none in the book, none Orca lists, or
  * the shell in front), `{ blocked }` for one with something on screen waiting
  * to be answered, and `{ unsure }`, a sentence, for one the kit cannot tell
- * about. Orca refusing throws, for the caller to report.
+ * about, with `psUnread` where `ps` could not read the tab (#350). Orca
+ * refusing throws, for the caller to report.
  *
  * The one gate for every line the kit types into a running session: the mail
  * nudge and the skills reload. A busy harness passes it, since both harnesses
@@ -497,7 +498,8 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
     const why = seen.front === undefined
       ? seen.unreadable
       : `${seen.command} holds its terminal, and Orca names ${seen.agent ?? 'no agent'} in it`;
-    return { unsure: `the kit could not tell whether a harness is running in it (${why}), so nothing was typed` };
+    // Where `ps` could not read the tab, a reader that can may yet tell (#350).
+    return { unsure: `the kit could not tell whether a harness is running in it (${why}), so nothing was typed`, ...(seen.psUnread ? { psUnread: true } : {}) };
   }
   // Orca's reason does not cover every question: it called Codex's update
   // offer idle, and a return typed into it took "Update now" (#329). So the
@@ -554,13 +556,13 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
  *
  * `ps` is asked first. Where it cannot read the tab, as inside Codex's
  * sandbox, where it does not start at all, Orca's runtime is asked instead
- * (#298, ADR 0031).
+ * (#298, ADR 0034).
  */
 function frontOf(handle, ptyId, readMs) {
   const read = frontByPs(ptyId, readMs);
   if (read.unreadable === undefined) return read;
   const asked = frontByOrca(handle);
-  return asked.unreadable === undefined ? asked : { unreadable: `${read.unreadable}, and ${asked.unreadable}` };
+  return { ...(asked.unreadable === undefined ? asked : { unreadable: `${read.unreadable}, and ${asked.unreadable}` }), psUnread: true };
 }
 
 /**
@@ -590,7 +592,7 @@ function frontByOrca(handle) {
  * Who holds the terminal of the pane `ptyId`, as `ps` says it.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
- * gives that pid's terminal's foreground process group (ADR 0031).
+ * gives that pid's terminal's foreground process group (ADR 0034).
  * On macOS the pane is `login` with the shell as its child, so the shell is in
  * front when the group is the pane's own or that of a child of a `login` pane.
  * `diagnostics memory` is a diagnostics command and may change, so everything

package/src/retire.js

@@ -25,6 +25,7 @@ import path from 'node:path';
 import { readBook, tabIdsIn, updateBook } from './book.js';
 import { botDir, dropSession, readBot } from './bot.js';
 import { deleteProject, findProject, projects, reloadWindow, tabs } from './orca.js';
+import { shellWord } from './launch.js';
 import { fleetMember } from './pause.js';
 import { closeTabs, commandLine, tabsToClose } from './restart.js';
 import { unlinkSkills } from './skills.js';
@@ -34,26 +35,57 @@ import { promptPath, sessionsOf } from './up.js';
 export const retiredDir = (bots) => path.join(bots, 'retired');
 
 /**
- * Retire the session `session` of the bot `bot`. Returns `{ bot, session,
- * closed }`, and `promptsLeft` when its prompt file could not be removed.
+ * 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
+ * session that went with it, deepest first, with its own `promptsLeft`.
  */
 export async function retireSession(bots, { bot, session }) {
   const home = fleetMember(bots, bot, 'retire', session);
-  const sessions = sessionsOf(readBot(home, bot), session);
+  const known = readBot(home, bot);
+  const sessions = sessionsOf(known, session);
 
-  const closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot, commandLine('retire', bots, bot, session));
-  dropSession(bots, bot, session);
+  const retiredWith = [];
+  const book = readBook(home);
+  const made = known.sessions.filter((one) => book.sessions[one.name]?.temporary?.maker === session);
+  let closed;
+  try {
+    for (const { name } of made) {
+      const { retiredWith: theirs, ...gone } = await retireSession(bots, { bot, session: name });
+      retiredWith.push(...theirs, { ...gone, maker: 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 }];
-  });
+    closed = await closeTabs(home, tabsToClose(bots, bot, home, sessions, { keepless: true }), bots, bot, commandLine('retire', bots, bot, session));
+    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 }];
+    });
+  } catch (error) {
+    // What already went stays gone, and is named: a retire run again finds
+    // nothing of it left to name (#464).
+    if (retiredWith.length > 0) error.message = `${error.message} ${goneBefore(session, retiredWith)}`;
+    throw error;
+  }
   const left = removePrompts([promptPath(bots, bot, session)]);
 
-  return { bot, session, closed, ...left };
+  return { bot, session, closed, retiredWith, ...left };
+}
+
+/**
+ * The sessions retired along with `session` before its own retire failed, in
+ * words, with any prompt file of theirs left and how to remove it.
+ */
+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('')}`;
 }
 
 /**

package/src/sent.js

@@ -0,0 +1,111 @@
+// `obk session sent`: what the kit's PostToolUse hook says after a session's
+// native message (#451, ADR 0032).
+//
+// Claude Code's own messaging reaches every Claude session on the machine, not
+// only the sessions of one bots folder. After a send to another session, this
+// looks at where it went: to a session address none of the fleet's books name,
+// the session is told so, with the road the kit would have given it. The send
+// has gone either way. Nothing here decides anything about it, and anything it
+// cannot read is silence (ADR 0022: a hook never disturbs the session).
+//
+// It reads the send from its fields, never from its wording. Seen on Claude
+// Code 2.1.283: a send to an in-process teammate answers with a `routing`
+// object, and one to another session without it; the input's `to` names the
+// target, as a session's name with an optional ` [xxxxxx]` reference, or as a
+// `uds:` socket path when answering a message, which no book can map.
+
+import { readBook } from './book.js';
+import { botDir, botNames } from './bot.js';
+import { isAddressOf, ownCli, shellWord } from './launch.js';
+import { lookUp } from './message.js';
+import { TAB_ENV } from './record.js';
+
+/**
+ * The warning for a send the hook was told about, or undefined when there is
+ * nothing to say. `said` is what Claude Code handed the hook.
+ */
+export function sentWarning(bots, said) {
+  if (said?.tool_name !== 'SendMessage') return undefined;
+  const to = said.tool_input?.to;
+  if (typeof to !== 'string') return undefined;
+  const result = resultOf(said);
+  // A teammate in the same session, or a send that did not go: not this.
+  if (result === undefined || result.success !== true || 'routing' in result) return undefined;
+  if (/^(uds|bridge):/.test(to)) return undefined;
+
+  const name = to.replace(/\s*\[[^\]]*\]\s*$/, '').trim();
+  if (name === '') return undefined;
+  const fleet = addressesIn(bots);
+  if (fleet === undefined || fleet.all.has(name)) return undefined;
+
+  const meant = fleet.byName.get(name.split('.').slice(0, 2).join('.'));
+  const ask = (to) => `\`${shellWord(ownCli())} message to --bots ${shellWord(bots)} --to ${to}\``;
+  const road = meant === undefined
+    ? `${ask('<bot>/<session>')} gives the road to a session of this fleet.`
+    : roadTo(bots, meant, ask(`${meant.bot}/${meant.session}`));
+  return `That message went to ${name}, which is not one of the sessions of your bots folder, ${bots}: Claude Code's messaging reaches every session on this machine. ${road} Check before you send to it again.`;
+}
+
+/**
+ * The road to the session the sender probably meant, as `obk message to` would
+ * answer it from the sender's own tab: native to its address only between
+ * sessions of one approval class, the kit's mailbox otherwise (PRD 6.9). Where
+ * the sender cannot be told by its tab, the session's address and the question
+ * to ask, without claiming the address is the answer (#451 review).
+ */
+function roadTo(bots, meant, ask) {
+  let found;
+  try {
+    found = lookUp(bots, { to: `${meant.bot}/${meant.session}`, tab: process.env[TAB_ENV] });
+  } catch {
+    found = undefined;
+  }
+  const who = `${meant.bot}/${meant.session}`;
+  if (found?.transport === 'native' && typeof found.address === 'string') {
+    return `If you meant ${who}, ${ask} gives the road from your session: write to ${found.address} with your own messaging.`;
+  }
+  if (found?.transport === 'orca' && typeof found.address === 'string') {
+    return `If you meant ${who}, ${ask} gives the road from your session: its mailbox, ${found.address}, by \`${shellWord(ownCli())} message send\`, not your own messaging.`;
+  }
+  return `If you meant ${who}, its session address is ${meant.address}; ${ask} says which road to take from your session.`;
+}
+
+/** What the send answered, as an object: Claude Code hands it over as one, or as its JSON. */
+function resultOf(said) {
+  const raw = said.tool_output ?? said.tool_response;
+  if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) return raw;
+  if (typeof raw !== 'string') return undefined;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Every session address the fleet's books name, retired sessions' included, and
+ * each live one by `<bot>.<session>`: `{ all, byName }`. Undefined when a book
+ * cannot be read, since an address missing from it would be warned about wrongly.
+ */
+function addressesIn(bots) {
+  const all = new Set();
+  const byName = new Map();
+  try {
+    for (const bot of botNames(bots)) {
+      const book = readBook(botDir(bots, bot));
+      for (const [session, entry] of Object.entries(book.sessions ?? {})) {
+        const address = entry?.address;
+        if (typeof address !== 'string') continue;
+        all.add(address);
+        if (isAddressOf(bot, session, address)) byName.set(`${bot}.${session}`, { bot, session, address });
+      }
+      for (const entry of Array.isArray(book.retired) ? book.retired : []) {
+        if (typeof entry?.address === 'string') all.add(entry.address);
+      }
+    }
+  } catch {
+    return undefined;
+  }
+  return { all, byName };
+}