@assuredloop/orca-bot-kit 0.1.0 → 0.2.0

package/src/orca.js

@@ -0,0 +1,291 @@
+// Every call the kit makes to Orca goes through here (ADR 0001). Orca's CLI
+// changes often, so the kit reads `--json` and never the human text, and keeps
+// the parsing in one place.
+//
+// A word on words: Orca calls every workspace a "worktree", a plain folder
+// included. Nothing the user reads may say that, or they will think a git
+// worktree was made. Say "Orca project". The word belongs only in the selector
+// handed to Orca on the command line.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+// The Orca that works for a normal user: `/usr/local/bin/orca` is a root-only
+// symlink on this machine (tech notes, section 1). OBK_ORCA overrides it, for a
+// machine that keeps Orca somewhere else.
+const BUILT_IN = '/Applications/Orca.app/Contents/Resources/bin/orca';
+
+/** The Orca CLI this run talks to. */
+export const orcaCli = () => process.env.OBK_ORCA || BUILT_IN;
+
+/**
+ * Run one Orca command and give back its `result`.
+ * Every call asks for `--json`; anything else would be text to guess at.
+ */
+export function orca(args) {
+  const answer = ask(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'}`);
+  }
+  return answer.result;
+}
+
+/** One Orca command, and the whole envelope back, refusals included. */
+function ask(args) {
+  const asked = spawnSync(orcaCli(), [...args, '--json'], { encoding: 'utf8' });
+  if (asked.error) {
+    throw new Error(`could not run Orca at ${orcaCli()}: ${asked.error.message}`);
+  }
+
+  const answer = parse(asked.stdout);
+  if (answer === null || typeof answer !== 'object') {
+    throw new Error(`Orca answered ${args.join(' ')} with something that is not JSON.`);
+  }
+  return answer;
+}
+
+function parse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * What is wrong with Orca, or undefined when nothing is: it is up and its
+ * runtime is reachable, the only state in which any of the calls below mean
+ * anything. Asking is cheap, and asking first is what turns "Orca refused
+ * terminal create" into a sentence the caller can act on.
+ */
+export function orcaTrouble() {
+  const where = `Start Orca and run the command again, or point OBK_ORCA at its CLI if it lives somewhere else.`;
+
+  const asked = spawnSync(orcaCli(), ['status', '--json'], { encoding: 'utf8' });
+  if (asked.error) return `could not run Orca at ${orcaCli()}: ${asked.error.message}. ${where}`;
+
+  const answer = parse(asked.stdout);
+  // Orca knowing what is wrong beats the kit guessing, so its own words go
+  // first when it gave any.
+  if (answer !== null && typeof answer === 'object' && answer.ok !== true && answer.error?.message) {
+    return `Orca is not ready: ${answer.error.message}. ${where}`;
+  }
+  // `null` is valid JSON with nothing to say, and so is anything else that
+  // does not carry a runtime calling itself reachable.
+  if (answer?.ok === true && answer.result?.runtime?.reachable === true) return undefined;
+
+  return `Orca is not answering at ${orcaCli()}. ${where}`;
+}
+
+/** Every workspace Orca has a record of, folder and git alike. */
+export const projects = () => orca(['project', 'setups']).setups;
+
+/** Orca's record of the folder at `home`, or undefined when it knows none. */
+export function findProject(home) {
+  return projects().find((setup) => setup.path === home);
+}
+
+/** Where Orca keeps its own settings: one file per profile, under the user's home. */
+export const profilesDir = () => path.join(homedir(), 'Library', 'Application Support', 'orca', 'profiles');
+
+/**
+ * Orca's own default launch arguments, per profile it keeps:
+ * `{ dir, profiles: [{ file, args }] }`, where `args` maps an agent name to the
+ * arguments Orca adds to it, and is undefined for a file that cannot be read.
+ *
+ * Orca adds these to the agents it launches, relaunches and resumes itself, so
+ * they override the approval level a session was started with (PRD 6.5). The
+ * kit reads the file and never writes it.
+ *
+ * A mapping with no entry for an agent is not "no arguments": Orca falls back
+ * to its own built-in default, which is the permission bypass itself (tech
+ * notes, section 1). So the caller reads a missing entry as one.
+ */
+export function orcaDefaultArgs() {
+  const dir = profilesDir();
+
+  let profiles;
+  try {
+    profiles = readdirSync(dir);
+  } catch {
+    return { dir, profiles: [] };
+  }
+
+  return {
+    dir,
+    profiles: profiles
+      .map((name) => path.join(dir, name, 'orca-data.json'))
+      .filter((file) => existsSync(file))
+      .map((file) => ({ file, args: argsIn(file) })),
+  };
+}
+
+/** What one profile file says about the agents' default arguments. */
+function argsIn(file) {
+  try {
+    const settings = JSON.parse(readFileSync(file, 'utf8'))?.settings?.agentDefaultArgs;
+    // Anything that is not a mapping of agents is a mapping with nothing in it,
+    // which is Orca falling back to its own defaults for every agent.
+    return settings !== null && typeof settings === 'object' && !Array.isArray(settings) ? settings : {};
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Register the folder at `home` and make it a folder workspace called `title`.
+ *
+ * Two calls, and both are needed: `repo add` registers a folder inside the bots
+ * repo as git kind, which Orca gives no workspace at all, so no tab can be
+ * created in it. `setup-update` turns it into the folder workspace a bot needs
+ * and names the project in one go.
+ */
+export function makeProject(home, title) {
+  const setupId = orca(['repo', 'add', '--path', home]).repo.id;
+  return asFolderProject(setupId, title);
+}
+
+/** Make an existing registration a folder workspace called `title`. */
+export function asFolderProject(setupId, title) {
+  return orca(['project', 'setup-update', '--setup', setupId, '--kind', 'folder', '--display-name', title])
+    .result.setup;
+}
+
+/**
+ * Take a bot's Orca project away: the setup, the project and the repo record,
+ * in one call (tech notes, section 1). Only after its tabs are closed: a
+ * project taken away first leaves tabs no command line can reach.
+ */
+export const deleteProject = (setupId) => orca(['project', 'setup-delete', '--setup', setupId]);
+
+/**
+ * The live tabs of the Orca project at `home`, each under its own tab id.
+ *
+ * The listing gives a tab whose pane the window has not loaded as orphaned,
+ * under `pty:<ptyId>` rather than its id, and a running harness puts a tab the
+ * kit opened in that state within seconds. `terminal show` still answers with
+ * the real id, so an orphaned entry is given that one: the tab id is the key
+ * (PRD 6.2), and this is where Orca is asked for it (tech notes, section 1).
+ */
+export const tabs = (home) => orca(['terminal', 'list', '--worktree', `path:${home}`]).terminals
+  .map((tab) => (tab.orphaned === true
+    ? { ...tab, tabId: orca(['terminal', 'show', '--terminal', tab.handle]).terminal.tabId }
+    : tab));
+
+/**
+ * Open a tab in the Orca project at `home`, titled `title`.
+ *
+ * No `--command`: for a project the kit has just made, `--command` with a
+ * harness times out and leaves a tab that never goes live (tech notes). The
+ * launch command is typed in afterwards. No `--focus` either: the user is
+ * working, and the kit does not take his screen.
+ */
+export const openTab = (home, title) =>
+  orca(['terminal', 'create', '--worktree', `path:${home}`, '--title', title]).terminal;
+
+/** Set a tab's title. The kit sets titles; it never reads them. */
+export const retitleTab = (handle, title) =>
+  orca(['terminal', 'rename', '--terminal', handle, '--title', title]).rename;
+
+/**
+ * Whether a TUI is running in the tab, and what it is waiting on if Orca says.
+ *
+ * `tui-idle` asks about a TUI, not about a shell: a tab sitting at a shell
+ * prompt is refused with `timeout` however long you wait, a TUI that is up
+ * answers `ok:true`, and `satisfied` only tells idle from busy. So this is the
+ * way to learn whether a harness actually started — and `blockedReason` is
+ * Orca saying something on screen wants answering, which is for the caller to
+ * deal with, not the kit.
+ */
+export function tuiInTab(handle, timeoutMs) {
+  const args = ['terminal', 'wait', '--terminal', handle, '--for', 'tui-idle', '--timeout-ms', String(timeoutMs)];
+  const answer = ask(args);
+
+  if (answer.ok !== true) {
+    // Out of time means no TUI came up. That is an answer, not a breakdown.
+    if (answer.error?.code === 'timeout') return { running: false };
+    throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
+  }
+  return { running: true, blockedReason: answer.result?.wait?.blockedReason };
+}
+
+/**
+ * Close one tab, by the handle Orca issued for it.
+ *
+ * The only place in the kit that takes anything away, and it takes away one
+ * tab: `--terminal <handle> --tab`. Orca's other form, `--worktree <sel> --all`,
+ * closes every tab of a project with its layouts and resume records, which are
+ * the user's work and not the kit's to end (tech notes, section 1).
+ */
+export const closeTab = (handle) =>
+  orca(['terminal', 'close', '--terminal', handle, '--tab']).close;
+
+/**
+ * Type `text` into a tab and press return.
+ *
+ * Orca sometimes gates a line going into a tab that has an agent in it and
+ * answers `agent_prompt_blocked`, carrying a request id and telling the caller
+ * to re-issue the exact command with that id and a time to wait for the line to
+ * be submitted — and not to retry without it. So that is what this does, once.
+ * Seen live on 2026-09-21 in a system test run; not reproduced since, including
+ * from a plain shell, long lines and lines sent while the agent was working.
+ *
+ * The wait is short because the caller is telling a session it has mail, not
+ * handing it work: mail that has to wait for the next check is a smaller cost
+ * than a command that hangs for half a minute.
+ */
+export function typeIntoTab(handle, text) {
+  const args = ['terminal', 'send', '--terminal', handle, '--text', text, '--enter'];
+  const answer = ask(args);
+  if (answer.ok === true) return answer.result.send;
+
+  const again = answer.error?.data?.orchestrationRequestId;
+  if (answer.error?.code !== 'agent_prompt_blocked' || typeof again !== 'string') {
+    throw new Error(`Orca refused ${args.join(' ')}: ${answer.error?.message ?? 'no reason given'}`);
+  }
+  return orca([...args, '--retry-request', again, '--wait-submit', String(SUBMIT_WAIT_S)]).send;
+}
+
+/** How long a re-issued line is given to be submitted before Orca gives up on it. */
+const SUBMIT_WAIT_S = 5;
+
+/**
+ * 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
+ * person sees in `orca orchestration run-list`, so it says whose it is.
+ */
+export const makeMailbox = (objective) =>
+  orca(['orchestration', 'run-create', '--objective', `obk ${objective}`]).run.id;
+
+/**
+ * Take this process's turn at reading a mailbox.
+ *
+ * Orca fences a Run to one reader: a `check` from a caller bound elsewhere is
+ * refused with `consumer_fenced`, whatever the Run says. So a read binds first,
+ * every time — the kit's runs are short and the binding is the last one to have
+ * asked, not a lease anybody has to give back.
+ */
+export const useMailbox = (id) => orca(['orchestration', 'run-use', '--id', id]).run;
+
+/** Queue one message. `to` and `from` are mailboxes, written `run:<id>`. */
+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;
+}
+
+/**
+ * What is waiting in a mailbox: the oldest batch that has not been
+ * acknowledged, or, peeking, whatever is unread without touching it.
+ */
+export const readMailbox = (id, { peek = false } = {}) =>
+  orca(['orchestration', 'check', '--run', id, ...(peek ? ['--peek'] : [])]);
+
+/** Say a batch has been read, so the next check brings the one after it. */
+export const ackMailbox = (id, delivery) =>
+  orca(['orchestration', 'check', '--run', id, '--ack', delivery]);

package/src/pause.js

@@ -0,0 +1,58 @@
+// `obk pause` and `obk unpause`: stop a bot, or one of its sessions, for now,
+// and bring it back as it was.
+//
+// A pause is a mark in the bot's `bot.yaml` and the bot's tabs closed. The
+// mark is what `up` reads to leave it closed, and the book keeps the
+// conversation each session was in, so an unpause is the mark taken off and
+// the ordinary `up`, which resumes it (ADR 0002).
+//
+// The closing is restart's, with restart's rules: only the tabs the book names,
+// one at a time by their own handles, and none at all when one of them holds a
+// conversation the book could not name again.
+
+import { realpathSync } from 'node:fs';
+
+import { botDir, markPaused, readBot } from './bot.js';
+import { closeTabs, tabsToClose } from './restart.js';
+import { BOT_FATHER, botsNamed, bringUp, sessionsOf } from './up.js';
+
+/**
+ * Pause the bot `bot`, or its session `session`. Returns
+ * `{ bot, session, changed, closed }`: whether the mark was new, and one entry
+ * per tab it closed.
+ */
+export async function pauseSessions(bots, { bot, session }) {
+  const home = fleetMember(bots, bot, 'pause');
+  const sessions = sessionsOf(readBot(home, bot), session);
+
+  // Judged before anything is written or closed, so a refusal leaves both as
+  // they were.
+  const going = tabsToClose(bots, bot, home, sessions);
+  const changed = markPaused(bots, bot, session, true);
+  const closed = await closeTabs(home, going, bots, bot);
+  return { bot, session, changed, closed };
+}
+
+/**
+ * Take the pause off the bot `bot`, or its session `session`, and bring it up.
+ * Returns `{ bot, session, changed, ...what up answered }`.
+ */
+export async function unpauseSessions(bots, { bot, session }) {
+  const home = fleetMember(bots, bot, 'unpause');
+  sessionsOf(readBot(home, bot), session);
+
+  const changed = markPaused(bots, bot, session, false);
+  return { bot, session, changed, ...(await bringUp(bots, { bot, session })) };
+}
+
+/**
+ * The bot's home, once it is certain the bot is there and is not Bot Father,
+ * which runs the fleet and is the one the user asks to bring anything back.
+ */
+export function fleetMember(bots, bot, verb) {
+  if (bot === BOT_FATHER) {
+    throw new Error(`${BOT_FATHER} runs the fleet, and the kit does not ${verb} it: it is where you ask for everything else.`);
+  }
+  botsNamed(bots, bot);
+  return realpathSync(botDir(bots, bot));
+}

package/src/record.js

@@ -0,0 +1,209 @@
+// What a harness says when a session starts, and what the kit does with it.
+//
+// Both harnesses run the kit's hook (src/hooks.js) and hand it the session id
+// they are running under. That is how the book stays the authority for session
+// ids (ADR 0002) without the kit guessing from transcripts.
+//
+// Which session it is comes from the tab: Orca puts the tab id in the
+// environment of everything running in it, and the book says which session owns
+// which tab. Sessions of one bot share a folder, so the folder alone could not
+// tell them apart — the tab can.
+
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { forgetClaimed, readBook, rememberSession, sessionIdsIn, updateBook, withUnclaimed } from './book.js';
+import { botDir, readBot } from './bot.js';
+import { conversationsIn } from './conversations.js';
+import { harnessOf, SHELL_ENV, startPrompt, workDirOf } from './launch.js';
+
+/** Where Orca says which tab a program is running in (tech notes, section 1). */
+export const TAB_ENV = 'ORCA_TAB_ID';
+
+/**
+ * The launch line says which shell it ran in, and that is what tells a report
+ * from the session itself from a report by something the session started: a tab
+ * holds one session — the harness the kit typed in, the shell's own child — and
+ * everything started inside the tab inherits the tab's id without being it.
+ */
+export { SHELL_ENV };
+
+/** What a harness calls a session the user cleared, when it has a word for it. */
+const CLEARED = 'clear';
+
+/**
+ * Write down the session a harness reports, and answer with what the harness is
+ * to read back, or undefined when there is nothing to say to it.
+ *
+ * A cleared session is told its duty again, because the start prompt is the
+ * only thing that tells one session of a bot from another (PRD 6.4). A session
+ * that started or resumed has already been told, on the line that launched it.
+ *
+ * Two things say a session was cleared, and either is enough.
+ *
+ * The harness's own word, when it has one: Claude Code calls a `/clear` a clear.
+ * Codex has none to give — it calls its `/new` a startup (proved live, tech
+ * notes section 3) — so the second is the book: an id that is not the one this
+ * tab had is a conversation the kit did not start, and the only thing that
+ * starts one without the kit is the user beginning a new one.
+ *
+ * Neither can hand the duty over twice. `up` puts it on the launch line only
+ * when the book holds no id for the session, so a session with an id in the
+ * book was told nothing by the line that started it; and a launch is never a
+ * clear.
+ *
+ * Nothing here knows about Orca beyond the tab id it is handed: the hook runs
+ * inside the user's session, and a session is not a place to make calls from.
+ */
+export async function recordSession(bots, name, said, tabId, shellPid) {
+  // Without the tab there is no telling which session this is, and a guess
+  // would be the one thing this slice must never do.
+  if (typeof tabId !== 'string' || tabId === '') return undefined;
+
+  const id = said?.session_id;
+  if (typeof id !== 'string' || id === '') return undefined;
+
+  const home = realpathSync(botDir(bots, name));
+  // A tab no session of this bot owns: Bot Father's ops tab, or somebody else's
+  // work. The kit writes nothing down about tabs it does not keep.
+  if (sessionAt(readBook(home), tabId) === undefined) return undefined;
+
+  // And a report from something the session started rather than from the
+  // session itself is not this session's news, whatever tab it ran in.
+  if (!startedTheSession(shellPid)) return undefined;
+
+  const bot = readBot(home, name);
+  // Asking the harness what it has on record reads a folder of files, so it is
+  // done before the lock is taken and never while it is held. It answers about
+  // this bot's folder, which every session of the bot shares — so it can say
+  // that a conversation nobody claims exists, and never whose it is.
+  const unclaimed = unclaimedFor(readBook(home), home, bot, tabId, id);
+
+  let cleared = false;
+  let told;
+
+  await updateBook(home, (book) => {
+    const found = sessionAt(book, tabId);
+    // The book is read again under the lock, so a session that went away while
+    // this waited is a session this no longer has anything to say about.
+    if (found === undefined) return book;
+
+    const [session, was] = found;
+    // The harness's own word for it, or — for the harness that has no word — an
+    // id that is not the one this tab had, which is the same thing said twice.
+    cleared = said.source === CLEARED || (was.session !== undefined && was.session !== id);
+    // A first report with something unclaimed beside it is the third case: the
+    // kit cannot tell whether this conversation is the one the launch line spoke
+    // to or a later one, and a session left without its duty is the failure this
+    // slice exists to prevent, so it is told again.
+    const uncertain = was.session === undefined && unclaimed.length > 0;
+    told = session;
+
+    book.sessions[session] = withUnclaimed(rememberSession(was, id, said.source), unclaimed);
+    forgetClaimed(book);
+    if (uncertain) cleared = true;
+    return book;
+  });
+
+  if (!cleared || told === undefined) return undefined;
+
+  const settings = bot.sessions.find((entry) => entry.name === told);
+  if (settings === undefined) return undefined;
+
+  const duty = startPrompt(settings, { home, workDir: workDirOf(settings, home) });
+  if (duty === undefined) return undefined;
+
+  // The harness's own way of putting text into a session, answered on the event
+  // it asked about: what it reads back is added to what the session knows.
+  return { hookSpecificOutput: { hookEventName: said.hook_event_name, additionalContext: duty } };
+}
+
+/** The session of this bot that owns `tabId`, with what the book holds for it. */
+const sessionAt = (book, tabId) =>
+  Object.entries(book.sessions).find(([, entry]) => entry?.tab === tabId);
+
+/**
+ * The conversations of this bot home that nobody claims, for the session that
+ * owns `tabId`: started since the kit put a harness in that tab, not the one
+ * reporting now, and not a conversation any session of the bot holds or has
+ * held.
+ *
+ * It says that such a conversation exists. It never says whose it is, and the
+ * kit never decides: a bot's sessions share one folder, and so does every
+ * harness they start inside themselves, so the folder cannot tell them apart and
+ * the time they started cannot either. The review proved both — a `codex exec`
+ * child's conversation taken for its parent's, and two sessions reporting in
+ * reverse order taking each other's.
+ *
+ * Nothing either harness writes down ties a conversation that has already ended
+ * to the process that had it: Claude Code's registry maps a live pid to the
+ * conversation it is having now and keeps no earlier one, and Codex records no
+ * pid at all (tech notes, sections 2 and 3). So this is as far as evidence goes,
+ * and the rest is for a person or Bot Father to settle.
+ */
+function unclaimedFor(book, home, bot, tabId, id) {
+  const found = sessionAt(book, tabId);
+  if (found === undefined) return [];
+
+  const [session, was] = found;
+  if (typeof was.launched !== 'string') return [];
+
+  const settings = bot.sessions.find((entry) => entry.name === session);
+  if (settings === undefined) return [];
+
+  const claimed = sessionIdsIn(book);
+  return conversationsIn(harnessOf(settings, bot.harness), home, was.launched)
+    .filter((one) => one.id !== id && !claimed.has(one.id))
+    .map((one) => one.id);
+}
+
+/**
+ * Whether the harness that ran this hook is the session's own — the one the kit
+ * typed into the tab — rather than a harness started inside the session.
+ *
+ * Proved live on both harnesses (tech notes, sections 2 and 3): a hook's process
+ * is the harness's own child, or the child of the shell the harness ran the hook
+ * command through. Either way the harness itself is the process just above, and
+ * the session's harness is the child of the shell named in the launch line. A
+ * harness started inside the session sits further down a longer chain, under
+ * whatever shell the agent ran it from, so it can never answer this.
+ *
+ * Anything it cannot establish is a no: a report that cannot be shown to be the
+ * session's own is not written down.
+ */
+export function startedTheSession(shellPid, pid = process.pid) {
+  if (!/^[0-9]+$/.test(String(shellPid ?? ''))) return false;
+  const shell = Number(shellPid);
+
+  const tree = processTree();
+  if (tree === undefined) return false;
+
+  const mine = tree.get(pid);
+  const parent = mine === undefined ? undefined : tree.get(mine.ppid);
+  if (parent === undefined) return false;
+
+  if (parent.ppid === shell) return true;
+  if (!isShell(parent.command)) return false;
+
+  const above = tree.get(parent.ppid);
+  return above !== undefined && above.ppid === shell;
+}
+
+/** Every process on the machine, by pid: who its parent is and what it runs. */
+function processTree() {
+  const listed = spawnSync('ps', ['-Ao', 'pid=,ppid=,comm='], { encoding: 'utf8' });
+  if (listed.error !== undefined || listed.status !== 0) return undefined;
+
+  const tree = new Map();
+  for (const line of listed.stdout.split('\n')) {
+    const said = line.trim().match(/^([0-9]+)\s+([0-9]+)\s+(.*)$/);
+    if (said !== null) tree.set(Number(said[1]), { ppid: Number(said[2]), command: said[3] });
+  }
+  return tree.size === 0 ? undefined : tree;
+}
+
+/** The shells a harness may run a hook command through. */
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh']);
+
+const isShell = (command) => SHELLS.has(path.basename(command ?? ''));