aegiscode 6.3.0 → 6.3.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aegiscode",
   "productName": "AEGIS Code",
-  "version": "6.3.0",
+  "version": "6.3.2",
   "description": "aegiscode — the command-line version of AEGIS Desktop. The shared tool surface in your shell, over the same thin transport and tool registry as the MCP plugin and the desktop app. Ships transport + UI only; no brain.",
   "author": {
     "name": "AEGIS Code",

package/src/app.js

@@ -27,6 +27,7 @@ const { GLYPH, VERBS, themeOf, RESET, THEME_TABLE } = require('./theme.js');
 const { LiveRegion, termWidth, w } = require('./screen.js');
 const { parseLine, COMMANDS, visibleCommands } = require('./commands.js');
 const { updateConfig, loadPermissions, loadConfig, configExists } = require('./config.js');
+const { normalizeModelCatalog, pickerEntries, catalogIds } = require('./models.js');
 const { appendHistory, readSessionTranscript, readOwnSessions } = require('./history.js');
 const { snapshotCheckpoint } = require('./checkpoint.js');
 const screens = require('./screens.js');
@@ -86,7 +87,11 @@ function createApp(options = {}) {
   const commandCtx = {
     light: opts.light,
     model: opts.model,
-    effort: 'high',
+    // `null` = "auto": send no effort, so the server sizes the turn from the
+    // ask. This is the *budget* control on the pooled class (aegis1 sizes the
+    // token ladder from it), which is why it is not defaulted to a rung here —
+    // pinning one would make every turn cost what that rung grants.
+    effort: null,
     thinking: false,
     themeIndex: opts.light ? 2 : 1,
     vim: false,
@@ -146,6 +151,71 @@ function createApp(options = {}) {
     }
   }
 
+  // ── the AEGIS Cloud model catalog ──────────────────────────────────────────
+  //
+  // `/model` (and the alt+p chord that dispatches it) reads the pinnable ids
+  // from the server, and `state().models` is where it looks. That path had no
+  // source at all: `commands.js` calls `c.loadModels()` inside a `try {} catch
+  // {}`, `c.loadModels` was never defined on either command context, and
+  // `buildState()` hardcoded `models: []` — so the TypeError was swallowed and
+  // both `/model` and the picker reported "no models advertised" on a perfectly
+  // healthy account, forever. The ids themselves are the server's (see
+  // models.js), fetched here and cached, because the pool adds and retires
+  // providers without a client release.
+  const MODEL_CACHE_MS = 5 * 60_000;
+  const modelCache = { at: 0, models: [] };
+
+  /**
+   * Fetch (or return the cached) model catalog. Rejects when the account cannot
+   * read it at all — no key, offline, or a server error — which callers treat as
+   * "nothing to offer" rather than retrying per keystroke.
+   * @returns {Promise<Array<{id:string,label:string,note:string}>>}
+   */
+  async function loadModels({ force = false } = {}) {
+    const fresh = modelCache.models.length && Date.now() - modelCache.at < MODEL_CACHE_MS;
+    if (!force && fresh) return modelCache.models;
+    const data = await client.listModels();
+    modelCache.models = normalizeModelCatalog(data && data.models);
+    modelCache.at = Date.now();
+    return modelCache.models;
+  }
+
+  /**
+   * A pinned model id the server does not advertise is a *silent* fallback: the
+   * pool answers from its own default with no error, so the pin looks honoured
+   * while the reply came from another model — and the cost is attributed to the
+   * model that was pinned. Two shipped defaults did exactly that: `sonnet`
+   * (written into config.json by onboarding, merged in from DEFAULT_CONFIG, and
+   * never advertised by AEGIS Cloud) and any `provider/model` spelling a user
+   * typed by hand. Clears such a pin once, says so, and leaves the server's own
+   * default in its place.
+   *
+   * Best-effort and offline-safe: a catalog that cannot be read clears nothing.
+   */
+  async function validatePinnedModel() {
+    const pinned = commandCtx.model;
+    if (!pinned) return null;
+    let models;
+    try {
+      models = await loadModels();
+    } catch {
+      return null;
+    }
+    if (!models.length) return null;
+    if (catalogIds(models).has(String(pinned).toLowerCase())) return null;
+    commandCtx.model = null;
+    updateConfig({ model: null, currentModelId: null });
+    emit(
+      render.renderNotice(
+        ctx(),
+        'warn',
+        `pinned model "${pinned}" is not advertised by AEGIS Cloud — pin cleared, ` +
+          'the pool will choose; /models lists what you can pin.'
+      )
+    );
+    return pinned;
+  }
+
   function bannerLines() {
     return render.renderBanner(ctx(), {
       width: width(),
@@ -305,6 +375,14 @@ function createApp(options = {}) {
           model: commandCtx.model || undefined,
           system: opts.system,
           maxTokens: opts.maxTokens,
+          // `effort` is the pooled budget control, and it travels on every turn
+          // — this host only ever runs the 'aegis' class, whose calls are sized
+          // server-side from it (aegis1 services/pool_brain.py). It used to be
+          // held in the session state and rendered in the status line without
+          // ever reaching the wire, so /effort changed the display and nothing
+          // about what the turn cost. `null` (auto) is omitted so the server
+          // infers the rung from the ask.
+          effort: commandCtx.effort || undefined,
           // false asks the engine for the buffered (non-stream) wire form, so
           // `--no-stream` and piped runs get a single body rather than SSE.
           stream: commandCtx.stream !== false,
@@ -517,7 +595,9 @@ function createApp(options = {}) {
       plan: session.plan || null,
       account: session.account || null,
       permissions: { mode: rules.defaultMode, rules },
-      models: [],
+      // The selectable (pickable) catalog, not the raw payload: alias tiers are
+      // dropped, live ids only (see models.js pickerEntries).
+      models: pickerEntries(modelCache.models),
       commands: visibleCommands(),
       transcript: transcript.slice(),
       sessions: [],
@@ -633,6 +713,10 @@ function createApp(options = {}) {
       runPrompt: (text) => runPrompt(text),
       ask: (text) => ask(text),
       runTool: (name, args) => runTool(name, args),
+      // The AEGIS catalog fetch `/model` and alt+p expect (see loadModels).
+      // Wired on the app's context so the chatflow's `Object.assign`-based
+      // context inherits it too — one definition, both hosts.
+      loadModels: (o) => loadModels(o),
       refreshSpend: () => refreshSpend(),
       state: () => buildState(),
       setInput: () => {},
@@ -916,6 +1000,7 @@ function createApp(options = {}) {
       TOOLS,
       ask: (prompt, o) => ask(prompt, o),
       makeCommandContext: () => makeCommandContext(),
+      loadModels: (o) => loadModels(o),
       buildState: () => buildState(),
       dispatchLine: (line, c) => handleLine(line, c),
       refreshSpend: () => refreshSpend(),
@@ -1000,6 +1085,8 @@ function createApp(options = {}) {
       return;
     }
     if (!opts.model && cfg.model) commandCtx.model = cfg.model;
+    // `null` in the config is "auto" and is deliberately not assigned over the
+    // default — there is nothing to restore, because nothing is pinned.
     if (cfg.effort) commandCtx.effort = cfg.effort;
     if (typeof cfg.vim === 'boolean') commandCtx.vim = cfg.vim;
     if (cfg.lastRecap) commandCtx.lastRecap = cfg.lastRecap;
@@ -1037,6 +1124,11 @@ function createApp(options = {}) {
         save: (patch) => updateConfig(patch),
       });
       if (!onboard.ok) return 0;
+      // A stored pin the platform does not advertise routes elsewhere in
+      // silence (see validatePinnedModel) — checked once, here, where the user
+      // can act on it. Not on `-p`: a network round-trip ahead of the first
+      // token would be a startup cost bought for a warning no script watches.
+      await validatePinnedModel();
       // `--continue` must load the last session *before* the loop starts, and
       // it has to be read here rather than captured at construction: the
       // history file is written by the loop itself.
@@ -1071,6 +1163,8 @@ function createApp(options = {}) {
     refreshSpend,
     bannerLines,
     makeHost,
+    loadModels,
+    validatePinnedModel,
     recordTurn,
     persistTurn,
     restorePrefs,

package/src/chatflow.js

@@ -164,7 +164,7 @@ const separatorLine = (cols, ctx) => [span(themeOf(ctx).dim, '─'.repeat(cols))
 /** The idle bottom-left line: which effort level the next turn runs at. */
 function effortLine(ctx, cols) {
   const t = themeOf(ctx);
-  const txt = `● ${ctx.effort || 'high'} · /effort`;
+  const txt = `● ${ctx.effort || 'auto'} · /effort`;
   const pad = ' '.repeat(Math.max(0, cols - [...txt].length - 4));
   return [span(t.gray, pad + txt)];
 }
@@ -1111,12 +1111,15 @@ async function runSession(host) {
         return;
       }
       if (type === 'effort') {
-        const levels = ['low', 'medium', 'high'];
-        const chosen = levels[overlay.sel || 0];
+        // The picker's own order, not a second copy of the level names: this
+        // used to re-declare ['low','medium','high'] here while the picker drew
+        // its own table, so the row a user picked and the value it stored were
+        // resolved through different lists.
+        const chosen = overlays.EFFORT_VALUES[overlay.sel || 0];
         overlay = null;
         ctx.effort = chosen;
         host.updateConfig({ effort: chosen });
-        note(`effort: ${chosen}`);
+        note(`effort: ${chosen || 'auto'}`);
         render();
         return;
       }

package/src/commands.js

@@ -46,6 +46,7 @@ const { execSync } = require('node:child_process');
 const { span } = require('./screen.js');
 const { C, BOLD, BOLD_OFF } = require('./theme.js');
 const panels = require('./panels.js');
+const overlays = require('./overlays.js');
 const {
   updateConfig, loadConfig, loadPermissions, savePermissions, addPermissionRule,
   DEFAULT_PERMISSIONS, permissionsPath, configPath,
@@ -93,7 +94,13 @@ const CATEGORIES = [
 
 const categoryLabel = (id) => (CATEGORIES.find((cat) => cat.id === id) || {}).label || id;
 
-const EFFORT_LEVELS = ['low', 'medium', 'high'];
+// One table, shared with the picker that draws it. The two used to be separate
+// lists — this one a string array, chatflow.js's own copy of the same three
+// strings, and overlays.js's label/note rows — so adding a level meant editing
+// three places, and the index a picker row reported was mapped back to a value
+// through whichever list happened to be in scope. EFFORT_VALUES is the picker's
+// own order, `null` first for "auto".
+const EFFORT_LEVELS = overlays.EFFORT_VALUES;
 
 // ── Small handler helpers ─────────────────────────────────────────────────────
 
@@ -348,12 +355,12 @@ const COMMANDS = [
     },
   },
   {
-    name: 'effort', args: ['level'], hint: '[low|medium|high]', category: 'model',
-    desc: 'Set effort level for model usage',
+    name: 'effort', args: ['level'], hint: '[auto|low|medium|high]', category: 'model',
+    desc: 'Set the token budget the pool sizes each turn from',
     handler: async (c, args) => {
       const level = (args.level || '').toLowerCase();
-      if (level && !EFFORT_LEVELS.includes(level)) {
-        note(c, `Unknown effort level "${args.level}". Use ${EFFORT_LEVELS.join(', ')}.`);
+      if (level && level !== 'auto' && !EFFORT_LEVELS.includes(level)) {
+        note(c, `Unknown effort level "${args.level}". Use auto, ${EFFORT_LEVELS.filter(Boolean).join(', ')}.`);
         c.render();
         return true;
       }
@@ -361,9 +368,14 @@ const COMMANDS = [
         c.openOverlay({ type: 'effort', sel: Math.max(0, EFFORT_LEVELS.indexOf(c.ctx.effort)) });
         return true;
       }
-      c.ctx.effort = level;
-      c.saveConfig({ effort: level });
-      note(c, `Effort level: ${level}`);
+      // 'auto' is the absence of a pin, not a fourth rung: it is stored as null
+      // so nothing is sent and the server sizes the turn from the ask.
+      const pinned = level === 'auto' ? null : level;
+      c.ctx.effort = pinned;
+      c.saveConfig({ effort: pinned });
+      note(c, pinned
+        ? `Effort level: ${pinned} — the pool sizes this turn's token budget from it`
+        : 'Effort level: auto — the pool sizes each turn from the ask');
       c.render();
       return true;
     },
@@ -478,10 +490,25 @@ const COMMANDS = [
         await loadModels(c);
         const models = c.state().models || [];
         if (!models.length) {
-          note(c, 'No pinnable models advertised — /models lists what the server advertises.');
+          // Say why, and what unblocks it: an unreachable catalog is almost
+          // always a missing key or no network, and "no models advertised"
+          // read as "the platform has none" rather than "this client could not
+          // ask".
+          note(c, c.state().online
+            ? 'Could not read the model catalog (offline, or the server refused it) — /models retries.'
+            : // The key travels in the environment only (client/aegis.js reads
+              // AEGIS_API_KEY); /login is an unavailable command here, so
+              // pointing at it would send the user to a refusal.
+              'No API key set, so the model catalog cannot be read — export AEGIS_API_KEY (free at https://aegiscloud.org), then retry /model.');
           c.render();
           return true;
         }
+        // A pin that is not in the catalog is not honoured — the pool answers
+        // from its own default with no error. Say so where the pin is visible
+        // rather than letting the reply look like the pinned model.
+        if (c.ctx.model && !models.some((m) => m.id === c.ctx.model)) {
+          note(c, `pinned model "${c.ctx.model}" is not in the catalog — the pool will answer with its own default; pick one below.`);
+        }
         // The overlay's own copy promises /model add|remove (overlays.js, a
         // separate workstream); this build refuses both, so say here how a
         // model is actually selected.
@@ -516,6 +543,16 @@ const COMMANDS = [
       // dir, so the write stays inside that dir.
       c.saveConfig({ model: id, currentModelId: id });
       note(c, `Pinned model: ${id}`);
+      // The server accepts an id it does not advertise and answers from its own
+      // default — no error, a different model, and the spend attributed to the
+      // id that was pinned. Warn (never refuse: the catalog is cached, and
+      // refusing would break a pin made against a server that is briefly
+      // unreachable) so the mismatch is visible at the moment it is created.
+      await loadModels(c);
+      const models = c.state().models || [];
+      if (models.length && !models.some((m) => m.id === id)) {
+        note(c, `"${id}" is not in the AEGIS Cloud catalog — the pool will answer with its own default. /models lists the real ids.`);
+      }
       c.render();
       return true;
     },

package/src/config.js

@@ -43,13 +43,28 @@ function permissionsPath() {
 
 const DEFAULT_CONFIG = {
   themeIndex: 1,   // Dark mode
-  model: 'sonnet',
+  // No pinned model. This host runs on AEGIS Cloud, whose pinnable ids are the
+  // server's (`/models`) — a client-side default here would have to name one,
+  // and the one it named (`sonnet`) is not advertised by the platform at all:
+  // the pool accepts an unknown id and answers from its own default with no
+  // error, so the pin looked honoured while the reply came from another model.
+  // Worse, onboarding persists this object on first run (`updateConfig` merges
+  // DEFAULT_CONFIG under the patch), so the phantom pin was written to disk for
+  // every user who ever completed the trust check. `null` = no pin; the server
+  // chooses, and app.js's validatePinnedModel() clears a stored id the catalog
+  // does not advertise.
+  model: null,
   // Phase 6: the full model table (seeded from src/models.js MODELS on first
   // read by pickerModels()). 'currentModelId' mirrors `model` under the
   // aegiscode- name so /model add/remove/switch stay compatible both ways.
   models: null,
   currentModelId: null,
-  effort: 'high',
+  // `null` = no effort pinned, i.e. "auto": each turn is sized by the server
+  // from the ask itself (aegis1 services/pool_brain.py estimate_effort). The
+  // old 'high' was a *pin* on the top rung of the budget ladder — the most the
+  // server can grant — so the CLI's default turn was the most expensive one it
+  // could make, and /effort could only ever move it down.
+  effort: null,
   vim: false,
   lastCwd: '',
 };

package/src/models.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * AEGIS Cloud model catalog shaping — the one place `/model`, the alt+p picker
+ * and `/models` agree on what a pinnable model is.
+ *
+ * The ids a user may pin are the *server's*, never ours: the pool adds, renames
+ * and retires providers without a client release, so the catalog is fetched
+ * (`client.listModels()` → GET /api/v1/models on aegiscloud.org) and this module
+ * only normalises the payload. It deliberately invents no id, and has no
+ * fallback list: an offline client offers nothing rather than a model name that
+ * would silently route somewhere else.
+ *
+ * The platform lists per-provider ids (`deepseek`, `anthropic`, `groq`, …) plus
+ * the pooled-brain tiers. The desktop host collapsed all of that to a single
+ * "Nexus" entry because its dropdown *is* the model choice and surfacing
+ * per-provider routing invites pinning a provider that happens to be dead right
+ * now (see desktop/lib/local/engine.js selectBrainEntry). This host keeps every
+ * distinct id — a CLI user pinning `deepseek` explicitly is a legitimate
+ * request — but drops the pure-alias duplicates the server itself marks
+ * `hidden: true, alias_of: "<id>"` (`aegis-brain`, `nexus-brain-smart`, …),
+ * which are the same model advertised under another spelling.
+ */
+
+/** A pinned id of `null` means "no pin — let the pool choose" (the server's own default). */
+const NO_PIN = null;
+
+/**
+ * Labels for catalog ids the platform advertises without capabilities or a
+ * label of their own — `openai-gpt4o-mini` reads like a typo next to `openai`,
+ * and the brain tier is the one id whose *cost shape* a user needs before
+ * pinning it: verified live 2026-09-14, `model: "nexus-brain"` streams
+ * `pool-brain: 3 workers · effort=high · tier=brain · passes=4`, i.e. four
+ * billed provider calls per turn, where a provider id is one.
+ */
+const ID_NOTES = Object.freeze({
+  'openai-gpt4o-mini': 'OpenAI gpt-4o-mini, pooled',
+  'anthropic-haiku': 'Anthropic Haiku, pooled',
+  'nexus-brain': 'pooled brain · 3 workers + synthesis',
+});
+
+/** One raw entry (string id or object) → a catalog entry, or null when unusable. */
+function normalizeModel(entry) {
+  const m = typeof entry === 'string' ? { id: entry } : entry;
+  if (!m || typeof m !== 'object') return null;
+  const id = typeof m.id === 'string' ? m.id.trim() : '';
+  if (!id) return null;
+  const aliasOf =
+    typeof m.alias_of === 'string' && m.alias_of.trim() ? m.alias_of.trim() : null;
+  const capabilities = Array.isArray(m.capabilities)
+    ? m.capabilities.filter((c) => typeof c === 'string' && c)
+    : [];
+  const label =
+    (typeof m.label === 'string' && m.label.trim()) ||
+    (typeof m.name === 'string' && m.name.trim()) ||
+    id;
+  // The picker's right-hand column: what this entry *is*. An alias says so —
+  // otherwise a user reads five brain tiers and assumes five different models.
+  const note = aliasOf
+    ? `alias of ${aliasOf}`
+    : ID_NOTES[id] || capabilities.join(', ');
+  return {
+    id,
+    label,
+    note,
+    hidden: m.hidden === true,
+    aliasOf,
+    capabilities,
+  };
+}
+
+/** Normalise a raw `/api/v1/models` payload (`{models: [...]}` or the array). */
+function normalizeModelCatalog(raw) {
+  const list = Array.isArray(raw) ? raw : Array.isArray(raw && raw.models) ? raw.models : [];
+  const out = [];
+  const seen = new Set();
+  for (const entry of list) {
+    const m = normalizeModel(entry);
+    if (!m || seen.has(m.id)) continue;
+    seen.add(m.id);
+    out.push(m);
+  }
+  return out;
+}
+
+/**
+ * The entries the picker and `/models` offer: every distinct advertised model,
+ * minus the alias duplicates — unless the catalog is *only* aliases, in which
+ * case the aliases are all the server advertises and are offered rather than
+ * leaving the user with an empty list.
+ */
+function pickerEntries(catalog) {
+  const all = Array.isArray(catalog) ? catalog.filter(Boolean) : [];
+  const distinct = all.filter((m) => !m.aliasOf);
+  return distinct.length ? distinct : all;
+}
+
+/** The catalog entry for `id`, or null — the "is this a real id?" question. */
+function findModel(catalog, id) {
+  const want = typeof id === 'string' ? id.trim() : '';
+  if (!want) return null;
+  return (Array.isArray(catalog) ? catalog : []).find((m) => m && m.id === want) || null;
+}
+
+/**
+ * The set of ids the server accepts, lower-cased: a catalog id and a pinned id
+ * are the same thing only when they match byte-for-byte, but `/model Nexus-Brain`
+ * is a typo a user will make and the server's routing is case-insensitive
+ * enough that warning about it would be noise.
+ */
+function catalogIds(catalog) {
+  return new Set((Array.isArray(catalog) ? catalog : []).map((m) => String((m && m.id) || '').toLowerCase()).filter(Boolean));
+}
+
+module.exports = {
+  NO_PIN,
+  ID_NOTES,
+  normalizeModel,
+  normalizeModelCatalog,
+  pickerEntries,
+  findModel,
+  catalogIds,
+};

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/vendor/client/aegis.js

@@ -278,6 +278,13 @@ function createClient(opts = {}) {
    *                 so a reasoning-only stream still counts as unanswered.
    *   - `idleTimeoutMs`  override the stalled-stream watchdog for this call
    *                 (a worker fan-out is legitimately silent between passes)
+   *   - `maxTokens`  output ceiling. Omitted from the body when absent so the
+   *                 server's own budget applies — on a pooled request that is
+   *                 the `effort` ladder, and a number sent from here caps it.
+   *   - `effort` / `workers`  pooled-brain budget rung and fan-out size.
+   *                 Forwarded only inside `extra`, as the server reads them off
+   *                 the body (aegis1 services/pool_brain.py parse_brain_request)
+   *                 and sizes the budget from them.
    */
   async function chatCompletion({
     prompt,
@@ -298,9 +305,17 @@ function createClient(opts = {}) {
     // model the server picks its default (no client-invented tier id). `mode`
     // is a legacy server-side shorthand — forwarded verbatim only when the
     // caller supplies it, never defaulted, never built into a model id.
+    //
+    // `max_tokens` is omitted entirely when the caller states none, rather than
+    // defaulted here. The server has its own budget ladder (`mode`/`effort` on
+    // the pooled path) and treats a body max_tokens as a *ceiling* over it, so
+    // an invented 4096 was not a harmless default: it capped every pass of a
+    // pooled-brain fan-out at 4096 and overrode the ladder the caller's effort
+    // selected. Omitting it is the documented way to say "server default" (see
+    // mcp/tools.js's max_tokens description).
     const body = {
       messages: buildMessages(messages, system, prompt),
-      max_tokens: maxTokens || 4096,
+      ...(maxTokens ? { max_tokens: maxTokens } : {}),
       ...(extra || {}),
     };
     if (model) body.model = model;

package/vendor/desktop/lib/local/engine.js

@@ -473,6 +473,17 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
 
   async function listModels(cls) {
     if (cls === 'aegis') {
+      // The catalog is behind the account's key: GET /api/v1/models answers
+      // `401 {"error":{"message":"No API key"}}` without one (verified against
+      // aegiscloud.org). Aegis Cloud is the *default* class, so firing the call
+      // anyway painted a raw "listModels failed: … 401" over the default model
+      // picker for every user who had just installed the app and not yet
+      // pasted a key — the one state where the UI must say what unblocks it and
+      // not what went wrong. Report the missing key as a state (`needsKey`) and
+      // let the renderer invite the user to connect; nothing else about the
+      // class changes, and the model dropdown keeps its "server default (auto)"
+      // entry so the class is usable the moment a key lands.
+      if (!aegis.apiKey) return { class: cls, models: [], needsKey: true };
       const data = await aegis.listModels();
       return { class: cls, models: filterAegisCatalog(normalizeCatalog(data && data.models)) };
     }
@@ -573,13 +584,18 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
           // model as the fan-out, one sample instead of four — otherwise
           // dropping the fan-out would have quietly changed the model too.
           ...(brainFlag === false ? { mode: 'brain' } : {}),
-          // Only meaningful (and only sent) alongside a running fan-out — aegis1
-          // services/pool_brain.py parse_brain_request reads `effort`/
-          // `workers` straight off the body and clamps them itself
-          // (EFFORT_LEVELS / MAX_WORKERS), so no client-side validation here.
-          // Keyed on the effective brain flag, not on `autonomous`: an opted-out
-          // single pass carries no fan-out tuning it cannot use.
-          ...(brainFlag === true && opts.effort ? { effort: opts.effort } : {}),
+          // `effort` is the budget rung, and it is sent whenever the caller has
+          // one — not only alongside a fan-out. The fan-out is triggered by the
+          // model id (this class sends ``nexus-brain``), so a caller that never
+          // ticked "work autonomously" still ran a pooled call and had no way to
+          // say how big it should be: the server fell through to its own default
+          // rung. That is how a one-word prompt came to reserve the top of the
+          // ladder. A single-pass pass carries it too — inert on that path, but
+          // it keeps the request honest about what it asked for.
+          ...(opts.effort ? { effort: opts.effort } : {}),
+          // Only meaningful with a running fan-out — aegis1 services/pool_brain.py
+          // parse_brain_request reads `workers` straight off the body and clamps
+          // it itself (MAX_WORKERS), so no client-side validation here.
           ...(brainFlag === true && opts.workers ? { workers: opts.workers } : {}),
           // The pool forwards `tools` to the provider and returns tool_calls
           // (aegis1 app.py:7765 → provider, pool_brain synthesis keeps them).