aegiscode 6.3.1 → 6.4.0

package/src/credentials.js

@@ -0,0 +1,323 @@
+'use strict';
+
+/**
+ * The AEGIS account credential store for the terminal host.
+ *
+ * Before this module the CLI had exactly one way to be given a key: an
+ * `AEGIS_API_KEY` environment variable, checked as `process.env.AEGIS_API_KEY`
+ * at five separate call sites. A shell export does not survive a new terminal,
+ * a reboot, an SSH session or a desktop launcher, so every one of those turned
+ * the product back into "no key — export one" with no in-band way to fix it:
+ * `/byok-set` stores *provider* keys server-side and `/login` is one of the
+ * reference commands this host deliberately marks unavailable. The only
+ * credential the CLI could not accept was its own.
+ *
+ * Resolution order, first hit wins:
+ *
+ *   1. `AEGIS_API_KEY` — the environment, so CI and `--key` keep working and
+ *      nothing written here can shadow an explicit export.
+ *   2. `credentials.json` in the data dir, mode 0600. The writable store.
+ *   3. `config.json`'s `aegiscloud.api_key` / `memory.token` — the shape an
+ *      earlier AEGIS CLI left in the same data dir. Read, never written, and
+ *      never deleted: it is another product's file and the user's key is in
+ *      it. When one is found it is *also* copied into credentials.json so the
+ *      next run reads the 0600 copy, and `/cloud status` says the plaintext
+ *      copy is still there rather than silently leaving it.
+ *
+ * The key is never printed in full by anything in this package; callers mask it
+ * with format.js's maskKey.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { aegisDir, configPath } = require('./config.js');
+
+const KEY_ENV = 'AEGIS_API_KEY';
+/** Optional override for the memory token (cloud sync's own credential). */
+const MEMORY_ENV = 'AEGIS_MEMORY_TOKEN';
+const CREDENTIALS_FILE = 'credentials.json';
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+
+function credentialsPath() {
+  return path.join(aegisDir(), CREDENTIALS_FILE);
+}
+
+/**
+ * Accept the key in the shapes a user actually pastes it.
+ *
+ * Copy-paste from a dashboard, a `.env` line, a shell profile or a chat message
+ * are all realistic — and pasting `AEGIS_API_KEY=aegis_…` or `"aegis_…"` into a
+ * prompt that stores the literal string produces an auth failure the user
+ * cannot see the cause of, because the key *looks* right in the status line.
+ */
+function normalizeApiKey(raw) {
+  let s = String(raw == null ? '' : raw).trim();
+  if (!s) return '';
+  s = s.replace(/^export\s+/i, '').trim();
+  const assignment = /^[A-Za-z_][A-Za-z0-9_]*\s*=\s*(.+)$/s.exec(s);
+  if (assignment) s = assignment[1].trim();
+  s = s.replace(/^["']|["']$/g, '').trim();
+  s = s.replace(/^Bearer\s+/i, '').trim();
+  return s;
+}
+
+/**
+ * Shape check only — no network. Catches the two mistakes that are structural
+ * (an empty paste, and a wrapped/truncated multi-line paste) so the caller can
+ * refuse before spending a verification round trip.
+ */
+function validateApiKey(raw) {
+  const key = normalizeApiKey(raw);
+  if (!key) return { ok: false, key, reason: 'empty', message: 'no key given' };
+  if (/\s/.test(key)) {
+    return {
+      ok: false,
+      key,
+      reason: 'whitespace',
+      message: 'that looks like more than one word — paste just the key',
+    };
+  }
+  if (key.length < 16) {
+    return {
+      ok: false,
+      key,
+      reason: 'too short',
+      message: `that key is ${key.length} characters — AEGIS keys are longer than that`,
+    };
+  }
+  return { ok: true, key, reason: null, message: null };
+}
+
+/** The stored credential object, or {} — never throws on a missing/corrupt file. */
+function readCredentials() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(credentialsPath(), 'utf8'));
+    if (parsed && typeof parsed === 'object') return parsed;
+  } catch {}
+  return {};
+}
+
+/**
+ * Merge a patch into the store, creating it 0600 (and tightening an existing
+ * file that is wider — a key file that a previous run left 0644 is exactly the
+ * leak this file exists to avoid).
+ */
+function writeCredentials(patch) {
+  const next = { ...readCredentials(), ...patch, version: 1 };
+  try {
+    fs.mkdirSync(aegisDir(), { recursive: true, mode: DIR_MODE });
+    const target = credentialsPath();
+    const tmp = target + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { mode: FILE_MODE });
+    fs.renameSync(tmp, target);
+    try {
+      fs.chmodSync(target, FILE_MODE);
+    } catch {}
+  } catch (e) {
+    if (process.env.AEGIS_HIST_DEBUG) console.error('[credentials] write failed:', e);
+    return { ok: false, error: e, credentials: next };
+  }
+  return { ok: true, credentials: next };
+}
+
+/**
+ * The key an earlier AEGIS CLI wrote into config.json (the `aegiscloud` /
+ * `memory` blocks are not ours — config.js cannot produce them). Read-only.
+ */
+function readLegacyConfig() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return {};
+    const cloud = parsed.aegiscloud && typeof parsed.aegiscloud === 'object' ? parsed.aegiscloud : {};
+    const memory = parsed.memory && typeof parsed.memory === 'object' ? parsed.memory : {};
+    return {
+      apiKey: normalizeApiKey(cloud.api_key),
+      memoryToken: String(memory.token || '').trim(),
+      syncConversations: cloud.syncConversations === true ? true : undefined,
+      lastVerified: cloud.lastVerified || null,
+      memorySubscribed: memory.subscribed === true ? true : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** True when config.json still carries a plaintext copy of the account key. */
+function legacyKeyOnDisk() {
+  return !!readLegacyConfig().apiKey;
+}
+
+/**
+ * Copy a legacy key/token into the 0600 store, once, without touching the file
+ * it came from. Returns which fields were adopted so the caller can say so.
+ */
+function adoptLegacy() {
+  const legacy = readLegacyConfig();
+  const creds = readCredentials();
+  const patch = {};
+  if (legacy.apiKey && !creds.aegisApiKey) patch.aegisApiKey = legacy.apiKey;
+  if (legacy.memoryToken && !creds.memoryToken) patch.memoryToken = legacy.memoryToken;
+  if (!Object.keys(patch).length) return { adopted: [] };
+  const written = writeCredentials({ ...patch, adoptedFrom: configPath() });
+  if (!written.ok) return { adopted: [] };
+  return { adopted: Object.keys(patch) };
+}
+
+/**
+ * The key to use, and where it came from.
+ *
+ * @returns {{key:string, source:'env'|'credentials'|'config'|'none', from:string}}
+ */
+function resolveApiKey(o = {}) {
+  const env = o.env || process.env;
+  const fromEnv = normalizeApiKey(env && env[KEY_ENV]);
+  if (fromEnv) return { key: fromEnv, source: 'env', from: KEY_ENV };
+
+  const creds = readCredentials();
+  const stored = normalizeApiKey(creds.aegisApiKey);
+  if (stored) return { key: stored, source: 'credentials', from: credentialsPath() };
+
+  const legacy = readLegacyConfig().apiKey;
+  if (legacy) return { key: legacy, source: 'config', from: configPath() };
+
+  return { key: '', source: 'none', from: '' };
+}
+
+/** Whether any credential is available (env, store or legacy config). */
+function hasApiKey(o = {}) {
+  return !!resolveApiKey(o).key;
+}
+
+/**
+ * Persist a key.
+ *
+ * @returns {{ok:boolean, key:string, path:string, error?:Error, message?:string}}
+ */
+function saveApiKey(raw) {
+  const v = validateApiKey(raw);
+  if (!v.ok) return { ok: false, key: v.key, path: credentialsPath(), message: v.message };
+  const written = writeCredentials({ aegisApiKey: v.key, savedAt: new Date().toISOString() });
+  if (!written.ok) {
+    return {
+      ok: false,
+      key: v.key,
+      path: credentialsPath(),
+      error: written.error,
+      message: `could not write ${credentialsPath()}`,
+    };
+  }
+  return { ok: true, key: v.key, path: credentialsPath() };
+}
+
+/**
+ * Remove the stored key (and nothing else — the memory token stays, since a
+ * key rotation should not silently unsubscribe cloud memory). config.json is
+ * never touched: another product writes it.
+ */
+function clearApiKey() {
+  const had = !!normalizeApiKey(readCredentials().aegisApiKey);
+  const written = writeCredentials({ aegisApiKey: '', adoptedFrom: '' });
+  return { cleared: had, ok: written.ok, path: credentialsPath() };
+}
+
+/** The memory token cloud sync authenticates with, from store or legacy. */
+function resolveMemoryToken(o = {}) {
+  const env = o.env || process.env;
+  const fromEnv = String((env && env[MEMORY_ENV]) || '').trim();
+  if (fromEnv) return { token: fromEnv, source: 'env' };
+  const creds = readCredentials();
+  const stored = String(creds.memoryToken || '').trim();
+  if (stored) return { token: stored, source: 'credentials' };
+  const legacy = readLegacyConfig().memoryToken;
+  if (legacy) return { token: legacy, source: 'config' };
+  return { token: '', source: 'none' };
+}
+
+function saveMemoryToken(token, extra = {}) {
+  return writeCredentials({ memoryToken: String(token || '').trim(), ...extra });
+}
+
+function clearMemoryToken() {
+  return writeCredentials({ memoryToken: '', memorySubscribed: false });
+}
+
+/**
+ * Everything a status screen or a `doctor` line needs about the credential,
+ * without ever exposing the key itself.
+ */
+function keyStatus(o = {}) {
+  const { key, source, from } = resolveApiKey(o);
+  const creds = readCredentials();
+  let mode = null;
+  try {
+    mode = fs.statSync(credentialsPath()).mode & 0o777;
+  } catch {}
+  return {
+    configured: !!key,
+    key,
+    source,
+    from,
+    path: credentialsPath(),
+    fileMode: mode == null ? null : '0' + mode.toString(8),
+    stored: !!normalizeApiKey(creds.aegisApiKey),
+    legacyPlaintext: legacyKeyOnDisk(),
+    verifiedAt: creds.verifiedAt || null,
+    account: creds.account || null,
+    memoryToken: !!resolveMemoryToken(o).token,
+    memorySource: resolveMemoryToken(o).source,
+  };
+}
+
+/**
+ * Client options for `createClient`: the resolved key plus the stored memory
+ * token, so a restart does not re-exchange for a token it already has.
+ */
+function clientOptions(o = {}) {
+  const { key } = resolveApiKey(o);
+  const { token } = resolveMemoryToken(o);
+  const opts = {};
+  if (key) opts.apiKey = key;
+  if (token) opts.memoryToken = token;
+  return opts;
+}
+
+/** Human label for a resolution source, for status lines. */
+const SOURCE_LABEL = {
+  env: `$${KEY_ENV}`,
+  credentials: 'saved key file',
+  config: 'config.json (aegis CLI)',
+  none: 'not set',
+};
+
+function sourceLabel(source) {
+  return SOURCE_LABEL[source] || SOURCE_LABEL.none;
+}
+
+/** One line telling the user how to supply a key, used by every error path. */
+const HOW_TO_SET = 'run `aegiscode login` (or /key inside a session) to save one';
+
+module.exports = {
+  KEY_ENV,
+  MEMORY_ENV,
+  CREDENTIALS_FILE,
+  credentialsPath,
+  normalizeApiKey,
+  validateApiKey,
+  readCredentials,
+  writeCredentials,
+  readLegacyConfig,
+  legacyKeyOnDisk,
+  adoptLegacy,
+  resolveApiKey,
+  hasApiKey,
+  saveApiKey,
+  clearApiKey,
+  resolveMemoryToken,
+  saveMemoryToken,
+  clearMemoryToken,
+  keyStatus,
+  clientOptions,
+  sourceLabel,
+  HOW_TO_SET,
+};

package/src/history.js

@@ -35,7 +35,6 @@ function ensureHistoryDir() {
  */
 function appendHistory({ sessionId, prompt, reply, status, usage }) {
   try {
-    ensureHistoryDir();
     const entry = {
       ts: new Date().toISOString(),
       sessionId,
@@ -54,14 +53,40 @@ function appendHistory({ sessionId, prompt, reply, status, usage }) {
         : { input: estimateTokens(prompt), output: estimateTokens(reply || ''), real: false },
     };
     if (usage && typeof usage.costUsd === 'number') entry.costUsd = usage.costUsd;
+    return appendHistoryEntries([entry]);
+  } catch (e) {
+    // Persistence is best-effort; never crash the session over it.
+    if (process.env.AEGIS_HIST_DEBUG) console.error('[history] write failed:', e);
+    return 0;
+  }
+}
+
+/**
+ * Append a batch of already-shaped entries in ONE read/trim/write pass.
+ *
+ * `appendHistory` re-reads and rewrites the whole file per exchange, which is
+ * fine for one turn at a time but quadratic for a caller with a list of them —
+ * importing 50 pulled sessions would rewrite the file 50 times, each pass
+ * re-parsing everything the previous pass just wrote. The single writer (and
+ * therefore the single place the file format is defined) stays here.
+ *
+ * @returns {number} entries written
+ */
+function appendHistoryEntries(entries) {
+  const list = (Array.isArray(entries) ? entries : []).filter(Boolean);
+  if (!list.length) return 0;
+  try {
+    ensureHistoryDir();
     const p = historyPath();
     const prev = fs.existsSync(p) ? fs.readFileSync(p, 'utf8').split('\n').filter(Boolean) : [];
-    const lines = [...prev, JSON.stringify(entry)];
+    const lines = [...prev, ...list.map((e) => JSON.stringify(e))];
     const trimmed = lines.slice(Math.max(0, lines.length - HISTORY_LIMIT));
     fs.writeFileSync(p, trimmed.join('\n') + '\n');
+    return list.length;
   } catch (e) {
     // Persistence is best-effort; never crash the session over it.
     if (process.env.AEGIS_HIST_DEBUG) console.error('[history] write failed:', e);
+    return 0;
   }
 }
 
@@ -79,6 +104,11 @@ function readEntries() {
   }
 }
 
+/** Every history record, oldest first. Public name for other modules. */
+function readHistoryEntries() {
+  return readEntries();
+}
+
 /** Newest-first list of own sessions, one per distinct sessionId. */
 function readOwnSessions(limit = 8) {
   const entries = readEntries();
@@ -192,6 +222,8 @@ module.exports = {
   historyPath,
   ensureHistoryDir,
   appendHistory,
+  appendHistoryEntries,
+  readHistoryEntries,
   readOwnSessions,
   readSessionTranscript,
   sessionHistoryEntries,

package/src/overlays.js

@@ -177,27 +177,38 @@ function renderModelPicker(models, sel = 0, width = 80, height = 24, current = n
 // ── Effort picker overlay (/effort) ──────────────────────────────────────────
 
 const EFFORT_LEVELS = [
-  { label: 'Low', note: 'Fastest, most efficient' },
+  { label: 'Auto', value: null, note: 'Sized per turn from the ask (default)' },
+  { label: 'Low', note: 'Fastest, cheapest budget' },
   { label: 'Medium', note: 'Balanced' },
-  { label: 'High', note: 'Highest quality, slowest' },
+  { label: 'High', note: 'Highest budget, slowest' },
 ];
 
+// The picker's order reduced to the values a selection means, so the row a user
+// picks and the value the session stores can never come from two different
+// lists (commands.js validates against this, chatflow.js resolves the overlay
+// through it). `null` is "auto" — no rung pinned.
+const EFFORT_VALUES = EFFORT_LEVELS.map((lv) => (lv.value === undefined ? lv.label.toLowerCase() : lv.value));
+
 /**
  * @param {number} sel selected index
  * @param {number} width
- * @param {string|null} current the currently-selected effort level
+ * @param {string|null} current the currently-selected effort level (null = auto)
  * @param {Array} [levels] override the level table
  */
 function renderEffortPicker(sel = 0, width = 80, current = null, levels = EFFORT_LEVELS) {
   const lines = [];
   lines.push(blank(width));
   lines.push([span('', ' '), span(C.white + BOLD, 'Select effort'), span(BOLD_OFF, '')]);
-  lines.push([span('', ' '), span(C.gray, 'Controls how much reasoning the model puts into each turn.')]);
+  lines.push([span('', ' '), span(C.gray, 'Sets the token budget the pool sizes each turn from.')]);
   lines.push(blank(width));
   for (let i = 0; i < levels.length; i++) {
     const lv = levels[i];
     const active = i === sel;
-    const cur = current != null && String(current).toLowerCase() === String(lv.label).toLowerCase();
+    // `current == null` is auto, which is the first row's own value — matching
+    // on the label alone would never mark the default as the current choice.
+    const cur = current == null
+      ? lv.value === null
+      : String(current).toLowerCase() === String(lv.label).toLowerCase();
     const left = active ? span(C.lavender, GLYPH.cursor) : span('', ' ');
     const nameSpan = active ? span(C.lavender, lv.label) : span(C.white, lv.label);
     const mark = cur ? span(C.green, ' ' + GLYPH.check) : span('', '');
@@ -283,4 +294,6 @@ module.exports = {
   renderModelPicker,
   renderEffortPicker,
   renderResumeList,
+  EFFORT_LEVELS,
+  EFFORT_VALUES,
 };

package/src/panels.js

@@ -202,7 +202,9 @@ function buildStatus(state, ctx = {}) {
   add('Working directory', s.cwd);
   add('Home', s.home);
   add('Model', s.model);
-  add('Effort', s.effort);
+  // `null` = auto: the pool sizes each turn from the ask, so the row says so
+  // rather than vanishing (add() skips empty values).
+  add('Effort', s.effort || 'auto');
   if (s.thinking != null) add('Thinking', s.thinking ? 'on' : 'off');
   if (s.stream != null) add('Streaming', s.stream === false ? 'off' : 'on');
   if (s.vim != null) add('Vim keymap', s.vim ? 'on' : 'off');

package/src/screens.js

@@ -36,6 +36,7 @@ const { welcomeArtParts } = require('./art.js');
 const { renderDiffPreview } = require('./markdown.js');
 const render = require('./render.js');
 const { updateConfig, configExists } = require('./config.js');
+const credentials = require('./credentials.js');
 
 const VERSION = require('../package.json').version;
 
@@ -387,6 +388,115 @@ async function showWelcome(ctx, firstRun = true) {
   }
 }
 
+// ── the account key ──────────────────────────────────────────────────────────
+
+const KEY_URL = 'https://aegiscloud.org';
+
+/**
+ * The key screen's lines. Pure, so what the user is told is asserted directly.
+ *
+ * `value` is echoed back as bullets: this is the one screen in the product
+ * where the thing being typed is a secret, and a screen that echoes it would
+ * put the key in a scrollback buffer, a screenshot and a screen share.
+ */
+function keyLines(ctx, cols, { value = '', error = null, verify = false } = {}) {
+  const t = themeOf(ctx);
+  const lines = [];
+  lines.push([span(t.gold, '─'.repeat(Math.max(1, cols)))]);
+  lines.push([span(t.white + BOLD, 'Connect your AEGIS account')]);
+  lines.push([span('', '')]);
+  for (const l of wrapped(
+    `Paste an API key to use AEGIS Cloud. Get one free at ${KEY_URL}. ` +
+      'It is stored in your user config directory with owner-only permissions, so later launches and scripts pick it up without an export.',
+    cols,
+    t.white
+  )) {
+    lines.push(l);
+  }
+  lines.push([span('', '')]);
+  lines.push([
+    span(t.lavender, GLYPH.cursor),
+    span(t.gray, ' API key: '),
+    span(t.white, '•'.repeat(String(value).length)),
+    span(verify ? t.cyan : t.gray, verify ? '  verifying…' : ''),
+  ]);
+  if (error) lines.push([span(t.coral, `  ${error}`)]);
+  lines.push([span('', '')]);
+  lines.push([
+    span(t.gray, `  ${GLYPH.check} `),
+    span(t.gray, 'Enter to save'),
+    span(t.gray, ' · '),
+    span(t.gray, 'Esc to skip'),
+  ]);
+  return lines;
+}
+
+/**
+ * Ask for the account key. Resolves `{key}` when submitted, `{skipped:true}`
+ * when the user declines, `{exit:true}` on ctrl+c.
+ *
+ * `submit(key)` is the caller's verification+persistence step; its rejection
+ * message is shown on the screen and the user stays on it, because the failure
+ * mode this prevents is a key that is accepted into the config while the
+ * account behind it rejects every call.
+ */
+async function requestApiKey(ctx, o = {}) {
+  const submit = o.submit || (async () => ({ ok: true }));
+  const { cols } = getSize();
+  let value = '';
+  let error = null;
+  let verify = false;
+  const paintScreen = () => paint(keyLines(ctx, cols, { value, error, verify }));
+  paintScreen();
+
+  for (;;) {
+    const key = await nextKey();
+    if (key.name === KEY.ENTER) {
+      if (!value.trim()) return { skipped: true };
+      verify = true;
+      error = null;
+      paintScreen();
+      let res;
+      try {
+        res = await submit(value);
+      } catch (e) {
+        res = { ok: false, message: (e && e.message) || String(e) };
+      }
+      verify = false;
+      if (res && res.ok === false) {
+        error = res.message || 'that key was refused';
+        paintScreen();
+        continue;
+      }
+      return { key: value, result: res };
+    }
+    if (key.name === KEY.ESC) return { skipped: true };
+    if (key.name === KEY.CTRL_C || key.name === KEY.CTRL_D) return { exit: true };
+    if (key.name === KEY.BACKSPACE) {
+      value = value.slice(0, -1);
+      error = null;
+      paintScreen();
+      continue;
+    }
+    if (key.name === 'char') {
+      const ch = key.ch;
+      if (ch && ch >= ' ') {
+        value += ch;
+        error = null;
+        paintScreen();
+      }
+      continue;
+    }
+    // A paste arrives as its own event (events.js rushes multi-char reads);
+    // without this a pasted key is dropped on the floor.
+    if (key.name === 'paste' && key.text) {
+      value = (value + String(key.text)).replace(/\s+/g, '');
+      error = null;
+      paintScreen();
+    }
+  }
+}
+
 // ── the sequence ─────────────────────────────────────────────────────────────
 
 /**
@@ -398,8 +508,12 @@ async function showWelcome(ctx, firstRun = true) {
  * @param {() => boolean} [o.seen] an explicit "has run before" probe; defaults
  *                                 to the config file's existence
  * @param {(patch:object)=>void} [o.save] persist patch; defaults to updateConfig
- * @returns {Promise<{ok:boolean, firstRun:boolean, themeIndex:number}>} `ok`
- *          is false when the user declined the trust check or asked to exit.
+ * @param {() => boolean} [o.needsKey] true when no account key is configured —
+ *                                 the key screen is shown only then
+ * @param {(key:string)=>Promise<object>} [o.submitKey] verify + persist a key
+ * @returns {Promise<{ok:boolean, firstRun:boolean, themeIndex:number,
+ *          key:{set:boolean, skipped:boolean}}>} `ok` is false when the user
+ *          declined the trust check or asked to exit.
  */
 async function runOnboarding(ctx, o = {}) {
   const seen = o.seen || configExists;
@@ -407,8 +521,29 @@ async function runOnboarding(ctx, o = {}) {
   // Injectable so the *sequence* — which screens run, in what order, and what is
   // persisted — can be asserted without a terminal. The screens themselves are
   // tested directly through their pure line-builders.
-  const ui = o.ui || { showTrustCheck, showThemePicker, showWelcome };
-  if (o.continue) return { ok: true, firstRun: false, themeIndex: ctx.themeIndex };
+  const ui = {
+    showTrustCheck,
+    showThemePicker,
+    showWelcome,
+    requestApiKey: (c, opts) =>
+      requestApiKey(c, { submit: o.submitKey || (async () => ({ ok: true })), ...opts }),
+    // An injected `ui` overrides the screens it names and inherits the rest, so
+    // a caller testing the sequence does not have to supply a key screen it
+    // never wants to exercise.
+    ...(o.ui || {}),
+  };
+  // No key is the one state where the session cannot do anything at all, so it
+  // is asked for in-band rather than left to a shell export the user has to
+  // discover. Default reads the credential store so a caller that forgets to
+  // pass it still gets the right behaviour.
+  const needsKey = o.needsKey || (() => !credentials.hasApiKey());
+  // …but only where a question can actually be asked. Without this a library
+  // caller with no TTY reaches a screen that waits on a key queue nothing will
+  // ever feed — a hang instead of a missing credential.
+  const canPrompt = o.canPrompt || (() => !!(process.stdin && process.stdin.isTTY));
+  // Declared out here because both the sequence and its key step report on it.
+  const key = { set: false, skipped: false };
+  if (o.continue) return { ok: true, firstRun: false, themeIndex: ctx.themeIndex, key: { set: false, skipped: false } };
 
   // Onboarding runs *before* the session loop, and the session loop is what
   // normally attaches the key pump — so without this the first screen paints and
@@ -429,17 +564,29 @@ async function runOnboarding(ctx, o = {}) {
       // neither is ever shown again. Re-running this every launch greeted
       // returning users with "Let's get started." and discarded their session.
       const trusted = await ui.showTrustCheck(ctx);
-      if (!trusted) return { ok: false, firstRun: true, themeIndex: ctx.themeIndex };
+      if (!trusted) return { ok: false, firstRun: true, themeIndex: ctx.themeIndex, key };
       await ui.showThemePicker(ctx);
       save({ themeIndex: ctx.themeIndex, light: ctx.light });
+      if (await askKey()) return { ok: false, firstRun: true, themeIndex: ctx.themeIndex, key };
       const welcome = await ui.showWelcome(ctx, true);
-      if (welcome && welcome.exit) return { ok: false, firstRun: true, themeIndex: ctx.themeIndex };
-      return { ok: true, firstRun: true, themeIndex: ctx.themeIndex };
+      if (welcome && welcome.exit) return { ok: false, firstRun: true, themeIndex: ctx.themeIndex, key };
+      return { ok: true, firstRun: true, themeIndex: ctx.themeIndex, key };
     }
 
+    if (await askKey()) return { ok: false, firstRun: false, themeIndex: ctx.themeIndex, key };
     const welcome = await ui.showWelcome(ctx, false);
-    if (welcome && welcome.exit) return { ok: false, firstRun: false, themeIndex: ctx.themeIndex };
-    return { ok: true, firstRun: false, themeIndex: ctx.themeIndex };
+    if (welcome && welcome.exit) return { ok: false, firstRun: false, themeIndex: ctx.themeIndex, key };
+    return { ok: true, firstRun: false, themeIndex: ctx.themeIndex, key };
+  }
+
+  /** @returns {Promise<boolean>} true when the user asked to exit. */
+  async function askKey() {
+    if (!needsKey() || !canPrompt()) return false;
+    const res = await ui.requestApiKey(ctx);
+    if (res && res.exit) return true;
+    if (res && res.key) key.set = true;
+    else key.skipped = true;
+    return false;
   }
 }
 
@@ -449,6 +596,7 @@ module.exports = {
   WHATS_NEW,
   trustLines,
   themePickerLines,
+  keyLines,
   applyTheme,
   welcomeLines,
   boxes,
@@ -458,6 +606,8 @@ module.exports = {
   wrapPlain,
   showTrustCheck,
   showThemePicker,
+  requestApiKey,
   showWelcome,
   runOnboarding,
+  KEY_URL,
 };