@assuredloop/orca-bot-kit 0.20.0 → 0.22.0

package/src/temp.js

@@ -4,7 +4,10 @@
 //
 // 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 is an ordinary
+// 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). 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
@@ -26,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';
@@ -38,87 +41,232 @@ 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');
-  if (caller.temporary !== undefined) {
-    throw new Error(`${caller.bot}/${caller.session} is a temporary session, and only a long-lived session makes one. Nothing was made.`);
-  }
+  // 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);
-  // Refuses a name the bot already has, and a setting that will not work,
-  // before it writes anything; the prompt written first goes with a refusal.
-  let added;
-  try {
-    added = addSession(bots, caller.bot, settings);
-  } catch (error) {
-    if (written !== undefined) rmSync(written, { force: true });
-    throw error;
-  }
+  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,
+  // before it writes anything.
   const made = new Date().toISOString();
+  let locked = false;
+  let added;
   try {
     await updateBook(caller.home, (book) => {
-      book.sessions[given.name] = { ...book.sessions[given.name], temporary: { maker: caller.session, made } };
+      locked = true;
+      refuseNested(bots, caller, book);
+      if (role !== undefined) refuseCap(caller, role, book);
+      added = addSession(bots, caller.bot, settings);
+      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}/${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.
-    const failed = `${caller.bot}/${given.name} could not be recorded in the book as temporary (${error.message})`;
-    try {
-      dropSession(bots, caller.bot, given.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}`);
+    if (added !== undefined) {
+      try {
+        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 ${name}`);
+      }
     }
     // Off bot.yaml, nothing is made; a prompt file that stays is only a file,
     // and nothing reads it (#393).
+    const why = refused ? error.message.replace(/ ?Nothing was made\.$/, '') : `${failed}${added === undefined ? '.' : ', so it was taken back off bot.yaml.'}`;
     try {
       if (written !== undefined) rmSync(written, { force: true });
     } catch (left) {
-      throw new Error(`${failed}, so it was taken back off bot.yaml and nothing was made. Its start prompt ${written} could not be removed (${left.message}), and nothing reads it. Remove it with  rm ${shellWord(written)}`);
+      throw new Error(`${why} Nothing was made. Its start prompt ${written} could not be removed (${left.message}), and nothing reads it. Remove it with  rm ${shellWord(written)}`);
     }
-    throw new Error(`${failed}, so it was taken back off bot.yaml and nothing was made. Run this again once the book can be written.`);
+    if (refused) throw error;
+    throw new Error(`${why} Nothing was made. Run this again once the book can be written.`);
   }
 
   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.`);
+  }
+  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 };
+}
+
+/**
+ * Refuse a make by a temporary session that may not make one now, against
+ * `book`: one made by a temporary session makes none, and a temporary session
+ * has one of its own open at a time (#464, ADR 0033).
+ */
+function refuseNested(bots, caller, book) {
+  if (caller.temporary === undefined) return;
+  const maker = caller.temporary.maker;
+  if (book.sessions[maker]?.temporary !== undefined) {
+    throw new Error(`${caller.bot}/${caller.session} is a temporary session ${maker} made, and ${maker} is temporary itself, so it makes none of its own: temporary sessions go one level deep. Nothing was made.`);
+  }
+  const open = Object.keys(book.sessions).filter((name) => book.sessions[name]?.temporary?.maker === caller.session);
+  if (open.length > 0) {
+    throw new Error(`${caller.bot}/${caller.session} is a temporary session, and it already has ${open.join(', ')} open; a temporary session has one of its own at a time. Retire it first with  ${shellWord(ownCli())} temp retire --bots ${shellWord(bots)} --name ${open[0]}  Nothing was made.`);
   }
-  return { bot: caller.bot, session: given.name, maker: caller.session, settings: added.session, up };
 }
 
 /**