@assuredloop/orca-bot-kit 0.36.0 → 0.36.1

package/package.json

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

package/skills/obk-bot-building/SKILL.md

@@ -127,6 +127,22 @@ the bots folder moves. `obk session add` and `obk session change` say so when a
 work dir leads out of the bot home; take that back to the user rather than
 past them.
 
+## How its sessions choose a subagent's model
+
+A session runs on one model of its own, but the model of each subagent it starts
+can be chosen task by task. A bot that should choose carries its way of working
+for this as a rule unit of its own. The bot can decide that way of working, or
+the user can. Write it in their words as a unit in `rules/` of the bots folder,
+name it in that bot's `rules:` list, and run `obk rules build`: every session
+of the bot then reads it in its `AGENTS.md`. Another bot can carry another
+rule, or none. A bot with none works as before, and each subagent runs on what
+the harness gives it.
+
+The rule acts where the harness lets a session choose a model for a subagent,
+as Claude Code's Agent tool does with its `model`. Where the harness does not,
+nothing changes. The kit names no model and no table from a task to a model:
+any model in the rule is the bot's or the user's choice.
+
 ## Offer a line-up rather than a blank page
 
 Someone making their first bots does not know what a good set looks like, so

package/skills/obk-finops/SKILL.md

@@ -119,6 +119,9 @@ A usual shape: high effort for the session that orchestrates, medium for the
 ones doing the work, and the top of the range only for deep read-only
 analysis.
 
+A bot can also carry its own rule on the model each subagent gets: see "How
+its sessions choose a subagent's model" in the obk-bot-building skill.
+
 ## When a model is not up to the work
 
 The signs are in the work, not in the answers. The same instruction given

package/src/cli.js

@@ -1177,6 +1177,10 @@ const commands = {
       answer,
       lines: [
         `${'sent'.padEnd(9)}  ${where.padEnd(24)}  ${answer.subject}`,
+        // Orca took it, and its answer named no letter (#730).
+        ...(answer.id === undefined
+          ? ['             Orca queued it, and its answer gave no message id for it.']
+          : []),
         ...(answer.file === undefined
           ? []
           : [`             it was too long to travel as itself, so it went as a file:  ${answer.file}`]),

package/src/message.js

@@ -203,19 +203,21 @@ export async function sendMessage(bots, { to: target, from: sender, tab, subject
   const shown = await loaded(to);
   // The Escape goes first, so the turn has ended when the letter is in.
   const interrupted = interrupt ? interruptBusy(to) : {};
-  const message = postMessage({
+  const posted = postMessage({
     to: road.address,
     from: `run:${from.mailbox}`,
     subject,
     body: written.body,
     thread,
   });
+  // Orca took it: sent, whatever else its answer says or leaves out (#730).
+  const message = posted?.message;
 
   return {
     ...answer,
     sent: true,
-    id: message.id,
-    thread: message.thread_id ?? thread,
+    id: message?.id ?? posted?.messageId,
+    thread: message?.thread_id ?? thread,
     file: written.file,
     ...interrupted,
     ...shown,
@@ -356,12 +358,14 @@ function mailOf(bots, who, peek, until) {
       trouble: `${who.bot}/${who.session} is not up, and its mailbox is bound to no tab, so there is nothing to read it as. Its mail waits until its tab is back: \`up\` brings it back, or \`unpause\` when it is paused.`,
     };
   }
-  // Orca hands mail over a batch at a time and replays the oldest until it is
-  // acknowledged; the acknowledgement answers with the next batch. So a read
-  // takes every batch in turn, or newer mail waits behind an older one (#299).
-  //
-  // A batch is given back once it is acknowledged, and not before: one this
-  // check stops short of acknowledging is handed over again to the next.
+  // Orca hands mail over a batch at a time, so a read takes every batch in
+  // turn, or newer mail waits behind an older one (#299). Up to 1.4.245 it
+  // replays the oldest until it is acknowledged, and the acknowledgement
+  // answers with the next batch: a batch this check stops short of
+  // acknowledging is handed over again to the next. From 1.4.246 a read
+  // acknowledges the batch it hands over and says so (`deliveryAcknowledged`),
+  // and an acknowledgement answers with no batch, so the next is read again
+  // (#729; read in the 1.4.246 and 1.4.255 source).
   const messages = [];
   const read = { bots, bot: who.bot, session: who.session, mailbox: who.mailbox, read: !peek, messages };
   let found = readMailbox(who.mailbox, { peek, handle }, timeLeft(until));
@@ -372,6 +376,24 @@ function mailOf(bots, who, peek, until) {
       return read;
     }
     const wait = timeLeft(until, false);
+    if (found.deliveryAcknowledged === true) {
+      // Read already, so shown whatever comes after.
+      messages.push(...batch);
+      if (wait === undefined) {
+        return { ...read, trouble: `${who.bot}/${who.session} has more mail than one check reads in ${HOLD_MS / 1000} seconds, so it stopped there. The rest is still waiting: check again.` };
+      }
+      try {
+        found = readMailbox(who.mailbox, { handle }, wait);
+      } catch (error) {
+        // A read Orca did not answer about may have taken the next batch all
+        // the same, and taken is read: that batch is not handed over again.
+        if (error.code === TIMED_OUT) {
+          return { ...read, trouble: `${error.message} Orca may have taken the next letters as read without the kit seeing them. The mail shown above is read.` };
+        }
+        return { ...read, trouble: `${error.message} The mail shown above is read, and the rest waits for the next check.` };
+      }
+      continue;
+    }
     if (wait === undefined) {
       return { ...read, trouble: `${who.bot}/${who.session} has more mail than one check reads in ${HOLD_MS / 1000} seconds, so it stopped there. The rest is still waiting: check again.` };
     }

package/src/orca.js

@@ -1203,6 +1203,33 @@ export const pressEscape = (handle) =>
 /** Where Orca names the terminal a process runs in, in every pane it opens. */
 export const TERMINAL_ENV = 'ORCA_TERMINAL_HANDLE';
 
+/**
+ * One `orca orchestration` command, answered in full. From 1.4.246 Orca prints
+ * a short answer for each of these unless it is given `--full`, and the short
+ * one leaves out what the kit reads: a Run's `id` and `coordinator_handle`, a
+ * letter's `from_handle`, `created_at`, `thread_id`, `read` and `delivered_at`,
+ * and a sent letter's `message` (#729, #730; read in the 1.4.246 and 1.4.255
+ * source, and seen live on 1.4.255). Orca 1.4.245 and older do not know the
+ * flag on any of them but `inbox`, and refuse it before they do anything, as
+ * `deleteProject` finds with `--force` (#528). Only that refusal sends the
+ * command again without it: one Orca took, or did not answer, is never sent a
+ * second time. Once refused, the rest of this run sends no `--full`.
+ */
+function orchestration(args, options) {
+  if (fullKnown) {
+    try {
+      return orca([...args, '--full'], options);
+    } catch (error) {
+      if (error.code !== 'invalid_argument' || !error.reason?.startsWith('Unknown flag --full for command: ')) throw error;
+      fullKnown = false;
+    }
+  }
+  return orca(args, options);
+}
+
+/** Whether this Orca may know `--full` on its orchestration commands: false once it has refused it. */
+let fullKnown = true;
+
 /**
  * A mailbox of one session's own: an Orca Run, which is a name and an inbox and
  * nothing else — it schedules nothing and runs nobody. The objective is what a
@@ -1215,7 +1242,7 @@ export const TERMINAL_ENV = 'ORCA_TERMINAL_HANDLE';
  * tab and names no `--from` (tech notes, section 1; #317).
  */
 export const makeMailbox = (objective, options) =>
-  orca(['orchestration', 'run-create', '--objective', `obk ${objective}`], options).run.id;
+  orchestration(['orchestration', 'run-create', '--objective', `obk ${objective}`], options).run.id;
 
 /**
  * Bind a mailbox to the terminal `handle`, which makes it the Run's coordinator
@@ -1226,7 +1253,7 @@ export const makeMailbox = (objective, options) =>
  * tab may name no other (#317).
  */
 export const useMailbox = (id, handle, options) =>
-  orca(['orchestration', 'run-use', '--id', id, ...(handle === undefined ? [] : ['--from', handle])], options).run;
+  orchestration(['orchestration', 'run-use', '--id', id, ...(handle === undefined ? [] : ['--from', handle])], options).run;
 
 /**
  * The terminal a mailbox is bound to, or undefined when it has none. A closed
@@ -1234,7 +1261,7 @@ export const useMailbox = (id, handle, options) =>
  * nothing, only `run-use` does (tech notes, section 1).
  */
 export const coordinatorOf = (id, options) =>
-  orca(['orchestration', 'run-show', '--id', id], options).run.coordinator_handle ?? undefined;
+  orchestration(['orchestration', 'run-show', '--id', id], options).run.coordinator_handle ?? undefined;
 
 /**
  * Whether this Orca has no Run of that id at all, as when the book was written
@@ -1245,29 +1272,36 @@ export const coordinatorOf = (id, options) =>
  */
 export function runMissing(id, options) {
   try {
-    orca(['orchestration', 'run-show', '--id', id], options);
+    orchestration(['orchestration', 'run-show', '--id', id], options);
     return false;
   } catch (error) {
     return error.code === 'run_not_found';
   }
 }
 
-/** Queue one message. `to` and `from` are mailboxes, written `run:<id>`. */
+/**
+ * Queue one message. `to` and `from` are mailboxes, written `run:<id>`. Orca's
+ * whole answer comes back: the letter it queued is its `message`, where Orca
+ * says so. Once Orca has taken it, an answer the kit cannot read is no reason
+ * to say it was not sent (#730).
+ */
 export function postMessage({ to, from, subject, body, type = 'status', thread }) {
   const args = ['orchestration', 'send', '--to', to, '--subject', subject, '--body', body, '--type', type];
   if (from !== undefined) args.push('--from', from);
   if (thread !== undefined) args.push('--thread-id', thread);
-  return orca(args).message;
+  return orchestration(args);
 }
 
 /**
  * What is waiting in a mailbox: the oldest batch that has not been
- * acknowledged, or, peeking, whatever is unread without touching it. Read as
+ * acknowledged, or, peeking, whatever is unread without touching it. From
+ * Orca 1.4.246 a read that is not a peek acknowledges the batch it hands over,
+ * and says so with `deliveryAcknowledged: true` (#729). Read as
  * the terminal `handle` when one is given, which is how a read works from a tab
  * bound to another Run; otherwise as this process's own terminal.
  */
 export const readMailbox = (id, { peek = false, handle } = {}, options) =>
-  orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])], options);
+  orchestration(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])], options);
 
 /**
  * The newest `limit` messages in a mailbox, newest first, with every column
@@ -1278,11 +1312,14 @@ export const readMailbox = (id, { peek = false, handle } = {}, options) =>
  * cap in Orca, so the answer is taken whatever its size.
  */
 export const mailIn = (id, limit) =>
-  orca(['orchestration', 'inbox', '--terminal', `run:${id}`, '--limit', String(limit)], { whole: true }).messages ?? [];
+  orchestration(['orchestration', 'inbox', '--terminal', `run:${id}`, '--limit', String(limit)], { whole: true }).messages ?? [];
 
-/** Say a batch has been read. Orca answers with the batch after it. */
+/**
+ * Say a batch has been read. Up to Orca 1.4.245 Orca answers with the batch
+ * after it; from 1.4.246 with no batch, since its read acknowledged it (#729).
+ */
 export const ackMailbox = (id, delivery, handle, options) =>
-  orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery], options);
+  orchestration(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery], options);
 
 /** The reader of a `check`: the terminal named, or this process's own. */
 const as = (handle) => (handle === undefined ? [] : ['--terminal', handle]);