@assuredloop/orca-bot-kit 0.23.0 → 0.25.0

package/src/hooks.js

@@ -69,6 +69,21 @@ const NUDGE_TIMEOUT = 30;
 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
+ * 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
+ * a look through Orca's gate, and a hook stopped partway would leave half the
+ * command in the input line, so the timeout leaves room to spare.
+ */
+const NAME_EVENT = 'Stop';
+const NAME_TIMEOUT = 300;
+
+/** What the naming hook runs, by the kit's own path, as `hookCommand` does. */
+export const nameCommand = (bots, bot, cli = ownCli()) =>
+  `${shellWord(cli)} session name --bots ${shellWord(bots)} --bot ${shellWord(bot)} 2>/dev/null || true`;
+
 /**
  * Make sure the bot at `home` has the kit's SessionStart hook for `harness`.
  * Returns the file it wrote, relative to the bot home, or undefined when the
@@ -91,7 +106,7 @@ 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: withToolHook(started, toolHookOf(harness, bots, bot)) };
+  const wanted = { ...settings, hooks: toolHooksOf(harness, bots, bot).reduce(withToolHook, started) };
 
   // Compared as documents, not as text: how the user laid their file out is
   // theirs, and a run that changes nothing writes nothing.
@@ -138,26 +153,29 @@ 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 second hook is judged on its own: the session hook may be
-    // right while the warning after a native message (ADR 0032), or the nudge
-    // a Codex sender left (ADR 0034), is missing.
+    // 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.
     if (isDeepStrictEqual(settings, wanted)) {
-      const tool = toolHookOf(harness, bots, bot);
-      const toolRunning = programIn(settings, tool.pattern);
-      // One that runs a kit no longer there is as quiet as a missing one:
-      // `|| true` hides it (#451 review).
-      if (toolRunning !== undefined && toolRunning !== BARE && !existsSync(toolRunning)) {
-        return {
-          where: file,
-          says: `${file} holds the kit's ${tool.event} hook for ${tool.matcher}, but it runs ${toolRunning}, which is not there any more, so ${tool.missing}. obk up puts back one that runs the kit you have.`,
-        };
-      }
-      const withTool = { ...settings, hooks: withToolHook(settings.hooks, toolHookOf(harness, bots, bot, toolRunning ?? program)) };
-      if (!isDeepStrictEqual(settings, withTool)) {
-        return {
-          where: file,
-          says: `${file} does not hold the kit's ${tool.event} hook for ${tool.matcher}, without which ${tool.missing}. obk up puts it back.`,
-        };
+      for (const tool of toolHooksOf(harness, bots, bot)) {
+        const toolRunning = programIn(settings, tool.pattern);
+        const what = tool.matcher === undefined ? `${tool.event} hook` : `${tool.event} hook for ${tool.matcher}`;
+        // One that runs a kit no longer there is as quiet as a missing one:
+        // `|| true` hides it (#451 review).
+        if (toolRunning !== undefined && toolRunning !== BARE && !existsSync(toolRunning)) {
+          return {
+            where: file,
+            says: `${file} holds the kit's ${what}, but it runs ${toolRunning}, which is not there any more, so ${tool.missing}. obk up puts back one that runs the kit you have.`,
+          };
+        }
+        const withTool = { ...settings, hooks: withToolHook(settings.hooks, toolHookOf(tool.kind, bots, bot, toolRunning ?? program)) };
+        if (!isDeepStrictEqual(settings, withTool)) {
+          return {
+            where: file,
+            says: `${file} does not hold the kit's ${what}, without which ${tool.missing}. obk up puts it back.`,
+          };
+        }
       }
     }
   } catch (error) {
@@ -230,15 +248,29 @@ function withKitHook(hooks, file, mine) {
   return { ...events, [EVENT]: [...(events[EVENT] ?? []), { hooks: [mine] }] };
 }
 
+/** Each harness's kit hooks beside its session hook, as `toolHookOf` gives each. */
+const toolHooksOf = (harness, bots, bot, cli = ownCli()) =>
+  (harness === 'claude' ? ['sent'] : ['nudge', 'name']).map((kind) => toolHookOf(kind, bots, bot, cli));
+
 /**
- * Each harness's second kit hook, after one of its tools: Claude Code's after a
- * native `SendMessage` (ADR 0032), Codex's after its shell tool (ADR 0034).
- * The entry, where it goes, how the kit knows its own, and what is lost
- * without it.
+ * 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.
  */
-function toolHookOf(harness, bots, bot, cli = ownCli()) {
-  if (harness === 'claude') {
+function toolHookOf(kind, bots, bot, cli = ownCli()) {
+  if (kind === 'name') {
+    return {
+      kind,
+      event: NAME_EVENT,
+      pattern: KIT_NAME,
+      mine: { type: 'command', command: nameCommand(bots, bot, cli), timeout: NAME_TIMEOUT, async: true },
+      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,
@@ -247,6 +279,7 @@ function toolHookOf(harness, bots, bot, cli = ownCli()) {
     };
   }
   return {
+    kind,
     event: NUDGE_EVENT,
     matcher: NUDGE_MATCHER,
     pattern: KIT_NUDGE,
@@ -257,10 +290,11 @@ function toolHookOf(harness, bots, bot, cli = ownCli()) {
 
 /**
  * The hooks with the kit's tool hook in a group of its event matched to its
- * tool, and everything else as the user left it, as `withKitHook` keeps the
- * session hook: one entry of the kit's, written in place where it already sits
- * in such a group, taken out of anywhere else, and added in a group of its own
- * when there is none. A group the kit empties goes.
+ * tool (or with no matcher, for one that has none), and everything else as the
+ * user left it, as `withKitHook` keeps the session hook: one entry of the
+ * kit's, written in place where it already sits in such a group, taken out of
+ * anywhere else, and added in a group of its own when there is none. A group
+ * the kit empties goes.
  */
 function withToolHook(hooks, { event: wantedEvent, matcher, pattern, mine }) {
   let placed = false;
@@ -279,7 +313,8 @@ function withToolHook(hooks, { event: wantedEvent, matcher, pattern, mine }) {
     return kept.length === 0 ? [] : [[event, kept]];
   }));
   if (placed) return events;
-  return { ...events, [wantedEvent]: [...(events[wantedEvent] ?? []), { matcher, hooks: [mine] }] };
+  const group = matcher === undefined ? { hooks: [mine] } : { matcher, hooks: [mine] };
+  return { ...events, [wantedEvent]: [...(events[wantedEvent] ?? []), group] };
 }
 
 /** The program a command of the kit's of this pattern runs, unquoted, or undefined for any other command. */
@@ -320,6 +355,7 @@ 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$`);
 const KIT_NUDGE = new RegExp(String.raw`^(${WORD}) session nudge --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$`);
 
 /** The program a bot made before the kit named itself by path runs. */
 const BARE = 'obk';

package/src/message.js

@@ -19,7 +19,7 @@ import { mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync,
 import os from 'node:os';
 import path from 'node:path';
 
-import { MAILBOX_WAIT_MS, readBook, takeMailboxTurn } from './book.js';
+import { MAILBOX_WAIT_MS, readBook, takeLineTurn, takeMailboxTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 import { botDir, botNames, readBot } from './bot.js';
 import { harnessOf, isAddressOf, ownCli, reachesMail, SHELL_ENV, shellWord } from './launch.js';
 import { ackMailbox, coordinatorOf, postMessage, readMailbox, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, typeIntoTab, useMailbox } from './orca.js';
@@ -456,6 +456,18 @@ const stamp = () => new Date().toISOString().replaceAll(':', '-').replace('.', '
 function nudge(to, from, subject, tab) {
   if (to.tab === undefined) return { nudged: false };
 
+  // A line typed while the kit types a command one key at a time would land
+  // in it and send it with its own return (#480): so the receiver's turn for
+  // a line first, for a bounded time, and the mail waits in its mailbox if not.
+  let turn;
+  try {
+    turn = takeLineTurn(to.home, to.session, TYPING_WAIT_MS);
+  } catch (error) {
+    return { nudged: false, nudgeTrouble: error.message };
+  }
+  if (turn === undefined) {
+    return { nudged: false, nudgeTrouble: TYPING_HELD };
+  }
   try {
     const found = lookAt(to);
     if (found.blocked !== undefined) return { nudged: false, blocked: found.blocked };
@@ -483,6 +495,8 @@ function nudge(to, from, subject, tab) {
     // silent `false` would read as "the session is not up", which is a
     // different thing from "Orca would not say".
     return { nudged: false, nudgeTrouble: error.message };
+  } finally {
+    turn.release();
   }
 }
 

package/src/name.js

@@ -0,0 +1,138 @@
+// `obk session name`: the kit names a Codex session's thread `<bot>.<session>`
+// (#480), so the tab, which Codex titles with the thread's name after every
+// turn, says which bot and session it is. A Claude session has its name from
+// the kit's `-n` already.
+//
+// Codex 0.160.0 has no launch-time way to name a thread, so this types Codex's
+// own `/rename` (the architect's ruling on #480). It runs from the kit's async
+// Stop hook (src/hooks.js) at each turn end, never inside a turn: a fresh
+// start's first turn is its start prompt, which nothing may cut off. It types
+// only through the path `obk session clear` takes (src/clear.js, #391), and
+// what is not safe to type now waits for the next turn end.
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { setTimeout as pause } from 'node:timers/promises';
+
+import { readBook, takeNameTurn, takeTypingTurn } from './book.js';
+import { botDir, readBot } from './bot.js';
+import { sessionToType, typeCommand } from './clear.js';
+import { harnessOf } from './launch.js';
+import { sessionsOf } from './up.js';
+
+/**
+ * Where Codex keeps its threads' names: a line `{ id, thread_name, updated_at }`
+ * a name, the file only growing and the newest line for an id winning
+ * (codex-rs/rollout/src/session_index.rs, rust-v0.160.0).
+ */
+const sessionIndex = () => path.join(homedir(), '.codex', 'session_index.jsonl');
+
+/**
+ * When a naming stops typing, counted from its start: well inside the hook's
+ * 300 s (src/hooks.js), at which Codex kills the hook's whole process group
+ * (codex-rs/hooks/src/engine/command_runner.rs), so that what was typed is
+ * taken back first.
+ */
+const DEADLINE_MS = 240_000;
+
+/** How long Codex is given to write the name down after the return. */
+const CONFIRM_MS = 10_000;
+const ASK_MS = 500;
+
+/**
+ * Name the thread that just ended a turn in the tab `tabId`, as Codex's Stop
+ * hook `said` it, when that tab is a Codex session of `bot` and its thread does
+ * not have the name yet. Returns whether Codex's record names it afterwards,
+ * or undefined when there was nothing to do. Throws when it could not type.
+ */
+export async function nameSession(bots, bot, said, tabId) {
+  const deadline = Date.now() + DEADLINE_MS;
+  if (said?.hook_event_name !== 'Stop') return undefined;
+  if (typeof tabId !== 'string' || tabId === '') return undefined;
+
+  const home = realpathSync(botDir(bots, bot));
+  const [session, entry] = Object.entries(readBook(home).sessions).find(([, one]) => one?.tab === tabId) ?? [];
+  if (session === undefined) return undefined;
+  const known = readBot(home, bot);
+  const [settings] = sessionsOf(known, session);
+  if (harnessOf(settings, known.harness) !== 'codex') return undefined;
+  // Only the thread the book says this tab is running. A Codex that Orca
+  // brought back by itself runs its hooks in Codex's shared background server,
+  // under another session's tab (#408), and that tab shows another thread.
+  const thread = said.session_id;
+  if (typeof thread !== 'string' || thread !== entry.session) return undefined;
+
+  const name = `${bot}.${session}`;
+  if (nameOf(thread) === name) return undefined;
+
+  const turn = takeNameTurn(home, session);
+  if (turn === undefined) return undefined;
+  let typing;
+  try {
+    // Another naming may have finished while this one waited for its turn.
+    if (nameOf(thread) === name) return undefined;
+    // Only into the tab the hook ran in: one whose Codex was killed hard can
+    // leave its hook running (Codex starts each hook in a session of its own,
+    // codex-rs/hooks/src/engine/command_runner.rs), and the tab the book holds
+    // now shows another process.
+    const it = { ...sessionToType(bots, bot, session), conversation: thread };
+    if (it.tabId !== tabId) return undefined;
+    // The session's typing turn, taken once it is idle and not before, so a
+    // mail nudge waits seconds for it and not the whole wait for idle. Held by
+    // anything else: nothing is typed, and the next turn end tries again.
+    const before = () => {
+      typing = takeTypingTurn(home, session, 0);
+      if (typing === undefined) throw new Error(`${it.name}: nothing was typed, because the kit is typing into its tab already.`);
+    };
+    try {
+      await typeCommand(it, `/rename ${name}`, { check: renameWrong, deadline, before });
+    } finally {
+      typing?.release();
+    }
+    const until = Date.now() + CONFIRM_MS;
+    while (nameOf(thread) !== name && Date.now() < until) await pause(ASK_MS);
+    return nameOf(thread) === name;
+  } finally {
+    turn.release();
+  }
+}
+
+/** The name Codex's record gives `thread` now, or undefined. */
+function nameOf(thread) {
+  let text;
+  try {
+    text = readFileSync(sessionIndex(), 'utf8');
+  } catch {
+    return undefined;
+  }
+  let name;
+  for (const line of text.split('\n')) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry?.id === thread && typeof entry.thread_name === 'string') name = entry.thread_name;
+  }
+  return name;
+}
+
+/**
+ * Why the screen does not show `command` typed and ready, or undefined when it
+ * does: the input line, the lowest row Codex's pointer starts, reads the
+ * pointer and the command exactly, and no row of its slash menu stands above
+ * it. With words after the command Codex has closed its menu (chat_composer.rs
+ * `sync_command_popup`, rust-v0.160.0), so a menu still open means the line is
+ * not what it seems.
+ */
+function renameWrong(rows, _harness, command) {
+  const at = rows.findLastIndex((row) => /^ *›/.test(row));
+  if (at < 0) return { why: 'its screen shows no input line' };
+  const line = rows[at].replaceAll(' ', ' ').trim();
+  if (line !== `› ${command}`) return { why: `its input line reads "${line}"` };
+  const above = rows.slice(0, at).findLast((row) => row.trim() !== '');
+  if (above !== undefined && /^ *(?:› +)?\/\S/.test(above)) return { why: `a menu of commands stands above its input line: "${above.trim()}"` };
+  return undefined;
+}

package/src/orca.js

@@ -420,8 +420,9 @@ const ON_A_CHOICE = /^( *[›❯] +)\d+\. /;
  * Every one seen is a numbered list of choices with the harness's pointer on
  * 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.
+ * lowest of them whenever it is on screen, so the lowest pointer row is asked
+ * about: a question counts while it stands in the input line's place, or
+ * while it is the last thing drawn right above the input box (#491).
  * Unnumbered lists do not count. Codex puts a status row right under its input
  * line, lined up with it, and by its layout that is one.
  */
@@ -434,6 +435,37 @@ export function questionIn(rows) {
   // there is none: under old words of one in the history, the input line is
   // the lowest pointer, and nothing below it is a foot.
   if (rows.slice(Math.max(at, 0)).some((row) => FORM_FOOT.test(row))) return true;
+  if (pointedChoiceAt(rows, at)) return true;
+  // Claude Code 2.1.289 draws its Teach list above its input box, whose own
+  // `❯` stays the lowest pointer row (#491). A question there is the last
+  // thing drawn above the box's top rule: its foot, or its numbered choices
+  // with the pointer on one, under it a foot that a narrow pane wraps onto
+  // rows of its own. The same words with anything after them are history.
+  if (at < 1 || !RULE_ROW.test(rows[at - 1])) return false;
+  let end = rows.slice(0, at - 1).findLastIndex((row) => row.trim() !== '');
+  if (end < 0) return false;
+  if (FORM_FOOT.test(rows[end])) return true;
+  while (end > 0 && FOOT_PART.test(rows[end])) end -= 1;
+  if (!NUMBERED.test(rows[end])) return false;
+  let first = end;
+  while (first > 0 && NUMBERED.test(rows[first - 1])) first -= 1;
+  for (let row = first; row <= end; row += 1) {
+    if (pointedChoiceAt(rows, row)) return true;
+  }
+  return false;
+}
+
+/** A rule Claude Code draws right across, as the top of its input box: `─` or `▔`. */
+const RULE_ROW = /^ *[─▔]{8,}/;
+
+/** A numbered choice, with the pointer on it or not. */
+const NUMBERED = /^ *(?:[›❯] +)?\d+\. /;
+
+/** A part of a foot, as a narrow pane wraps it: `Enter to confirm ·`, `Esc to cancel`. */
+const FOOT_PART = /\b(?:Enter to (?:continue|confirm|select)|Esc to cancel)\b/i;
+
+/** Whether `rows[at]` has the pointer on a numbered choice, with another lined up right above or below it. */
+function pointedChoiceAt(rows, at) {
   const pointer = at < 0 ? null : ON_A_CHOICE.exec(rows[at]);
   if (pointer === null) return false;
   const column = pointer[1].length;

package/src/skills.js

@@ -23,7 +23,7 @@ import { fileURLToPath } from 'node:url';
 
 import { parse, parseDocument, stringify } from 'yaml';
 
-import { bookFile, readBook } from './book.js';
+import { bookFile, readBook, takeLineTurn, TYPING_HELD, TYPING_WAIT_MS } from './book.js';
 import { botDir, botNames, changesExactly, leadsOutside, readBot, YAML_OUT } from './bot.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 import { orcaCli, orcaTrouble, tabToTypeInto, typeIntoTab } from './orca.js';
@@ -473,7 +473,14 @@ function tellSessions(home, bot, linked) {
     const tab = typeof book[session.name]?.tab === 'string' ? book[session.name].tab : undefined;
     if (tab === undefined) return { ...told, state: 'not-up' };
     if (down !== undefined) return { ...told, state: 'unknown', trouble: `Orca is not answering at ${orcaCli()}, so the kit could not look at its tab, and nothing was typed` };
+    let turn;
     try {
+      // The session's turn for a line (#482), for the look and its line. Codex
+      // is typed nothing here, so it waits for none.
+      if (harness !== 'codex') {
+        turn = takeLineTurn(real, session.name, TYPING_WAIT_MS);
+        if (turn === undefined) return { ...told, state: 'unknown', trouble: TYPING_HELD };
+      }
       const found = tabToTypeInto(real, tab, LOOK_MS);
       if (found.blocked !== undefined) return { ...told, state: 'blocked', blocked: found.blocked };
       if (found.unsure !== undefined) return { ...told, state: 'unknown', trouble: found.unsure };
@@ -495,6 +502,8 @@ function tellSessions(home, bot, linked) {
       // The links are made whatever Orca says, so this is reported, not
       // thrown: the build did what it was asked, and the session was not told.
       return { ...told, state: 'unknown', trouble: error.message };
+    } finally {
+      turn?.release();
     }
   });
 }