@assuredloop/orca-bot-kit 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/bot.js

@@ -277,14 +277,15 @@ export function allowedNow(bots, bot, rules, flag = '--allow') {
  * added }: the whole list now, and what this call put in it.
  *
  * Only the list: the rules are written into the harness's settings by the
- * caller, as the rules build is run by the caller of `changeBot`.
+ * caller, as the rules build is run by the caller of `changeBot`. With `write`
+ * false it only refuses what the edit would refuse, and writes nothing.
  */
-export function allowRules(bots, bot, rules) {
+export function allowRules(bots, bot, rules, { write = true } = {}) {
   const { home, was } = allowedNow(bots, bot, rules);
   const added = [...new Set(rules)].filter((rule) => !was.includes(rule));
   const allow = [...was, ...added];
   if (added.length > 0) {
-    editBot(bots, bot, `allow ${added.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }));
+    editBot(bots, bot, `allow ${added.join(', ')} for ${bot}`, (doc) => doc.set('allow', allow), (before) => ({ ...before, allow }), write);
   }
   return { bot, home, allow, added };
 }
@@ -410,10 +411,15 @@ function editBot(bots, bot, what, edit, expected, write = true) {
   const source = readFileSync(file, 'utf8');
   const doc = parseDocument(source);
   edit(doc);
-  const text = doc.toString(YAML_OUT);
-  if (!changesExactly(source, text, expected)) {
-    throw new Error(`${file} cannot be changed to ${what} without changing something else in it, so nothing was written. Make the change by hand.`);
+  const refusal = new Error(`${file} cannot be changed to ${what} without changing something else in it, so nothing was written. Make the change by hand.`);
+  let text;
+  try {
+    // An edit that leaves an alias with no anchor cannot be written at all.
+    text = doc.toString(YAML_OUT);
+  } catch {
+    throw refusal;
   }
+  if (!changesExactly(source, text, expected)) throw refusal;
   if (write && text !== source) writeFileSync(file, text);
 }
 

package/src/cli.js

@@ -19,7 +19,7 @@ import { initBots } from './init.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
 import { checkMail, lookUp, noMailboxYet, sendMessage } from './message.js';
 import { orcaCli, orcaTrouble, RELOAD_LINE } from './orca.js';
-import { allowCommand, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
+import { allowCommand, allowIn, beyondDefaults, refuseBroad, refuseNoCodexForm, runsOnClaude, runsOnCodex, takeBack, writePermissions } from './permissions.js';
 import { pauseSessions, unpauseSessions } from './pause.js';
 import { recordSession, SHELL_ENV, TAB_ENV } from './record.js';
 import { restartSessions } from './restart.js';
@@ -618,10 +618,14 @@ const commands = {
     }
     // Refused before anything is written, so a bad rule, or a bad list already
     // there, leaves the charter as it was too.
+    let allowInto;
     if (values.allow !== undefined) {
       const { home } = allowedNow(bots, values.bot, values.allow);
       refuseBroad(home, values.allow);
-      refuseNoCodexForm(readBot(home, values.bot), values.allow);
+      const bot = readBot(home, values.bot);
+      refuseNoCodexForm(bot, values.allow);
+      const { allow } = allowRules(bots, values.bot, values.allow, { write: false });
+      allowInto = allowIn(bots, home, { ...bot, allow });
     }
     let takeBackFrom;
     if (values.disallow !== undefined) {
@@ -662,9 +666,11 @@ const commands = {
       }
     }
     if (values.allow !== undefined) {
+      // Written at once, as the charter's rules are built at once (#344): the
+      // harness's files first, bot.yaml last, so a write that fails leaves
+      // `allow` as it was, and the same command can run again (#383).
+      const permissions = allowInto();
       const allowed = allowRules(bots, values.bot, values.allow);
-      // Written at once, as the charter's rules are built at once (#344).
-      const permissions = writePermissions(bots, allowed.home, readBot(allowed.home));
       Object.assign(answer, { allow: allowed.allow, permissions });
       const codex = permissions.find((entry) => entry.unwritten !== undefined);
       lines.push(

package/src/conversations.js

@@ -50,9 +50,16 @@ export function conversationsIn(harness, home, since) {
  */
 export function hasConversation(harness, home, id) {
   if (harness === 'claude') return existsSync(claudeTranscript(home, id));
-  return rollouts(codexDir()).some((file) => path.basename(file).endsWith(`-${id}.jsonl`));
+  return codexRollout(id) !== undefined;
 }
 
+/**
+ * Where Codex keeps the conversation `id`, whatever folder it ran in, found by
+ * the file name Codex makes from the id; `undefined` when it has none.
+ */
+export const codexRollout = (id) =>
+  rollouts(codexDir()).find((file) => path.basename(file).endsWith(`-${id}.jsonl`));
+
 /**
  * Where Claude Code keeps the conversation `id` of this bot home, whether or
  * not it has written it yet.

package/src/orca.js

@@ -180,7 +180,12 @@ export const deleteProject = (setupId) => orca(['project', 'setup-delete', '--se
 /** 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. */
+/**
+ * How long Orca's client waits for its runtime, and how long the kit waits for
+ * the client. Measured beside the full unit suite on Orca 1.4.214, the whole
+ * call took at most 721 ms and the call inside the client at most 447 ms
+ * (tech notes, #384).
+ */
 const CLIENT_WAIT_MS = 2000;
 const CLIENT_KILL_MS = 3000;
 

package/src/permissions.js

@@ -19,7 +19,7 @@
 // `Bash(<words>:*)` becomes a `prefix_rule` of those words in
 // `.codex/rules/obk.rules`, a file the kit owns whole and rewrites from `allow`.
 
-import { accessSync, constants, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { accessSync, constants, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { leadsOutside } from './bot.js';
@@ -267,10 +267,10 @@ export const allowCommand = (bots, bot, rules) => [
  * the kit may not write is an entry with its `trouble` rather than a throw.
  */
 export function writePermissions(bots, home, bot, { keepGoing = false } = {}) {
-  const writers = [[runsOnClaude, FILE, writeClaude], [runsOnCodex, CODEX_FILE, writeCodex]];
-  return writers.filter(([runs]) => runs(bot)).map(([, file, write]) => {
+  const writers = [[runsOnClaude, FILE, planClaude], [runsOnCodex, CODEX_FILE, planCodex]];
+  return writers.filter(([runs]) => runs(bot)).map(([, file, plan]) => {
     try {
-      return write(bots, home, bot);
+      return plan(bots, home, bot).write();
     } catch (error) {
       if (!keepGoing) throw error;
       return { bot: bot.name, file: path.join(home, file), written: [], waiting: [], trouble: error.message };
@@ -279,30 +279,55 @@ export function writePermissions(bots, home, bot, { keepGoing = false } = {}) {
 }
 
 /**
- * Write what the bot is allowed into its Claude settings: `{ bot, file,
- * written, waiting }`, with `written` the rules this run added.
+ * Check every file `bot change --allow` writes before any is written (#383):
+ * bot.yaml, and the files of the harnesses the bot runs on, read and found
+ * writable. `bot` is the bot as it will be, with the new rules in `allow`.
+ * What comes back writes the harness files, one entry per file, Claude's
+ * first; the caller writes bot.yaml after, so a write that fails leaves
+ * `allow` as it was, for the same command to run again.
+ */
+export function allowIn(bots, home, bot) {
+  refuseUnwritable(path.join(home, 'bot.yaml'));
+  const plans = [[runsOnClaude, planClaude], [runsOnCodex, planCodex]]
+    .filter(([runs]) => runs(bot)).map(([, plan]) => plan(bots, home, bot));
+  for (const plan of plans) if (plan.writes) refuseUnwritable(plan.answer.file);
+  return () => plans.map((plan) => plan.write());
+}
+
+/**
+ * What writing the bot's allowed rules into its Claude settings would do,
+ * read and refused before anything is written: `{ answer, writes, write }`.
+ * `write()` gives `{ bot, file, written, waiting }`, with `written` the rules
+ * it added.
  *
  * Only rules `allow` holds are written. Everything else in the file stays as it
  * is, the user's own entries and their order included; a rule missing from the
  * file goes after them, and a run with nothing to add writes nothing.
  */
-function writeClaude(bots, home, bot) {
+function planClaude(bots, home, bot) {
   const file = path.join(home, FILE);
   const allowed = allowOf(home, bot);
   const waiting = waitingFor(bots, home, bot, 'claude');
   const answer = { bot: bot.name, file, written: [], waiting };
-  if (allowed.length === 0) return answer;
+  const none = { answer, writes: false, write: () => answer };
+  if (allowed.length === 0) return none;
 
   refuseOutside(home, file);
   const settings = readSettings(file, 'the permission rules the user allowed');
   const present = presentIn(settings, file);
   const missing = [...new Set(allowed)].filter((rule) => !present.includes(rule));
-  if (missing.length === 0) return answer;
+  if (missing.length === 0) return none;
 
   const wanted = { ...settings, permissions: { ...settings.permissions, allow: [...present, ...missing] } };
-  mkdirSync(path.dirname(file), { recursive: true });
-  writeFileSync(file, `${JSON.stringify(wanted, null, 2)}\n`);
-  return { ...answer, written: missing };
+  return {
+    answer,
+    writes: true,
+    write: () => {
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, `${JSON.stringify(wanted, null, 2)}\n`);
+      return { ...answer, written: missing };
+    },
+  };
 }
 
 /**
@@ -358,7 +383,7 @@ export function takeBack(bots, home, bot, rules) {
       entries.push({ bot: bot.name, file, written: [], removed, waiting: waitingFor(bots, home, after, 'claude') });
     }
     if (runsOnCodex(after)) {
-      const entry = writeCodex(bots, home, after);
+      const entry = planCodex(bots, home, after).write();
       // A line goes only when no rule still allowed gives it.
       const kept = [...codexOf(home, after).lines.keys()];
       const removed = taken.filter((rule) => {
@@ -371,12 +396,20 @@ export function takeBack(bots, home, bot, rules) {
   };
 }
 
-/** A refusal, before anything is written, of a file the kit could not write. */
+/**
+ * A refusal, before anything is written, of a file the kit could not write: one
+ * not there yet is made in the nearest folder that is, which the kit must be
+ * able to enter and write in, and which must be a folder.
+ */
 function refuseUnwritable(file) {
+  let where = file;
+  while (!existsSync(where) && path.dirname(where) !== where) where = path.dirname(where);
   try {
-    accessSync(file, constants.W_OK);
+    if (where !== file && !statSync(where).isDirectory()) throw Object.assign(new Error('not a folder'), { code: 'ENOTDIR' });
+    accessSync(where, where === file ? constants.W_OK : constants.W_OK | constants.X_OK);
   } catch (error) {
-    throw new Error(`${file} cannot be written (${error.code ?? error.message}), so nothing was changed. Let the kit write it, then run the command again.`);
+    const at = where === file ? '' : ` at ${where}`;
+    throw new Error(`${file} cannot be written (${error.code ?? error.message}${at}), so nothing was changed. Let the kit write it, then run the command again.`);
   }
 }
 
@@ -417,16 +450,18 @@ function codexOf(home, bot) {
 const ruleLines = (text) => text.split('\n').map((line) => line.trim()).filter((line) => line !== '' && !line.startsWith('#'));
 
 /**
- * Write the Codex form of what the bot is allowed into `.codex/rules/obk.rules`:
+ * What writing the Codex form of what the bot is allowed into
+ * `.codex/rules/obk.rules` would do, as `planClaude` gives it. `write()` gives
  * `{ bot, file, written, waiting, unwritten }`, with `written` every rule in
- * the file when this run wrote it. The kit owns the file whole and writes it
- * only when it would change; with nothing to write and no file, it makes none.
+ * the file when it wrote it. The kit owns the file whole and writes it only
+ * when it would change; with nothing to write and no file, it makes none.
  */
-function writeCodex(bots, home, bot) {
+function planCodex(bots, home, bot) {
   const file = path.join(home, CODEX_FILE);
   const { lines, unwritten } = codexOf(home, bot);
   const answer = { bot: bot.name, file, written: [], waiting: waitingFor(bots, home, bot, 'codex'), unwritten };
-  if (lines.size === 0 && !existsSync(file)) return answer;
+  const none = { answer, writes: false, write: () => answer };
+  if (lines.size === 0 && !existsSync(file)) return none;
 
   refuseOutside(home, file);
   const text = [
@@ -434,10 +469,16 @@ function writeCodex(bots, home, bot) {
     '# obk rewrites this whole file: put rules of your own in another file in this folder.',
     ...lines.keys(),
   ].join('\n');
-  if (existsSync(file) && readFileSync(file, 'utf8') === `${text}\n`) return answer;
-  mkdirSync(path.dirname(file), { recursive: true });
-  writeFileSync(file, `${text}\n`);
-  return { ...answer, written: [...lines.values()].flat() };
+  if (existsSync(file) && readFileSync(file, 'utf8') === `${text}\n`) return none;
+  return {
+    answer,
+    writes: true,
+    write: () => {
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, `${text}\n`);
+      return { ...answer, written: [...lines.values()].flat() };
+    },
+  };
 }
 
 /**

package/src/usage.js

@@ -25,6 +25,9 @@
 //      `last_token_usage` counts a call written down twice twice. So a call is
 //      the difference in the running total from the event before: none is a
 //      repeat, and a fall is a new window, whose own `last_token_usage` counts.
+//      A rollout's first record counts its own figure too: a child's running
+//      total can start with its parent's inside it, and a fork can begin with
+//      its origin's records copied in, which are the origin's calls (#376).
 //   2. The two harnesses do not mean the same thing by `input_tokens`. Claude
 //      Code leaves the cache reads out of it; Codex counts them inside it. So
 //      the Codex figure has its cached tokens taken back out, and `input` means
@@ -40,7 +43,7 @@ import { readFileSync, realpathSync } from 'node:fs';
 
 import { botDir, botNames, readBot } from './bot.js';
 import { readBook, sessionIdsIn } from './book.js';
-import { claudeSubagentTranscripts, transcriptsIn } from './conversations.js';
+import { claudeSubagentTranscripts, codexRollout, transcriptsIn } from './conversations.js';
 import { HARNESSES, harnessOf } from './launch.js';
 
 /** The kinds a call's tokens are reported in, the same on either harness. */
@@ -193,7 +196,10 @@ function counted(one, window) {
       return { entries, subagent: index > 0 };
     });
   if (one.harness === 'claude') fromClaude(sources, window, tally);
-  else fromCodex(sources[0].entries, window, tally);
+  else {
+    const copied = originOf(sources[0].entries, tally);
+    if (copied !== null) fromCodex(sources[0].entries, window, tally, copied);
+  }
   if (tally.calls === 0 && KINDS.every((kind) => tally.tokens[kind] === 0)) return { gaps: tally.gaps };
 
   return { gaps: tally.gaps, row: {
@@ -351,13 +357,22 @@ const CODEX_FIELDS = [
  * counted either, and is said to be; the running total follows on from it. A
  * call whose figure is needed and has something missing is not counted, and is
  * said to be; nothing missing is taken as zero.
+ *
+ * A fork begins with the records of the conversation it was forked from, copied
+ * in and stamped at the fork's start, or all at one time in a file Codex rebuilt.
+ * Those are the origin's calls, counted with the origin: the leading records
+ * that are in `copied`, both figures, are followed and not counted (#376).
+ * A leading record with a figure missing may be a copy or the fork's own call;
+ * it is not counted, and is said to be.
  */
-function fromCodex(entries, window, tally) {
+function fromCodex(entries, window, tally, copied) {
   let model;
   let effort;
   let running;
   // Whether a running total with something missing came since the last complete one.
   let broken = false;
+  // Whether the records so far are all the origin's, copied into a fork.
+  let copying = copied !== undefined;
 
   for (const entry of entries) {
     const when = Date.parse(entry.timestamp ?? '');
@@ -381,10 +396,26 @@ function fromCodex(entries, window, tally) {
     if (info === undefined || info === null) continue;
 
     const total = info.total_token_usage;
+    const whole = complete(total, CODEX_READ) && complete(info.last_token_usage, CODEX_READ);
+    if (copying && whole && copied.has(key(info))) {
+      running = total;
+      broken = false;
+      continue;
+    }
+    // A record with a figure missing cannot be told from a copy while copies
+    // may still be coming: it is not counted and is said to be, and the next
+    // record is matched as before.
+    const unknown = copying && !whole;
+    if (!unknown) copying = false;
+
     let used;
     // No running total at all is a running total with every figure missing:
     // the next one's rise would take this call in again (#302).
-    if (!complete(total, CODEX_READ)) {
+    if (unknown && complete(total, CODEX_READ)) {
+      used = null;
+      running = total;
+      broken = false;
+    } else if (!complete(total, CODEX_READ)) {
       used = null;
       broken = true;
     } else {
@@ -412,13 +443,56 @@ function fromCodex(entries, window, tally) {
 /** The fields Codex itself writes; it has no cache writes to report. */
 const CODEX_READ = CODEX_FIELDS.filter((field) => field !== 'cache_write_input_tokens').concat('total_tokens');
 
+/**
+ * A usage record as one value, both its figures: a call of the child's own can
+ * bring the running total back to one the origin once had, but not with the same
+ * figure of its own.
+ */
+const key = (info) => [info.total_token_usage, info.last_token_usage]
+  .map((figure) => CODEX_READ.map((field) => figure[field]).join('/')).join('|');
+
+/**
+ * The usage records of the conversation a Codex rollout was forked from, which
+ * it may begin with copies of (tech notes, section 3). `undefined` when it names
+ * no origin. When the origin cannot be read whole, a line of it broken or a
+ * figure missing from a record, where the copies end cannot be told, so none of
+ * the fork is counted: `null`, and said to be.
+ */
+function originOf(entries, tally) {
+  const id = entries.find((entry) => entry.type === 'session_meta')?.payload?.forked_from_id;
+  if (typeof id !== 'string' || id === '') return undefined;
+
+  const file = codexRollout(id);
+  const origin = file === undefined ? { unreadable: 1 } : transcript(file);
+  // No `info` is a note about rate limits, not a record of usage.
+  const records = origin.unreadable > 0 ? [] : origin.entries
+    .filter((entry) => entry.type === 'event_msg' && entry.payload?.type === 'token_count')
+    .map((entry) => entry.payload.info)
+    .filter((info) => info !== undefined && info !== null);
+  const whole = origin.unreadable === 0 && origin.broken === 0 && records.every((info) =>
+    complete(info.total_token_usage, CODEX_READ) && complete(info.last_token_usage, CODEX_READ));
+  if (!whole) {
+    tally.gaps.unreadable_transcripts += 1;
+    return null;
+  }
+  return new Set(records.map(key));
+}
+
 /**
  * What one Codex event says its call used, measured against the running total
  * before it: `undefined` where the event is the one before written down again,
- * and `null` where what it used cannot be known.
+ * and `null` where what it used cannot be known. The first has nothing before
+ * it, and its running total can hold what a parent spent before this rollout
+ * began, so its own figure is what it used. An own figure of nothing in every
+ * field is a note of where the running total stands, not a call: wherever else
+ * Codex writes one, the running total does not move (tech notes, section 3).
  */
 function spent(running, total, info) {
-  if (running === undefined) return kindsOf(total);
+  if (running === undefined) {
+    const own = info.last_token_usage;
+    if (complete(own, CODEX_READ) && CODEX_FIELDS.every((field) => number(own[field]) === 0)) return undefined;
+    return perCall(info);
+  }
 
   const moved = total.total_tokens - running.total_tokens;
   if (moved === 0) return undefined;