agentbox-app 0.1.13 → 0.1.16

package/main/cloud/marker.mjs

@@ -0,0 +1,104 @@
+// "A CLOUD RUN'S WORK IS STILL ON ITS WAY BACK TO THIS FOLDER."
+//
+// A cloud run (docs/cloud/PLAN.md) commits in the sandbox, and the commits
+// reach the task folder only when the run is over. Until then the folder's
+// branch is stale, and two things in the app would act on it as if it were
+// not: the ship queue (a worker adds `ship` BEFORE it exits, and "there is
+// nothing to ship" counts as shipped) and the folder cleaner (a clean, merged
+// folder is removed). This record is what both of them check.
+//
+// It lives in the folder's own git directory, not in the working tree, so no
+// commit, park or `git clean` can carry it off or delete it, and it names the
+// run, so a later run in the same folder can bring that run's work home first.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const NAME = 'agentbox-cloud.json';
+
+// Read off the folder's `.git` rather than asked of `git rev-parse`: this runs
+// for every task folder on the app's main process and at every marker read in
+// the relay all cloud runs share, and a busy Mac takes half a second to start git.
+export function gitDirOf(folder) {
+  if (!folder) return null;
+  for (let dir = path.resolve(folder); ; dir = path.dirname(dir)) {
+    const dotGit = path.join(dir, '.git');
+    let st = null;
+    try { st = fs.statSync(dotGit); } catch { /* not here */ }
+    if (st?.isDirectory() && fs.existsSync(path.join(dotGit, 'HEAD'))) return dotGit;
+    if (st?.isFile()) {
+      const m = /^gitdir:\s*(.+?)\s*$/m.exec(fs.readFileSync(dotGit, 'utf8'));
+      const linked = m && path.resolve(dir, m[1]);
+      return linked && fs.existsSync(linked) ? linked : null;
+    }
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+// The main repository's git directory, which a linked worktree's names in `commondir`.
+export function commonGitDirOf(folder) {
+  const dir = gitDirOf(folder);
+  if (!dir) return null;
+  try { return path.resolve(dir, fs.readFileSync(path.join(dir, 'commondir'), 'utf8').trim()); } catch { return dir; }
+}
+
+// `folder` is a task folder, or `{ folder, file }` for a project with no
+// repository: its threads share one documents folder, so each keeps its own
+// marker at `file` (Supervisor#_plainMarker).
+export function markerPath(folder) {
+  if (folder && typeof folder === 'object') return folder.file || null;
+  const dir = gitDirOf(folder);
+  return dir ? path.join(dir, NAME) : null;
+}
+
+export function readMarker(folder) {
+  const file = markerPath(folder);
+  if (!file) return null;
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+export function writeMarker(folder, record) {
+  const file = markerPath(folder);
+  if (!file) throw new Error(`${folder} is not a git folder`);
+  if (typeof folder === 'object') fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ ...record, at: Date.now() }, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+export function clearMarker(folder) {
+  const file = markerPath(folder);
+  if (file) fs.rmSync(file, { force: true });
+}
+
+// The one question the ship queue and the folder cleaner ask. A folder that
+// is not there, or not a git folder, has nothing pending.
+export function cloudWorkPending(folder) {
+  if (folder && typeof folder === 'object') return !!folder.file && !!readMarker(folder);
+  if (!folder || !fs.existsSync(folder)) return false;
+  return !!readMarker(folder);
+}
+
+// WHAT A RUN BROUGHT HOME THAT ITS ROW MUST SAY (main/cloud/run.mjs `park`):
+// written by the relay, which cannot reach the store, and said by the
+// supervisor (`_sayCloudNews`). Beside the marker, and outliving it.
+const NEWS = 'agentbox-cloud-news.json';
+const newsPath = (folder) => { const dir = gitDirOf(folder); return dir ? path.join(dir, NEWS) : null; };
+
+export function addCloudNews(folder, news) {
+  const file = newsPath(folder);
+  if (!file) return;
+  let all = [];
+  try { all = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { /* none yet */ }
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify([...(Array.isArray(all) ? all : []), { ...news, at: Date.now() }], null, 2));
+  fs.renameSync(tmp, file);
+}
+
+export function takeCloudNews(folder) {
+  const file = folder && fs.existsSync(folder) ? newsPath(folder) : null;
+  if (!file || !fs.existsSync(file)) return [];
+  let all = [];
+  try { all = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { /* unreadable: dropped */ }
+  fs.rmSync(file, { force: true });
+  return Array.isArray(all) ? all : [];
+}

package/main/cloud/org.mjs

@@ -0,0 +1,53 @@
+// WHICH CLAUDE ACCOUNT A CLOUD SIGN-IN IS, BY ITS ORGANIZATION.
+//
+// The profile lookup refuses these sign-ins (403, no user:profile scope), so
+// the cloud cannot learn an account's email. A free token count answers with
+// the `anthropic-organization-id` header instead, which is the same for two
+// sign-ins of one account (measured 2026-10-16). It is asked by a short run in
+// the cloud, with that account's own sign-in, so the sign-in never comes to
+// this Mac; only the id does.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+import { EventEmitter } from 'node:events';
+import { execFileSync } from 'node:child_process';
+import { cloudRun } from './run.mjs';
+import { loginObjectKey } from './logins.mjs';
+import { Name, nameSlug } from '../../shared/product-name.mjs';
+
+const MARK = 'agentbox-org:';
+const SANDBOX_NODE = '/usr/local/bin/node';
+const PROBE = `fetch('https://api.anthropic.com/v1/messages/count_tokens',{method:'POST',headers:{Authorization:'Bearer '+process.env.CLAUDE_CODE_OAUTH_TOKEN,'anthropic-beta':'oauth-2025-04-20','anthropic-version':'2023-06-01','content-type':'application/json'},body:JSON.stringify({model:'claude-haiku-4-5',messages:[{role:'user',content:'hi'}]})}).then(r=>console.log('${MARK}'+(r.headers.get('anthropic-organization-id')||''))).catch(()=>console.log('${MARK}'))`;
+
+/** The id on the probe's own line, when it is one; null otherwise. */
+export function orgFromOutput(text) {
+  const line = String(text ?? '').split('\n').find((l) => l.startsWith(MARK));
+  const id = line?.slice(MARK.length).trim();
+  return id && /^[0-9a-f-]{8,64}$/i.test(id) ? id : null;
+}
+
+/** The organization of one cloud Claude account, or null when the cloud would not say. */
+export async function readCloudOrg(rec, { transport, storage }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agentbox-org-'));
+  try {
+    const git = (...a) => execFileSync('git', a, { cwd: dir, stdio: 'pipe' });
+    git('init', '-q', '-b', 'main', '.');
+    git('-c', `user.name=${Name}`, '-c', `user.email=${nameSlug}@localhost`, 'commit', '-q', '--allow-empty', '-m', 'org check');
+    git('checkout', '-q', '-b', 'agentbox/org-check');
+    const stdout = new PassThrough();
+    let out = '';
+    stdout.on('data', (d) => { out += d; });
+    const stdin = new PassThrough();
+    stdin.end();
+    await cloudRun({
+      argv: ['-e', PROBE], env: { PATH: process.env.PATH, ZERO_ITEM: 'org-check' }, cwd: dir,
+      transport, storage, login: { engine: 'claude', id: rec.id, key: loginObjectKey('claude', rec.id) },
+      remoteCommand: SANDBOX_NODE, stdin, stdout, stderr: new PassThrough(),
+      homeDir: path.join(dir, 'home'), watchParent: false, signals: new EventEmitter(),
+    });
+    return orgFromOutput(out);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}

package/main/cloud/reuse.mjs

@@ -0,0 +1,208 @@
+// WHAT A CLOUD RUN SENDS ONCE AND THEN REUSES.
+//
+// Every reply in the cloud is a new machine, but the project's history and
+// the account's skills and memories barely change between replies. Each is
+// kept in the bucket under a name made from what it holds and sent again only
+// when that changes. The history goes as one base shared by every thread of
+// the repository, and each run sends only the commits past it (`pickBase`).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { run } from './exec.mjs';
+import { commonGitDirOf, markerPath } from './marker.mjs';
+
+// The bucket deletes everything under `runs/` seven days after it was written
+// (scripts/cloud-setup.mjs). Names carry the six-day period they were written
+// in and are only reused inside it, so nothing reused is ever that old.
+export const CACHE_PERIOD_MS = 6 * 24 * 60 * 60_000;
+
+export const periodOf = (now = Date.now()) => Math.floor(now / CACHE_PERIOD_MS);
+export const cacheKey = (name, now = Date.now()) => `runs/cache/${periodOf(now)}/${name}`;
+
+// What a folder holds, as tar -h packs it: every file, following links, by its
+// path, size, time and mode. Unchanged files give the same name; any change
+// gives a new one.
+export async function folderKey(dir) {
+  const h = crypto.createHash('sha256');
+  const seen = new Set();
+  async function walk(d, rel) {
+    let real;
+    try { real = await fs.promises.realpath(d); } catch { return; }
+    if (seen.has(real)) return;
+    seen.add(real);
+    let names;
+    try { names = (await fs.promises.readdir(d)).sort(); } catch { return; }
+    for (const name of names) {
+      const p = path.join(d, name);
+      const r = rel ? `${rel}/${name}` : name;
+      let st;
+      try { st = await fs.promises.stat(p); } catch { continue; }
+      if (st.isDirectory()) await walk(p, r);
+      else if (st.isFile()) h.update(`${r}\0${st.size}\0${st.mtimeMs}\0${st.mode}\n`);
+    }
+  }
+  await walk(dir, '');
+  return h.digest('hex');
+}
+
+// Puts `make()` at `key` unless the bucket already has it. A storage that
+// cannot say what it has gets everything sent, as before.
+export async function sendOnce(storage, key, make) {
+  if (storage.exists && await storage.exists(key).catch(() => false)) return { key, sent: false };
+  const body = await make();
+  await storage.put(key, body);
+  return { key, sent: true };
+}
+
+const has = (storage, key) => (storage.exists ? storage.exists(key).catch(() => false) : false);
+
+// S3 copies a part only from 5 MiB, so a conversation smaller than that is
+// sent whole every time.
+export const MIN_JOIN_BYTES = 5 * 1024 * 1024;
+
+// Where this Mac notes the conversation it last sent from a folder: beside
+// the folder's cloud marker.
+export function sentRecordPath(here) {
+  const marker = markerPath(here);
+  return marker ? `${marker.replace(/\.json$/, '')}-sent.json` : null;
+}
+
+// The hash of the first `upTo` bytes (null when the file is shorter) and of
+// the whole file, in one read.
+async function hashes(file, upTo) {
+  const whole = crypto.createHash('sha256');
+  let prefix = null;
+  let seen = 0;
+  for await (const chunk of fs.createReadStream(file)) {
+    if (prefix === null && upTo > 0 && seen + chunk.length >= upTo) {
+      whole.update(chunk.subarray(0, upTo - seen));
+      prefix = whole.copy().digest('hex');
+      whole.update(chunk.subarray(upTo - seen));
+    } else whole.update(chunk);
+    seen += chunk.length;
+  }
+  return { prefix, whole: whole.digest('hex'), size: seen };
+}
+
+/**
+ * Puts a resumed conversation in the bucket and returns its key. Claude Code
+ * only ever adds to one, so once a copy is there only what was added since is
+ * sent, and joined to it in the bucket (`storage.extend`). Anything else, a
+ * conversation that changed or a copy the bucket no longer has, goes whole.
+ * A copy from an earlier period is joined from, never read by the cloud: the
+ * join is a new object under this period's name. `record` is where the last
+ * send is noted.
+ */
+export async function sendConversation(storage, file, { record = null, now = Date.now() } = {}) {
+  // Hashed and sent from one copy, so the key always names what was sent.
+  const copy = path.join(os.tmpdir(), `agentbox-conversation-${crypto.randomUUID()}.jsonl`);
+  try {
+    fs.copyFileSync(file, copy, fs.constants.COPYFILE_FICLONE);
+    let had = null;
+    try { had = record ? JSON.parse(fs.readFileSync(record, 'utf8')) : null; } catch { /* none yet */ }
+    const joinable = !!storage.extend && Number.isInteger(had?.size)
+      && had.size >= MIN_JOIN_BYTES && typeof had.key === 'string' && typeof had.sha === 'string';
+    const { prefix, whole, size } = await hashes(copy, joinable ? had.size : 0);
+    const key = cacheKey(`conversation-${whole}.jsonl`, now);
+    let sent = 0;
+    if (!(await has(storage, key))) {
+      if (joinable && prefix === had.sha && size > had.size && await has(storage, had.key)) {
+        try { await storage.extend(key, had.key, copy, had.size); sent = size - had.size; } catch { /* sent whole below */ }
+      }
+      if (!sent) {
+        if (storage.putFile) await storage.putFile(key, copy);
+        else await storage.put(key, fs.readFileSync(copy));
+        sent = size;
+      }
+    }
+    if (record) {
+      try {
+        const tmp = `${record}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify({ period: periodOf(now), key, size, sha: whole }));
+        fs.renameSync(tmp, record);
+      } catch { /* the next send goes whole */ }
+    }
+    return { key, size, sent };
+  } finally {
+    fs.rmSync(copy, { force: true });
+  }
+}
+
+const git = (cwd, args) => run('git', args, { cwd });
+const gitOk = (cwd, args) => git(cwd, args).then(() => true, () => false);
+
+async function mergeBase(cwd) {
+  for (const r of ['refs/remotes/origin/main', 'refs/heads/main']) {
+    try { return (await git(cwd, ['merge-base', 'HEAD', r])).trim(); } catch { /* not there */ }
+  }
+  return (await git(cwd, ['rev-parse', 'HEAD'])).trim();
+}
+
+const baseRecordPath = (cwd) => {
+  const common = commonGitDirOf(cwd);
+  return common ? path.join(common, 'agentbox-cloud-base.json') : null;
+};
+
+/**
+ * The commit this run's history is sent against, and its bundle's name in the
+ * bucket. Kept beside the repository so every thread of it shares one base for
+ * the period; made afresh, from where the branch meets main, when the period
+ * has turned or the bucket no longer has it.
+ */
+export async function pickBase(cwd, storage, { now = Date.now(), runId = crypto.randomUUID() } = {}) {
+  const record = baseRecordPath(cwd);
+  const period = periodOf(now);
+  let had = null;
+  try { had = JSON.parse(fs.readFileSync(record, 'utf8')); } catch { /* none yet */ }
+  if (had?.period === period && /^[0-9a-f]{40,64}$/.test(had.sha || '')
+    && await gitOk(cwd, ['cat-file', '-e', `${had.sha}^{commit}`])) {
+    const key = cacheKey(`base-${had.sha}.bundle`, now);
+    if (await storage.exists(key).catch(() => false)) return { sha: had.sha, key, sent: false };
+  }
+  const sha = await mergeBase(cwd);
+  const key = cacheKey(`base-${sha}.bundle`, now);
+  let sent = false;
+  if (!(await storage.exists(key).catch(() => false))) {
+    const ref = `refs/agentbox/cloud-base/${runId}`;
+    const file = path.join(os.tmpdir(), `agentbox-cloud-base-${runId}.bundle`);
+    try {
+      await git(cwd, ['update-ref', ref, sha]);
+      await git(cwd, ['bundle', 'create', '-q', file, ref]);
+      if (storage.putFile) await storage.putFile(key, file);
+      else await storage.put(key, fs.readFileSync(file));
+      sent = true;
+    } finally {
+      fs.rmSync(file, { force: true });
+      await gitOk(cwd, ['update-ref', '-d', ref]);
+    }
+  }
+  if (record) {
+    try {
+      const tmp = `${record}.${process.pid}.${runId}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify({ period, sha }));
+      fs.renameSync(tmp, record);
+    } catch { /* the next run makes its own */ }
+  }
+  return { sha, key, sent };
+}
+
+/**
+ * The commits of `refs` past `base`, as a bundle file, or null when the base
+ * already holds every one of them (git refuses a bundle with nothing in it).
+ */
+export async function bundlePast(cwd, refs, base, file) {
+  const ahead = [];
+  for (const r of refs) if (!(await gitOk(cwd, ['merge-base', '--is-ancestor', r, base]))) ahead.push(r);
+  if (!ahead.length) return null;
+  await git(cwd, ['bundle', 'create', '-q', file, ...ahead, `^${base}`]);
+  return file;
+}
+
+// Each ref the run takes, with the commit it names, so the cloud can set the
+// ones a thin bundle leaves out because the base already holds them.
+export async function refsAt(cwd, refs) {
+  const out = {};
+  for (const r of refs) out[r] = (await git(cwd, ['rev-parse', `${r}^{commit}`])).trim();
+  return out;
+}

package/main/cloud/run-cli.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// THE PROGRAM THE SUPERVISOR STARTS IN PLACE OF `claude` FOR A CLOUD RUN.
+//
+//   ELECTRON_RUN_AS_NODE=1 <electron> main/cloud/run-cli.mjs <claude's argv>
+//
+// Same argv, env and cwd as the local run would have had. Everything it does
+// is main/cloud/run.mjs; this only connects it to the real AWS account named
+// in ~/.agentbox/cloud.json and names this account's cloud sign-in, which
+// lives in the cloud and is never read here (main/cloud/logins.mjs).
+// `cloudRunFromArgs` is the same, for one of many runs sharing a process
+// (main/cloud/host.mjs).
+import fs from 'node:fs';
+import path from 'node:path';
+import { cloudRun, IMPORT_FAILED, LOGIN_TROUBLE } from './run.mjs';
+import { NEW_THREAD, NEW_THREAD_CODEX } from '../../shared/cloud-kit.mjs';
+import { cloudClients } from './clients.mjs';
+import { readCloudConfig, readCloudKey, imageCaps, noteImageCaps } from './config.mjs';
+import { pickCloudLogin, markCloudLogin, loginObjectKey, cloudAccountsFrom, cloudAccountFrom, cloudLoginInUse, noCloudAccountSentence } from './logins.mjs';
+
+// SIGNED AS THE CLOUD RUNS' OWN USER AND NOBODY ELSE. AWS's libraries read
+// keys from the environment before they read a named profile, so an app
+// started from a shell signed in as an admin would run every cloud call as
+// that admin. Those keys go, and the `agentbox-cloud` profile is what signs.
+export function dropAwsSignIns(env = process.env) {
+  for (const k of Object.keys(env)) {
+    if (/^AWS_(ACCESS_KEY_ID|SECRET_ACCESS_KEY|SESSION_TOKEN|SECURITY_TOKEN|PROFILE|DEFAULT_PROFILE|CREDENTIAL_EXPIRATION|WEB_IDENTITY_TOKEN_FILE|ROLE_ARN)$/.test(k)) delete env[k];
+  }
+}
+
+/**
+ * The other sign-ins a run carries besides its own, so the agent can call the
+ * other tool there the way it can on their Mac. A Claude run carries the Codex
+ * account a Codex run would use, when it is ready; a Codex run carries nothing,
+ * because Claude's token is long-lived and Codex's is not. Named only, like the
+ * run's own.
+ */
+export function loginsCarriedBy(engine, { only = null, prefer = null, home } = {}) {
+  if (engine !== 'claude') return [];
+  const codex = pickCloudLogin('codex', { only, prefer, ...(home ? { home } : {}) });
+  return codex ? [{ engine: 'codex', id: codex.id, key: loginObjectKey('codex', codex.id) }] : [];
+}
+
+/**
+ * The cloud account a run of `engine` takes, from the run's own environment:
+ * the test copy's list and the account this Mac runs on. With none to take,
+ * `trouble` is why.
+ */
+export function loginForCloudRun(engine, env, { home, now = Date.now() } = {}) {
+  const ask = { only: cloudAccountsFrom(env), prefer: cloudAccountFrom(env, engine), now, ...(home ? { home } : {}) };
+  const rec = pickCloudLogin(engine, ask);
+  return { rec, trouble: rec ? null : noCloudAccountSentence(engine, cloudLoginInUse(engine, ask), { now }) };
+}
+
+// One client pair per account and cloud key, shared by every run in a process.
+const clients = new Map();
+function clientsFor(config) {
+  const k = JSON.stringify([config, typeof config.gateway === 'string' ? readCloudKey() : null]);
+  if (!clients.has(k)) clients.set(k, cloudClients(config).catch((err) => { clients.delete(k); throw err; }));
+  return clients.get(k);
+}
+
+/** One cloud run from the relay's own arguments; resolves to its exit code. */
+export async function cloudRunFromArgs({ args, env, cwd, stdin, stdout, stderr, signals, pid, watchParent }) {
+  const say = (m) => stderr.write(`agentbox cloud: ${m}\n`);
+  const config = readCloudConfig();
+  if (!config) { say('cloud runs are not set up on this Mac (run scripts/cloud-setup.mjs)'); return 1; }
+  // `--agentbox-import-only`: bring an earlier run in this folder home, and
+  // start nothing (Supervisor#_bringCloudHome).
+  // `--agentbox-codex app-server ...`: a Codex run, its own `codex app-server`
+  // in the sandbox, on the Codex login CODEX_HOME names.
+  // `--agentbox-kit <claude's argv>`: leave this thread's next turn ready
+  // for the cloud server to start with the computer shut, and start nothing
+  // (shared/cloud-kit.mjs, Supervisor#_writeKit).
+  const importOnly = args[0] === '--agentbox-import-only';
+  const kitOnly = args[0] === '--agentbox-kit';
+  // A kit for a Codex thread: `--agentbox-kit --agentbox-codex app-server`.
+  const codex = args[0] === '--agentbox-codex' || (kitOnly && args[1] === '--agentbox-codex');
+  const engine = codex ? 'codex' : 'claude';
+  // The cloud account it runs on (main/cloud/logins.mjs pickCloudLogin). The
+  // folder below only says where the conversation is kept.
+  const { rec, trouble } = importOnly ? { rec: null, trouble: null } : loginForCloudRun(engine, env);
+  if (!importOnly && !rec) { say(trouble); return LOGIN_TROUBLE; }
+  const dir = rec?.key;
+  let made;
+  try { made = await clientsFor(config); } catch (err) { say(err.message); return LOGIN_TROUBLE; }
+  const { transport, storage } = made;
+  let kit = null;
+  if (kitOnly) {
+    kit = kitFrom(env);
+    if (!kit) { say('no kit: the thread, its project, this computer or the reply\'s place was not named'); return 1; }
+  }
+  return cloudRun({
+    importOnly,
+    kit,
+    engine,
+    login: rec ? { engine, id: rec.id, key: loginObjectKey(engine, rec.id) } : null,
+    also: rec ? loginsCarriedBy(engine, { only: cloudAccountsFrom(env), prefer: cloudAccountFrom(env, 'codex') }) : [],
+    // A missing or refused login is marked so the menu asks for a new sign-in;
+    // an expired Codex one is left for the supervisor to renew.
+    onLoginTrouble: ({ state, id }) => {
+      if (state === 'expired') markCloudLogin(engine, dir, id, { expiresAt: Date.now() });
+      else markCloudLogin(engine, dir, id, { broken: state });
+    },
+    // An account at its usage limit sits out until it resets; the next run
+    // takes another cloud account, or this Mac.
+    onLimit: ({ until }) => { if (rec) markCloudLogin(engine, dir, rec.id, { limitedUntil: until }); },
+    imageCaps: imageCaps(config),
+    onCaps: (caps) => noteImageCaps(config, caps),
+    remoteCommand: codex ? 'codex' : 'claude',
+    argv: importOnly ? [] : args.slice((codex ? 1 : 0) + (kitOnly ? 1 : 0)),
+    env, cwd, transport, storage,
+    ...(stdin ? { stdin, stdout, stderr } : {}),
+    ...(signals ? { signals } : {}),
+    ...(pid ? { pid } : {}),
+    ...(watchParent !== undefined ? { watchParent } : {}),
+  });
+}
+
+// What the supervisor names for a kit: the thread, its project, this computer
+// as the phone knows it, the reply's place (a file, read once) and where the
+// copy is kept here.
+export function kitFrom(env) {
+  const device = env.AGENTBOX_KIT_DEVICE;
+  const project = env.ZERO_PRODUCT;
+  const item = env.ZERO_ITEM;
+  if (!/^[0-9a-f]{12}$/.test(device || '') || !project || !item || !env.AGENTBOX_KIT_FRAME) return null;
+  let frame = null;
+  try { frame = JSON.parse(fs.readFileSync(env.AGENTBOX_KIT_FRAME, 'utf8')); } catch { return null; }
+  fs.rmSync(env.AGENTBOX_KIT_FRAME, { force: true });
+  if (typeof frame?.before !== 'string' || typeof frame?.after !== 'string') return null;
+  const codex = env.AGENTBOX_KIT_CODEX ? codexKitAsked(env.AGENTBOX_KIT_CODEX) : undefined;
+  if (codex === null) return null;
+  const newThread = env.AGENTBOX_KIT_NEW ? newThreadAsked(env.AGENTBOX_KIT_NEW) : undefined;
+  if (newThread === null) return null;
+  return {
+    device, project, item: newThread ? (codex ? NEW_THREAD_CODEX : NEW_THREAD) : item, frame: { before: frame.before, after: frame.after }, copy: env.AGENTBOX_KIT_COPY || null,
+    ...(codex ? { codex } : {}), ...(newThread ? { newThread } : {}),
+  };
+}
+
+// A project's kit for a new thread (Supervisor#_leaveNewThreadKit) names where
+// the thread's folder will be, its first prompt with the marks, and the model
+// and effort its command line runs, in a file read once.
+function newThreadAsked(file) {
+  let n = null;
+  try { n = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+  fs.rmSync(file, { force: true });
+  if (typeof n?.cwd !== 'string' || !path.isAbsolute(n.cwd) || typeof n.brief !== 'string') return null;
+  return {
+    cwd: n.cwd, brief: n.brief, model: typeof n.model === 'string' ? n.model : null, effort: typeof n.effort === 'string' ? n.effort : null,
+    // The engine the project gives a new thread nobody chose one for.
+    ...(n.defaultEngine === 'claude' || n.defaultEngine === 'codex' ? { defaultEngine: n.defaultEngine } : {}),
+  };
+}
+
+// A Codex thread's kit also names the thread to resume and its turn's
+// settings (Supervisor#_writeKit), in a file read once; a new thread's names
+// the thread to start instead (Supervisor#_leaveCodexNewThreadKit).
+function codexKitAsked(file) {
+  let asked = null;
+  try { asked = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+  fs.rmSync(file, { force: true });
+  if (asked?.start && typeof asked.start === 'object' && asked.turn && typeof asked.turn === 'object' && asked.turn.threadId === undefined) return { start: asked.start, turn: asked.turn };
+  if (typeof asked?.resume?.threadId !== 'string' || typeof asked?.turn?.threadId !== 'string') return null;
+  return { resume: asked.resume, turn: asked.turn };
+}
+
+// Run as a program, not imported by the host: by the file's name, which holds
+// inside the packaged app's archive as well as out of it.
+const startedAsProgram = path.basename(process.argv[1] || '') === 'run-cli.mjs';
+if (startedAsProgram) {
+  dropAwsSignIns();
+  cloudRunFromArgs({ args: process.argv.slice(2), env: process.env, cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr }).then(
+    (code) => process.exit(code ?? 1),
+    (err) => { process.stderr.write(`agentbox cloud: stopped: ${err?.message || err}\n`); process.exit(IMPORT_FAILED); },
+  );
+}