@assuredloop/orca-bot-kit 0.26.1 → 0.28.0

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0034). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0046). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -106,6 +106,15 @@ export function orcaTrouble() {
   if (asked.error) return `could not run Orca at ${orcaCli()}: ${asked.error.message}. ${where}`;
 
   const answer = parse(asked.stdout);
+  // A CLI that dies with no answer has not reached the app at all: it can fail
+  // on its own, as on a current folder macOS will not let it read, while Orca
+  // runs (#556). So what it said is passed on, and nobody is sent to start Orca.
+  if (answer === undefined && asked.status !== 0) {
+    const exit = asked.status ?? `signal ${asked.signal}`;
+    return `the Orca CLI at ${orcaCli()} failed before it answered status (exit ${exit}; `
+      + `stdout ${said(asked.stdout)}; stderr ${said(asked.stderr)}). `
+      + 'Fix what it says and run the command again, or point OBK_ORCA at another Orca CLI.';
+  }
   // Orca knowing what is wrong beats the kit guessing, so its own words go
   // first when it gave any.
   if (answer !== null && typeof answer === 'object' && answer.ok !== true && answer.error?.message) {
@@ -319,7 +328,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 0034). The caller prints
+ * changes does, and Orca's CLI does not offer it (ADR 0046). The caller prints
  * `RELOAD_LINE` either way. It does not take a removed project out of the
  * sidebar: `reloadWindow` does.
  */
@@ -330,7 +339,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 0034). None of that is
+ * Orca's binary the way its `bin/orca` runs its CLI (ADR 0046). 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.
  */
@@ -367,7 +376,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 0034).
+ * only when it did (#343, ADR 0046).
  *
  * 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
@@ -426,23 +435,6 @@ export const openTab = (home, title) =>
 export const retitleTab = (handle, title) =>
   orca(['terminal', 'rename', '--terminal', handle, '--title', title]).rename;
 
-/**
- * One quick look at whether the harness in a tab is at rest, for a caller that
- * already knows a harness is there and is watching for a turn to start (#509):
- * `idle` when Orca's tui-idle answers ok, `busy` when it times out, and
- * `unknown` when Orca refuses or does not answer within `waitMs` and a second
- * more. Never throws.
- */
-export function idleNow(handle, waitMs) {
-  try {
-    const answer = ask(['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle', '--timeout-ms', String(waitMs)], waitMs + 1000);
-    if (answer.ok === true) return answer.result?.wait?.blockedReason === undefined ? 'idle' : 'unknown';
-    return answer.error?.code === 'timeout' ? 'busy' : 'unknown';
-  } catch {
-    return 'unknown';
-  }
-}
-
 /**
  * What can be learned about the harness in a tab: what Orca says, and who is
  * in front of the tab's terminal.
@@ -541,7 +533,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 0034). The same pointer starts the harness's
+ * one (tech notes, section 1; ADR 0046). 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 the lowest pointer row is asked
  * about: a question counts while it stands in the input line's place, or
@@ -637,14 +629,14 @@ function pointedChoiceAt(rows, at) {
  * is typed, and the answer says why. `idle` says whether Orca's `tui-idle` wait
  * answered ok, and `rows` is the screen the gate read, for a caller that must
  * not type into a busy harness (#391), with the `draft` Orca gave beside it (#510):
- * `{}` 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
+ * `{}` for a tab with no harness in it (none in the book, or the shell in
+ * front), `{ gone: true }` for one Orca does not list, `{ blocked }` for one with something on screen waiting
  * to be answered, and `{ unsure }`, a sentence, for one the kit cannot tell
  * 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
+ * interrupt and the skills reload. A busy harness passes it, since both harnesses
  * take a typed line as their next turn.
  */
 export function tabToTypeInto(home, tabId, timeoutMs) {
@@ -655,7 +647,7 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   let seen;
   try {
     live = tabs(home, { timeoutMs: GATE_READ_MS }).find((tab) => tab.tabId === tabId);
-    if (live === undefined) return {};
+    if (live === undefined) return { gone: true };
     seen = harnessInTab(live.handle, timeoutMs, GATE_READ_MS);
   } catch (error) {
     if (error.code !== TIMED_OUT) throw error;
@@ -737,7 +729,7 @@ export function frontOfTab(handle) {
 }
 
 /** The `ps` this run reads. OBK_PS overrides it, as OBK_ORCA does Orca. */
-const psCli = () => process.env.OBK_PS || '/bin/ps';
+export const psCli = () => process.env.OBK_PS || '/bin/ps';
 
 /**
  * Who holds the terminal of the tab `handle`, whose pane is `ptyId`:
@@ -747,7 +739,7 @@ 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 0034). `readMs` bounds each call: a number, or a function that
+ * (#298, ADR 0046). `readMs` bounds each call: a number, or a function that
  * says what is left of a wait, asked before each one (#498). A `ps` that runs
  * out of it ends the look, `late`, with no runtime asked after it.
  */
@@ -787,7 +779,7 @@ function frontByOrca(handle, readMs) {
  * 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 0034).
+ * gives that pid's terminal's foreground process group (ADR 0046).
  * 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
@@ -834,7 +826,7 @@ function panePid(ptyId, readMs) {
 }
 
 /** The `lsof` and `stty` this run asks. OBK_LSOF and OBK_STTY override them, as OBK_PS does `ps`. */
-const lsofCli = () => process.env.OBK_LSOF || '/usr/sbin/lsof';
+export const lsofCli = () => process.env.OBK_LSOF || '/usr/sbin/lsof';
 const sttyCli = () => process.env.OBK_STTY || '/bin/stty';
 
 /**
@@ -968,18 +960,12 @@ export const closeTerminal = (handle) =>
  * Seen live on 2026-09-21 in a system test run; not reproduced since, including
  * from a plain shell, long lines and lines sent while the agent was working.
  *
- * The wait is short because the caller is telling a session it has mail, not
- * handing it work: mail that has to wait for the next check is a smaller cost
- * than a command that hangs for half a minute.
- *
- * With `watch`, the line is sent with that wait from the start, and Orca's
- * receipt says whether it saw the line start a turn (#394). It gives back
- * Orca's `result`: the receipt is in its `send.prompt`, and Orca's words about
- * a turn it did not see in its `warnings`.
+ * The wait is short: a line that has to wait is a smaller cost than a
+ * command that hangs for half a minute.
  */
-export function typeIntoTab(handle, text, { watch = false } = {}) {
+export function typeIntoTab(handle, text) {
   const args = ['terminal', 'send', '--terminal', handle, '--text', text, '--enter'];
-  const answer = ask(watch ? [...args, '--wait-submit', String(SUBMIT_WAIT_S)] : args);
+  const answer = ask(args);
   if (answer.ok === true) return answer.result;
 
   const again = answer.error?.data?.orchestrationRequestId;
@@ -990,11 +976,18 @@ export function typeIntoTab(handle, text, { watch = false } = {}) {
 }
 
 /**
- * How long a watched or re-issued line is given to be submitted before Orca
- * gives up on it. An idle harness started its turn in about 2 s, live (#394).
+ * How long a re-issued line is given to be submitted before Orca gives up on
+ * it. An idle harness started its turn in about 2 s, live (#394).
  */
 const SUBMIT_WAIT_S = 5;
 
+/**
+ * Press Escape once in a tab, with no return after it: what `obk message send
+ * --interrupt` sends to a busy receiver (#555).
+ */
+export const pressEscape = (handle) =>
+  orca(['terminal', 'send', '--terminal', handle, '--text', '\x1b']);
+
 /** Where Orca names the terminal a process runs in, in every pane it opens. */
 export const TERMINAL_ENV = 'ORCA_TERMINAL_HANDLE';
 

package/src/permissions.js

@@ -6,7 +6,7 @@
 // body beside the bots folder, commit. A matching allow rule is settled before
 // that check (Claude Code's permissions docs), so the kit gives every bot a
 // default set, spelled with its real CLI and bots folder, with nobody asked
-// (#527, ADR 0036). A rule beyond it is the user's yes, which
+// (#527, ADR 0050). A rule beyond it is the user's yes, which
 // `permission allow` keeps in bot.yaml's `allow`. The kit's code writes what
 // `allow` holds into `.claude/settings.json` in the bot folder, beside its hook
 // (ADR 0022). A model editing the file by hand may get the format wrong; code
@@ -24,7 +24,7 @@ import { accessSync, constants, existsSync, mkdirSync, readdirSync, readFileSync
 import path from 'node:path';
 
 import { allowRules, leadsOutside } from './bot.js';
-import { DEFAULT_COMMANDS, NO_LONGER_DEFAULT } from './commands.js';
+import { DEFAULT_COMMANDS, NO_LONGER_DEFAULT, REMOVED } from './commands.js';
 import { readSettings } from './hooks.js';
 import { harnessOf, ownCli, shellWord } from './launch.js';
 
@@ -36,11 +36,10 @@ const CODEX_RULES = '.codex/rules';
 const CODEX_FILE = `${CODEX_RULES}/obk.rules`;
 
 /**
- * The rules every bot is given (ADR 0036): each of the kit's default commands,
- * and none kept back for the user's yes (ADR 0041), narrowed to this bots folder and
+ * The rules every bot is given (ADR 0050): each of the kit's default commands,
+ * and none kept back for the user's yes (ADR 0051), narrowed to this bots folder and
  * spelled as the kit prints them, which is what a bot runs; reading a long
- * message; committing; and the check Orca's mail notice tells a session to
- * run. `//` is Claude's form for an absolute path.
+ * message; and committing. `//` is Claude's form for an absolute path.
  */
 export function defaultRules(bots, cli = ownCli()) {
   const kit = shellWord(cli);
@@ -50,19 +49,27 @@ export function defaultRules(bots, cli = ownCli()) {
     `Read(/${bots}.messages/**)`,
     'Bash(git add:*)',
     'Bash(git commit:*)',
-    'Bash(orca orchestration check --run:*)',
   ];
 }
 
 /**
- * The rules of the commands that were defaults once and are kept back now
- * (#548), spelled as `defaultRules` spelled them, that the bot's `allow`
- * holds. The kit cannot tell its own old entry from a user's yes to the same
- * rule, so it names them and leaves them (ADR 0041).
+ * Orca's check, which the set held until #564: the kit's rules tell a bot to
+ * read its mail with `obk message check`, never with the bare check, which
+ * leaves it unread (ADR 0042).
+ */
+const ORCA_CHECK = 'Bash(orca orchestration check --run:*)';
+
+/**
+ * The rules that were defaults once and are not now, that the bot's `allow`
+ * holds: those of the commands kept back (#548, #615) or gone from the kit (#555),
+ * spelled as `defaultRules` spelled them, and Orca's check (#564). The kit
+ * cannot tell its own old entry from a user's yes to the same rule, so it
+ * names them and leaves them (ADR 0051, ADR 0050).
  */
 export function heldRules(bots, home, bot, cli = ownCli()) {
   const allowed = allowOf(home, bot);
-  return NO_LONGER_DEFAULT.map((command) => `Bash(${shellWord(cli)} ${command} --bots ${shellWord(bots)}:*)`)
+  return [...NO_LONGER_DEFAULT, ...REMOVED].map((command) => `Bash(${shellWord(cli)} ${command} --bots ${shellWord(bots)}:*)`)
+    .concat(ORCA_CHECK)
     .filter((rule) => allowed.includes(rule));
 }
 
@@ -220,9 +227,16 @@ export const runsOnCodex = (bot) => bot.harness === 'codex'
  */
 function missingDefaults(bots, home, bot) {
   const allowed = allowOf(home, bot);
-  return defaultRules(bots)
-    .filter((rule) => runsOnClaude(bot) || codexForm(rule).line !== undefined)
-    .filter((rule) => !allowed.includes(rule));
+  return botDefaults(bots, bot).filter((rule) => !allowed.includes(rule));
+}
+
+/**
+ * The default rules a bot on Claude or Codex is given, in the default order:
+ * what `bot create` writes into a new bot's bot.yaml (#595).
+ */
+export function botDefaults(bots, bot) {
+  if (!runsOnClaude(bot) && !runsOnCodex(bot)) return [];
+  return defaultRules(bots).filter((rule) => runsOnClaude(bot) || codexForm(rule).line !== undefined);
 }
 
 /**
@@ -270,7 +284,7 @@ export function refuseNoCodexForm(bot, rules) {
 }
 
 /**
- * Add the default rules the bot is not allowed yet to its `allow` (ADR 0036),
+ * Add the default rules the bot is not allowed yet to its `allow` (ADR 0050),
  * then write what it is allowed into the files of the harnesses it runs on:
  * one entry per file, Claude's first, each with `defaults`, the rules this run
  * added, and `held`, the rules of commands no longer in the set that the bot

package/src/pi.js

@@ -0,0 +1,55 @@
+// Whether Pi is ready to start a session: it runs, it can use a model, and it
+// can use the one the session names (#578).
+//
+// The kit never handles Pi's credentials: the user signs in to Pi on their own,
+// and the kit only asks Pi what it can use. `pi auth check` is not asked, since
+// it does not know a provider an extension of Pi's brings, such as Cursor's;
+// `pi --list-models` lists the models Pi can use, those included (tech notes,
+// section 6).
+
+import { spawnSync } from 'node:child_process';
+
+/** How long each question to Pi is given. Each took about 0.3 s on Pi 1.1.0. */
+const ASK_MS = 30_000;
+
+/** Pi's thinking levels, which a model name may carry after a colon. */
+const THINKING = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+
+/**
+ * Why Pi cannot start these sessions, or undefined when it can. `models` are
+ * the models they name; a session that names none takes Pi's own default.
+ */
+export function piTrouble(models) {
+  const version = ask(['--version']);
+  if (version.error !== undefined || version.status !== 0) {
+    const why = version.error?.code === 'ENOENT' ? 'there is no pi on PATH' : (version.error?.message ?? ((version.stderr ?? '').trim() || `it exited with ${version.status}`));
+    return `Pi does not run here (${why}), so no Pi session was started. Install Pi, then run this again.`;
+  }
+
+  const any = ask(['--list-models']);
+  if (any.error !== undefined || any.status !== 0 || /^No models available\b/m.test(any.stdout ?? '')) {
+    return 'Pi has no model it can use: it is signed in to no provider. Sign in to Pi yourself (start pi and use /login, or set a provider\'s API key), then run this again. The kit never handles Pi\'s credentials.';
+  }
+
+  for (const model of new Set(models)) {
+    const found = ask(['--list-models', withoutThinking(model)]);
+    if (found.error !== undefined || found.status !== 0) {
+      const why = found.error?.message ?? ((found.stderr ?? '').trim() || `it exited with ${found.status ?? found.signal}`);
+      return `Pi cannot say whether it can use the model ${model}: pi --list-models ${withoutThinking(model)} failed (${why}), so no Pi session was started. Run that command yourself to see why, then run this again.`;
+    }
+    // Pi says it has no model at all before it searches, so the answer may be
+    // that one too, when a provider dropped out since the question above.
+    if (/^No models (matching|available)\b/m.test(found.stdout ?? '')) {
+      return `Pi cannot use the model ${model}: pi --list-models lists none matching it. Sign in to its provider in Pi yourself, or give the session a model Pi lists.`;
+    }
+  }
+  return undefined;
+}
+
+/** The model without a trailing `:<thinking level>`, which `--list-models` does not match. */
+function withoutThinking(model) {
+  const at = model.lastIndexOf(':');
+  return at > 0 && THINKING.includes(model.slice(at + 1)) ? model.slice(0, at) : model;
+}
+
+const ask = (args) => spawnSync('pi', args, { encoding: 'utf8', timeout: ASK_MS });