@assuredloop/orca-bot-kit 0.2.0 → 0.3.0

package/src/roster.js

@@ -5,7 +5,7 @@
 // reads files and only files. It does not ask Orca, it changes nothing, and it
 // judges nothing: whether a bot is the right bot, what its charter comes to in
 // two lines, and which of its limits is the hard one are the reader's to say
-// (ADR 0006). What is wrong with the setup is a different question, and
+// (ADR 0016). What is wrong with the setup is a different question, and
 // `obk health` is the command that answers it.
 //
 // So a list here is the list as the user wrote it, unchecked. A skill named in

package/src/rules.js

@@ -1,5 +1,5 @@
 // A bot's `AGENTS.md`, built from its charter and the rule units it carries
-// (PRD 6.6, ADR 0003).
+// (PRD 6.6, ADR 0013).
 //
 // This is the one place the kit's own text lands inside the user's repo, so the
 // promise around it is narrow: the build owns one marked block and nothing else
@@ -299,7 +299,7 @@ function writeBlock(file, body) {
  * Whatever is already there is the user's and stays. What the build owes them
  * is the fact they cannot see: Claude Code reads a `CLAUDE.md` *instead of*
  * `AGENTS.md`, so one that is not this bot's `AGENTS.md` leaves the two
- * harnesses starting from different rules, which is the one thing ADR 0003
+ * harnesses starting from different rules, which is the one thing ADR 0013
  * says must not happen.
  *
  * Returns `{ linked }` on the run that made the link, `{ trouble }` when what

package/src/skills.js

@@ -1,5 +1,5 @@
 // The skills a bot has: links in the bot's own folder, into both harnesses
-// (PRD 6.7, ADR 0004, ADR 0009).
+// (PRD 6.7, ADR 0014, ADR 0019).
 //
 // Linked, never copied, in both directions. Inwards: what lands in the bot home
 // is a symlink to the skill's own directory, so a kit skill is read where the
@@ -21,6 +21,7 @@ import { fileURLToPath } from 'node:url';
 import { parse, parseDocument, stringify } from 'yaml';
 
 import { botDir, botNames, changesExactly, leadsOutside, readBot, YAML_OUT } from './bot.js';
+import { ownCli, shellWord } from './launch.js';
 import { listIn } from './rules.js';
 import { cloneDir, isCloned, readSources, skillsIn, wrongClone } from './sources.js';
 
@@ -39,7 +40,7 @@ export const SKILL_DIRS = {
 /**
  * What a skill may be called: the Agent Skills name, which is also the name of
  * the directory it lives in and of the link the kit makes (tech notes, section
- * 4, and ADR 0009).
+ * 4, and ADR 0019).
  */
 const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
@@ -280,7 +281,7 @@ export function unlinkSkills(home) {
  * user made, or one of the kit's that they have since repointed, is theirs.
  *
  * It is the kit's own file and lives beside the hook files it already keeps in
- * the bot folder (ADR 0010). A record that cannot be read is treated as an
+ * the bot folder (ADR 0020). A record that cannot be read is treated as an
  * empty one: the worst that follows is that the kit leaves alone something it
  * would otherwise have tidied up, which is the safe way round.
  */
@@ -311,7 +312,7 @@ function writeRecord(home, record) {
  *
  * A link that leads nowhere is reported whoever made it. Whose it is changes
  * what may be done about it, not the fact that a session cannot read the skill
- * (ADR 0004).
+ * (ADR 0014).
  */
 export function skillsTrouble(bots, home, bot) {
   const record = readRecord(home);
@@ -460,7 +461,7 @@ function follow(bots, ref, sources) {
         throw new Error(`${ref} names the source ${named}, and skills.yaml lists no source called that.`);
       }
       if (!isCloned(bots, named)) {
-        throw new Error(`${ref}: ${named} has not been fetched yet, so there is nothing to link. Run obk skills fetch --bots ${bots} --source ${named}.`);
+        throw new Error(`${ref}: ${named} has not been fetched yet, so there is nothing to link. Run ${shellWord(ownCli())} skills fetch --bots ${shellWord(bots)} --source ${named}.`);
       }
       const wrong = wrongClone(bots, source);
       if (wrong !== undefined) throw new Error(`${ref}: ${wrong}`);
@@ -537,7 +538,7 @@ function link(dir, wanted, record) {
     }
 
     // Absolute: a kit skill lives in the installed package, outside the user's
-    // repo, and the link has to reach out of the repo to find it (ADR 0004).
+    // repo, and the link has to reach out of the repo to find it (ADR 0014).
     symlinkSync(skill.dir, at);
     record[skill.name] = skill.dir;
   }

package/src/sources.js

@@ -1,4 +1,4 @@
-// Skills from an online repo, at the version the user pinned (PRD 6.7, ADR 0004).
+// Skills from an online repo, at the version the user pinned (PRD 6.7, ADR 0014).
 //
 // A source is a git repository the user names in `<bots>/skills.yaml`. The kit
 // clones it into `<bots>.skill-sources/<name>`, a sibling of the bots folder and
@@ -19,6 +19,7 @@ import path from 'node:path';
 import { parseDocument } from 'yaml';
 
 import { changesExactly, requireBotsFolder, YAML_OUT } from './bot.js';
+import { ownCli, shellWord } from './launch.js';
 
 /** The user's file that lists where skills come from. */
 const SKILLS_YAML = 'skills.yaml';
@@ -201,7 +202,7 @@ function clone(bots, source, rev, recorded) {
 export function wrongClone(bots, source) {
   const from = originOf(cloneDir(bots, source.name));
   if (from === source.repo) return undefined;
-  return `${source.name}: the clone beside your bots folder came from ${from}, and skills.yaml now names ${source.repo}. Run obk skills update --source ${source.name} to take it from there instead.`;
+  return `${source.name}: the clone beside your bots folder came from ${from}, and skills.yaml now names ${source.repo}. Run ${shellWord(ownCli())} skills update --source ${source.name} to take it from there instead.`;
 }
 
 /** Where a clone came from, as git itself has it written down. */
@@ -226,7 +227,7 @@ function checkout(dir, source, rev, recorded) {
 
   if (at === undefined) {
     throw new Error(recorded
-      ? `${source.name}: ${source.repo} no longer has the commit skills.yaml records for it (${rev.slice(0, 7)}), so the version you pinned cannot be put back. Run obk skills update --source ${source.name} to take what ${source.ref} names now, or point it at a version the repo still has.`
+      ? `${source.name}: ${source.repo} no longer has the commit skills.yaml records for it (${rev.slice(0, 7)}), so the version you pinned cannot be put back. Run ${shellWord(ownCli())} skills update --source ${source.name} to take what ${source.ref} names now, or point it at a version the repo still has.`
       : `${source.name}: ${source.repo} has nothing called ${rev}`);
   }
   git(['-c', 'advice.detachedHead=false', 'checkout', '--quiet', at], dir, `${source.name}: could not go to ${rev}`);

package/src/up.js

@@ -12,7 +12,7 @@ import { botDir, botNames, displayName, readBot } from './bot.js';
 import { conversationsIn } from './conversations.js';
 import { installHook } from './hooks.js';
 import { addressOf, harnessOf, isShortPrompt, launchCommand, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
-import { asFolderProject, findProject, makeMailbox, makeProject, openTab, retitleTab, tabs, tuiInTab, typeIntoTab } from './orca.js';
+import { asFolderProject, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, typeIntoTab, useMailbox } from './orca.js';
 import { buildAgents } from './rules.js';
 import { linkSkills } from './skills.js';
 
@@ -26,8 +26,8 @@ const STARTUP_MS = 10000;
  * And how long the second look takes. A harness can draw its first screen and
  * then die on something it was handed — a context window it cannot read, an
  * extra argument it does not know — and the first look would have called it
- * started. A tab whose TUI is still there answers this at once; only one that
- * has fallen back to a shell waits it out.
+ * started. An idle harness answers this at once; a busy one and a shell both
+ * wait it out, and it is the tab's foreground that tells them apart (#232).
  */
 const SECOND_LOOK_MS = 2000;
 
@@ -87,7 +87,7 @@ export async function bringUp(bots, { bot: onlyBot, session: onlySession } = {})
  *
  * Separate from the tabs because the order matters twice over. A session reads
  * its rules, its skills and its hooks as it comes up, so all three have to be
- * there before the tab is (PRD 6.6, ADR 0010) — and a restart closes a tab in
+ * there before the tab is (PRD 6.6, ADR 0020) — and a restart closes a tab in
  * between, so everything that can refuse must have refused before that. It
  * refuses by throwing, exactly as `up` always has; a bot it leaves out of
  * `running` is one whose sessions must not be started.
@@ -133,7 +133,7 @@ export function prepareBots(bots, names, onlySession) {
 
   // And the kit's hook goes into every bot folder before Orca is asked for
   // anything, for the same reason: a harness reads its hooks when it comes up,
-  // so one written later would miss the session it was written for (ADR 0010),
+  // so one written later would miss the session it was written for (ADR 0020),
   // and a bot folder the kit cannot write it into stops the run with nothing
   // opened anywhere. Only the harnesses a bot actually runs on; a bot with no
   // sessions gets none.
@@ -234,7 +234,7 @@ async function bringUpSession(bots, home, live, session, bot, title) {
     // live harness. Writing the name down here would advertise an address that
     // answers to nobody (review of PR #132, finding 1). It gets one the next
     // time it starts, which is the next time the kit types its launch line.
-    await ensureMailbox(home, bot, session, harness);
+    await ensureMailbox(home, bot, session, harness, known.handle);
 
     // Whatever runs in the tab may have rewritten its title. The kit writes its
     // own back, and reports that one rather than the name Orca last saw: the id
@@ -312,7 +312,7 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // tab is on the books, so a mailbox Orca will not make leaves a tab the next
   // run finds and finishes rather than a tab nobody owns (review of PR #132,
   // finding 3).
-  await ensureMailbox(home, bot, session, harness, { named: harness === 'claude' });
+  await ensureMailbox(home, bot, session, harness, made.handle, { named: harness === 'claude', opened: true });
 
   // And then asking whether a TUI came up, rather than assuming one did. The
   // text goes into the tab's own shell, which may have been busy with a
@@ -321,9 +321,9 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // Twice, because coming up and staying up are different things: a harness
   // that refuses what it was handed draws a screen, prints its complaint and
   // leaves a shell behind, and a run that looked once would report it as
-  // started. A tab that still has a TUI answers the second look at once,
-  // whatever the agent in it is busy with.
-  const tui = tuiInTab(made.handle, STARTUP_MS).running ? tuiInTab(made.handle, SECOND_LOOK_MS) : { running: false };
+  // started.
+  const first = lookFor(made.handle, STARTUP_MS);
+  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
@@ -344,6 +344,23 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   });
 }
 
+/**
+ * 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.
+ *
+ * The harness is up when something other than the shell holds the tab's
+ * terminal, busy or not, or when Orca sees a question on its screen. Orca's
+ * `agentIdentity` is not asked for: it can come seconds after the launch
+ * (tech notes, section 1). When the tab's foreground cannot be read, Orca's own
+ * answers stand in, for this report only: nothing more is typed here.
+ */
+function lookFor(handle, timeoutMs) {
+  const seen = harnessInTab(handle, timeoutMs);
+  const running = seen.blockedReason !== undefined
+    || (seen.front === undefined ? seen.answered || seen.agent !== undefined : seen.front === 'program');
+  return { running, blockedReason: seen.blockedReason };
+}
+
 /**
  * Make sure the book holds this session's mailbox, and — only where this run
  * has just launched the session under it — the name it answers to.
@@ -361,15 +378,23 @@ async function bringUpSession(bots, home, live, session, bot, title) {
  * a restart (tech notes, section 1). Orca offers no way to delete one, so this
  * makes exactly one per session and never a second.
  *
+ * It is bound to `handle`, the session's own tab, and never to the tab this run
+ * of `obk up` was typed in: Orca tells a Run's coordinator about its mail, and
+ * only the session the mail is for should be told (issue #228). A mailbox the
+ * session already had is bound again when this run `opened` a new tab for it —
+ * after a restart, or a closed tab brought back — or it would stay with the tab
+ * that is gone (review of PR #248, finding 1).
+ *
  * A Codex session whose user turned the sandbox switch off gets none: it could
  * not read a mailbox if it had one, and an address nobody can read is worse
  * than none at all. `obk message` says so in those words.
  */
-async function ensureMailbox(home, bot, session, harness, { named = false } = {}) {
+async function ensureMailbox(home, bot, session, harness, handle, { named = false, opened = false } = {}) {
   const held = readBook(home).sessions[session.name] ?? {};
+  if (opened && typeof held.mailbox === 'string') useMailbox(held.mailbox, handle);
 
   const address = named ? addressOf(bot.name, session.name) : undefined;
-  const mailbox = mailboxFor(readBook(home), bot, session, harness);
+  const mailbox = mailboxFor(readBook(home), bot, session, harness, handle);
 
   if (mailbox === undefined && (address === undefined || held.address === address)) return;
 
@@ -392,10 +417,10 @@ async function ensureMailbox(home, bot, session, harness, { named = false } = {}
  * The Orca call is made outside the book's lock, which is held for one read and
  * one write (book.js).
  */
-function mailboxFor(book, bot, session, harness) {
+function mailboxFor(book, bot, session, harness, handle) {
   const held = book.sessions[session.name] ?? {};
   if (typeof held.mailbox === 'string' || !reachesMail(session, harness)) return undefined;
-  return makeMailbox(`${bot.name}/${session.name}`);
+  return makeMailbox(`${bot.name}/${session.name}`, handle);
 }
 
 /**
@@ -403,7 +428,7 @@ function mailboxFor(book, bot, session, harness) {
  * the one the book holds, one the harness itself still has on record, or none.
  *
  * One tab holds one session, and the book is the authority for which
- * conversation that is (ADR 0002). But the book can be incomplete — on Codex a
+ * conversation that is (ADR 0012). But the book can be incomplete — on Codex a
  * hooks file must be trusted before any hook runs, and trusting it does not
  * replay the event it missed — and "the book does not say" must never be read as
  * "there was no conversation". So where the book is silent about a tab the kit

package/src/usage.js

@@ -5,10 +5,10 @@
 // and efforts, between which two moments, and how many times it was compacted.
 // What any of that costs is a skill's to work out: a price comes from a live
 // lookup and a price that cannot be found has to be said to be unknown, which is
-// judgement and not arithmetic (ADR 0006).
+// judgement and not arithmetic (ADR 0016).
 //
 // Which conversation belongs to which session is the book's to say and is never
-// guessed, as everywhere else in the kit (ADR 0002). A session's conversations
+// guessed, as everywhere else in the kit (ADR 0012). A session's conversations
 // are the one the book names for it now and the ones in its history. One in the
 // bot's folder that no session claims is reported under the bot instead, with
 // its figures, so that what it spent is visible rather than quietly dropped.