@assuredloop/orca-bot-kit 0.22.0 → 0.24.1

package/README.md

@@ -10,7 +10,7 @@ an `obk` command and a set of skills. You are meant to manage the fleet by
 talking to Bot Father, the first bot, whose skills call the CLI for you — not by
 editing files.
 
-The design is in [`docs/prd.md`](docs/prd.md); the decisions with lasting
+The design is in [`docs/prd/prd.md`](docs/prd/prd.md); the decisions with lasting
 consequences are in [`docs/adr/`](docs/adr/); what we know about Orca and the
 two harnesses is in [`docs/tech-notes.md`](docs/tech-notes.md).
 
@@ -364,6 +364,22 @@ 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.
 
+Ask the kit to clear or compact a session, rather than typing into its tab:
+
+```sh
+obk session clear   --bots /path/to/my-bots --bot api-bot --session daily
+obk session compact --bots /path/to/my-bots --bot api-bot --session daily
+```
+
+Each waits up to 30 s for the session to be idle, and types nothing into one
+that is busy or has a question on its screen. It types the harness's own
+command, checks the screen before it presses return, and then confirms the
+result: for a clear, the new conversation in the book; for a compact, the
+compaction in the harness's own record, within 5 minutes, or it says it is not
+confirmed yet. A harness that does not offer `/compact` is told so, and nothing
+is entered. A cleared session reads its `AGENTS.md` again, so a clear also
+brings it onto changed rules.
+
 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
@@ -649,7 +665,7 @@ editor's runner, skips and says how to run it.
 JavaScript this branch changed against `main` — committed, still in the working
 tree, or not tracked yet — and reports the mutants the tests do not kill. It is
 an audit, not a step of every pull request
-([PRD 7.3](docs/prd.md#73-decided-rules-inside-the-skills)): the everyday
+([PRD 7.3](docs/prd/prd.md#prd-21-73-decided-rules-inside-the-skills)): the everyday
 check is the implementer's own hand check, and the tool runs over the whole
 suite at a milestone or when the owner asks, or once, narrowed to the changed
 logic, for a change at the core of the kit. A surviving mutant is a change to

package/package.json

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

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

@@ -368,8 +368,9 @@ already up even when a skill change would, and a session's model, effort or
 approval only changes when it is started again (`obk restart`, on the user's
 word, and then read its tabs as above). Say which you changed, and what that
 means for the sessions running now. `obk health` names each running session
-still on the older rules or on other settings, and what brings it up to date: on
-Claude Code a `/clear` reads the rules again, and a start does on both harnesses.
+still on the older rules or on other settings, and what brings it up to date: a
+clear reads the rules again (`obk session clear`), and so does a start, on both
+harnesses.
 Where everything needs restarting, remind
 them to do it from Bot Father's ops tab.
 

package/src/book.js

@@ -152,8 +152,13 @@ function takeLock(home) {
   }
 }
 
-/** The lock on `file`, waited for `waitMs` at most: see `takeLock` for why it is this one. */
-function lockOn(file, waitMs) {
+/**
+ * The lock on `file`, waited for `waitMs` at most: see `takeLock` for why it is
+ * this one. `how` is SQLite's: `IMMEDIATE`, one holder at a time; `SHARED`,
+ * any number at once, none while an `EXCLUSIVE` is held or waited for; and
+ * `EXCLUSIVE`, alone, once every `SHARED` holder has let go.
+ */
+function lockOn(file, waitMs, how = 'IMMEDIATE') {
   mkdirSync(path.dirname(file), { recursive: true });
 
   const db = new DatabaseSync(file);
@@ -161,7 +166,13 @@ function lockOn(file, waitMs) {
     // A writer that arrives while another is working waits for it rather than
     // failing at once, and gives up saying so rather than waiting for ever.
     db.exec(`PRAGMA busy_timeout = ${waitMs}`);
-    db.exec('BEGIN IMMEDIATE');
+    if (how === 'SHARED') {
+      // A reading transaction holds its shared lock from its first read.
+      db.exec('BEGIN');
+      db.prepare('SELECT count(*) FROM sqlite_master').get();
+    } else {
+      db.exec(`BEGIN ${how}`);
+    }
   } catch (error) {
     db.close();
     throw error;
@@ -233,6 +244,86 @@ export function takeMailboxTurn(home, session) {
   }
 }
 
+/**
+ * A session's turn to have its Codex thread named (#480), beside its mailbox
+ * turn: `{ release }`, or undefined at once when another naming holds it, so
+ * that two turn ends close together type the name once.
+ */
+export const takeNameTurn = (home, session) => turnOn(home, session, 'name', 0);
+
+/**
+ * A session's typing turn (#480, the architect's ruling), for what the kit
+ * types into the session's tab one key at a time: no line of the kit's may
+ * land in between and send what is there with its own return. Two locks
+ * beside its mailbox turn: `typing`, the gate, held for the whole typing, and
+ * `lines`, taken alone once the lines already on their way have gone in.
+ * Returns `{ release }`, or undefined when it did not come within `waitMs`,
+ * or the lines in flight did not finish within LINES_WAIT_MS.
+ */
+export function takeTypingTurn(home, session, waitMs) {
+  const gate = turnOn(home, session, 'typing', waitMs);
+  if (gate === undefined) return undefined;
+  let lines;
+  try {
+    lines = turnOn(home, session, 'lines', LINES_WAIT_MS, 'EXCLUSIVE');
+  } finally {
+    if (lines === undefined) gate.release();
+  }
+  if (lines === undefined) return undefined;
+  return {
+    release() {
+      try {
+        lines.release();
+      } finally {
+        gate.release();
+      }
+    },
+  };
+}
+
+/**
+ * A session's turn for one whole line, sent with its return in one go, as the
+ * mail nudge is: through the typing turn's gate, waited for `waitMs` at most,
+ * and then held beside any other line, so whole lines never wait on each
+ * other, only on typing one key at a time. Returns `{ release }`, or undefined
+ * when the gate did not come within `waitMs`. Every whole line the kit types
+ * takes it: the nudge, the list line, the skills reload and the grooming line (#482).
+ */
+export function takeLineTurn(home, session, waitMs) {
+  const gate = turnOn(home, session, 'typing', waitMs);
+  if (gate === undefined) return undefined;
+  try {
+    return turnOn(home, session, 'lines', 0, 'SHARED');
+  } finally {
+    gate.release();
+  }
+}
+
+/**
+ * How long a kit path waits for a session's typing turn before it types
+ * nothing (#480, #482): a naming holds it for seconds.
+ */
+export const TYPING_WAIT_MS = 5000;
+
+/** What a kit path reports when the session's typing turn did not come within TYPING_WAIT_MS. */
+export const TYPING_HELD = `the kit is typing into it, and it was still at it after ${TYPING_WAIT_MS / 1000} s, so nothing was typed`;
+
+/**
+ * How long a typing turn waits for the lines already on their way: a nudge
+ * holds its line's turn while Orca waits up to 5 s to see it start a turn.
+ */
+const LINES_WAIT_MS = 10_000;
+
+/** A turn of the kit's own for one session, on a file beside its mailbox turn's. */
+function turnOn(home, session, kind, waitMs, how) {
+  try {
+    return lockOn(mailboxLockFile(home, session).replace(/\.mailbox\.lock$/, `.${kind}.lock`), waitMs, how);
+  } catch (error) {
+    if (error.errcode === SQLITE_BUSY) return undefined;
+    throw error;
+  }
+}
+
 /**
  * How long a step, a check or an `up` waits for a session's turn. Longer than a
  * step can hold it — three Orca calls of twenty seconds each at most — and short