@assuredloop/orca-bot-kit 0.4.0 → 0.5.1

package/src/orca.js

@@ -30,11 +30,17 @@ export function orca(args) {
   if (answer.ok !== true) {
     // Orca's own words: it knows what went wrong, and the caller is an LLM
     // that can act on them.
-    throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
+    throw refusal(args, answer);
   }
   return answer.result;
 }
 
+/** Orca's refusal as an error, with its code on it, so a caller can tell a stale handle from the rest (#294). */
+const refusal = (args, answer) => Object.assign(
+  new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`),
+  { code: answer.error?.code },
+);
+
 /** One Orca command, and the whole envelope back, refusals included. */
 function ask(args) {
   const asked = spawnSync(orcaCli(), [...args, '--json'], { encoding: 'utf8' });
@@ -257,7 +263,7 @@ export function harnessInTab(handle, timeoutMs) {
   // Out of time means nothing went idle, busy or absent alike. That is an
   // answer, not a breakdown.
   if (answer.ok !== true && answer.error?.code !== 'timeout') {
-    throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
+    throw refusal(args, answer);
   }
 
   const shown = orca(['terminal', 'show', '--terminal', handle]).terminal;
@@ -312,6 +318,21 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   return { handle: live.handle, agent: seen.agent };
 }
 
+/**
+ * Who holds the terminal of the tab `handle`, as `frontOf` answers, without
+ * waiting on the tab: for a caller that asks about every tab and has nothing
+ * to type. Orca refusing is an answer that cannot be read, not an error.
+ */
+export function frontOfTab(handle) {
+  let shown;
+  try {
+    shown = orca(['terminal', 'show', '--terminal', handle]).terminal;
+  } catch (error) {
+    return { unreadable: `Orca would not show the tab: ${error.message}` };
+  }
+  return frontOf(shown?.ptyId);
+}
+
 /** The `ps` this run reads. OBK_PS overrides it, as OBK_ORCA does Orca. */
 const psCli = () => process.env.OBK_PS || '/bin/ps';
 
@@ -446,7 +467,7 @@ export function postMessage({ to, from, subject, body, type = 'status', thread }
 export const readMailbox = (id, { peek = false, handle } = {}) =>
   orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])]);
 
-/** Say a batch has been read, so the next check brings the one after it. */
+/** 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]);
 

package/src/record.js

@@ -17,6 +17,7 @@ import { forgetClaimed, readBook, rememberSession, sessionIdsIn, updateBook, wit
 import { botDir, readBot } from './bot.js';
 import { conversationsIn } from './conversations.js';
 import { harnessOf, SHELL_ENV, startPrompt, workDirOf } from './launch.js';
+import { rulesStamp } from './rules.js';
 
 /** Where Orca says which tab a program is running in (tech notes, section 1). */
 export const TAB_ENV = 'ORCA_TAB_ID';
@@ -79,6 +80,11 @@ export async function recordSession(bots, name, said, tabId, shellPid) {
   // this bot's folder, which every session of the bot shares — so it can say
   // that a conversation nobody claims exists, and never whose it is.
   const unclaimed = unclaimedFor(readBook(home), home, bot, tabId, id);
+  // A clear on Claude Code reads the bot's instructions again, as a start does
+  // (tech notes, section 2), so the book notes which ones it read. Codex has no
+  // word for its clear, and whether its new conversation reads them again is
+  // not established, so nothing is noted for it.
+  const rules = said.source === CLEARED ? rulesStamp(home) : undefined;
 
   let cleared = false;
   let told;
@@ -100,7 +106,8 @@ export async function recordSession(bots, name, said, tabId, shellPid) {
     const uncertain = was.session === undefined && unclaimed.length > 0;
     told = session;
 
-    book.sessions[session] = withUnclaimed(rememberSession(was, id, said.source), unclaimed);
+    const now = rememberSession(was, id, said.source);
+    book.sessions[session] = withUnclaimed(rules === undefined ? now : { ...now, rules }, unclaimed);
     forgetClaimed(book);
     if (uncertain) cleared = true;
     return book;

package/src/rules.js

@@ -406,3 +406,18 @@ function sameFile(one, other) {
     return false;
   }
 }
+
+/**
+ * A stamp of a bot's `AGENTS.md` as it is now, or undefined when there is none
+ * to read. It is what a session read when it started, noted in the book at that
+ * moment, so that health can tell a session running on older rules from one on
+ * the current ones. The whole file, not only the build's block: what the user
+ * wrote below the end marker is part of what the session reads.
+ */
+export function rulesStamp(home) {
+  try {
+    return checksum(readFileSync(path.join(home, AGENTS), 'utf8'));
+  } catch {
+    return undefined;
+  }
+}

package/src/settings.js

@@ -0,0 +1,158 @@
+// What a running session really runs with, set beside what its bot.yaml asks for.
+//
+// A session can run on settings other than the ones bot.yaml asks for: it
+// started before a change, a default of the user's own leaked in, or a flag was
+// dropped. Each harness writes down what it used (tech notes, sections 2 and 3),
+// so the two can be put side by side. Read only: these are the harness's files.
+//
+// Four answers, and only one of them is good news. A record that cannot be read,
+// or that does not carry the setting, is not agreement: it is `unknown`. A
+// setting the session never asked for is not a disagreement either, whatever the
+// harness chose: it is `not-asked-for`.
+
+import { DEFAULT_APPROVAL } from './launch.js';
+import { lines } from './usage.js';
+
+export const SETTINGS = ['model', 'effort', 'context', 'approval'];
+
+/**
+ * Each setting of `session` as `{ state, configured?, observed? }`, judged
+ * against `file`, the harness's record of the conversation the session is in
+ * now, from `since`, when the kit last started it. No file is no record, and
+ * every setting asked for is then unknown.
+ */
+export function settingsInUse(harness, session, file, since) {
+  const used = file === undefined ? {} : (harness === 'claude' ? fromClaude : fromCodex)(sinceStart(lines(file), since));
+  return Object.fromEntries(SETTINGS.map((name) => [name, judged(harness, name, asked(session, name), used[name])]));
+}
+
+/**
+ * What the record says since the kit last started the session. A start resumes
+ * the conversation it had, so the file still holds what the process before it
+ * wrote, and that says what that process ran with, not this one. Everything
+ * from the first line written at or after the start counts, a line with no time
+ * of its own included. With no start to go by, no line can be shown to be this
+ * process's, so none counts.
+ */
+function sinceStart(entries, since) {
+  const from = Date.parse(since ?? '');
+  if (Number.isNaN(from)) return [];
+  const first = entries.findIndex((entry) => Date.parse(entry.timestamp ?? '') >= from);
+  return first === -1 ? [] : entries.slice(first);
+}
+
+/** What the session asks for, as bot.yaml has it, or undefined when it asks for nothing. */
+function asked(session, name) {
+  const value = session[name];
+  const set = value !== undefined && value !== null && String(value).trim() !== '';
+  // The kit puts an approval level on every launch line, so a session always
+  // asks for one: the default, when it names none (ADR 0015).
+  if (name === 'approval') return set ? String(value).trim() : DEFAULT_APPROVAL;
+  return set ? String(value).trim() : undefined;
+}
+
+function judged(harness, name, configured, observed) {
+  const shown = observed === undefined ? {} : { observed: said(name, observed) };
+  if (configured === undefined) return { state: 'not-asked-for', ...shown };
+  const verdict = same(harness, name, configured, observed);
+  if (verdict === undefined) return { state: 'unknown', configured, ...shown };
+  return { state: verdict ? 'match' : 'mismatch', configured, ...shown };
+}
+
+/** Whether the record says what was asked for; undefined when it cannot say. */
+function same(harness, name, configured, observed) {
+  if (observed === undefined) return undefined;
+  if (name === 'model') return sameModel(configured, observed);
+  // Codex reports the window it was given at 95%, rounded down (tech notes,
+  // section 3): 200000 comes back as 190000.
+  if (name === 'context') return Number(observed) === Math.floor(Number(configured) * 0.95);
+  if (name === 'approval') return harness === 'claude' ? observed === CLAUDE_MODES[configured] : sameCodexApproval(configured, observed);
+  return observed === configured;
+}
+
+/**
+ * A model named without a dash is an alias, `sonnet`, and the harness writes the
+ * id it stands for, `claude-sonnet-5`: it matches an id it is one part of. A
+ * model with a dash is an id already, and has to be the one that ran. The
+ * context window Claude Code carries on the model name, `sonnet[1m]`, is not
+ * part of what it writes down.
+ */
+function sameModel(configured, observed) {
+  const model = configured.replace(/\[[^\]]*\]$/, '');
+  return model.includes('-') ? observed === model : observed.split('-').includes(model);
+}
+
+/** The permission mode Claude Code records for each level (tech notes, section 2). */
+const CLAUDE_MODES = { auto: 'auto', ask: 'default', 'dangerously-skip': 'bypassPermissions' };
+
+/**
+ * What Codex records for each level, and only the words that level decides: at
+ * `ask` the kit passes only the approval policy, so the sandbox is the user's
+ * own (ADR 0015), and at `dangerously-skip` nothing is reviewed (tech notes,
+ * section 3).
+ */
+const CODEX_WORDS = {
+  auto: { policy: 'on-request', reviewer: 'auto_review', sandbox: 'workspace-write' },
+  ask: { policy: 'on-request', reviewer: 'user' },
+  'dangerously-skip': { policy: 'never', sandbox: 'danger-full-access' },
+};
+
+function sameCodexApproval(configured, observed) {
+  const wanted = CODEX_WORDS[configured];
+  if (wanted === undefined) return false;
+  const pairs = Object.entries(wanted);
+  // A word the level decides and the record does not carry leaves it unsaid.
+  if (pairs.some(([key]) => observed[key] === undefined)) return undefined;
+  return pairs.every(([key, word]) => observed[key] === word);
+}
+
+/** A value the record carried, as the report shows it. */
+function said(name, observed) {
+  if (name !== 'approval' || typeof observed === 'string') return String(observed);
+  return [
+    `approval_policy ${observed.policy}`,
+    ...(observed.reviewer === undefined ? [] : [`approvals_reviewer ${observed.reviewer}`]),
+    ...(observed.sandbox === undefined ? [] : [`sandbox ${observed.sandbox}`]),
+  ].join(', ');
+}
+
+/**
+ * What a Claude Code transcript says it runs with, the latest of each: the
+ * model and effort on its replies, the permission mode wherever it is noted.
+ * Claude Code writes nothing that shows the context window.
+ */
+function fromClaude(entries) {
+  const used = {};
+  for (const entry of entries) {
+    if (entry.type === 'assistant' && entry.isSidechain !== true) {
+      const model = entry.message?.model;
+      if (typeof model === 'string' && model !== '<synthetic>') used.model = model;
+      if (typeof entry.effort === 'string') used.effort = entry.effort;
+    }
+    if (typeof entry.permissionMode === 'string') used.approval = entry.permissionMode;
+  }
+  return used;
+}
+
+/** What a Codex rollout says it runs with: its latest turn, and its latest count. */
+function fromCodex(entries) {
+  const used = {};
+  for (const entry of entries) {
+    const payload = entry.payload;
+    if (payload === null || typeof payload !== 'object') continue;
+    if (entry.type === 'turn_context') {
+      if (typeof payload.model === 'string') used.model = payload.model;
+      if (typeof payload.effort === 'string') used.effort = payload.effort;
+      if (typeof payload.approval_policy === 'string') {
+        used.approval = {
+          policy: payload.approval_policy,
+          reviewer: typeof payload.approvals_reviewer === 'string' ? payload.approvals_reviewer : undefined,
+          sandbox: typeof payload.sandbox_policy?.type === 'string' ? payload.sandbox_policy.type : undefined,
+        };
+      }
+    }
+    const window = payload.info?.model_context_window;
+    if (entry.type === 'event_msg' && payload.type === 'token_count' && typeof window === 'number') used.context = window;
+  }
+  return used;
+}

package/src/up.js

@@ -6,14 +6,15 @@
 
 import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { setTimeout as pause } from 'node:timers/promises';
 
-import { forgetClaimed, readBook, sessionIdsIn, tabIdsIn, updateBook, withUnclaimed } from './book.js';
+import { forgetClaimed, forgetSession, readBook, sessionIdsIn, tabIdsIn, updateBook, withUnclaimed } from './book.js';
 import { botDir, botNames, displayName, readBot } from './bot.js';
-import { conversationsIn } from './conversations.js';
+import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
 import { addressOf, harnessOf, isShortPrompt, launchCommand, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
 import { asFolderProject, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, tellWindow, typeIntoTab, useMailbox } from './orca.js';
-import { buildAgents } from './rules.js';
+import { buildAgents, rulesStamp } from './rules.js';
 import { linkSkills } from './skills.js';
 
 /** The one bot with a tab beside its sessions: the ops tab (PRD 6.2). */
@@ -262,33 +263,14 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // given again (PRD 6.4) — after a clear it is, and that is the hook's work.
   // Asked before the book is held, because it reads a folder of the harness's
   // own files: nothing slow happens under the lock.
-  const which = whichConversation(book, home, bot, session, was, harness);
-  const resume = which.resume;
-  const prompt = resume === undefined ? startPrompt(session, { home, workDir }) : undefined;
-  // Anything longer than a line goes to the harness out of a file, rather than
-  // through the tab's shell a character at a time.
-  const promptFile = prompt === undefined || isShortPrompt(prompt) ? undefined : promptPath(bots, bot.name, session.name);
-  const command = launchCommand(session, {
-    harness,
-    home,
-    workDir,
-    prompt,
-    promptFile,
-    resume,
-    address: harness === 'claude' ? addressOf(bot.name, session.name) : undefined,
-  });
+  let which = whichConversation(book, home, bot, session, was, harness);
+  const launchOf = (chosen) => launchFor(bots, bot, session, harness, home, workDir, chosen.resume);
+  let launch = launchOf(which);
 
   // A work dir is a plain folder, made for the session before it is told about
   // it (PRD 6.4). Nothing here is a git worktree.
   if (workDir !== undefined) mkdirSync(workDir, { recursive: true });
-
-  // The prompt is written where the launch line can read it from, before that
-  // line is typed. It is the kit's own file, not the user's: theirs stays where
-  // they put it, in the bot home.
-  if (promptFile !== undefined) {
-    mkdirSync(path.dirname(promptFile), { recursive: true });
-    writeFileSync(promptFile, prompt);
-  }
+  writePrompt(launch);
 
   const made = openTab(home, tabTitle);
 
@@ -300,19 +282,45 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // started a harness in it, and a conversation taken over from the harness's
   // own record are new.
   const launched = new Date().toISOString();
+  // Which instructions it is about to read: the AGENTS.md this run has just
+  // built, noted so that health can say when the file moves on and the session
+  // does not (#272).
+  const rules = rulesStamp(home);
+  let held;
   await updateBook(home, (current) => {
     // What the harness has in this folder that nobody claims goes on the record,
     // for a person or Bot Father to settle — added to whatever was already noted,
     // because this run's scan cannot see what an earlier one found. The kit never
     // settles it itself.
-    const entry = { ...current.sessions[session.name], tab: made.tabId, launched };
+    let entry = { ...current.sessions[session.name], tab: made.tabId, launched, rules };
+    if (rules === undefined) delete entry.rules;
+    held = entry.session;
+    // Before the line is typed, so the hook finds no id here and takes the one
+    // it reports for a start rather than a clear, which would tell the duty twice.
+    if (which.noConversation !== undefined && held === which.noConversation) entry = forgetSession(entry, 'no conversation');
     current.sessions[session.name] = withUnclaimed(entry, which.unclaimed ?? []);
     forgetClaimed(current);
   });
 
+  // The old tab's hook can name another conversation while the tab is being
+  // opened. A fresh start chosen before that is chosen again from the id the
+  // book holds now: resumed if the harness has it, and otherwise set aside the
+  // same way (review of PR #310).
+  if (which.noConversation !== undefined && typeof held === 'string' && held !== which.noConversation) {
+    which = hasConversation(harness, home, held) ? { resume: held } : { noConversation: held };
+    if (which.noConversation !== undefined) {
+      await updateBook(home, (current) => {
+        const entry = current.sessions[session.name];
+        if (entry?.session === held) current.sessions[session.name] = forgetSession(entry, 'no conversation');
+      });
+    }
+    launch = launchOf(which);
+    writePrompt(launch);
+  }
+
   // Typing it in is the way: for a project the kit has just made, giving Orca
   // the harness as the tab's own command times out and leaves a dead tab.
-  typeIntoTab(made.handle, command);
+  typeIntoTab(made.handle, launch.command);
 
   // Now the session has an address, and not before: the mailbox it can be
   // written to, and — on Claude Code — the name that line just gave it, which
@@ -334,24 +342,87 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   const tui = first.running ? lookFor(made.handle, SECOND_LOOK_MS) : first;
 
   // The start prompt went in with that line, as the harness's own prompt
-  // argument, so it is the harness that holds it until it is ready — through
-  // its folder-trust question and its update offer. What is still worth saying
-  // is whether the line took at all: a shell that swallowed it swallowed the
-  // duty with it, and nobody has been told anything.
-  const promptSent = prompt === undefined ? undefined : tui.running === true;
+  // argument, and a harness running in the tab is not yet a session told its
+  // duty: one held on a first-run screen, or one that refused the argument, has
+  // been told nothing. So it is received only when the session's own record
+  // holds it as a user turn, and otherwise not confirmed (#274).
+  const promptReceived = launch.prompt === undefined
+    ? undefined
+    : await heldInRecord(home, session.name, harness, launch.prompt, { launched, running: tui.running === true });
 
   return entry(made, {
     bot: bot.name,
     name: session.name,
     created: true,
     ...tui,
-    promptSent,
-    promptFile,
-    resumed: resume !== undefined,
+    promptReceived,
+    promptFile: launch.promptFile,
+    resumed: launch.resume !== undefined,
+    noConversation: which.noConversation,
     unclaimed: which.unclaimed,
   });
 }
 
+/**
+ * The line that starts this session: resuming `resume`, or, with none, a fresh
+ * start carrying its duty. Returns `{ resume, prompt, promptFile, command }`.
+ */
+function launchFor(bots, bot, session, harness, home, workDir, resume) {
+  const prompt = resume === undefined ? startPrompt(session, { home, workDir }) : undefined;
+  // Anything longer than a line goes to the harness out of a file, rather than
+  // through the tab's shell a character at a time.
+  const promptFile = prompt === undefined || isShortPrompt(prompt) ? undefined : promptPath(bots, bot.name, session.name);
+  const command = launchCommand(session, {
+    harness,
+    home,
+    workDir,
+    prompt,
+    promptFile,
+    resume,
+    address: harness === 'claude' ? addressOf(bot.name, session.name) : undefined,
+  });
+  return { resume, prompt, promptFile, command };
+}
+
+/**
+ * The prompt is written where the launch line can read it from, before that
+ * line is typed. It is the kit's own file, not the user's: theirs stays where
+ * they put it, in the bot home.
+ */
+function writePrompt({ prompt, promptFile }) {
+  if (promptFile === undefined) return;
+  mkdirSync(path.dirname(promptFile), { recursive: true });
+  writeFileSync(promptFile, prompt);
+}
+
+/**
+ * How long a running harness's own record is given to show the start prompt.
+ * Seen live (Claude Code 2.1.282, a trusted folder): the hook's id and the
+ * user turn landed about as the second look ended, so one read there comes a
+ * moment too early. A harness held on a first-run screen costs the whole wait.
+ */
+const RECORD_MS = 5000;
+const RECORD_ASK_MS = 250;
+
+/**
+ * Whether the conversation the book names for this session holds `prompt` as a
+ * user turn in the harness's own record. The name comes from the session's own
+ * hook, so a harness that has not reported one — held on a first-run screen,
+ * say — has no record to be read, and the answer is that it is not confirmed.
+ * Another conversation in the same folder is never asked: it may be a sister
+ * session told the same words.
+ */
+async function heldInRecord(home, name, harness, prompt, { launched, running }) {
+  const until = Date.now() + (running ? RECORD_MS : 0);
+  for (;;) {
+    const id = readBook(home).sessions[name]?.session;
+    const record = typeof id === 'string' ? transcriptsIn(harness, home, launched).find((one) => one.id === id) : undefined;
+    if (record !== undefined && heldAsUserTurn(harness, record.file, prompt)) return true;
+    if (Date.now() >= until) return false;
+    await pause(RECORD_ASK_MS);
+  }
+}
+
 /**
  * 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.
@@ -443,7 +514,14 @@ function mailboxFor(book, bot, session, harness, handle) {
  * has already started a harness in, the harness's own record is asked.
  */
 function whichConversation(book, home, bot, session, was, harness) {
-  if (typeof was?.session === 'string') return { resume: was.session };
+  if (typeof was?.session === 'string') {
+    if (hasConversation(harness, home, was.session)) return { resume: was.session };
+    // The hook reported an id and the harness never wrote a conversation behind
+    // it: a session paused before its first turn is one. There is nothing to
+    // resume, so it starts again with its duty, and the book keeps the id in the
+    // history with the reason (#295).
+    return { noConversation: was.session };
+  }
   // No tab: nothing has ever run for this session, so there is nothing to find.
   if (typeof was?.tab !== 'string') return {};
 
@@ -490,11 +568,13 @@ const ids = (setup, change) => ({ project: setup.projectId, setup: setup.id, cha
 export const promptPath = (bots, bot, session) =>
   path.join(`${bots}.prompts`, `${encodeURIComponent(bot)}.${encodeURIComponent(session)}.txt`);
 
-function entry(tab, { bot, name, created, running = false, blockedReason, promptSent, promptFile, resumed, unclaimed }) {
+function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, noConversation, unclaimed }) {
   const made = { bot, name, title: tab.title, tabId: tab.tabId, terminal: tab.handle, created, harnessStarted: running };
   // Whether this run picked the session up where it was or started a new one.
   // Only for a tab this run opened: a tab that was already there was left alone.
   if (resumed !== undefined) made.resumed = resumed;
+  // The id the book held that had no conversation behind it, now in the history.
+  if (noConversation !== undefined) made.noConversation = noConversation;
   // Orca's own words for what is on screen waiting to be answered, when it
   // gave any: the caller acts on it, the kit only passes it on.
   if (blockedReason !== undefined) made.blockedReason = blockedReason;
@@ -502,7 +582,7 @@ function entry(tab, { bot, name, created, running = false, blockedReason, prompt
   // claims: the caller is told, because the kit will not pick one.
   if (unclaimed !== undefined && unclaimed.length > 0) made.unclaimed = unclaimed;
   // Only for a session this run started that had something to be told.
-  if (promptSent !== undefined) made.promptSent = promptSent;
+  if (promptReceived !== undefined) made.promptReceived = promptReceived;
   // And the file it was told it out of, when it was too long for the line.
   if (promptFile !== undefined) made.promptFile = promptFile;
   return made;