@assuredloop/orca-bot-kit 0.5.0 → 0.5.1

package/README.md

@@ -350,6 +350,11 @@ conversation it was having, rather than starting a new one. Clear a session —
 keeps the old one, and gives the session its start prompt again, because that
 prompt is what tells one session's duty from another's.
 
+A session paused before its first turn can have an id in the book and no
+conversation behind it: the harness has nothing on record for that id. There is
+nothing to resume, so it starts again with its duty, and the book moves the id
+into its history as `no conversation`.
+
 One tab holds one session: the harness the kit started in it. Anything that
 session runs inside the tab — a `codex exec`, a helper, a subagent's own process
 — is not the session, and never becomes the conversation the kit brings back.

package/package.json

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

package/src/book.js

@@ -269,3 +269,13 @@ export function rememberSession(entry = {}, id, ended) {
   const was = { session: entry.session, ended: ended ?? 'replaced', at: new Date().toISOString() };
   return { ...entry, session: id, history: [...(entry.history ?? []), was] };
 }
+
+/**
+ * The session entry once the id it held has turned out to have no conversation
+ * behind it: the id goes into the history with that reason, and the entry holds
+ * none until the harness names the new one.
+ */
+export function forgetSession(entry, ended) {
+  const { session, ...rest } = entry;
+  return { ...rest, history: [...(entry.history ?? []), { session, ended, at: new Date().toISOString() }] };
+}

package/src/cli.js

@@ -892,9 +892,14 @@ function refuseWhenOrcaIsDown() {
 
 /** The same facts as `--json`, as lines, for a person reading along. */
 /** The one line that says which conversation this tab was given, and from where. */
-const howLine = (tab) => (tab.resumed === true
-  ? '             it was told to resume the session the book holds, with its conversation.'
-  : '             it was told to start a new session: the book holds none for this one yet.');
+const howLines = (tab) => {
+  if (tab.resumed === true) return ['             it was told to resume the session the book holds, with its conversation.'];
+  if (tab.noConversation === undefined) return ['             it was told to start a new session: the book holds none for this one yet.'];
+  return [
+    `             it was told to start a new session: the book's conversation ${tab.noConversation} had nothing on record`,
+    "             behind it, so it went into the session's history.",
+  ];
+};
 
 /**
  * What the harness still has in this bot's folder that no session claims. The
@@ -1205,7 +1210,7 @@ function harnessLines(tab, bots) {
   // What the line that was typed in asked for, and where the kit got it: the
   // session the book holds, one the harness itself still had on record, or a new
   // one — and if a new one, whether anything was known about an older one.
-  const how = [howLine(tab)];
+  const how = howLines(tab);
 
   if (!tab.harnessStarted) {
     return [

package/src/conversations.js

@@ -10,7 +10,7 @@
 // directory, and every session starts at its bot home. Read only, never
 // written: these are the harness's files (tech notes, sections 2 and 3).
 
-import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 
@@ -39,6 +39,20 @@ export function conversationsIn(harness, home, since) {
     .map((one) => ({ id: one.id, at: one.at }));
 }
 
+/**
+ * Whether the harness has a record of the conversation `id` for this bot home,
+ * which is what its own resume looks for. A session paused before its first
+ * turn has an id the hook reported and nothing written behind it, and Claude
+ * Code answers a resume of it with "No conversation found" (#295).
+ *
+ * Asked of the file names alone, which both harnesses make from the id: nothing
+ * is opened, however many conversations the machine has.
+ */
+export function hasConversation(harness, home, id) {
+  if (harness === 'claude') return existsSync(path.join(claudeDir(home), `${id}.jsonl`));
+  return rollouts(codexDir()).some((file) => path.basename(file).endsWith(`-${id}.jsonl`));
+}
+
 /**
  * The same conversations, each with the file the harness keeps it in, for a
  * caller that has to read what is inside one rather than only know it is there,

package/src/message.js

@@ -176,8 +176,8 @@ export function sendMessage(bots, { to: target, from: sender, tab, subject, text
  * Orca fences a Run to one reader, its coordinator. A session whose tab is live
  * is bound to that tab and read as it; one whose tab is down is read as its
  * Run's coordinator, and nothing is bound (issue #249). A read that
- * is not a peek acknowledges the batch it read: that is what makes the next
- * check bring the next one rather than the same again.
+ * is not a peek acknowledges every batch waiting, one after another, so one
+ * check hands over all of it (issue #299).
  */
 export function checkMail(bots, { bot: botName, session: sessionName, tab, peek = false }) {
   const who = sessionName === undefined && botName === undefined
@@ -212,9 +212,16 @@ export function checkMail(bots, { bot: botName, session: sessionName, tab, peek
       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.`,
     };
   }
-  const found = readMailbox(who.mailbox, { peek, handle });
-  const messages = (found.messages ?? []).map((message) => asMessage(bots, message));
-  if (!peek && found.deliveryId !== undefined && messages.length > 0) ackMailbox(who.mailbox, found.deliveryId, handle);
+  // 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).
+  const messages = [];
+  let found = readMailbox(who.mailbox, { peek, handle });
+  for (;;) {
+    messages.push(...(found.messages ?? []).map((message) => asMessage(bots, message)));
+    if (peek || !found.deliveryId || (found.messages ?? []).length === 0) break;
+    found = ackMailbox(who.mailbox, found.deliveryId, handle);
+  }
 
   return { bots, bot: who.bot, session: who.session, mailbox: who.mailbox, read: !peek, messages };
 }
@@ -335,7 +342,7 @@ function nudge(to, from, subject) {
   if (to.tab === undefined) return { nudged: false };
 
   try {
-    const found = tabToTypeInto(to.home, to.tab, LOOK_MS);
+    const found = lookAt(to);
     if (found.blocked !== undefined) return { nudged: false, blocked: found.blocked };
     // A line that lands in a shell is run there, with the sender's subject in it.
     if (found.unsure !== undefined) return { nudged: false, nudgeTrouble: found.unsure };
@@ -356,6 +363,21 @@ function nudge(to, from, subject) {
   }
 }
 
+/**
+ * The look before the nudge. Orca now and then refuses a handle it has just
+ * listed as stale, and a fresh listing hands out one that works (tech notes,
+ * section 1), so that refusal earns one more listing and one more look. Only
+ * one: a second refusal is reported as it is (#294).
+ */
+function lookAt(to) {
+  try {
+    return tabToTypeInto(to.home, to.tab, LOOK_MS);
+  } catch (error) {
+    if (error.code !== 'terminal_handle_stale') throw error;
+    return tabToTypeInto(to.home, to.tab, LOOK_MS);
+  }
+}
+
 /** `<bot>/<session>`, or a bot on its own when it has only the one session. */
 function splitTarget(target) {
   const parts = target.split('/');

package/src/orca.js

@@ -30,11 +30,17 @@ export function orca(args) {
   if (answer.ok !== true) {
     // Orca's own words: it knows what went wrong, and the caller is an LLM
     // that can act on them.
-    throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
+    throw refusal(args, answer);
   }
   return answer.result;
 }
 
+/** Orca's refusal as an error, with its code on it, so a caller can tell a stale handle from the rest (#294). */
+const refusal = (args, answer) => Object.assign(
+  new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`),
+  { code: answer.error?.code },
+);
+
 /** One Orca command, and the whole envelope back, refusals included. */
 function ask(args) {
   const asked = spawnSync(orcaCli(), [...args, '--json'], { encoding: 'utf8' });
@@ -257,7 +263,7 @@ export function harnessInTab(handle, timeoutMs) {
   // Out of time means nothing went idle, busy or absent alike. That is an
   // answer, not a breakdown.
   if (answer.ok !== true && answer.error?.code !== 'timeout') {
-    throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
+    throw refusal(args, answer);
   }
 
   const shown = orca(['terminal', 'show', '--terminal', handle]).terminal;
@@ -461,7 +467,7 @@ export function postMessage({ to, from, subject, body, type = 'status', thread }
 export const readMailbox = (id, { peek = false, handle } = {}) =>
   orca(['orchestration', 'check', '--run', id, ...as(handle), ...(peek ? ['--peek'] : [])]);
 
-/** Say a batch has been read, so the next check brings the one after it. */
+/** Say a batch has been read. Orca answers with the batch after it. */
 export const ackMailbox = (id, delivery, handle) =>
   orca(['orchestration', 'check', '--run', id, ...as(handle), '--ack', delivery]);
 

package/src/up.js

@@ -8,9 +8,9 @@ import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { setTimeout as pause } from 'node:timers/promises';
 
-import { forgetClaimed, readBook, sessionIdsIn, tabIdsIn, updateBook, withUnclaimed } from './book.js';
+import { forgetClaimed, forgetSession, readBook, sessionIdsIn, tabIdsIn, updateBook, withUnclaimed } from './book.js';
 import { botDir, botNames, displayName, readBot } from './bot.js';
-import { conversationsIn, heldAsUserTurn, transcriptsIn } from './conversations.js';
+import { conversationsIn, hasConversation, heldAsUserTurn, transcriptsIn } from './conversations.js';
 import { installHook } from './hooks.js';
 import { addressOf, harnessOf, isShortPrompt, launchCommand, reachesMail, sessionTrouble, startPrompt, workDirOf } from './launch.js';
 import { asFolderProject, findProject, harnessInTab, makeMailbox, makeProject, openTab, retitleTab, tabs, tellWindow, typeIntoTab, useMailbox } from './orca.js';
@@ -263,33 +263,14 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // given again (PRD 6.4) — after a clear it is, and that is the hook's work.
   // Asked before the book is held, because it reads a folder of the harness's
   // own files: nothing slow happens under the lock.
-  const which = whichConversation(book, home, bot, session, was, harness);
-  const resume = which.resume;
-  const prompt = resume === undefined ? startPrompt(session, { home, workDir }) : undefined;
-  // Anything longer than a line goes to the harness out of a file, rather than
-  // through the tab's shell a character at a time.
-  const promptFile = prompt === undefined || isShortPrompt(prompt) ? undefined : promptPath(bots, bot.name, session.name);
-  const command = launchCommand(session, {
-    harness,
-    home,
-    workDir,
-    prompt,
-    promptFile,
-    resume,
-    address: harness === 'claude' ? addressOf(bot.name, session.name) : undefined,
-  });
+  let which = whichConversation(book, home, bot, session, was, harness);
+  const launchOf = (chosen) => launchFor(bots, bot, session, harness, home, workDir, chosen.resume);
+  let launch = launchOf(which);
 
   // A work dir is a plain folder, made for the session before it is told about
   // it (PRD 6.4). Nothing here is a git worktree.
   if (workDir !== undefined) mkdirSync(workDir, { recursive: true });
-
-  // The prompt is written where the launch line can read it from, before that
-  // line is typed. It is the kit's own file, not the user's: theirs stays where
-  // they put it, in the bot home.
-  if (promptFile !== undefined) {
-    mkdirSync(path.dirname(promptFile), { recursive: true });
-    writeFileSync(promptFile, prompt);
-  }
+  writePrompt(launch);
 
   const made = openTab(home, tabTitle);
 
@@ -305,20 +286,41 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // built, noted so that health can say when the file moves on and the session
   // does not (#272).
   const rules = rulesStamp(home);
+  let held;
   await updateBook(home, (current) => {
     // What the harness has in this folder that nobody claims goes on the record,
     // for a person or Bot Father to settle — added to whatever was already noted,
     // because this run's scan cannot see what an earlier one found. The kit never
     // settles it itself.
-    const entry = { ...current.sessions[session.name], tab: made.tabId, launched, rules };
+    let entry = { ...current.sessions[session.name], tab: made.tabId, launched, rules };
     if (rules === undefined) delete entry.rules;
+    held = entry.session;
+    // Before the line is typed, so the hook finds no id here and takes the one
+    // it reports for a start rather than a clear, which would tell the duty twice.
+    if (which.noConversation !== undefined && held === which.noConversation) entry = forgetSession(entry, 'no conversation');
     current.sessions[session.name] = withUnclaimed(entry, which.unclaimed ?? []);
     forgetClaimed(current);
   });
 
+  // The old tab's hook can name another conversation while the tab is being
+  // opened. A fresh start chosen before that is chosen again from the id the
+  // book holds now: resumed if the harness has it, and otherwise set aside the
+  // same way (review of PR #310).
+  if (which.noConversation !== undefined && typeof held === 'string' && held !== which.noConversation) {
+    which = hasConversation(harness, home, held) ? { resume: held } : { noConversation: held };
+    if (which.noConversation !== undefined) {
+      await updateBook(home, (current) => {
+        const entry = current.sessions[session.name];
+        if (entry?.session === held) current.sessions[session.name] = forgetSession(entry, 'no conversation');
+      });
+    }
+    launch = launchOf(which);
+    writePrompt(launch);
+  }
+
   // Typing it in is the way: for a project the kit has just made, giving Orca
   // the harness as the tab's own command times out and leaves a dead tab.
-  typeIntoTab(made.handle, command);
+  typeIntoTab(made.handle, launch.command);
 
   // Now the session has an address, and not before: the mailbox it can be
   // written to, and — on Claude Code — the name that line just gave it, which
@@ -344,9 +346,9 @@ async function bringUpSession(bots, home, live, session, bot, title) {
   // duty: one held on a first-run screen, or one that refused the argument, has
   // been told nothing. So it is received only when the session's own record
   // holds it as a user turn, and otherwise not confirmed (#274).
-  const promptReceived = prompt === undefined
+  const promptReceived = launch.prompt === undefined
     ? undefined
-    : await heldInRecord(home, session.name, harness, prompt, { launched, running: tui.running === true });
+    : await heldInRecord(home, session.name, harness, launch.prompt, { launched, running: tui.running === true });
 
   return entry(made, {
     bot: bot.name,
@@ -354,12 +356,45 @@ async function bringUpSession(bots, home, live, session, bot, title) {
     created: true,
     ...tui,
     promptReceived,
-    promptFile,
-    resumed: resume !== undefined,
+    promptFile: launch.promptFile,
+    resumed: launch.resume !== undefined,
+    noConversation: which.noConversation,
     unclaimed: which.unclaimed,
   });
 }
 
+/**
+ * The line that starts this session: resuming `resume`, or, with none, a fresh
+ * start carrying its duty. Returns `{ resume, prompt, promptFile, command }`.
+ */
+function launchFor(bots, bot, session, harness, home, workDir, resume) {
+  const prompt = resume === undefined ? startPrompt(session, { home, workDir }) : undefined;
+  // Anything longer than a line goes to the harness out of a file, rather than
+  // through the tab's shell a character at a time.
+  const promptFile = prompt === undefined || isShortPrompt(prompt) ? undefined : promptPath(bots, bot.name, session.name);
+  const command = launchCommand(session, {
+    harness,
+    home,
+    workDir,
+    prompt,
+    promptFile,
+    resume,
+    address: harness === 'claude' ? addressOf(bot.name, session.name) : undefined,
+  });
+  return { resume, prompt, promptFile, command };
+}
+
+/**
+ * The prompt is written where the launch line can read it from, before that
+ * line is typed. It is the kit's own file, not the user's: theirs stays where
+ * they put it, in the bot home.
+ */
+function writePrompt({ prompt, promptFile }) {
+  if (promptFile === undefined) return;
+  mkdirSync(path.dirname(promptFile), { recursive: true });
+  writeFileSync(promptFile, prompt);
+}
+
 /**
  * How long a running harness's own record is given to show the start prompt.
  * Seen live (Claude Code 2.1.282, a trusted folder): the hook's id and the
@@ -479,7 +514,14 @@ function mailboxFor(book, bot, session, harness, handle) {
  * has already started a harness in, the harness's own record is asked.
  */
 function whichConversation(book, home, bot, session, was, harness) {
-  if (typeof was?.session === 'string') return { resume: was.session };
+  if (typeof was?.session === 'string') {
+    if (hasConversation(harness, home, was.session)) return { resume: was.session };
+    // The hook reported an id and the harness never wrote a conversation behind
+    // it: a session paused before its first turn is one. There is nothing to
+    // resume, so it starts again with its duty, and the book keeps the id in the
+    // history with the reason (#295).
+    return { noConversation: was.session };
+  }
   // No tab: nothing has ever run for this session, so there is nothing to find.
   if (typeof was?.tab !== 'string') return {};
 
@@ -526,11 +568,13 @@ const ids = (setup, change) => ({ project: setup.projectId, setup: setup.id, cha
 export const promptPath = (bots, bot, session) =>
   path.join(`${bots}.prompts`, `${encodeURIComponent(bot)}.${encodeURIComponent(session)}.txt`);
 
-function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, unclaimed }) {
+function entry(tab, { bot, name, created, running = false, blockedReason, promptReceived, promptFile, resumed, noConversation, unclaimed }) {
   const made = { bot, name, title: tab.title, tabId: tab.tabId, terminal: tab.handle, created, harnessStarted: running };
   // Whether this run picked the session up where it was or started a new one.
   // Only for a tab this run opened: a tab that was already there was left alone.
   if (resumed !== undefined) made.resumed = resumed;
+  // The id the book held that had no conversation behind it, now in the history.
+  if (noConversation !== undefined) made.noConversation = noConversation;
   // Orca's own words for what is on screen waiting to be answered, when it
   // gave any: the caller acts on it, the kit only passes it on.
   if (blockedReason !== undefined) made.blockedReason = blockedReason;