@assuredloop/orca-bot-kit 0.26.1 → 0.28.0

package/src/init.js

@@ -10,7 +10,7 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync,
 import path from 'node:path';
 import { parseDocument } from 'yaml';
 
-import { BOT_GITIGNORE, changesExactly, YAML_OUT } from './bot.js';
+import { BOT_GITIGNORE, changesExactly, refuseOutside, withBotTurn, writeWhole, YAML_OUT } from './bot.js';
 import { RECORD, SKILL_DIRS } from './skills.js';
 
 /**
@@ -266,6 +266,11 @@ function checkBotFather(file, harness) {
   if (bot.sessions !== undefined && bot.sessions !== null && !Array.isArray(bot.sessions)) {
     throw new Error(`${file} has a sessions entry that is not a list, so init cannot add Bot Father's daily session to it. Fix it, then run init again.`);
   }
+  // One init would complete is refused here, before init writes anything, when a
+  // link takes it out of the bot folder (#569).
+  if (bot.harness === undefined || !Array.isArray(bot.sessions) || bot.sessions.length === 0) {
+    refuseOutside(path.dirname(file), file);
+  }
 }
 
 /**
@@ -281,35 +286,37 @@ function checkBotFather(file, harness) {
  * are theirs, and `up` brings up what it finds.
  */
 function completeBotFather(file, harness) {
-  const source = readFileSync(file, 'utf8');
-  const doc = parseDocument(source);
-
-  // What is missing is settled from the document, not from the text it is
-  // written back as: a file that needs nothing is not rewritten, however the
-  // library would have laid it out.
-  const sessions = doc.get('sessions', true);
-  const needsSession = sessions?.items === undefined || sessions.items.length === 0;
-  const needsHarness = doc.get('harness') === undefined;
-  if (!needsSession && !needsHarness) return [];
-
-  if (sessions?.items === undefined) {
-    doc.set('sessions', [{ name: DAILY_SESSION }]);
-  } else if (needsSession) {
-    sessions.flow = false;
-    doc.addIn(['sessions'], { name: DAILY_SESSION });
-  }
-  if (needsHarness) doc.set('harness', harness);
+  return withBotTurn(path.dirname(file), () => {
+    const source = readFileSync(file, 'utf8');
+    const doc = parseDocument(source);
+
+    // What is missing is settled from the document, not from the text it is
+    // written back as: a file that needs nothing is not rewritten, however the
+    // library would have laid it out.
+    const sessions = doc.get('sessions', true);
+    const needsSession = sessions?.items === undefined || sessions.items.length === 0;
+    const needsHarness = doc.get('harness') === undefined;
+    if (!needsSession && !needsHarness) return [];
+
+    if (sessions?.items === undefined) {
+      doc.set('sessions', [{ name: DAILY_SESSION }]);
+    } else if (needsSession) {
+      sessions.flow = false;
+      doc.addIn(['sessions'], { name: DAILY_SESSION });
+    }
+    if (needsHarness) doc.set('harness', harness);
 
-  const text = doc.toString(YAML_OUT);
+    const text = doc.toString(YAML_OUT);
 
-  if (!changesExactly(source, text, (was) => ({
-    ...was,
-    harness: was.harness ?? harness,
-    sessions: was.sessions?.length > 0 ? was.sessions : [{ name: DAILY_SESSION }],
-  }))) {
-    throw new Error(`${file} cannot be completed without changing something else in it, so nothing was written. Give it a harness and a session by hand, then run init again.`);
-  }
+    if (!changesExactly(source, text, (was) => ({
+      ...was,
+      harness: was.harness ?? harness,
+      sessions: was.sessions?.length > 0 ? was.sessions : [{ name: DAILY_SESSION }],
+    }))) {
+      throw new Error(`${file} cannot be completed without changing something else in it, so nothing was written. Give it a harness and a session by hand, then run init again.`);
+    }
 
-  writeFileSync(file, text);
-  return [BOT_FATHER_YAML];
+    writeWhole(file, text);
+    return [BOT_FATHER_YAML];
+  });
 }

package/src/launch.js

@@ -2,7 +2,7 @@
 // the harness up and carries the session's start prompt with it.
 //
 // The flag mapping is PRD 6.4 and ADR 0015, re-checked against the installed
-// CLIs (Claude Code 2.1.278, Codex 0.155.1). Every session is given its
+// CLIs (Claude Code 2.1.278, Codex 0.155.1, Pi 1.1.0). Every session is given its
 // approval level explicitly, so a user's own global harness defaults cannot
 // leak into a bot. The kit names no model: a session that sets none gets the
 // harness's own.
@@ -27,6 +27,11 @@ const APPROVAL = {
     ask: ['-a', 'on-request'],
     'dangerously-skip': ['--dangerously-bypass-approvals-and-sandbox'],
   },
+  // Pi asks before no tool call and has no rule for each command, so it has
+  // one level, and no flag for it (the owner, #547).
+  pi: {
+    'dangerously-skip': [],
+  },
 };
 
 export const APPROVALS = Object.keys(APPROVAL.claude);
@@ -44,39 +49,186 @@ export const HARNESSES = Object.keys(APPROVAL);
 export const approvalRank = (level) => ['ask', 'auto', 'dangerously-skip'].indexOf(level);
 
 /**
- * The harness flags that set approval or permissions, which only
- * `obk permission approval` may change, not an extra argument (ADR 0041).
- * Codex's `-a` and `-s` take their value glued on too.
+ * The harness flags that set approval or permissions, or widen what a session
+ * may write or run, which only `obk permission approval` may change, not an
+ * extra argument (ADR 0051, ADR 0049). Codex's short flags take their value
+ * glued on too. Pi's `--approve` and `-a` make it trust the folder's own
+ * files, which the kit's `--no-approve` keeps it from (#578).
  */
 const APPROVAL_FLAGS = {
-  claude: ['--permission-mode', '--dangerously-skip-permissions', '--allow-dangerously-skip-permissions', '--allowedTools', '--allowed-tools'],
-  codex: ['-a', '--ask-for-approval', '--approve-for-me', '--dangerously-bypass-approvals-and-sandbox', '-s', '--sandbox'],
+  claude: [
+    '--permission-mode', '--dangerously-skip-permissions', '--allow-dangerously-skip-permissions', '--allowedTools', '--allowed-tools',
+    '--add-dir', '--settings', '--setting-sources', '--plugin-dir', '--plugin-url', '--mcp-config', '--agents', '--agent', '--debug-file', '--bare', '--restricted',
+  ],
+  codex: [
+    '-a', '--ask-for-approval', '--approve-for-me', '--dangerously-bypass-approvals-and-sandbox', '-s', '--sandbox',
+    '--add-dir', '-C', '--cd', '-p', '--profile', '--enable', '--disable', '--remote', '--remote-auth-token-env',
+  ],
+  pi: ['--approve', '-a'],
+};
+
+/**
+ * The Codex `-c` keys an extra argument may set, with any value or with only
+ * the values named. Every other key is refused: Codex 0.163.0's config has
+ * dozens that widen a session, and more in each release (ADR 0049).
+ */
+const CONFIG_KEYS = {
+  model: true,
+  model_reasoning_effort: true,
+  model_reasoning_summary: true,
+  model_verbosity: true,
+  model_context_window: true,
+  model_auto_compact_token_limit: true,
+  plan_mode_reasoning_effort: true,
+  service_tier: true,
+  hide_agent_reasoning: true,
+  show_raw_agent_reasoning: true,
+  tool_output_token_limit: true,
+  'tui.animations': true,
+  'tui.show_tooltips': true,
+  'tui.notifications': true,
+  'tui.notification_method': true,
+  'tui.notification_condition': true,
+  'tui.alternate_screen': true,
+  'tui.theme': true,
+  'tui.vim_mode_default': true,
+  'tui.status_line': true,
+  'tui.terminal_title': true,
+  'tui.raw_output_mode': true,
+  'tui.disable_paste_burst': true,
+  'tui.fullscreen_transcript': true,
+  'tui.mouse_scroll_speed': true,
+  'tui.show_server_version_notice': true,
+  // The network the kit turns on, which a user may turn off (NETWORK_ACCESS).
+  'sandbox_workspace_write.network_access': ['true', 'false'],
+  // These only narrow: `false` is Codex's default.
+  'sandbox_workspace_write.exclude_tmpdir_env_var': ['true', 'false'],
+  'sandbox_workspace_write.exclude_slash_tmp': ['true', 'false'],
+  'features.sleep_tool': ['false'],
+  // No update check at start, so no update offer (#581).
+  check_for_update_on_startup: ['false'],
 };
 
+/**
+ * The one trust a `-c` may give: one folder, an absolute path in a TOML basic
+ * string, trusted. It is what the kit's own answer to Codex's trust screen
+ * gives, for that run only and with nothing written to config.toml (ADR 0049).
+ */
+const TRUST = /^\{[ \t]*"([^"\\\x00-\x1f\x7f]*)"[ \t]*=[ \t]*\{[ \t]*trust_level[ \t]*=[ \t]*"trusted"[ \t]*\}[ \t]*\}$/;
+
+/** Whether a Codex `-c` value, `key=value`, sets only what an extra argument may. */
+function allowedConfig(setting) {
+  const at = setting.indexOf('=');
+  if (at === -1) return false;
+  const key = setting.slice(0, at).trim();
+  const value = setting.slice(at + 1).trim();
+  if (key === 'projects') {
+    const folder = TRUST.exec(value)?.[1];
+    return folder !== undefined && folder.startsWith('/') && !folder.split('/').includes('..');
+  }
+  if (!/^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$/.test(key) || !Object.hasOwn(CONFIG_KEYS, key)) return false;
+  return CONFIG_KEYS[key] === true || CONFIG_KEYS[key].includes(value);
+}
+
 /**
  * Refuse extra arguments that set a session's approval or permissions on
- * `harness`, before anything is written, naming the command that does it.
+ * `harness`, or widen what it may write or run, before anything is written,
+ * naming the command that does it (ADR 0051, ADR 0049).
+ * `args` is a list, or, as a user may write `extra_args` by hand, one string
+ * of shell text. The kit types such a string into the tab's shell as it
+ * stands, so the guard takes it only when it can be sure of the words the
+ * shell makes of it, and refuses it otherwise (#565).
  */
 export function refuseApprovalArgs(harness, args) {
-  const found = (args ?? []).find((arg) => (APPROVAL_FLAGS[harness] ?? []).some((flag) => arg === flag
-    || arg.startsWith(`${flag}=`)
-    || (/^-[as]$/.test(flag) && arg.startsWith(flag) && !arg.startsWith('--'))));
-  if (found === undefined) return;
-  throw new Error(`--extra-arg=${found} sets the session's approval or permissions on ${harness}, and only obk permission approval changes those, after the user's yes. Nothing was changed.`);
+  const words = Array.isArray(args) ? args.map(String) : set(args) ? sureWords(String(args)) : [];
+  if (words === undefined) {
+    throw new Error(`extra_args is written as one string, ${quoted(String(args))}, with shell syntax the kit cannot be sure of the words of, so it cannot tell whether it sets the session's approval or permissions. Write extra_args as a list, one --extra-arg for each argument. Nothing was changed.`);
+  }
+  for (let at = 0; at < words.length; at += 1) {
+    const arg = words[at];
+    if ((APPROVAL_FLAGS[harness] ?? []).some((flag) => arg === flag
+      || arg.startsWith(`${flag}=`)
+      || (/^-[asCp]$/.test(flag) && arg.startsWith(flag) && !arg.startsWith('--')))) {
+      throw new Error(`--extra-arg=${arg} sets the session's approval or permissions on ${harness}, or widens what it may write or run, and only obk permission approval changes those, after the user's yes. Nothing was changed.`);
+    }
+    // Codex's config override: the value is the next word, or after `=`, or glued on.
+    const setting = harness !== 'codex' ? undefined
+      : arg === '-c' || arg === '--config' ? (at += 1, words[at] ?? '')
+        : arg.startsWith('--config=') ? arg.slice('--config='.length)
+          : arg.startsWith('-c') && !arg.startsWith('--') ? arg.slice(2).replace(/^=/, '')
+            : undefined;
+    if (setting !== undefined && !allowedConfig(setting)) {
+      throw new Error(`--extra-arg=-c ${setting} sets a Codex setting that an extra argument may not set: the kit takes -c only for the model, the display, the network switch and a few settings that narrow (ADR 0049). Set the others in your own ~/.codex/config.toml; the session's approval and sandbox change only through obk permission approval, after the user's yes. Nothing was changed.`);
+    }
+  }
+}
+
+/**
+ * The words of the shell text `text`, when the kit can be sure they are the
+ * ones the tab's shell makes of it, and undefined when it cannot (#565). Sure
+ * means plain words of the characters `quoted` leaves bare, separated by
+ * spaces, with no unquoted `=` before any other character of its word, empty
+ * quotes included (zsh's equals expansion makes `''=sh` into /bin/sh); single quotes with no
+ * backslash (fish reads `\'` and `\\` there) and no control character; and
+ * double quotes with none of `$`, backquote, backslash or `!`, and no control
+ * character. Read so, it is the same words in zsh, bash and fish. Everything
+ * else, a newline or a tab included, is shell syntax this does not read.
+ */
+function sureWords(text) {
+  const words = [];
+  let word;
+  let quote;
+  for (const char of text) {
+    if (/[\x00-\x1f\x7f]/.test(char)) return undefined;
+    if (quote === "'") {
+      if (char === '\\') return undefined;
+      if (char === "'") quote = undefined;
+      else word += char;
+    } else if (quote === '"') {
+      if ('$`\\!'.includes(char)) return undefined;
+      if (char === '"') quote = undefined;
+      else word += char;
+    } else if (char === ' ') {
+      if (word !== undefined) words.push(word);
+      word = undefined;
+    } else if (char === "'" || char === '"') {
+      word ??= '';
+      quote = char;
+    } else if (/^[A-Za-z0-9,._+:@%/=-]$/.test(char) && !(char === '=' && !word)) {
+      word = (word ?? '') + char;
+    } else {
+      return undefined;
+    }
+  }
+  if (quote !== undefined) return undefined;
+  if (word !== undefined) words.push(word);
+  return words;
 }
 
 /** The level a session that names none runs at (ADR 0015). */
 export const DEFAULT_APPROVAL = 'auto';
 
+/** The level a session on `harness` is written with when it names none: Pi has only one (#547). */
+export const defaultApproval = (harness) => (harness === 'pi' ? 'dangerously-skip' : DEFAULT_APPROVAL);
+
+/**
+ * Why a level is refused on Pi, or undefined when it is taken there. The
+ * owner's decision (#547): every Pi session counts as dangerously-skip.
+ */
+export function piApprovalTrouble(level, who = 'this session') {
+  if (!set(level) || level === 'dangerously-skip') return undefined;
+  return `${who} runs on Pi and is set to approval ${level}. Pi has no approval prompt and no permission rules, so every Pi session runs as dangerously-skip (the owner's decision, #547); auto and ask are refused on Pi. Set it to dangerously-skip, or run the session on claude or codex.`;
+}
+
 /** A setting the user left out. An empty string is one too: it means the harness's own. */
-const set = (value) => value !== undefined && value !== null && String(value).trim() !== '';
+export const set = (value) => value !== undefined && value !== null && String(value).trim() !== '';
 
 /** Which harness a session runs on: its own, or the bot's. */
 export const harnessOf = (session, botHarness) => (set(session.harness) ? session.harness : botHarness);
 
 /**
  * A session's name on Claude Code, which is also the address another Claude
- * session writes to (ADR 0035). It goes on the launch line as `-n`, and it is
+ * session writes to (ADR 0042). It goes on the launch line as `-n`, and it is
  * re-applied every time the session is started: a resume keeps the name by
  * itself (tech notes, section 2), and the kit does not depend on that.
  *
@@ -201,6 +353,22 @@ export function sessionTrouble(session, harness, home) {
   if (set(session.approval) && !APPROVALS.includes(session.approval)) {
     return `${where(session)} is set to approval ${session.approval}, and the levels are ${APPROVALS.join(', ')}.`;
   }
+  if (harness === 'pi') {
+    const trouble = piApprovalTrouble(session.approval, where(session));
+    if (trouble !== undefined) return trouble;
+    // Pi has no context setting: a model's own name carries it, as in
+    // cursor/claude-opus-5-5@1m (tech notes, section 6).
+    if (set(session.context)) {
+      return `${where(session)} sets a context of ${session.context} on Pi, and Pi has no context setting: the model's name carries it, as in cursor/claude-opus-5-5@1m. Name such a model, or leave the context out.`;
+    }
+    // Pi 1.1.0 reads a word after `--` that starts with `@` as a file to
+    // attach, and has no escape for it, so such a prompt cannot arrive as
+    // written (tech notes, section 6). It is checked trimmed, as it is sent.
+    const said = set(session.prompt_file) ? readFileSync(promptFile(session, home), 'utf8') : session.prompt;
+    if (set(said) && String(said).trim().startsWith('@')) {
+      return `${where(session)} runs on Pi, and its prompt begins with @. Pi would read the prompt as a file to attach, not as text. Give it a prompt that does not begin with @.`;
+    }
+  }
   // Codex is given the context window as a number of tokens. `1m` is what a
   // Claude session would say, and copying it here does not fail at the kit but
   // in Codex, which exits with a type error the moment it starts.
@@ -231,16 +399,21 @@ const where = (session) => (set(session.name) ? `session ${session.name}` : 'thi
  * send would land on that list and answer it. A prompt given as an argument is
  * held by the harness until it is ready for it (tech notes, section 1).
  */
-export function launchCommand(session, { harness, home, workDir, prompt, promptFile: fromFile, resume, address }) {
+export function launchCommand(session, { harness, home, workDir, prompt, promptFile: fromFile, resume, address, kit, sessionId, name }) {
   const trouble = sessionTrouble(session, harness, home);
   if (trouble !== undefined) throw new Error(trouble);
+  // Pi is told which conversation it is, a new one too: the kit names it, and
+  // that is how the book knows it (tech notes, section 6).
+  if (harness === 'pi' && resume === undefined && sessionId === undefined) {
+    throw new Error(`${where(session)} runs on Pi, and a Pi session is started with the id the book gives it, so the kit names one before it launches. None was given.`);
+  }
 
   const words = [harness];
   // Codex resumes through a subcommand, which has to come first; Claude Code
   // resumes through a flag, which goes with the session id at the end. Both
   // take every other flag exactly as a fresh session does.
   if (resume !== undefined && harness === 'codex') words.push('resume');
-  words.push(...APPROVAL[harness][set(session.approval) ? session.approval : DEFAULT_APPROVAL]);
+  words.push(...APPROVAL[harness][set(session.approval) ? session.approval : defaultApproval(harness)]);
   // Codex 0.157 shares one background server between sessions by default, and
   // a resume through it was seen to fail; without it Codex runs as 0.156 did
   // (tech notes, section 3, #330). Codex refuses the flag twice, so the user's
@@ -249,11 +422,21 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
 
   if (harness === 'claude') {
     // The name is the address other Claude sessions write to, so it goes on
-    // every launch line, a resume included (ADR 0035).
+    // every launch line, a resume included (ADR 0042).
     if (address !== undefined) words.push('-n', address);
     // The context window rides on the model name: `sonnet[1m]`.
     if (set(session.model)) words.push('--model', set(session.context) ? `${session.model}[${session.context}]` : session.model);
     if (set(session.effort)) words.push('--effort', String(session.effort));
+  } else if (harness === 'pi') {
+    // Pi trusts none of the folder's own files (`.pi/`, `.agents/skills`), so it
+    // shows no trust screen and runs nothing the kit has not looked at (#578).
+    words.push('--no-approve');
+    // The id the book holds, resumed or new: Pi opens the conversation with it,
+    // and makes it when there is none (tech notes, section 6).
+    words.push('--session-id', resume ?? sessionId);
+    if (name !== undefined) words.push('--name', name);
+    if (set(session.model)) words.push('--model', session.model);
+    if (set(session.effort)) words.push('--thinking', String(session.effort));
   } else {
     // Without this the Orca CLI cannot reach Orca from inside the sandbox, so
     // the session is in no fleet at all. The user's own setting of it wins.
@@ -265,6 +448,10 @@ export function launchCommand(session, { harness, home, workDir, prompt, promptF
     // started in, and nowhere else (ADR 0015), so a work dir outside the bot
     // home has to be named.
     if (workDir !== undefined && !inside(home, workDir)) words.push('--add-dir', workDir);
+    // And the kit's own folders for this bot beside the bots folder: its long
+    // message bodies, its start prompts and its locks (#534). The bot's, and no
+    // other bot's: a session never gets to write another bot's mail.
+    if (kit !== undefined) for (const folder of Object.values(kit)) words.push('--add-dir', folder);
   }
 
   return [
@@ -309,7 +496,7 @@ export function startPrompt(session, { home, workDir }) {
 }
 
 /** Where a session's prompt file is: in the bot home, where the user put it. */
-export const promptFile = (session, home) => path.resolve(home, session.prompt_file);
+export const promptFile = (session, home) => path.resolve(home, String(session.prompt_file));
 
 /**
  * A prompt short and simple enough to type into the launch line as it is: one
@@ -332,13 +519,27 @@ function promptWords(prompt, fromFile) {
 
 /**
  * The session the harness is told to pick up again, when there is one: a flag
- * on Claude Code, the argument of the `resume` subcommand on Codex.
+ * on Claude Code, the argument of the `resume` subcommand on Codex. Pi's is
+ * its `--session-id`, which goes with its other flags.
  */
 const resumeWords = (harness, resume) => {
-  if (resume === undefined) return [];
+  if (resume === undefined || harness === 'pi') return [];
   return harness === 'claude' ? ['--resume', quoted(resume)] : [quoted(resume)];
 };
 
+/**
+ * The kit's own folders for one bot, beside the bots folder: `messages` for
+ * the bodies of its long fleet mail, `prompts` for its sessions' start
+ * prompts, `locks` for its book's and its sessions' turns. Each is a folder of
+ * the bot's own, so that a Codex session, whose sandbox writes only where its
+ * launch line says, can be given its bot's and no other's (#534).
+ */
+export const kitFolders = (bots, bot) => ({
+  messages: path.join(`${bots}.messages`, bot),
+  prompts: path.join(`${bots}.prompts`, bot),
+  locks: path.join(`${bots}.locks`, bot),
+});
+
 /** Whether `target` is the folder at `home` or something inside it. */
 const inside = (home, target) => target === home || target.startsWith(home + path.sep);