@assuredloop/orca-bot-kit 0.21.0 → 0.23.0

package/src/orca.js

@@ -1,4 +1,4 @@
-// Every call the kit makes to Orca goes through here (ADR 0031). Orca's CLI
+// Every call the kit makes to Orca goes through here (ADR 0034). Orca's CLI
 // changes often, so the kit reads `--json` and never the human text, and keeps
 // the parsing in one place.
 //
@@ -216,7 +216,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 0031). The caller prints
+ * changes does, and Orca's CLI does not offer it (ADR 0034). The caller prints
  * `RELOAD_LINE` either way. It does not take a removed project out of the
  * sidebar: `reloadWindow` does.
  */
@@ -227,7 +227,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 0031). None of that is
+ * Orca's binary the way its `bin/orca` runs its CLI (ADR 0034). 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.
  */
@@ -264,7 +264,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 0031).
+ * only when it did (#343, ADR 0034).
  *
  * 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
@@ -377,14 +377,14 @@ export const QUESTION_ON_SCREEN = 'question-on-screen';
 
 /**
  * What the tab `handle` renders: `{ question }`, true when it shows a question
- * of its harness's own, or `{ screenUnreadable: <why> }`. Orca refusing is an
+ * of its harness's own, with the `rows` it read, or `{ screenUnreadable: <why> }`. Orca refusing is an
  * answer that cannot be read, not an error, and so is anything that is not the
  * rendered screen: accumulated output comes back in fragments (tech notes,
  * section 1).
  */
 function screenOf(handle, readMs) {
   const read = screenRows(handle, readMs);
-  return read.rows === undefined ? { screenUnreadable: read.unreadable } : { question: questionIn(read.rows) };
+  return read.rows === undefined ? { screenUnreadable: read.unreadable } : { question: questionIn(read.rows), rows: read.rows };
 }
 
 /**
@@ -418,7 +418,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 0031). The same pointer starts the harness's
+ * one (tech notes, section 1; ADR 0034). 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.
@@ -445,11 +445,14 @@ export function questionIn(rows) {
  * Whether the kit may type a line into `tabId`, the tab the book holds for a
  * session in the Orca project at `home`, and the handle to type into when it
  * may: `{ handle, agent }`, with the agent Orca names there. Otherwise nothing
- * is typed, and the answer says why:
+ * 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):
  * `{}` 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
  * to be answered, and `{ unsure }`, a sentence, for one the kit cannot tell
- * about. Orca refusing throws, for the caller to report.
+ * 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
@@ -497,7 +500,8 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
     const why = seen.front === undefined
       ? seen.unreadable
       : `${seen.command} holds its terminal, and Orca names ${seen.agent ?? 'no agent'} in it`;
-    return { unsure: `the kit could not tell whether a harness is running in it (${why}), so nothing was typed` };
+    // Where `ps` could not read the tab, a reader that can may yet tell (#350).
+    return { unsure: `the kit could not tell whether a harness is running in it (${why}), so nothing was typed`, ...(seen.psUnread ? { psUnread: true } : {}) };
   }
   // Orca's reason does not cover every question: it called Codex's update
   // offer idle, and a return typed into it took "Update now" (#329). So the
@@ -506,7 +510,7 @@ export function tabToTypeInto(home, tabId, timeoutMs) {
   if (seen.question === undefined) {
     return { unsure: `the kit could not tell whether a question is waiting on its screen (${seen.screenUnreadable}), so nothing was typed` };
   }
-  return { handle: live.handle, agent: seen.agent };
+  return { handle: live.handle, agent: seen.agent, idle: seen.answered, rows: seen.rows };
 }
 
 /**
@@ -554,13 +558,13 @@ 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 0031).
+ * (#298, ADR 0034).
  */
 function frontOf(handle, ptyId, readMs) {
   const read = frontByPs(ptyId, readMs);
   if (read.unreadable === undefined) return read;
   const asked = frontByOrca(handle);
-  return asked.unreadable === undefined ? asked : { unreadable: `${read.unreadable}, and ${asked.unreadable}` };
+  return { ...(asked.unreadable === undefined ? asked : { unreadable: `${read.unreadable}, and ${asked.unreadable}` }), psUnread: true };
 }
 
 /**
@@ -590,7 +594,7 @@ function frontByOrca(handle) {
  * 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 0031).
+ * gives that pid's terminal's foreground process group (ADR 0034).
  * 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

package/src/record.js

@@ -80,11 +80,10 @@ 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;
+  // A clear reads the bot's instructions again, as a start does, so the book
+  // notes which ones it read: Claude Code's `/clear` (tech notes, section 2),
+  // and Codex's `/new`, seen here as a new id (#391).
+  const stamp = rulesStamp(home);
 
   let cleared = false;
   let told;
@@ -106,6 +105,7 @@ export async function recordSession(bots, name, said, tabId, shellPid) {
     const uncertain = was.session === undefined && unclaimed.length > 0;
     told = session;
 
+    const rules = cleared ? stamp : undefined;
     const now = rememberSession(was, id, said.source);
     book.sessions[session] = withUnclaimed(rules === undefined ? now : { ...now, rules }, unclaimed);
     forgetClaimed(book);

package/src/temp.js

@@ -5,7 +5,9 @@
 // Any long-lived session can make a temporary session of its own bot for a
 // piece of work, and retire it when the work is done, without Bot Father, who
 // stays the manager of long-lived sessions. A temporary session can make one
-// of its own, one level deep and one at a time (#464, ADR 0033). A temporary session is an ordinary
+// of its own, one level deep and one at a time (#464, ADR 0033). It can be
+// made in a role of its bot's `temp_roles`, which gives its settings, and
+// whose cap limits how many are open (#465). A temporary session is an ordinary
 // session in every other way: in bot.yaml, brought up with a tab and a mailbox,
 // its conversations kept in the book. What makes it temporary is one field of
 // its book entry, `temporary: { maker, made }`, and the book is the one place
@@ -27,8 +29,8 @@ import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
 import { readBook, updateBook } from './book.js';
-import { addSession, dropSession, NAME, readBot } from './bot.js';
-import { harnessOf, isShortPrompt, ownCli, shellWord, startPrompt, workDirOf } from './launch.js';
+import { addSession, dropSession, NAME, readBot, tempRoles } from './bot.js';
+import { DEFAULT_APPROVAL, harnessOf, isShortPrompt, ownCli, shellWord, startPrompt, workDirOf } from './launch.js';
 import { sessionInTab } from './message.js';
 import { orca, screenRows, tabs } from './orca.js';
 import { retireSession } from './retire.js';
@@ -39,45 +41,43 @@ const INHERITED = ['model', 'effort', 'context', 'approval'];
 
 /**
  * Make a temporary session of the caller's own bot and bring it up. `given`
- * holds what the caller said: `name`, `prompt` or `prompt_file`, and any of
- * `harness` and the inherited settings. Returns `{ bot, session, maker,
- * settings, up }`, where `up` is what bringing it up answered.
+ * holds what the caller said: `name`, `prompt` or `prompt_file`, any of
+ * `harness` and the inherited settings, and `role`, as `role` or
+ * `role:option`, to take the settings that role's option gives in its bot's
+ * `temp_roles` (#465). Returns `{ bot, session, maker, settings, chosen,
+ * role, up }`: `chosen` says where each setting came from, `role` is there
+ * when one was asked for, and `up` is what bringing it up answered.
  */
 export async function makeTemp(bots, { tab, ...given }) {
   const caller = callerIn(bots, tab, 'make');
   // Checked here, before anything is written, and again under the book's lock
   // below, where two makes at once cannot both pass it.
   refuseNested(bots, caller, readBook(caller.home));
+  const bot = readBot(caller.home, caller.bot);
+  const role = given.role === undefined ? undefined : roleAsked(caller, bot, given.role);
+  const name = role === undefined ? given.name : roleName(caller, bot, role, given.name);
   // The name is a folder under work/ and a file beside the bots folder, so it
   // is held to the rule a bot's name is: one plain name, never a path.
-  if (!NAME.test(given.name)) {
-    throw new Error(`${given.name} cannot be a session's name: a name is lower-case letters, digits and single hyphens, such as review-250. Nothing was made.`);
-  }
-  if (given.prompt === undefined && given.prompt_file === undefined) {
-    throw new Error(`temp make needs the task: --prompt <text> or --prompt-file <path>. Nothing was made.`);
+  if (!NAME.test(name)) {
+    throw new Error(`${name} cannot be a session's name: a name is lower-case letters, digits and single hyphens, such as review-250. Nothing was made.`);
   }
   if (given.prompt !== undefined && given.prompt_file !== undefined) {
     throw new Error(`temp make was given the task twice, as --prompt and as --prompt-file, and a session is told its duty once. Give it one way. Nothing was made.`);
   }
+  if (given.prompt === undefined && given.prompt_file === undefined && role?.prompt_file === undefined) {
+    throw new Error(`temp make needs the task: --prompt <text> or --prompt-file <path>${role === undefined ? '' : `, since the role ${role.name} has no prompt file`}. Nothing was made.`);
+  }
+  if (role !== undefined) refuseCap(caller, role, readBook(caller.home));
 
-  const bot = readBot(caller.home, caller.bot);
   const maker = bot.sessions.find((session) => session.name === caller.session);
-  const settings = { name: given.name };
-  const harness = given.harness ?? maker?.harness;
-  if (harness !== undefined) settings.harness = harness;
-  // On another harness than its maker's, the model, the effort and the context
-  // are that harness's own, and only the approval carries over (#238, PRD 6.4).
-  const same = (harness ?? bot.harness) === harnessOf(maker ?? {}, bot.harness);
-  for (const field of INHERITED) {
-    const value = given[field] ?? (same || field === 'approval' ? maker?.[field] : undefined);
-    if (value !== undefined) settings[field] = value;
-  }
+  const { settings, chosen } = settingsFor(bot, maker, role?.option ?? {}, given);
+  settings.name = name;
   if (given.extra_args !== undefined) settings.extra_args = given.extra_args;
   if (given.prompt !== undefined) settings.prompt = given.prompt;
-  else settings.prompt_file = given.prompt_file;
-  settings.work_dir = `work/${given.name}`;
+  else settings.prompt_file = given.prompt_file ?? role.prompt_file;
+  settings.work_dir = `work/${name}`;
 
-  const written = bot.sessions.some((session) => session.name === given.name) ? undefined : writePromptFirst(bots, caller, settings);
+  const written = bot.sessions.some((session) => session.name === name) ? undefined : writePromptFirst(bots, caller, settings);
   // bot.yaml and the book are written under the book's lock, so that a second
   // make from the same maker waits, and then sees this one (#464). addSession
   // refuses a name the bot already has, and a setting that will not work,
@@ -89,21 +89,23 @@ export async function makeTemp(bots, { tab, ...given }) {
     await updateBook(caller.home, (book) => {
       locked = true;
       refuseNested(bots, caller, book);
+      if (role !== undefined) refuseCap(caller, role, book);
       added = addSession(bots, caller.bot, settings);
-      book.sessions[given.name] = { ...book.sessions[given.name], temporary: { maker: caller.session, made } };
+      const kind = role === undefined ? {} : { role: role.name, option: role.option.name };
+      book.sessions[name] = { ...book.sessions[name], temporary: { maker: caller.session, made, ...kind } };
     });
   } catch (error) {
     // A refusal under the lock has written nothing but the prompt file.
     const refused = locked && added === undefined;
-    const failed = `${caller.bot}/${given.name} could not be recorded in the book as temporary (${error.message})`;
+    const failed = `${caller.bot}/${name} could not be recorded in the book as temporary (${error.message})`;
     // A session in bot.yaml that the book does not call temporary would be a
     // long-lived one to everything that reads it, its maker's retire included,
     // so it is taken back off rather than left that way.
     if (added !== undefined) {
       try {
-        dropSession(bots, caller.bot, given.name);
+        dropSession(bots, caller.bot, name);
       } catch (undo) {
-        throw new Error(`${failed}, and taking it back off bot.yaml failed too (${undo.message}). It is in bot.yaml as a session the book does not call temporary. Take it off with  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${caller.bot} --session ${given.name}`);
+        throw new Error(`${failed}, and taking it back off bot.yaml failed too (${undo.message}). It is in bot.yaml as a session the book does not call temporary. Take it off with  ${shellWord(ownCli())} retire --bots ${shellWord(bots)} --bot ${caller.bot} --session ${name}`);
       }
     }
     // Off bot.yaml, nothing is made; a prompt file that stays is only a file,
@@ -120,12 +122,134 @@ export async function makeTemp(bots, { tab, ...given }) {
 
   let up;
   try {
-    up = await bringUp(bots, { bot: caller.bot, session: given.name });
+    up = await bringUp(bots, { bot: caller.bot, session: name });
   } catch (error) {
     const cli = shellWord(ownCli());
-    throw new Error(`${caller.bot}/${given.name} is made, in bot.yaml and in the book as temporary with its maker ${caller.session}, and could not be brought up: ${error.message} Bring it up with  ${cli} up --bots ${shellWord(bots)} --bot ${caller.bot} --session ${given.name}  or retire it with  ${cli} temp retire --bots ${shellWord(bots)} --name ${given.name}`);
+    throw new Error(`${caller.bot}/${name} is made, in bot.yaml and in the book as temporary with its maker ${caller.session}, and could not be brought up: ${error.message} Bring it up with  ${cli} up --bots ${shellWord(bots)} --bot ${caller.bot} --session ${name}  or retire it with  ${cli} temp retire --bots ${shellWord(bots)} --name ${name}`);
+  }
+  return { bot: caller.bot, session: name, maker: caller.session, settings: added.session, chosen, ...(role === undefined ? {} : { role: roleAnswer(role) }), up };
+}
+
+/**
+ * The settings a temporary session is made with, and for each of the ones
+ * that can be inherited, what it got and where from: `chosen` (#465). A flag
+ * wins; then the role's option, on the option's harness, which is the maker's
+ * when the option names none; then the maker, on the maker's harness; and
+ * otherwise the harness's own default. On another harness than its maker's,
+ * only the approval carries over (#238, PRD 6.4).
+ */
+function settingsFor(bot, maker, option, given) {
+  const makers = harnessOf(maker ?? {}, bot.harness);
+  const settings = {};
+  const chosen = {};
+  const pick = (field, ...sources) => {
+    // YAML reads a setting written with no value as null, which gives nothing.
+    const found = sources.find(([, value]) => value !== undefined && value !== null);
+    if (found === undefined) {
+      chosen[field] = { from: 'harness default' };
+      return;
+    }
+    chosen[field] = { value: found[1], from: found[0] };
+    if (found[0] !== 'maker' || field !== 'harness' || maker?.harness !== undefined) settings[field] = found[1];
+  };
+  pick('harness', ['flag', given.harness], ['role', option.harness], ['maker', makers]);
+  const harness = chosen.harness.value;
+  const fromRole = harness === (option.harness ?? makers);
+  const same = harness === makers;
+  for (const field of INHERITED) {
+    pick(
+      field,
+      ['flag', given[field]],
+      ['role', fromRole && field !== 'approval' ? option[field] : undefined],
+      ['maker', same || field === 'approval' ? maker?.[field] : undefined],
+      // A session's approval is never left to the harness (ADR 0015).
+      ['kit default', field === 'approval' ? DEFAULT_APPROVAL : undefined],
+    );
+  }
+  return { settings, chosen };
+}
+
+/**
+ * The role and option `asked` names, as `role` or `role:option`, from the
+ * bot's roles, with the option it takes; or a refusal that names what the bot
+ * has to choose from.
+ */
+function roleAsked(caller, bot, asked) {
+  const [name, optionName, ...more] = asked.split(':');
+  const roles = tempRoles(caller.home, bot);
+  if (roles.length === 0) {
+    throw new Error(`${caller.bot} has no roles for temporary sessions: its bot.yaml has no temp_roles. Make it without --role, or give the bot its roles first. Nothing was made.`);
   }
-  return { bot: caller.bot, session: given.name, maker: caller.session, settings: added.session, up };
+  const role = roles.find((one) => one.name === name);
+  if (role === undefined || more.length > 0) {
+    throw new Error(`${caller.bot} has no role ${asked}. Its roles are ${roles.map((one) => one.name).join(', ')}; ask for one as --role <role> or --role <role>:<option>. Nothing was made.`);
+  }
+  if (role.trouble.length > 0) {
+    throw new Error(`the role ${name} cannot be used as it is written: ${role.trouble.join(' ')} Nothing was made.`);
+  }
+  const option = optionName === undefined ? role.options[0] : role.options.find((one) => one.name === optionName);
+  if (option === undefined) {
+    throw new Error(`the role ${name} has no option ${optionName}. Its options are ${optionsLine(optionsOf(role))}. Nothing was made.`);
+  }
+  return { ...role, option };
+}
+
+/**
+ * The name of a session made in `role`: `--name` as given when it already
+ * begins with the role, or with the role put in front. A name that begins with
+ * another of the bot's roles would say the wrong one, and is refused.
+ */
+function roleName(caller, bot, role, given) {
+  if (given.startsWith(`${role.name}-`)) return given;
+  const other = tempRoles(caller.home, bot).find((one) => given.startsWith(`${one.name}-`));
+  if (other !== undefined) {
+    throw new Error(`${given} begins with ${other.name}-, the name of another of ${caller.bot}'s roles, and a session made in ${role.name} is named for ${role.name}. Give --name without it, such as --name ${given.slice(other.name.length + 1)}, to make ${role.name}-${given.slice(other.name.length + 1)}. Nothing was made.`);
+  }
+  return `${role.name}-${given}`;
+}
+
+/** Refuse a make in a role whose cap of open sessions is reached, against `book` (#465). */
+function refuseCap(caller, role, book) {
+  if (role.cap === undefined) return;
+  const open = Object.keys(book.sessions).filter((name) => book.sessions[name]?.temporary?.role === role.name);
+  if (open.length >= role.cap) {
+    throw new Error(`the role ${role.name} has a cap of ${role.cap} open temporary sessions, and ${caller.bot} has ${open.length} open: ${open.join(', ')}. Retire one whose work is done first. Nothing was made.`);
+  }
+}
+
+/** A role's options as an answer gives them: each one's name, what it is for, and whether it is the default. */
+const optionsOf = (role) => role.options.map((option, at) => ({ name: option.name, ...(option.for === undefined ? {} : { for: option.for }), default: at === 0 }));
+
+/** Options as `optionsOf` gives them, on one line. */
+export const optionsLine = (options) => options
+  .map((option) => `${option.name}${option.default ? ' (the default)' : ''}${option.for === undefined ? '' : `, for ${option.for}`}`)
+  .join('; ');
+
+/** A role as an answer gives it: the option used, and every option the role has. */
+const roleAnswer = (role) => ({
+  name: role.name,
+  option: role.option.name,
+  ...(role.option.for === undefined ? {} : { for: role.option.for }),
+  options: optionsOf(role),
+});
+
+/**
+ * The roles of the caller's bot, each with its cap, its open temporary
+ * sessions, its prompt file and its options, the first the default (#465).
+ * Returns `{ bot, roles }`.
+ */
+export function listRoles(bots, { tab }) {
+  const caller = callerIn(bots, tab, 'roles', 'list the roles');
+  const book = readBook(caller.home);
+  const roles = tempRoles(caller.home, readBot(caller.home, caller.bot)).map((role) => ({
+    name: role.name,
+    ...(role.cap === undefined ? {} : { cap: role.cap }),
+    open: Object.keys(book.sessions).filter((name) => book.sessions[name]?.temporary?.role === role.name),
+    ...(role.prompt_file === undefined ? {} : { prompt_file: role.prompt_file }),
+    options: role.options.map((option, at) => ({ ...option, default: at === 0 })),
+    ...(role.trouble.length === 0 ? {} : { trouble: role.trouble }),
+  }));
+  return { bot: caller.bot, roles };
 }
 
 /**

package/src/up.js

@@ -408,12 +408,13 @@ const LIST_LOOK_MS = 2000;
 const LIST_ASK_MS = 500;
 
 /**
- * Type LIST_LINE into the tab `tabId` once the gate every typed line goes
- * through lets it: `{ typed: true }`, or `{ typed: false, why }` with the
- * gate's last reason once LIST_WAIT_MS is up. Nothing goes into a question, a
- * form or a menu (#329, #416), nor into a tab the kit cannot tell about.
+ * Type `line`, LIST_LINE unless told otherwise, into the tab `tabId` once the
+ * gate every typed line goes through lets it: `{ typed: true }`, or
+ * `{ typed: false, why }` with the gate's last reason once LIST_WAIT_MS is up.
+ * Nothing goes into a question, a form or a menu (#329, #416), nor into a tab
+ * the kit cannot tell about.
  */
-async function typeListLine(home, tabId) {
+export async function typeListLine(home, tabId, line = LIST_LINE) {
   const until = Date.now() + LIST_WAIT_MS;
   for (;;) {
     let found;
@@ -430,7 +431,7 @@ async function typeListLine(home, tabId) {
     }
     if (found.handle !== undefined) {
       try {
-        typeIntoTab(found.handle, LIST_LINE);
+        typeIntoTab(found.handle, line);
         return { typed: true };
       } catch (error) {
         return { typed: false, why: `Orca refused the line: ${error.message}` };