@assuredloop/orca-bot-kit 0.9.0 → 0.11.0

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0023). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0025). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -177,7 +177,7 @@ export function asFolderProject(setupId, title) {
  */
 export const deleteProject = (setupId) => orca(['project', 'setup-delete', '--setup', setupId]);
 
-/** Said after a run that made, renamed or removed a project, whatever `tellWindow` answered. */
+/** Said after a run that made or renamed a project, whatever `tellWindow` answered, and after a removal `reloadWindow` could not follow. */
 export const RELOAD_LINE = "If Orca's sidebar does not show it, reload the window with Cmd+Shift+R.";
 
 /** How long Orca's client waits for its runtime, and how long the kit waits for the client. */
@@ -190,13 +190,22 @@ 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, 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 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.
+ * changes does, and Orca's CLI does not offer it (ADR 0025). The caller prints
+ * `RELOAD_LINE` either way. It does not take a removed project out of the
+ * sidebar: `reloadWindow` does.
  */
-export function tellWindow(projectId) {
+export const tellWindow = (projectId) => askRuntime('project.update', { projectId, updates: {} }) !== undefined;
+
+/**
+ * One call to Orca's runtime for a method its CLI does not offer, and the
+ * 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 0025). 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.
+ */
+function askRuntime(method, params) {
   try {
     // The CLI sits at <Orca.app>/Contents/Resources/bin/orca, often reached
     // through a link.
@@ -209,16 +218,55 @@ export function tellWindow(projectId) {
 
     const asked = spawnSync(
       path.join(contents, 'MacOS', 'Orca'),
-      [WINDOW_SCRIPT, client, projectId, String(CLIENT_WAIT_MS)],
-      { env, stdio: 'ignore', timeout: CLIENT_KILL_MS },
+      [RUNTIME_SCRIPT, client, method, JSON.stringify(params), String(CLIENT_WAIT_MS)],
+      { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: CLIENT_KILL_MS },
     );
-    return asked.error === undefined && asked.status === 0;
+    if (asked.error !== undefined || asked.status !== 0) return undefined;
+    return parse(asked.stdout) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const RUNTIME_SCRIPT = fileURLToPath(new URL('./orca-runtime.cjs', import.meta.url));
+
+/** The `osascript` this run asks. OBK_OSASCRIPT overrides it, as OBK_PS does `ps`. */
+const osascriptCli = () => process.env.OBK_OSASCRIPT || '/usr/bin/osascript';
+
+/** How long macOS is given to click the menu item. */
+const RELOAD_KILL_MS = 5000;
+
+/**
+ * Have Orca's window force-reload itself, after a project was removed: true
+ * only when it did (#343, ADR 0025).
+ *
+ * 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
+ * release fixes it, this can go behind a version check). Orca's own menu item
+ * Force Reload rebuilds it and keeps every terminal. So on macOS the kit has
+ * System Events click that item, in the Orca app its CLI belongs to and no
+ * other, and only while that Orca is the front app: a click on a background
+ * Orca is taken and does nothing, and the kit does not take the user's screen. None of that is Orca's published interface, and macOS may refuse it,
+ * so anything that goes wrong is a quiet false, as with `tellWindow`: it never
+ * throws and is never tried twice, and the caller prints `RELOAD_LINE`.
+ */
+export function reloadWindow() {
+  if (process.platform !== 'darwin') return false;
+  try {
+    // <Orca.app>/Contents/Resources/bin/orca, often reached through a link.
+    const app = path.resolve(realpathSync(orcaCli()), '..', '..', '..', '..');
+    const asked = spawnSync(osascriptCli(), [RELOAD_SCRIPT, app], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: RELOAD_KILL_MS,
+    });
+    return asked.error === undefined && asked.status === 0 && asked.stdout.trim() === 'reloaded';
   } catch {
     return false;
   }
 }
 
-const WINDOW_SCRIPT = fileURLToPath(new URL('./orca-window.cjs', import.meta.url));
+const RELOAD_SCRIPT = fileURLToPath(new URL('./orca-reload.applescript', import.meta.url));
 
 /**
  * The live tabs of the Orca project at `home`, each under its own tab id.
@@ -229,9 +277,9 @@ const WINDOW_SCRIPT = fileURLToPath(new URL('./orca-window.cjs', import.meta.url
  * the real id, so an orphaned entry is given that one: the tab id is the key
  * (PRD 6.2), and this is where Orca is asked for it (tech notes, section 1).
  */
-export const tabs = (home) => orca(['terminal', 'list', '--worktree', `path:${home}`]).terminals
+export const tabs = (home, options) => orca(['terminal', 'list', '--worktree', `path:${home}`], options).terminals
   .map((tab) => (tab.orphaned === true
-    ? { ...tab, tabId: orca(['terminal', 'show', '--terminal', tab.handle]).terminal.tabId }
+    ? { ...tab, tabId: orca(['terminal', 'show', '--terminal', tab.handle], options).terminal.tabId }
     : tab));
 
 /**
@@ -282,11 +330,14 @@ export function harnessInTab(handle, timeoutMs) {
     answered: answer.ok === true,
     blockedReason: answer.result?.wait?.blockedReason,
     agent,
-    ...frontOf(shown?.ptyId),
+    ...frontOf(handle, shown?.ptyId),
     ...screenOf(handle),
   };
 }
 
+/** Orca's reason for a folder-trust screen, which it can go on giving once that is answered (#342). */
+const TRUST_REASON = 'agent-trust-workspace';
+
 /** 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';
 
@@ -320,7 +371,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 0023). The same pointer starts the harness's
+ * one (tech notes, section 1; ADR 0025). 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.
@@ -359,6 +410,14 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   // A line typed into a screen waiting for an answer is that answer: once, it
   // confirmed Claude Code's folder-trust default, `No, exit` (tech notes,
   // section 1).
+  // Except where Orca still reports Codex's trust screen after it was
+  // answered, over an idle screen (#342). Nothing is typed then either, but
+  // there is nothing to answer, so the kit says what it saw. Claude Code's
+  // trust list is not numbered and the screen read cannot see it, so this is
+  // for Codex alone.
+  if (seen.blockedReason === TRUST_REASON && seen.agent === 'codex' && seen.question === false) {
+    return { unsure: `Orca still reports ${TRUST_REASON} in it, and its screen shows no question: Orca can go on reporting the trust screen after it is answered, and refuse a typed line while it does, so nothing was typed` };
+  }
   if (seen.blockedReason !== undefined) return { blocked: seen.blockedReason };
   // The shell in front is a tab with no harness, whatever a stale
   // `agentIdentity` says.
@@ -397,25 +456,63 @@ export function frontOfTab(handle) {
   } catch (error) {
     return { unreadable: `Orca would not show the tab: ${error.message}` };
   }
-  return frontOf(shown?.ptyId);
+  return frontOf(handle, shown?.ptyId);
 }
 
 /** The `ps` this run reads. OBK_PS overrides it, as OBK_ORCA does Orca. */
 const psCli = () => process.env.OBK_PS || '/bin/ps';
 
 /**
- * Who holds the terminal of the pane `ptyId`: `{ front: 'shell' }`,
- * `{ front: 'program', command, pid }` with the name and pid of the process
- * leading the group in front, or `{ unreadable: <why> }`.
+ * Who holds the terminal of the tab `handle`, whose pane is `ptyId`:
+ * `{ front: 'shell' }`, `{ front: 'program', command, pid }` with the name and,
+ * where `ps` gave it, the pid of the process leading the group in front, or
+ * `{ unreadable: <why> }`.
+ *
+ * `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 0025).
+ */
+function frontOf(handle, ptyId) {
+  const read = frontByPs(ptyId);
+  if (read.unreadable === undefined) return read;
+  const asked = frontByOrca(handle);
+  return asked.unreadable === undefined ? asked : { unreadable: `${read.unreadable}, and ${asked.unreadable}` };
+}
+
+/**
+ * Who holds the tab's terminal as Orca's runtime says it, through
+ * `terminal.inspectProcess`: Orca's own daemon reads the process table from
+ * outside any sandbox of the kit's, and names what leads the terminal's
+ * foreground group. Only a `live` answer counts. A process named there is the
+ * program in front; none named and no child in front is the shell. Anything
+ * else is "cannot tell": for a moment after a harness quits, Orca can name
+ * nothing and still see a child in front (read in the Orca 1.4.212 bundle).
+ */
+function frontByOrca(handle) {
+  const seen = askRuntime('terminal.inspectProcess', { terminal: handle })?.result?.process;
+  const evidence = seen?.foregroundProcessEvidence;
+  if (evidence?.verdict !== 'live') {
+    const why = typeof evidence?.reason === 'string' ? `: ${evidence.reason}` : '';
+    return { unreadable: `Orca's runtime could not say who is in front of it${why}` };
+  }
+  const name = (word) => typeof word === 'string' && word !== '';
+  if (name(evidence.processName)) return { front: 'program', command: evidence.processName };
+  if (evidence.processName === null && name(seen.foregroundProcess)) return { front: 'program', command: seen.foregroundProcess };
+  if (evidence.processName === null && seen.foregroundProcess === null && seen.hasChildProcesses === false) return { front: 'shell' };
+  return { unreadable: "Orca's runtime gave no answer the kit can read about who is in front of it" };
+}
+
+/**
+ * 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 0023).
+ * gives that pid's terminal's foreground process group (ADR 0025).
  * 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
  * here ends in "cannot tell" rather than in an error or a guess.
  */
-function frontOf(ptyId) {
+function frontByPs(ptyId) {
   let pane;
   try {
     pane = orca(['diagnostics', 'memory']).worktrees
@@ -548,12 +645,12 @@ export function postMessage({ to, from, subject, body, type = 'status', thread }
  * the terminal `handle` when one is given, which is how a read works from a tab
  * bound to another Run; otherwise as this process's own terminal.
  */
-export const readMailbox = (id, { peek = false, handle } = {}) =>
-  orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])]);
+export const readMailbox = (id, { peek = false, handle } = {}, options) =>
+  orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])], options);
 
 /** Say a batch has been read. Orca answers with the batch after it. */
-export const ackMailbox = (id, delivery, handle) =>
-  orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery]);
+export const ackMailbox = (id, delivery, handle, options) =>
+  orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery], options);
 
 /** The reader of a `check`: the terminal named, or this process's own. */
 const as = (handle) => (handle === undefined ? [] : ['--terminal', handle]);