@assuredloop/orca-bot-kit 0.6.0 → 0.8.0

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0021). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0023). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -192,7 +192,7 @@ const CLIENT_KILL_MS = 3000;
  * `setup-update` and `setup-delete` do not say so. `project.update` with no
  * changes does, and Orca's CLI does not offer it, so this 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 0021). None of that is Orca's published
+ * its `bin/orca` runs its CLI (ADR 0023). None of that is Orca's published
  * interface, so anything that goes wrong is a quiet false: it never throws and
  * is never tried twice, and the caller prints `RELOAD_LINE` either way.
  */
@@ -262,7 +262,9 @@ export const retitleTab = (handle, title) =>
  * undefined when that cannot be read, with `unreadable` saying why. `answered` (an `ok` from `tui-idle`) and
  * `agent` are Orca's own hints, for a caller that has nothing better.
  * `blockedReason` is Orca saying something on screen wants answering, which is
- * for the caller to deal with, not the kit.
+ * for the caller to deal with, not the kit. `question` is the kit's own look at
+ * the screen, as `questionIn` answers, and `screenUnreadable` says why there
+ * was none.
  */
 export function harnessInTab(handle, timeoutMs) {
   const args = ['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle', '--timeout-ms', String(timeoutMs)];
@@ -281,9 +283,59 @@ export function harnessInTab(handle, timeoutMs) {
     blockedReason: answer.result?.wait?.blockedReason,
     agent,
     ...frontOf(shown?.ptyId),
+    ...screenOf(handle),
   };
 }
 
+/** The kit's word for a tab whose screen shows a question of its harness's own (#329). */
+export const QUESTION_ON_SCREEN = 'question-on-screen';
+
+/**
+ * What the tab `handle` renders: `{ question }`, true when it shows a question
+ * of its harness's own, or `{ screenUnreadable: <why> }`. Orca refusing is an
+ * answer that cannot be read, not an error, and so is anything that is not the
+ * rendered screen: accumulated output comes back in fragments (tech notes,
+ * section 1).
+ */
+function screenOf(handle) {
+  let read;
+  try {
+    read = orca(['terminal', 'read', '--terminal', handle, '--screen']).terminal;
+  } catch (error) {
+    return { screenUnreadable: `Orca would not read its screen: ${error.message}` };
+  }
+  if (read?.source !== 'screen' || !Array.isArray(read.tail)) {
+    return { screenUnreadable: `Orca gave no rendered screen for it (source: ${read?.source ?? 'none'})` };
+  }
+  return { question: questionIn(read.tail) };
+}
+
+/** A row the harness starts with its selection pointer: `›` on Codex, `❯` on Claude Code. */
+const POINTER_ROW = /^ *[›❯]/;
+
+/** That pointer on a numbered choice, and the column its number starts in. */
+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 0023). 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.
+ * 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.
+ */
+export function questionIn(rows) {
+  const at = rows.findLastIndex((row) => POINTER_ROW.test(row));
+  const pointer = at < 0 ? null : ON_A_CHOICE.exec(rows[at]);
+  if (pointer === null) return false;
+  const column = pointer[1].length;
+  const choice = (row) => typeof row === 'string' && row.slice(0, column).trim() === '' && /^\d+\. /.test(row.slice(column));
+  return choice(rows[at - 1]) || choice(rows[at + 1]);
+}
+
 /**
  * Whether the kit may type a line into `tabId`, the tab the book holds for a
  * session in the Orca project at `home`, and the handle to type into when it
@@ -323,6 +375,13 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
       : `${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` };
   }
+  // 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
+  // screen is read too, and one that cannot be read is not a reason to type.
+  if (seen.question === true) return { blocked: QUESTION_ON_SCREEN };
+  if (seen.question === undefined) {
+    return { unsure: `the kit could not tell whether a question is waiting on its screen (${seen.screenUnreadable}), so nothing was typed` };
+  }
   return { handle: live.handle, agent: seen.agent };
 }
 
@@ -346,11 +405,11 @@ const psCli = () => process.env.OBK_PS || '/bin/ps';
 
 /**
  * Who holds the terminal of the pane `ptyId`: `{ front: 'shell' }`,
- * `{ front: 'program', command }` with the name of the process leading the
- * group in front, or `{ unreadable: <why> }`.
+ * `{ front: 'program', command, pid }` with the name and pid of the process
+ * leading the group in front, or `{ unreadable: <why> }`.
  *
  * Orca gives the pane's pid in `diagnostics memory` and nowhere else, and `ps`
- * gives that pid's terminal's foreground process group (ADR 0021).
+ * gives that pid's terminal's foreground process group (ADR 0023).
  * 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
@@ -374,7 +433,20 @@ function frontOf(ptyId) {
   const front = psLine(own.tpgid);
   if (front === undefined) return { unreadable: `ps could not read the process in front, pid ${own.tpgid}` };
   const shell = front.ppid === pane && path.basename(own.comm) === 'login';
-  return shell ? { front: 'shell' } : { front: 'program', command: path.basename(front.comm) };
+  return shell ? { front: 'shell' } : { front: 'program', command: path.basename(front.comm), pid: own.tpgid };
+}
+
+/**
+ * The process `pid` as `ps -E` gives it, word by word: its command, its
+ * arguments, then its environment as `NAME=value` words. Undefined when it
+ * cannot be read. macOS gives a same-user harness's environment this way (tech
+ * notes, section 1); nothing in it says where the arguments end, so a caller
+ * looks for one whole word it knows.
+ */
+export function wordsOfProcess(pid) {
+  const asked = spawnSync(psCli(), ['-E', '-ww', '-o', 'command=', '-p', String(pid)], { encoding: 'utf8' });
+  if (asked.error || asked.status !== 0) return undefined;
+  return asked.stdout.trim().split(/\s+/);
 }
 
 /** One process as `ps` gives it, read only: `{ ppid, tpgid, comm }`, or undefined. */

package/src/record.js

@@ -166,22 +166,26 @@ function unclaimedFor(book, home, bot, tabId, id) {
 }
 
 /**
- * Whether the harness that ran this hook is the session's own — the one the kit
- * typed into the tab — rather than a harness started inside the session.
+ * Whether the harness that ran this hook is the session's own — the one the
+ * tab's shell started — rather than a harness started inside the session.
  *
  * Proved live on both harnesses (tech notes, sections 2 and 3): a hook's process
  * is the harness's own child, or the child of the shell the harness ran the hook
  * command through. Either way the harness itself is the process just above, and
- * the session's harness is the child of the shell named in the launch line. A
- * harness started inside the session sits further down a longer chain, under
- * whatever shell the agent ran it from, so it can never answer this.
+ * the session's harness is the child of the tab's shell. A harness started
+ * inside the session sits further down a longer chain, under whatever shell the
+ * agent ran it from, so it can never answer this.
+ *
+ * The launch line names the tab's shell. A tab Orca brought back by itself has
+ * no launch line (#318), and there the tab's shell is the one `login` started
+ * for the pane, which is where Orca's own resume puts the harness too (tech
+ * notes, section 1).
  *
  * Anything it cannot establish is a no: a report that cannot be shown to be the
  * session's own is not written down.
  */
 export function startedTheSession(shellPid, pid = process.pid) {
-  if (!/^[0-9]+$/.test(String(shellPid ?? ''))) return false;
-  const shell = Number(shellPid);
+  if (shellPid !== undefined && !/^[0-9]+$/.test(String(shellPid))) return false;
 
   const tree = processTree();
   if (tree === undefined) return false;
@@ -190,11 +194,21 @@ export function startedTheSession(shellPid, pid = process.pid) {
   const parent = mine === undefined ? undefined : tree.get(mine.ppid);
   if (parent === undefined) return false;
 
-  if (parent.ppid === shell) return true;
-  if (!isShell(parent.command)) return false;
+  if (shellPid !== undefined) {
+    const shell = Number(shellPid);
+    if (parent.ppid === shell) return true;
+    if (!isShell(parent.command)) return false;
+
+    const above = tree.get(parent.ppid);
+    return above !== undefined && above.ppid === shell;
+  }
 
-  const above = tree.get(parent.ppid);
-  return above !== undefined && above.ppid === shell;
+  // With no shell named, which process is the harness has to be settled first:
+  // the one above the shell the hook ran through, or the hook's own parent.
+  const harness = isShell(parent.command) ? tree.get(parent.ppid) : parent;
+  const shell = harness === undefined ? undefined : tree.get(harness.ppid);
+  const pane = shell === undefined ? undefined : tree.get(shell.ppid);
+  return pane !== undefined && path.basename(pane.command) === 'login';
 }
 
 /** Every process on the machine, by pid: who its parent is and what it runs. */

package/src/skills.js

@@ -292,7 +292,7 @@ export function unlinkSkills(home) {
  * user made, or one of the kit's that they have since repointed, is theirs.
  *
  * It is the kit's own file and lives beside the hook files it already keeps in
- * the bot folder (ADR 0020). A record that cannot be read is treated as an
+ * the bot folder (ADR 0022). A record that cannot be read is treated as an
  * empty one: the worst that follows is that the kit leaves alone something it
  * would otherwise have tidied up, which is the safe way round.
  */

package/src/up.js

@@ -13,7 +13,7 @@ import { botDir, botNames, displayName, readBot } from './bot.js';
 import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
 import { addressOf, harnessOf, isAddressOf, isShortPrompt, launchCommand, mailboxStep, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
-import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
+import { asFolderProject, coordinatorOf, findProject, harnessInTab, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, tabs, 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';
@@ -94,7 +94,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
  *
  * Separate from the tabs because the order matters twice over. A session reads
  * its rules, its skills and its hooks as it comes up, so all three have to be
- * there before the tab is (PRD 6.6, ADR 0020) — and a restart closes a tab in
+ * there before the tab is (PRD 6.6, ADR 0022) — and a restart closes a tab in
  * between, so everything that can refuse must have refused before that. It
  * refuses by throwing, exactly as `up` always has; a bot it leaves out of
  * `running` is one whose sessions must not be started.
@@ -140,7 +140,7 @@ export function prepareBots(bots, names, onlySession) {
 
   // And the kit's hook goes into every bot folder before Orca is asked for
   // anything, for the same reason: a harness reads its hooks when it comes up,
-  // so one written later would miss the session it was written for (ADR 0020),
+  // so one written later would miss the session it was written for (ADR 0022),
   // and a bot folder the kit cannot write it into stops the run with nothing
   // opened anywhere. Only the harnesses a bot actually runs on; a bot with no
   // sessions gets none.
@@ -440,7 +440,7 @@ async function heldInRecord(home, name, harness, prompt, { launched, running })
 
 /**
  * One look at a tab the kit just typed a launch line into: whether a harness
- * is running there, and what it is waiting on if Orca says.
+ * is running there, and what it is waiting on if Orca or its screen says.
  *
  * The harness is up when something other than the shell holds the tab's
  * terminal, busy or not, or when Orca sees a question on its screen. Orca's
@@ -452,7 +452,10 @@ function lookFor(handle, timeoutMs) {
   const seen = harnessInTab(handle, timeoutMs);
   const running = seen.blockedReason !== undefined
     || (seen.front === undefined ? seen.answered || seen.agent !== undefined : seen.front === 'program');
-  return { running, blockedReason: seen.blockedReason };
+  // A question the kit sees on the screen of a harness that is running, where
+  // Orca named none (#329).
+  const question = running && seen.question === true ? QUESTION_ON_SCREEN : undefined;
+  return { running, blockedReason: seen.blockedReason ?? question };
 }
 
 /**