@assuredloop/orca-bot-kit 0.25.4 → 0.26.0

package/src/commands.js

@@ -0,0 +1,74 @@
+// The kit's commands, each with the flags it cannot do without, which `obk`
+// reads to parse a command line; and the two lists every command is on one of:
+// those every bot is allowed by default (#527, ADR 0036), and those kept back
+// for the user's yes (ADR 0037). A new command is on neither until someone
+// puts it on one, and a test holds every command to that choice.
+
+/** The commands, and the flags each one cannot do without. */
+export const COMMANDS = {
+  init: ['bots', 'harness'],
+  up: ['bots'],
+  restart: ['bots', 'bot'],
+  pause: ['bots', 'bot'],
+  unpause: ['bots', 'bot'],
+  retire: ['bots', 'bot'],
+  health: ['bots'],
+  groom: ['bots'],
+  roster: ['bots'],
+  usage: ['bots'],
+  'bot create': ['bots', 'name', 'harness'],
+  'bot change': ['bots', 'bot'],
+  'permission allow': ['bots', 'bot', 'rule'],
+  'permission disallow': ['bots', 'bot', 'rule'],
+  'permission approval': ['bots', 'bot', 'approval'],
+  'rules build': ['bots'],
+  'skills add': ['bots', 'bot', 'skill'],
+  'skills remove': ['bots', 'bot', 'skill'],
+  'skills build': ['bots'],
+  'skills fetch': ['bots'],
+  'skills update': ['bots'],
+  'source add': ['bots', 'name', 'repo', 'ref'],
+  'session add': ['bots', 'bot', 'name'],
+  'session change': ['bots', 'bot', 'session'],
+  'session clear': ['bots', 'bot', 'session'],
+  'session compact': ['bots', 'bot', 'session'],
+  'message to': ['bots', 'to'],
+  'message send': ['bots', 'to', 'subject'],
+  'message check': ['bots'],
+  'session record': ['bots', 'bot'],
+  'session sent': ['bots', 'bot'],
+  'session nudge': ['bots', 'bot'],
+  'session mail': ['bots', 'bot'],
+  'session name': ['bots', 'bot'],
+  'session mailbox': ['bots', 'bot', 'session'],
+  'session trust-hooks': ['bots', 'bot', 'session'],
+  'session answer': ['bots', 'bot', 'session'],
+  'temp make': ['bots', 'name'],
+  'temp roles': ['bots'],
+  'temp retire': ['bots', 'name'],
+  'temp trust-hooks': ['bots', 'name'],
+  'temp answer': ['bots', 'name'],
+};
+
+/**
+ * The commands every bot is allowed by default, each narrowed to its bots
+ * folder (ADR 0036). Only a command named here is in the default set; one that
+ * runs whatever its arguments say never is.
+ */
+export const DEFAULT_COMMANDS = [
+  'up', 'restart', 'unpause', 'health', 'groom', 'roster', 'usage',
+  'bot create', 'bot change', 'rules build',
+  'skills add', 'skills remove', 'skills build', 'skills fetch', 'skills update', 'source add',
+  'session add', 'session change', 'session clear', 'session compact',
+  'message to', 'message send', 'message check',
+  'session record', 'session sent', 'session nudge', 'session mail', 'session name', 'session mailbox',
+  'session trust-hooks', 'session answer',
+  'temp make', 'temp roles', 'temp retire', 'temp trust-hooks', 'temp answer',
+];
+
+/**
+ * The commands kept out of the default permission set, which keep the user's
+ * yes (ADR 0037): the ones that change permissions, close a long-lived
+ * session, or make the bots folder.
+ */
+export const KEPT_BACK = ['init', 'retire', 'pause', 'permission allow', 'permission disallow', 'permission approval'];

package/src/health.js

@@ -25,7 +25,7 @@ import { bookFile, readBook, sessionIdsIn, tabIdsIn } from './book.js';
 import { botDir, botNames, botsDir, readBot, tempRoles, unknownKeys } from './bot.js';
 import { transcriptsIn } from './conversations.js';
 import { hookTrouble } from './hooks.js';
-import { bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
+import { APPROVALS, bypassFlags, harnessOf, HARNESSES, isAddressOf, ownCli, sessionTrouble, SHELL_ENV, shellWord } from './launch.js';
 import { frontOfTab, orcaDefaultArgs, projects, runMissing, tabs, wordsOfProcess } from './orca.js';
 import { permissionsTrouble } from './permissions.js';
 import { TAB_ENV } from './record.js';
@@ -213,10 +213,16 @@ function sessionSettings(home, bot) {
 /** What is wrong with the roles the bot's temporary sessions are made in (#465). */
 function rolesTrouble(home, bot) {
   const where = path.join(home, 'bot.yaml');
+  // The widest approval they may be made at, the user's yes (ADR 0037).
+  const level = bot.temp_approval;
+  const approval = level === undefined || APPROVALS.includes(level) ? [] : [{
+    where,
+    says: `${where} has a temp_approval of ${JSON.stringify(level)}, and the levels are ${APPROVALS.join(', ')}, so obk temp make holds the bot's temporary sessions to their maker's own approval. Set it with obk permission approval --temps.`,
+  }];
   try {
-    return tempRoles(home, bot).flatMap((role) => role.trouble.map((says) => ({ where, says })));
+    return [...tempRoles(home, bot).flatMap((role) => role.trouble.map((says) => ({ where, says }))), ...approval];
   } catch (error) {
-    return [{ where, says: error.message }];
+    return [{ where, says: error.message }, ...approval];
   }
 }
 

package/src/hook-trust.js

@@ -0,0 +1,179 @@
+// Which of a Codex bot's hooks Codex does not trust yet, so that the kit
+// trusts only its own (#506).
+//
+// "Trust all and continue" on Codex's hooks review trusts every hook the
+// review counts, from every source Codex reads: the user's own files, Orca's
+// hooks among them, `-c` flags, plugins, and each `.codex/` folder from the git
+// root down (tech notes, section 3). So the kit answers a review only when the
+// bot's `.codex/hooks.json` holds the kit's hooks and nothing else, and the
+// count on the screen is the number of those that Codex does not trust yet.
+//
+// Codex keeps its trust in the user's config.toml, one table a hook, keyed by
+// the file, the event and the hook's place in it, with a hash of the hook. The
+// kit reads only those tables' headers and their `trusted_hash` lines: the
+// rest of the file can hold the user's secrets, and nothing of it is kept or
+// said. A file it cannot read that way for one of its hooks is one where it
+// cannot tell, and it refuses (the architect's ruling on #506).
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { hooksFileOf, readSettings, runsThisKit } from './hooks.js';
+
+/** The events whose hooks Codex hashes with no matcher, whatever the group says. */
+const NO_MATCHER = new Set(['user_prompt_submit', 'stop', 'interrupt']);
+
+/** A hook's timeout when its entry gives none, in seconds, as Codex takes it. */
+const DEFAULT_TIMEOUT = 600;
+
+/**
+ * How many of the hooks in the bot at `home`'s `.codex/hooks.json` Codex does
+ * not trust yet: `{ untrusted, file }`. It throws, with `nothing` at the end,
+ * when the file holds a hook that is not the kit's own as this kit writes it,
+ * or when the kit cannot tell whether Codex trusts one.
+ */
+export function untrustedKitHooks(home, run, nothing) {
+  const file = hooksFileOf(home, 'codex');
+  const settings = readSettings(file, "the kit's hooks");
+  const hooks = settings.hooks ?? {};
+  if (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks)) {
+    throw new Error(`${run}: ${file} has a hooks entry that is not a mapping of events, so the kit cannot tell which hooks its review covers. ${nothing}`);
+  }
+  const ours = [];
+  const foreign = [];
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) {
+      foreign.push(`${event}: ${JSON.stringify(groups)}`);
+      continue;
+    }
+    groups.forEach((group, at) => {
+      if (!Array.isArray(group?.hooks)) {
+        foreign.push(`${event}: ${JSON.stringify(group)}`);
+        return;
+      }
+      group.hooks.forEach((hook, handler) => {
+        if (runsThisKit(hook)) ours.push({ event: snake(event), at, handler, hash: hashOf(snake(event), group.matcher, hook) });
+        else foreign.push(`${event}: ${typeof hook?.command === 'string' ? hook.command : JSON.stringify(hook)}`);
+      });
+    });
+  }
+  if (foreign.length > 0) {
+    throw new Error(`${run}: ${file} holds hooks that are not the kit's own as this kit writes them, and "Trust all and continue" would let them run outside the sandbox: ${foreign.join('; ')}. ${nothing}`);
+  }
+
+  // Codex names the file by the path it found it at; the kit knows the bot
+  // home by its real path, and looks under both.
+  const files = [...new Set([file, realOr(file)])];
+  const keysOf = (hook) => files.map((one) => `${one}:${hook.event}:${hook.at}:${hook.handler}`);
+  const trusted = trustedHashes(ours.flatMap(keysOf), run, nothing);
+  const untrusted = ours.filter((hook) => !keysOf(hook).some((key) => trusted.get(key) === hook.hash)).length;
+  return { untrusted, file };
+}
+
+/** An event's name as Codex writes it in a key and a hash: `SessionStart` is `session_start`. */
+const snake = (event) => event.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+
+/**
+ * The hash Codex trusts a command hook at: SHA-256, in hex, of its event, its
+ * group's matcher and the hook as Codex reads it, as JSON with every key
+ * sorted (Codex 0.162.0, tech notes, section 3).
+ */
+function hashOf(event, matcher, hook) {
+  const handler = {
+    type: 'command',
+    command: hook.command,
+    timeout: hook.timeout ?? DEFAULT_TIMEOUT,
+    async: hook.async === true,
+    ...(hook.statusMessage === undefined ? {} : { statusMessage: hook.statusMessage }),
+  };
+  const identity = {
+    event_name: event,
+    ...(matcher === undefined || matcher === null || NO_MATCHER.has(event) ? {} : { matcher }),
+    hooks: [handler],
+  };
+  return `sha256:${createHash('sha256').update(sorted(identity)).digest('hex')}`;
+}
+
+/** A value as JSON with every object's keys sorted, and no spaces. */
+const sorted = (value) => {
+  if (Array.isArray(value)) return `[${value.map(sorted).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${sorted(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+};
+
+const realOr = (file) => {
+  try {
+    return realpathSync(file);
+  } catch {
+    return file;
+  }
+};
+
+const HEADER = /^\s*\[\s*hooks\.state\."((?:[^"\\]|\\.)*)"\s*\]\s*(?:#.*)?$/;
+const TRUSTED = /^\s*trusted_hash\s*=\s*"(sha256:[0-9a-f]{64})"\s*(?:#.*)?$/;
+const ANY_TABLE = /^\s*\[/;
+
+/** The short escapes of a TOML basic string. */
+const SHORT = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', e: '\x1b', '"': '"', '\\': '\\' };
+
+/**
+ * Text with a TOML basic string's escapes decoded, as Codex reads them: a key
+ * written `\u002f` is the key with a `/` in it (the review of PR #517). An
+ * escape TOML does not have is left as it is.
+ */
+const unescaped = (text) => text.replace(/\\(?:u([0-9A-Fa-f]{4})|U([0-9A-Fa-f]{8})|x([0-9A-Fa-f]{2})|(.))/g, (all, u4, u8, x2, one) => {
+  const code = u4 ?? u8 ?? x2;
+  if (code === undefined) return SHORT[one] ?? all;
+  const point = parseInt(code, 16);
+  return point <= 0x10ffff ? String.fromCodePoint(point) : all;
+});
+
+/**
+ * The `trusted_hash` for each of `keys` that has one, by key, from the
+ * config.toml the session's Codex uses: `$CODEX_HOME`'s, or else
+ * `~/.codex`'s. No file is no trust. A key the file holds in any other form
+ * than a `[hooks.state."<key>"]` table with a `trusted_hash` line, or holds
+ * twice, is one the kit cannot tell, and it throws.
+ */
+function trustedHashes(keys, run, nothing) {
+  const file = path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'config.toml');
+  if (!existsSync(file)) return new Map();
+  const wanted = new Set(keys);
+  const text = readFileSync(file, 'utf8');
+  const cannotTell = (key, how) =>
+    new Error(`${run}: ${file} holds Codex's trust for the kit's hook ${key} ${how}, so the kit cannot tell whether Codex trusts it. ${nothing}`);
+
+  const found = new Map();
+  const headers = new Set();
+  let table;
+  for (const line of text.split(/\r?\n/)) {
+    const header = HEADER.exec(line);
+    if (header !== null) {
+      table = unescaped(header[1]);
+      if (wanted.has(table)) {
+        if (headers.has(table)) throw cannotTell(table, 'twice');
+        headers.add(table);
+      }
+      continue;
+    }
+    if (ANY_TABLE.test(line)) {
+      table = undefined;
+      continue;
+    }
+    const hash = TRUSTED.exec(line);
+    if (hash !== null && wanted.has(table)) found.set(table, hash[1]);
+  }
+  // A key in any other form is one the kit cannot read: as it stands, which
+  // a literal string keeps, backslashes and all, or with a basic string's
+  // escapes decoded (the review of PR #517).
+  const decoded = unescaped(text);
+  for (const key of wanted) {
+    if (headers.has(key) && !found.has(key)) throw cannotTell(key, 'in a table with no trusted_hash line the kit reads');
+    if (!headers.has(key) && (text.includes(key) || decoded.includes(key))) throw cannotTell(key, 'in a form the kit does not read');
+  }
+  return found;
+}

package/src/hooks.js

@@ -20,6 +20,9 @@ import { ownCli, shellWord } from './launch.js';
 /** Where each harness reads a project's hooks, inside the bot home. */
 const HOOK_FILE = { claude: '.claude/settings.json', codex: '.codex/hooks.json' };
 
+/** The hooks file `harness` reads in the bot at `home`. */
+export const hooksFileOf = (home, harness) => path.join(home, HOOK_FILE[harness]);
+
 /**
  * The one thing the kit asks to be told: a session beginning. Both harnesses
  * report it whenever a session starts, resumes or is begun again by the user —
@@ -381,6 +384,14 @@ const KIT_NUDGE = new RegExp(String.raw`^(${WORD}) session nudge --bots ${WORD}
 const KIT_MAIL = new RegExp(String.raw`^(${WORD}) session mail --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$`);
 
+/**
+ * Whether a hook entry is one of the kit's own as this kit writes it: a
+ * command of exactly a shape the kit writes, run by `cli`, the kit running now
+ * (#506). One that runs some other program, even another `obk`, is not.
+ */
+export const runsThisKit = (hook, cli = ownCli()) =>
+  hook?.type === 'command' && [KIT_HOOK, KIT_SENT, KIT_NUDGE, KIT_NAME].some((pattern) => programOf(hook.command, pattern) === cli);
+
 /** The program a bot made before the kit named itself by path runs. */
 const BARE = 'obk';
 

package/src/launch.js

@@ -40,6 +40,31 @@ export const bypassFlags = (harness) => APPROVAL[harness]['dangerously-skip'];
 
 export const HARNESSES = Object.keys(APPROVAL);
 
+/** How wide a level is: `ask` is narrower than `auto`, and `auto` than `dangerously-skip`. */
+export const approvalRank = (level) => ['ask', 'auto', 'dangerously-skip'].indexOf(level);
+
+/**
+ * The harness flags that set approval or permissions, which only
+ * `obk permission approval` may change, not an extra argument (ADR 0037).
+ * Codex's `-a` and `-s` take their value glued on too.
+ */
+const APPROVAL_FLAGS = {
+  claude: ['--permission-mode', '--dangerously-skip-permissions', '--allow-dangerously-skip-permissions', '--allowedTools', '--allowed-tools'],
+  codex: ['-a', '--ask-for-approval', '--approve-for-me', '--dangerously-bypass-approvals-and-sandbox', '-s', '--sandbox'],
+};
+
+/**
+ * Refuse extra arguments that set a session's approval or permissions on
+ * `harness`, before anything is written, naming the command that does it.
+ */
+export function refuseApprovalArgs(harness, args) {
+  const found = (args ?? []).find((arg) => (APPROVAL_FLAGS[harness] ?? []).some((flag) => arg === flag
+    || arg.startsWith(`${flag}=`)
+    || (/^-[as]$/.test(flag) && arg.startsWith(flag) && !arg.startsWith('--'))));
+  if (found === undefined) return;
+  throw new Error(`--extra-arg=${found} sets the session's approval or permissions on ${harness}, and only obk permission approval changes those, after the user's yes. Nothing was changed.`);
+}
+
 /** The level a session that names none runs at (ADR 0015). */
 export const DEFAULT_APPROVAL = 'auto';
 

package/src/orca.js

@@ -284,8 +284,22 @@ export function asFolderProject(setupId, title) {
  * Take a bot's Orca project away: the setup, the project and the repo record,
  * in one call (tech notes, section 1). Only after its tabs are closed: a
  * project taken away first leaves tabs no command line can reach.
+ *
+ * With `--force`, because the caller has made those checks itself: Orca's next
+ * release refuses a plain delete of a project with saved workspace details,
+ * which a bot's project keeps after its tabs close (#528). Orca 1.4.223 does
+ * not know the flag and refuses it before it changes anything, so then the
+ * plain delete is sent, which it takes with no such guard.
  */
-export const deleteProject = (setupId) => orca(['project', 'setup-delete', '--setup', setupId]);
+export function deleteProject(setupId) {
+  const plain = ['project', 'setup-delete', '--setup', setupId];
+  try {
+    return orca([...plain, '--force']);
+  } catch (error) {
+    if (error.code !== 'invalid_argument' || !error.reason?.includes('Unknown flag --force')) throw error;
+    return orca(plain);
+  }
+}
 
 /** 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.";