@yanzc/claude-pro 0.0.0-stage → 0.4.1

package/src/oauth.js

@@ -0,0 +1,287 @@
+// Renewing the Claude Code subscription login.
+//
+// The access token in ~/.claude/.credentials.json lives 8 hours. The official client renews it when it
+// is used, with the refresh token stored next to it, and so does this program now: a token that is
+// expired or about to be is renewed before a request is sent, instead of failing and asking the user to
+// go and run `claude`.
+//
+// Renewing rotates the refresh token: the server answers with a new one and the old one stops working.
+// So the new tokens must reach the credentials file, or the official client (which reads the same file)
+// is left holding a dead one, and nobody may renew at the same moment as somebody else. The protocol is
+// the official client's, read from its code:
+//   - two directory locks (proper-lockfile style: mkdir to take it, rmdir to release, the holder touches
+//     it every 5 s, one not touched for 60 s is stale): <config dir>/.oauth_refresh.lock and, for older
+//     versions, <config dir>.lock, taken in that order;
+//   - after getting the locks, read the file again: whoever held them may just have renewed it;
+//   - the request: POST {grant_type: "refresh_token", refresh_token, client_id, scope} as JSON to
+//     the token endpoint; the answer has access_token, expires_in and, normally, a new refresh_token;
+//   - a refresh token that is rejected may have been used by another process a moment ago: look in the
+//     file before giving up.
+// Only the token fields of the file are changed, and it is replaced atomically.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const OAUTH_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
+export const OAUTH_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
+
+const REFRESH_MARGIN_MS = 5 * 60_000; // renew when this close to expiry, like the official client
+const LOCK_STALE_MS = 60_000;
+const LOCK_UPDATE_MS = 5_000;
+const LOCK_WAIT_MS = 30_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+
+// The token endpoint. Only tests replace it: it is deliberately not a setting, because the refresh token
+// is sent there, and a setting can come from a .env file or a settings file of whatever project is open.
+export const endpoint = { url: OAUTH_TOKEN_URL };
+
+export const timing = { // replaceable so tests need not wait
+  now: () => Date.now(),
+  sleep: (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortError());
+    const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
+    const onAbort = () => { clearTimeout(timer); reject(abortError()); };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  }),
+};
+
+const abortError = () => Object.assign(new Error('aborted'), { name: 'AbortError' });
+
+// What the credentials file holds, or null when it cannot be read.
+export function readStoredLogin(file) {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    const json = JSON.parse(text.replace(/^\uFEFF/, ''));
+    return { json, oauth: json?.claudeAiOauth || null, text };
+  } catch {
+    return null;
+  }
+}
+
+export function needsRefresh(oauth, now = timing.now()) {
+  const expiresAt = Number(oauth?.expiresAt);
+  return Number.isFinite(expiresAt) && expiresAt > 0 && now + REFRESH_MARGIN_MS >= expiresAt;
+}
+
+const isExpired = (oauth, now = timing.now()) => Number(oauth?.expiresAt) > 0 && Number(oauth.expiresAt) <= now;
+
+// ---------------------------------------------------------------- locks
+
+async function takeLock(lockPath, signal) {
+  const began = timing.now();
+  for (;;) {
+    try {
+      fs.mkdirSync(lockPath);
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      let age;
+      try {
+        age = timing.now() - fs.statSync(lockPath).mtimeMs;
+      } catch (statErr) {
+        if (statErr.code === 'ENOENT') continue; // released just now: take it
+        throw statErr;
+      }
+      if (age > LOCK_STALE_MS) { // its holder is gone
+        try { fs.rmdirSync(lockPath); } catch { /* somebody else took it over first */ }
+        continue;
+      }
+      if (timing.now() - began > LOCK_WAIT_MS) throw Object.assign(new Error(`Another process has held ${lockPath} for ${Math.round(LOCK_WAIT_MS / 1000)} seconds.`), { code: 'ELOCKED' });
+      await timing.sleep(250 + Math.floor(Math.random() * 250), signal);
+    }
+  }
+  const touch = setInterval(() => { try { const t = new Date(); fs.utimesSync(lockPath, t, t); } catch { /* released */ } }, LOCK_UPDATE_MS);
+  touch.unref?.();
+  return () => {
+    clearInterval(touch);
+    try { fs.rmdirSync(lockPath); } catch { /* already gone */ }
+  };
+}
+
+// Both of the official client's locks. Returns the function that lets go of them.
+async function lockLoginFile(file, signal) {
+  const dir = path.dirname(file);
+  const release = [];
+  try {
+    release.push(await takeLock(path.join(dir, '.oauth_refresh.lock'), signal));
+    release.push(await takeLock(`${dir}.lock`, signal));
+  } catch (err) {
+    for (const fn of release.reverse()) fn();
+    throw err;
+  }
+  return () => { for (const fn of release.reverse()) fn(); };
+}
+
+// ---------------------------------------------------------------- writing the file
+
+function replaceFile(file, text) {
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, text, { mode: 0o600 });
+  try {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        fs.renameSync(tmp, file);
+        return;
+      } catch (err) {
+        // On Windows the file may be open in another process for a moment.
+        if (attempt >= 8 || !['EPERM', 'EBUSY', 'EACCES'].includes(err.code)) throw err;
+        const until = Date.now() + 40 * attempt;
+        while (Date.now() < until) { /* a short blocking wait: this is a rare, tiny operation */ }
+      }
+    }
+  } finally {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best effort */ }
+  }
+}
+
+// Put the new tokens into the file, keeping everything else in it as it is (and its layout).
+function storeTokens(file, tokens, now) {
+  const stored = readStoredLogin(file);
+  if (!stored) throw new Error(`Could not read ${file} to store the renewed login.`);
+  const oauth = { ...(stored.oauth || {}) };
+  oauth.accessToken = tokens.accessToken;
+  oauth.refreshToken = tokens.refreshToken;
+  oauth.expiresAt = now + tokens.expiresInSec * 1000;
+  if (tokens.refreshExpiresInSec) oauth.refreshTokenExpiresAt = now + tokens.refreshExpiresInSec * 1000;
+  if (tokens.scopes?.length) oauth.scopes = tokens.scopes;
+  const json = { ...stored.json, claudeAiOauth: oauth };
+  const indent = /^\uFEFF?\{\r?\n([ \t]+)"/.exec(stored.text)?.[1];
+  const text = JSON.stringify(json, null, indent) + (/\n$/.test(stored.text) ? '\n' : '');
+  replaceFile(file, text);
+  // what was written is what is read back: a renewed token that did not reach the file is worse than none
+  const check = readStoredLogin(file);
+  if (check?.oauth?.accessToken !== tokens.accessToken || check?.oauth?.refreshToken !== tokens.refreshToken) {
+    throw new Error(`The renewed login was not saved correctly in ${file}.`);
+  }
+}
+
+// ---------------------------------------------------------------- the request
+
+// The server's own words about a failure, without anything that could be a token.
+function describeFailure(data) {
+  const text = [data?.error, data?.error_description || data?.error?.message].filter((x) => typeof x === 'string').join(': ');
+  return text.replace(/[A-Za-z0-9_-]{40,}/g, '…').slice(0, 200);
+}
+
+async function requestTokens(config, { refreshToken, scopes, signal }) {
+  const url = endpoint.url;
+  const post = async (withScope) => {
+    const body = { grant_type: 'refresh_token', refresh_token: refreshToken, client_id: OAUTH_CLIENT_ID };
+    if (withScope && scopes?.length) body.scope = scopes.join(' ');
+    const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': 'claude-cli (external, cli)' },
+      body: JSON.stringify(body),
+      signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+    });
+    let data = null;
+    try { data = await res.json(); } catch { /* not JSON */ }
+    return { status: res.status, data };
+  };
+  let res = await post(true);
+  // a scope the server does not know (any more): renewing without one keeps the scopes the token had
+  if (res.status === 400 && /invalid_scope/i.test(JSON.stringify(res.data?.error ?? '')) && scopes?.length) res = await post(false);
+  return res;
+}
+
+function parseTokens(data, oldRefreshToken) {
+  if (typeof data?.access_token !== 'string' || !data.access_token || !(Number(data.expires_in) > 0)) return null;
+  return {
+    accessToken: data.access_token,
+    refreshToken: typeof data.refresh_token === 'string' && data.refresh_token ? data.refresh_token : oldRefreshToken,
+    expiresInSec: Number(data.expires_in),
+    refreshExpiresInSec: Number(data.refresh_token_expires_in) > 0 ? Number(data.refresh_token_expires_in) : null,
+    scopes: typeof data.scope === 'string' && data.scope.trim() ? data.scope.trim().split(/\s+/) : null,
+  };
+}
+
+// ---------------------------------------------------------------- renewing
+
+const SIGN_IN_AGAIN = 'Sign in again: run `claude` and use /login.';
+
+async function renew(config, { force }) {
+  const signal = undefined; // one renewal serves every caller in the process, so none of them cancels it
+  const file = config.claudeCodeCredentialsFile;
+  const first = readStoredLogin(file);
+  const oauth = first?.oauth;
+  if (!oauth?.refreshToken) return { refreshed: false, reason: 'no refresh token' };
+  if (!force && !needsRefresh(oauth)) return { refreshed: false, reason: 'still valid' };
+  if (Number(oauth.refreshTokenExpiresAt) > 0 && Number(oauth.refreshTokenExpiresAt) <= timing.now()) {
+    throw new Error(`The Claude Code login has expired and cannot be renewed: its refresh token ran out. ${SIGN_IN_AGAIN}`);
+  }
+  const startedWith = oauth.accessToken;
+  // somebody else renewed it while we were looking: take theirs
+  const renewedElsewhere = () => {
+    const now = readStoredLogin(file)?.oauth;
+    return now && now.accessToken !== startedWith && !needsRefresh(now) ? now : null;
+  };
+  const failed = (why) => {
+    const now = readStoredLogin(file)?.oauth;
+    // renewing early failed but the token still works: carry on with it (unless renewing was asked for)
+    if (!force && now && !isExpired(now)) return { refreshed: false, reason: why, stillValid: true };
+    throw new Error(force ? `The Claude Code login could not be renewed: ${why}` : `The Claude Code access token has expired and could not be renewed: ${why}`);
+  };
+
+  let release;
+  try {
+    release = await lockLoginFile(file, signal);
+  } catch (err) {
+    if (err.name === 'AbortError') throw err;
+    if (renewedElsewhere()) return { refreshed: false, reason: 'renewed by another process' };
+    return failed(err.message);
+  }
+  try {
+    if (renewedElsewhere()) return { refreshed: false, reason: 'renewed by another process' };
+    const current = readStoredLogin(file)?.oauth || oauth;
+    let res;
+    try {
+      res = await requestTokens(config, { refreshToken: current.refreshToken, scopes: current.scopes, signal });
+    } catch (err) {
+      return failed(err.name === 'TimeoutError' ? 'the token server did not answer in time' : `the token server could not be reached (${err.cause?.code || err.message})`);
+    }
+    if (res.status === 200) {
+      const tokens = parseTokens(res.data, current.refreshToken);
+      if (!tokens) return failed('the token server sent an answer that is not a login');
+      storeTokens(file, tokens, timing.now());
+      return { refreshed: true, expiresAt: timing.now() + tokens.expiresInSec * 1000 };
+    }
+    // The refresh token was refused. Another process may have used it a moment ago and already stored the
+    // new one: look before giving up.
+    if (res.status === 400 || res.status === 401 || res.status === 403) {
+      if (renewedElsewhere()) return { refreshed: false, reason: 'renewed by another process' };
+      throw new Error(`The Claude Code login can no longer be renewed (${describeFailure(res.data) || `HTTP ${res.status}`}). ${SIGN_IN_AGAIN}`);
+    }
+    return failed(`the token server answered HTTP ${res.status}${describeFailure(res.data) ? ` (${describeFailure(res.data)})` : ''}`);
+  } finally {
+    release();
+  }
+}
+
+const inflight = new Map();
+
+const refreshDisabled = (config) => /^(1|true|yes)$/i.test(config.env?.CLAUDE_PRO_DISABLE_TOKEN_REFRESH || '');
+
+// Whether this program is able to renew the login by itself: switched on, and the file has a refresh
+// token that has not run out. (Whether the server will accept it is only known by asking.)
+export function canRenewLogin(config) {
+  if (refreshDisabled(config)) return false;
+  const oauth = readStoredLogin(config.claudeCodeCredentialsFile)?.oauth;
+  if (!oauth?.refreshToken) return false;
+  return !(Number(oauth.refreshTokenExpiresAt) > 0 && Number(oauth.refreshTokenExpiresAt) <= timing.now());
+}
+
+// Renew the login in the credentials file if it is expired or about to expire (always with `force`).
+// Resolves {refreshed, reason}; throws only when the login is unusable and could not be renewed: a
+// failure to renew a token that still has a few minutes left is not an error. Callers in the same
+// process share one renewal; `signal` only stops this caller from waiting for it.
+export async function refreshClaudeCodeLogin(config, { signal, force = false } = {}) {
+  if (refreshDisabled(config)) return { refreshed: false, reason: 'disabled' };
+  if (signal?.aborted) throw abortError();
+  const key = config.claudeCodeCredentialsFile;
+  if (!inflight.has(key)) inflight.set(key, renew(config, { force }).finally(() => inflight.delete(key)));
+  const shared = inflight.get(key);
+  if (!signal) return shared;
+  return Promise.race([shared, new Promise((resolve, reject) => signal.addEventListener('abort', () => reject(abortError()), { once: true }))]);
+}

package/src/peers.js

@@ -0,0 +1,157 @@
+// Peers: the other interactive claude-pro sessions on this machine. Each session registers itself in
+// CONFIG_DIR/peers/<id>.json (name, directory, pid, and a port and token of a small HTTP server on 127.0.0.1)
+// so that sessions can send each other tasks: the user with `@name task` in the input box, the model with the
+// MessagePeer tool. A task is answered automatically with the final text of the turn that handled it.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { CONFIG_DIR } from './config.js';
+
+export const PEERS_DIR = path.join(CONFIG_DIR, 'peers');
+const MAX_BODY = 2_000_000;
+
+export function peersEnabled(env = process.env) {
+  return !/^(0|false|no|off)$/i.test(env.CLAUDE_PRO_PEERS || '');
+}
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+export const cleanName = (s) => String(s || '').replace(/[^\w.-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, 40) || 'agent';
+
+// The sessions that are running now (stale entries of sessions that died are removed).
+export function listPeers({ excludeId } = {}) {
+  let files = [];
+  try { files = fs.readdirSync(PEERS_DIR).filter((f) => f.endsWith('.json')); } catch { return []; }
+  const peers = [];
+  for (const f of files) {
+    const file = path.join(PEERS_DIR, f);
+    let p;
+    try { p = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { continue; }
+    if (!p?.id || !p.port || !alive(p.pid)) { try { fs.unlinkSync(file); } catch { /* ignore */ } continue; }
+    if (p.id !== excludeId) peers.push(p);
+  }
+  return peers.sort((a, b) => a.startedAt - b.startedAt);
+}
+
+export function findPeer(peers, ref) {
+  const q = String(ref || '').replace(/^@/, '').toLowerCase();
+  if (!q) return null;
+  return peers.find((p) => p.name.toLowerCase() === q) || peers.find((p) => p.id.startsWith(q)) || null;
+}
+
+export class PeerNode {
+  // onMessage(msg): msg = {id, kind: 'task'|'reply', text, inReplyTo, from: {id, name, cwd}}
+  // `id`: the id this session had before a restart, so that answers on their way still find it.
+  constructor({ cwd, name, id, onMessage }) {
+    this.cwd = cwd;
+    this.wantedName = name || null;
+    this.onMessage = onMessage;
+    this.id = /^[0-9a-f]{12}$/.test(id || '') ? id : crypto.randomBytes(6).toString('hex');
+    this.token = crypto.randomBytes(16).toString('hex');
+    this.name = null;
+    this.server = null;
+    this.port = null;
+  }
+
+  get file() { return path.join(PEERS_DIR, `${this.id}.json`); }
+
+  async start() {
+    this.server = http.createServer((req, res) => this.handle(req, res));
+    await new Promise((resolve, reject) => {
+      this.server.once('error', reject);
+      this.server.listen(0, '127.0.0.1', resolve);
+    });
+    this.server.unref();
+    this.port = this.server.address().port;
+    this.setName(this.wantedName || path.basename(this.cwd) || 'agent');
+    return this;
+  }
+
+  // Take `name`, or name-2, name-3... when another live session has it. Returns the name taken.
+  setName(name) {
+    const base = cleanName(name);
+    const taken = new Set(listPeers({ excludeId: this.id }).map((p) => p.name.toLowerCase()));
+    let n = base;
+    for (let i = 2; taken.has(n.toLowerCase()); i++) n = `${base}-${i}`;
+    this.name = n;
+    this.write();
+    return n;
+  }
+
+  setCwd(cwd) {
+    if (cwd === this.cwd) return;
+    this.cwd = cwd;
+    this.write();
+  }
+
+  write() {
+    if (!this.port) return;
+    fs.mkdirSync(PEERS_DIR, { recursive: true });
+    const data = { id: this.id, name: this.name, cwd: this.cwd, pid: process.pid, port: this.port, token: this.token, startedAt: this.startedAt ??= Date.now() };
+    fs.writeFileSync(this.file, JSON.stringify(data));
+  }
+
+  peers() { return listPeers({ excludeId: this.id }); }
+
+  close() {
+    try { fs.unlinkSync(this.file); } catch { /* ignore */ }
+    try { this.server?.close(); } catch { /* ignore */ }
+    this.port = null;
+  }
+
+  handle(req, res) {
+    const reply = (code, body) => { res.writeHead(code, { 'content-type': 'application/json' }); res.end(JSON.stringify(body)); };
+    if (req.method !== 'POST' || req.url !== '/message') return reply(404, { error: 'not found' });
+    if (req.headers.authorization !== `Bearer ${this.token}`) return reply(401, { error: 'bad token' });
+    let body = '';
+    req.setEncoding('utf8');
+    req.on('data', (d) => { body += d; if (body.length > MAX_BODY) req.destroy(); });
+    req.on('end', () => {
+      let msg;
+      try { msg = JSON.parse(body); } catch { return reply(400, { error: 'bad json' }); }
+      if (typeof msg?.text !== 'string' || !msg.from?.name) return reply(400, { error: 'text and from are required' });
+      const id = crypto.randomBytes(4).toString('hex');
+      reply(200, { ok: true, id, name: this.name });
+      try { this.onMessage?.({ id, kind: msg.kind === 'reply' ? 'reply' : 'task', text: msg.text, inReplyTo: msg.inReplyTo || null, from: msg.from }); } catch { /* the receiver's problem */ }
+    });
+  }
+
+  // Send to a peer (an entry of peers(), or its name). Resolves with {id} (the id the receiver gave the message).
+  async send(target, { text, kind = 'task', inReplyTo = null }) {
+    const peer = typeof target === 'string' ? findPeer(this.peers(), target) : target;
+    if (!peer) throw new Error(`No running session called "${target}". /peers lists them.`);
+    const body = JSON.stringify({ kind, text, inReplyTo, from: { id: this.id, name: this.name, cwd: this.cwd } });
+    return await new Promise((resolve, reject) => {
+      const req = http.request({
+        host: '127.0.0.1', port: peer.port, path: '/message', method: 'POST', timeout: 10_000,
+        headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body), authorization: `Bearer ${peer.token}` },
+      }, (res) => {
+        let out = '';
+        res.setEncoding('utf8');
+        res.on('data', (d) => { out += d; });
+        res.on('end', () => {
+          let data = {};
+          try { data = JSON.parse(out); } catch { /* ignore */ }
+          if (res.statusCode !== 200) reject(new Error(`${peer.name} refused the message: ${data.error || res.statusCode}`));
+          else resolve({ id: data.id, peer });
+        });
+      });
+      req.on('timeout', () => req.destroy(new Error(`${peer.name} did not answer`)));
+      req.on('error', (e) => reject(new Error(`Could not reach ${peer.name}: ${e.message}`)));
+      req.end(body);
+    });
+  }
+}
+
+// What the model is given for a message from another session.
+export function peerMessagePrompt(msg) {
+  const from = `${msg.from.name}${msg.from.cwd ? ` (working in ${msg.from.cwd})` : ''}`;
+  if (msg.kind === 'reply') {
+    return `<peer-message from="${msg.from.name}" kind="reply">\n${msg.text}\n</peer-message>\n<system-reminder>This is the answer of another ${'claude-pro'} session, ${from}, to a message you sent it with MessagePeer. Carry on with your task using it.</system-reminder>`;
+  }
+  return `<peer-message from="${msg.from.name}" kind="task">\n${msg.text}\n</peer-message>\n<system-reminder>This task was sent to you by another claude-pro session, ${from}, not typed by your user. Do it as you would a request of the user. The final text of your answer is sent back to ${msg.from.name} automatically, so end with a self-contained report of what you did or found.</system-reminder>`;
+}

package/src/print.js

@@ -0,0 +1,106 @@
+// Non-interactive mode: `claude-pro -p "prompt"`. Prints only the final answer to stdout
+// (or JSON), tool activity goes to stderr with --verbose.
+
+import { createRuntime } from './runtime.js';
+import { SessionStore } from './session.js';
+import { describePause, shouldAnnounce } from './ratelimit.js';
+import { c } from './ui/ansi.js';
+
+export async function runPrint({ prompt, flags, cwd, stdout = process.stdout, stderr = process.stderr }) {
+  const format = flags.outputFormat || 'text';
+  const err = (s) => stderr.write(s + '\n');
+  const emit = (obj) => stdout.write(JSON.stringify(obj) + '\n');
+  // A pause can last hours: always say so, or the run looks hung. `who` names a sub-agent. A reporter
+  // remembers the pause it announced, so the waits that only continue it (polling) are not repeated.
+  const rateLimitReporter = (who = '') => {
+    let paused = null;
+    return (ev) => {
+      if (ev.type === 'rate_limit_wait') {
+        if (shouldAnnounce(paused, ev)) err(c.yellow(who + describePause(ev)));
+        paused = { resumeAt: ev.resumeAt, waitingForLogin: Boolean(ev.waitingForLogin) };
+      }
+      if (ev.type === 'rate_limit_resume') {
+        paused = null;
+        err(c.yellow(`${who}The limit has cleared; continuing.`));
+      }
+    };
+  };
+  const mainRateLimit = rateLimitReporter();
+  const io = {
+    approvePlan: async () => 'reject', // non-interactive: a plan is only presented, never executed
+    askQuestion: async () => null,
+    notice: (text) => err(c.yellow(text)),
+    toolStart: (tu, tool, input, agent) => {
+      if (flags.verbose) err(c.gray(`⏺ ${tool.name}(${tool.summarize?.(input, agent.makeCtx()) ?? ''})`));
+      return {};
+    },
+    assistantMessage: (msg) => { if (format === 'stream-json') emit({ type: 'assistant', message: msg }); },
+    messageAdded: (msg) => { store.message(msg); if (format === 'stream-json' && msg.role === 'user') emit({ type: 'user', message: msg }); },
+    messagesReplaced: (msgs) => store.reset(msgs),
+    systemPrompt: (text) => store.setSystemPrompt(text),
+    compactStart: (auto) => { if (flags.verbose) err(c.gray(`✻ ${auto ? 'Auto-compacting' : 'Compacting'} conversation…`)); },
+    streamEvent: (ev) => {
+      if (ev.type === 'retry' && flags.verbose) err(c.yellow(`API error (${ev.error.message}), retrying in ${Math.round(ev.delayMs / 1000)}s…`));
+      mainRateLimit(ev);
+    },
+    compactProgress: (ev) => mainRateLimit(ev),
+    // Sub-agents have no screen of their own here; their pauses are still reported, whether it is a
+    // turn or the compaction of their own conversation that is paused.
+    subagentIo: ({ def }) => {
+      const report = rateLimitReporter(`[${def.name}] `);
+      return { streamEvent: report, compactProgress: report };
+    },
+  };
+  const runtime = await createRuntime({ cwd, flags, io });
+  let store = new SessionStore(cwd);
+  if (flags.resumeFile) {
+    const loaded = SessionStore.load(flags.resumeFile);
+    runtime.agent.messages = loaded.messages;
+    runtime.agent.restoreFileState(loaded.messages, loaded.times);
+    runtime.agent.lastActivityAt = loaded.lastAt;
+    store = new SessionStore(cwd, flags.resumeId);
+    store.systemPrompt = loaded.systemPrompt;
+    runtime.resumeSystemPrompt(loaded.systemPrompt); // continue behind the prompt (and the cache) the conversation had
+  }
+  const ctrl = new AbortController();
+  const onSigint = () => ctrl.abort();
+  process.on('SIGINT', onSigint);
+  const started = Date.now();
+  let result;
+  try {
+    result = await runtime.agent.run(prompt, { signal: ctrl.signal });
+    // Background agents report back before we exit, so their work is part of the answer.
+    while (!result.interrupted && !ctrl.signal.aborted && (runtime.tasks.running().length || runtime.agent.notifications.length)) {
+      if (!runtime.agent.notifications.length) {
+        if (flags.verbose) err(c.gray(`… waiting for ${runtime.tasks.running().length} background agent(s)`));
+        await Promise.race([runtime.tasks.waitAny(), new Promise((r) => ctrl.signal.addEventListener('abort', r, { once: true }))]);
+        continue;
+      }
+      result = await runtime.agent.run(runtime.agent.drainNotifications(), { signal: ctrl.signal });
+    }
+  } catch (e) {
+    if (format === 'json') emit({ type: 'result', is_error: true, error: e.message });
+    else err(c.red(`Error: ${e.message}`));
+    runtime.tasks.killAll(); runtime.mcp.close();
+    return 1;
+  } finally {
+    process.off('SIGINT', onSigint);
+  }
+  const a = runtime.agent;
+  const used = a.totalUsage(); // sub-agents and compactions are billed too
+  if (format === 'json' || format === 'stream-json') {
+    emit({
+      type: 'result',
+      is_error: false,
+      result: result.text,
+      session_id: store.id,
+      duration_ms: Date.now() - started,
+      num_turns: a.usage.requests,
+      usage: { input_tokens: used.input, output_tokens: used.output, cache_read_input_tokens: used.cacheRead, cache_creation_input_tokens: used.cacheWrite },
+    });
+  } else {
+    stdout.write(result.text + '\n');
+  }
+  runtime.tasks.killAll(); runtime.mcp.close();
+  return result.interrupted ? 130 : 0;
+}