@assuredloop/orca-bot-kit 0.35.0 → 0.36.1

package/README.md

@@ -403,6 +403,18 @@ bot's sessions, set `"auto-mode-setup": "on"` under `skillOverrides` in the bot'
 `.claude/settings.local.json`, which wins over the kit's entry. The kit never
 writes that file.
 
+Under an Orca Claude account, the kit's line for a Claude session also carries
+`--settings` with one key, `autoMemoryDirectory`. It names the physical folder
+behind the account's linked `projects` folder, so a session saves its memory
+with no permission dialog. The memory is the same memory, and the kit writes no
+file for this. A bot, its repository or an account that names its own
+`autoMemoryDirectory` keeps it. A conversation that began before this keeps its old path until the
+session restarts under this version and then begins a new conversation with
+`/clear`. A restart alone or a `/clear` alone does not change the path. After
+Orca brings a tab back by itself, a `/clear` before a
+restart brings the dialog back; `obk health` names such a session
+([ADR 0054](docs/adr/0054-the-kits-launch-line-names-the-physical-memory-folder.md)).
+
 So: kill a tab, or reboot, and `obk up` brings the session back with the
 conversation it was having, rather than starting a new one. Clear a session —
 `/clear` on Claude Code, `/new` on Codex — and the kit writes down the new id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.35.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/conversations.js

@@ -20,7 +20,7 @@ import { eachLine, firstLine } from './lines.js';
 const claudeDir = (home) => path.join(homedir(), '.claude', 'projects', slug(home));
 
 /** The folder's name is the working directory with everything else turned into a dash. */
-const slug = (home) => home.replaceAll(/[^A-Za-z0-9]/g, '-');
+export const slug = (home) => home.replaceAll(/[^A-Za-z0-9]/g, '-');
 
 /**
  * Pi's sessions: one folder per working directory, named from its real path

package/src/launch.js

@@ -294,11 +294,12 @@ const NO_DAEMON = '--no-daemon';
 
 // A string is shell text, so it is read as the shell will split it: `'--no-daemon'`
 // is the flag, and `'/tmp/a --no-daemon b'` is one path that merely says it.
-const setsNoDaemon = (session) => {
-  const extra = session.extra_args;
-  const words = Array.isArray(extra) ? extra.map(String) : set(extra) ? shellWords(String(extra)) : [];
-  return words.includes(NO_DAEMON);
-};
+const extraArgWords = (extra) => (Array.isArray(extra) ? extra.map(String) : set(extra) ? shellWords(String(extra)) : []);
+
+const setsNoDaemon = (session) => extraArgWords(session.extra_args).includes(NO_DAEMON);
+
+/** Whether the session's own extra arguments hold Claude Code's `--settings`. */
+const setsSettings = (session) => extraArgWords(session.extra_args).some((word) => word === '--settings' || word.startsWith('--settings='));
 
 /**
  * The words a shell makes of `text`: split on blanks outside quotes, quotes
@@ -412,7 +413,7 @@ const where = (session) => (set(session.name) ? `session ${session.name}` : 'thi
  * send would land on that list and answer it. A prompt given as an argument is
  * held by the harness until it is ready for it (tech notes, section 1).
  */
-export function launchCommand(session, { harness, home, workDir, prompt, promptFile: fromFile, resume, address, kit, sessionId, name }) {
+export function launchCommand(session, { harness, home, workDir, prompt, promptFile: fromFile, resume, address, kit, sessionId, name, memoryFolder }) {
   const trouble = sessionTrouble(session, harness, home);
   if (trouble !== undefined) throw new Error(trouble);
   // Pi is told which conversation it is, a new one too: the kit names it, and
@@ -440,6 +441,10 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
     // The context window rides on the model name: `sonnet[1m]`.
     if (set(session.model)) words.push('--model', set(session.context) ? `${session.model}[${session.context}]` : session.model);
     if (set(session.effort)) words.push('--effort', String(session.effort));
+    // This one key and no other: `--settings` can carry rules, folders and
+    // hooks, which is why a user's extra argument may not use it (ADR 0054,
+    // ADR 0049). A hand-written one in bot.yaml is the user's, and wins.
+    if (memoryFolder !== undefined && !setsSettings(session)) words.push('--settings', JSON.stringify({ autoMemoryDirectory: memoryFolder }));
   } else if (harness === 'pi') {
     // Pi trusts none of the folder's own files (`.pi/`, `.agents/skills`), so it
     // shows no trust screen and runs nothing the kit has not looked at (#578).

package/src/memory.js

@@ -0,0 +1,113 @@
+// The physical memory folder of a Claude session, when the path Claude Code
+// would use leads through a link (#722, ADR 0054).
+//
+// Orca starts a Claude tab with CLAUDE_CONFIG_DIR at a profile of its own,
+// where `projects` is a link to `~/.claude/projects`. Claude Code names its
+// memory folder through that link, and a write there stops on a dialog that
+// only a person can answer (tech notes, section 2). Named by its real path, the
+// same folder has no dialog. Whenever the answer is not sure, there is no
+// answer, and the session runs as it did: a dialog costs a wait, and a wrong
+// folder costs the session its memory.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { slug } from './conversations.js';
+import { selectedClaudeProfile } from './orca.js';
+
+/** The longest slug Claude Code uses as it is. Past this it adds a hash of its own. */
+const LONGEST_SLUG = 200;
+
+/**
+ * The folder to name for a session of the bot at `home`, or undefined when the
+ * kit should name none: no profile is routed, its `projects` is no link, the
+ * bot or the profile names a folder of its own, the project root is not sure,
+ * or the slug is too long.
+ */
+export function physicalMemoryFolder(home) {
+  const profile = selectedClaudeProfile();
+  if (profile === undefined) return undefined;
+  const projects = linkedFolder(path.join(profile, 'projects'));
+  if (projects === undefined) return undefined;
+  const root = projectRoot(home);
+  if (root === undefined) return undefined;
+  // Claude Code reads a project's local settings from the top of its repository as well as from the bot's folder.
+  const named = [
+    path.join(home, '.claude', 'settings.json'),
+    path.join(home, '.claude', 'settings.local.json'),
+    path.join(root, '.claude', 'settings.local.json'),
+    path.join(profile, 'settings.json'),
+  ];
+  if (named.some(namesMemoryFolder)) return undefined;
+  // Claude Code holds its project root in NFC, whatever form the disk has.
+  const name = slug(root.normalize('NFC'));
+  return name.length > LONGEST_SLUG ? undefined : path.join(projects, name, 'memory');
+}
+
+/** The real path of the folder the link `entry` leads to, or undefined when it is not such a link. */
+function linkedFolder(entry) {
+  try {
+    if (!lstatSync(entry).isSymbolicLink()) return undefined;
+    return statSync(entry).isDirectory() ? realpathSync(entry) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Whether the settings file `file` may name a memory folder of its own: it has
+ * the key, or it is there and cannot be read, so the kit cannot tell.
+ */
+function namesMemoryFolder(file) {
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (error) {
+    return error.code !== 'ENOENT' && error.code !== 'ENOTDIR';
+  }
+  try {
+    const settings = JSON.parse(text);
+    return settings !== null && typeof settings === 'object' && Object.hasOwn(settings, 'autoMemoryDirectory');
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * The folder Claude Code keys memory by: the top of the git repository that
+ * holds `home`, the main repository's for a linked worktree, since every
+ * worktree of a repository shares one memory (tech notes, section 2). With no
+ * repository, it is `home` itself. Undefined when the kit is not sure: a `.git`
+ * is on the way and git cannot say what it is, a linked worktree's shared git
+ * folder is not named `.git`, or the `.git` at the top is a link.
+ */
+function projectRoot(home) {
+  const shared = revParse(home, '--git-common-dir');
+  if (shared === undefined) return gitOnTheWay(home) ? undefined : realpathSync(home);
+  const own = revParse(home, '--git-dir');
+  if (own === undefined) return undefined;
+  const main = realpathSync(path.resolve(home, shared));
+  const linked = realpathSync(path.resolve(home, own)) !== main;
+  // Only a linked worktree tells its main repository by the shared git folder:
+  // `--separate-git-dir` puts a repository's own git folder away from its top.
+  const top = !linked ? revParse(home, '--show-toplevel') : path.basename(main) === '.git' ? path.dirname(main) : undefined;
+  if (top === undefined) return undefined;
+  return lstatSync(path.join(top, '.git'), { throwIfNoEntry: false })?.isSymbolicLink() ? undefined : top;
+}
+
+/** Whether `folder` or a folder above it holds a `.git` entry. */
+function gitOnTheWay(folder) {
+  for (let at = realpathSync(folder); ; at = path.dirname(at)) {
+    if (existsSync(path.join(at, '.git'))) return true;
+    if (path.dirname(at) === at) return false;
+  }
+}
+
+/** One answer of `git rev-parse` in `folder`, or undefined when git gives none. */
+function revParse(folder, question) {
+  const asked = spawnSync('git', ['-C', folder, 'rev-parse', question], { encoding: 'utf8' });
+  // Only git's record terminator comes off: trailing whitespace may be part of the folder's name.
+  const answer = (asked.stdout ?? '').replace(/\n$/, '');
+  return asked.status === 0 && answer !== '' ? answer : undefined;
+}

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

@@ -146,10 +146,25 @@ export function findProject(home) {
  * names its CLI: a build's folder is written only inside its own CLI, so the
  * kit cannot tell it from the app (#551).
  */
-export const profilesDir = () => path.join(
-  process.env.OBK_ORCA_DATA || path.join(homedir(), 'Library', 'Application Support', 'orca'),
-  'profiles',
-);
+export const profilesDir = () => path.join(orcaData(), 'profiles');
+
+const orcaData = () => process.env.OBK_ORCA_DATA || path.join(homedir(), 'Library', 'Application Support', 'orca');
+
+/**
+ * The home of the Claude profile Orca routes a new Claude tab to, or undefined
+ * when it routes none. Orca writes the path to `selected-host`, with nothing
+ * in it when no profile is routed, and removes the file when it has no accounts
+ * (read in the bundle of Orca 1.4.245, tech notes, section 2).
+ */
+export function selectedClaudeProfile() {
+  let home;
+  try {
+    home = readFileSync(path.join(orcaData(), 'claude-profiles', 'selected-host'), 'utf8').replace(/\r?\n$/, '');
+  } catch {
+    return undefined;
+  }
+  return path.isAbsolute(home) ? home : undefined;
+}
 
 /**
  * Orca's own default launch arguments, per profile it keeps:
@@ -1188,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
@@ -1200,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
@@ -1211,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
@@ -1219,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
@@ -1230,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
@@ -1263,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]);

package/src/up.js

@@ -14,6 +14,7 @@ import { botDir, botNames, displayName, readBot } from './bot.js';
 import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { dropRemovedHooks, installHook } from './hooks.js';
 import { writePermissions } from './permissions.js';
+import { physicalMemoryFolder } from './memory.js';
 import { piTrouble } from './pi.js';
 import { addressOf, HARNESSES, harnessOf, isAddressOf, isShortPrompt, kitFolders, launchCommand, mailboxStep, ownCli, reachesMail, sessionTrouble, shellWord, startPrompt, workDirOf } from './launch.js';
 import { asFolderProject, coordinatorOf, dropLeftGit, findProject, harnessInTab, loadInWindow, makeMailbox, makeProject, openTab, QUESTION_ON_SCREEN, retitleTab, runMissing, screenRows, shellInTab, tabs, tabToTypeInto, TERMINAL_ENV, TIMED_OUT, tellWindow, typeIntoTab, useMailbox } from './orca.js';
@@ -610,6 +611,7 @@ function launchFor(bots, bot, session, harness, home, workDir, resume, held, fre
     resume,
     address,
     kit: kitFolders(bots, bot.name),
+    ...(harness === 'claude' ? { memoryFolder: physicalMemoryFolder(home) } : {}),
     // A new Pi conversation's id, and the name its tab and session list show,
     // `<bot>.<session>` as a Codex thread is named (#480).
     ...(harness === 'pi' ? { sessionId: resume === undefined ? fresh : undefined, name: `${bot.name}.${session.name}` } : {}),