@assuredloop/orca-bot-kit 0.26.1 → 0.28.0

package/src/book.js

@@ -6,12 +6,15 @@
 // theirs. Beside each session's tab it holds the harness session id that
 // session is running under, and every id it ran under before.
 
-import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { DatabaseSync } from 'node:sqlite';
 import { isDeepStrictEqual } from 'node:util';
 import { parse, stringify } from 'yaml';
 
+import { kitFolders } from './launch.js';
+
 const HEADER = `# What Orca calls this bot on this machine, and where each of its sessions
 # lives. \`obk up\` writes this file; it is committed with the rest of the repo.
 #
@@ -83,11 +86,18 @@ function withHistoryListed(entry) {
  * is, never half of it, and a writer that dies leaves the old file in place:
  * the new text goes to a file of this process's own and is moved over the book,
  * which is one operation the file system either did or did not do.
+ *
+ * Whatever is already at that file's name is taken away and the file is made
+ * new, never written through: a session can leave a link there in its own bot
+ * folder, which would take the book's text out of it, and the move would make
+ * the book that link (#599). A link made there in between makes the write fail,
+ * and the old book stays whole.
  */
 export function writeBook(home, book) {
   const file = bookFile(home);
   const half = `${file}.${process.pid}.part`;
-  writeFileSync(half, `${HEADER}${stringify(book)}`);
+  rmSync(half, { force: true });
+  writeFileSync(half, `${HEADER}${stringify(book)}`, { flag: 'wx' });
   renameSync(half, file);
 }
 
@@ -151,7 +161,7 @@ function takeLock(home) {
   try {
     return lockOn(lockFile(home), WAIT_MS);
   } catch (error) {
-    throw waitedTooLong(home, error);
+    throw error instanceof LockNotWritable ? error : waitedTooLong(home, error);
   }
 }
 
@@ -162,10 +172,47 @@ function takeLock(home) {
  * `EXCLUSIVE`, alone, once every `SHARED` holder has let go.
  */
 function lockOn(file, waitMs, how = 'IMMEDIATE') {
-  mkdirSync(path.dirname(file), { recursive: true });
+  // SQLite opens a file it cannot write read-only, without a word, and a
+  // read-only connection's BEGIN passes while another process holds the lock:
+  // seen in Codex's sandbox (#534). So the file is opened for writing first,
+  // and a lock that cannot be held is an error, never a turn that is not one.
+  // Only while this process holds no turn on it: closing any descriptor of a
+  // file lets go of every lock the process holds on that file, and SQLite's
+  // own are among them. A file a turn is held on was written already.
+  //
+  // A session can write its bot's folder of locks, so a link, a FIFO or a
+  // folder may sit at the lock's name, and a lock taken through a link would
+  // make or write a file anywhere the kit may write (#605). So the kit opens
+  // the file itself without following a link, and SQLite opens it only if it
+  // is there and makes nothing. A link put at the name only while SQLite
+  // opens it is followed, and SQLite names the file it opened, so a file of
+  // any other name is closed before it is locked or written. And the turn
+  // ends with ROLLBACK, so SQLite never writes the file it locks.
+  //
+  // What is left, accepted by the architect on #605: SQLite reads the first
+  // 100 bytes of the file it opens before the kit can ask its name, so such a
+  // link can have a file outside read into SQLite's memory and dropped; and a
+  // FIFO put there that instant can hang the command. A lock taken by name
+  // cannot close that without a lock Node does not have.
+  if (!heldHere.has(file)) {
+    try {
+      mkdirSync(path.dirname(file), { recursive: true });
+      plainFile(file);
+    } catch (error) {
+      throw new LockNotWritable(file, error);
+    }
+  }
 
-  const db = new DatabaseSync(file);
+  let db;
+  try {
+    db = new DatabaseSync(new URL(`${pathToFileURL(file).href}?mode=rw`));
+  } catch (error) {
+    throw new LockNotWritable(file, error);
+  }
   try {
+    if (db.location() !== path.join(realpathSync(path.dirname(file)), path.basename(file))) {
+      throw new LockNotWritable(file, notPlain(`a link at it led SQLite to ${db.location()}`));
+    }
     // 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}`);
@@ -181,17 +228,48 @@ function lockOn(file, waitMs, how = 'IMMEDIATE') {
     throw error;
   }
 
+  heldHere.set(file, (heldHere.get(file) ?? 0) + 1);
   return {
     release() {
       try {
-        db.exec('COMMIT');
+        db.exec('ROLLBACK');
       } finally {
         db.close();
+        const left = heldHere.get(file) - 1;
+        if (left > 0) heldHere.set(file, left);
+        else heldHere.delete(file);
       }
     },
   };
 }
 
+/**
+ * Make the lock file at `file` if it is not there, and open it for writing
+ * without following a link or waiting on a FIFO. Anything at the name but a
+ * plain file is refused.
+ */
+function plainFile(file) {
+  let fd;
+  try {
+    fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  } catch (error) {
+    // A link, a folder and a FIFO with no reader, in that order.
+    if (['ELOOP', 'EISDIR', 'ENXIO'].includes(error.code)) throw notPlain(error.code);
+    throw error;
+  }
+  try {
+    if (!fstatSync(fd).isFile()) throw notPlain('not a plain file');
+  } finally {
+    closeSync(fd);
+  }
+}
+
+const NOT_PLAIN = 'ENOTPLAIN';
+const notPlain = (message) => Object.assign(new Error(message), { code: NOT_PLAIN });
+
+/** How many turns this process holds on each lock file, by its path. */
+const heldHere = new Map();
+
 /**
  * Where a writer takes its turn: a folder of the kit's own beside the bots repo,
  * carrying that folder's own name, the way start-prompt files sit beside it
@@ -213,14 +291,56 @@ function lockOn(file, waitMs, how = 'IMMEDIATE') {
  * the bots folder through a link and another by its real path, and two paths
  * would be two locks for one book (#375).
  */
-const lockFile = (home) => {
+const lockFile = (home) => path.join(botLocks(home), `${encodeURIComponent(path.basename(realpathSync(home)))}.lock`);
+
+/**
+ * The bot's own folder of locks, `<bots>.locks/<bot>/`: the one a Codex
+ * session of the bot is given to write, beside its mail and its start prompts
+ * (#534). One folder per bot, so a bot's sessions can take each other's turns
+ * and no other bot's.
+ */
+const botLocks = (home) => {
   const real = realpathSync(home);
-  return path.join(
-    `${path.dirname(path.dirname(real))}.locks`,
-    `${encodeURIComponent(path.basename(real))}.lock`,
-  );
+  return kitFolders(path.dirname(path.dirname(real)), path.basename(real)).locks;
 };
 
+/**
+ * A lock the kit cannot write. Inside Codex's sandbox that is a session
+ * started before the kit gave its bot a folder of locks, so it says what puts
+ * it right.
+ */
+class LockNotWritable extends Error {
+  constructor(file, why) {
+    super(why.code === NOT_PLAIN
+      ? `something other than a plain file is at the name of the kit's lock ${file} (${why.message}), so the kit did not take the turn, and nothing was done. Remove ${file}; the kit makes it again.`
+      : `the kit cannot write its lock ${file} (${why.code ?? why.message}), so it did not take the turn, and nothing was done. A Codex session started before this version of the kit cannot write its bot's folder of locks: restart this session with the kit. Elsewhere, make ${path.dirname(file)} writable.`);
+    this.code = why.code;
+  }
+}
+
+/**
+ * The right to change the bot's `bot.yaml` (#595), held from the read a command
+ * makes its change on until that change is written. Two commands that change
+ * one bot at the same time then each change what the other left, and neither
+ * change is lost.
+ *
+ * The book's kind of lock, on a file of its own beside the book's: `temp make`
+ * writes bot.yaml while it holds the book's, and nothing takes the book's while
+ * it holds this one, so neither waits on the other.
+ */
+export function takeBotTurn(home) {
+  const file = botLockFile(home);
+  try {
+    return lockOn(file, WAIT_MS);
+  } catch (error) {
+    if (error instanceof LockNotWritable) throw error;
+    throw new Error(`waited ${WAIT_MS / 1000} seconds for something else to finish writing ${path.join(home, 'bot.yaml')} and it did not (${error.message}). bot.yaml was not changed. Try again; if nothing is running, remove ${file}, which is where writers take their turn.`);
+  }
+}
+
+/** Beside the book's lock, with the bot's name: the lock files of its sessions carry one more part. */
+const botLockFile = (home) => path.join(botLocks(home), `${encodeURIComponent(path.basename(realpathSync(home)))}.bot.lock`);
+
 /**
  * One session's turn at its mailbox (#321): held by `session mailbox` for its
  * whole step, by `message check` in the session's own tab for its bind, read and
@@ -286,11 +406,11 @@ export function takeTypingTurn(home, session, waitMs) {
 
 /**
  * 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,
+ * mail interrupt 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).
+ * takes it: the mail interrupt, the list line, the skills reload and the grooming line (#482).
  */
 export function takeLineTurn(home, session, waitMs) {
   const gate = turnOn(home, session, 'typing', waitMs);
@@ -312,8 +432,9 @@ export const TYPING_WAIT_MS = 5000;
 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.
+ * How long a typing turn waits for the lines already on their way: a line
+ * re-issued to Orca holds its turn while Orca waits up to 5 s to see it start
+ * a turn.
  */
 const LINES_WAIT_MS = 10_000;
 
@@ -344,10 +465,8 @@ const SQLITE_BUSY = 5;
  * link by one command and by its real path by another, and two paths would be
  * two turns.
  */
-const mailboxLockFile = (home, session) => {
-  const real = realpathSync(home);
-  return path.join(`${path.dirname(path.dirname(real))}.locks`, `${path.basename(real)}.${session}.mailbox.lock`);
-};
+const mailboxLockFile = (home, session) =>
+  path.join(botLocks(home), `${path.basename(realpathSync(home))}.${session}.mailbox.lock`);
 
 /**
  * Something else has been writing the book for longer than this run is prepared
@@ -429,10 +548,11 @@ export function rememberSession(entry = {}, id, ended) {
 
 /**
  * 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.
+ * behind it on the session's harness: the id goes into the history with that
+ * reason, and anything else worth knowing about it, such as the harness it ran
+ * on, and the entry holds none until the harness names the new one.
  */
-export function forgetSession(entry, ended) {
+export function forgetSession(entry, ended, more = {}) {
   const { session, ...rest } = entry;
-  return { ...rest, history: [...(entry.history ?? []), { session, ended, at: new Date().toISOString() }] };
+  return { ...rest, history: [...(entry.history ?? []), { session, ended, ...more, at: new Date().toISOString() }] };
 }