aegiscode 6.7.5 → 6.7.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,6 +13,42 @@ an editor — built on the same two shared pieces and no others:
13
13
 
14
14
  Routing, model tiers, memory and billing all stay behind aegiscloud.org.
15
15
 
16
+ ## Quick start
17
+
18
+ Four steps, in order. Everything past this section is the fuller reference for
19
+ each one.
20
+
21
+ **1. Install** — requires Node 18+.
22
+
23
+ ```bash
24
+ npm install -g aegiscode
25
+ ```
26
+
27
+ **2. Log in** — get a key at <https://aegiscloud.org> if you don't have one.
28
+
29
+ ```bash
30
+ aegiscode login # prompts, no echo
31
+ aegiscode key status # verify: masked key + which source is in use
32
+ ```
33
+
34
+ **3. (Optional) Bring your own key** — skip this if you're happy on the
35
+ pooled AEGIS Cloud route (the default). Use your own OpenAI/Anthropic/etc. key
36
+ instead, at a flat handling fee instead of the pooled margin — see [Bring your
37
+ own key](#bring-your-own-key).
38
+
39
+ ```bash
40
+ /byok # list providers and which are already set
41
+ /byok-key openai # save a key on this machine, prompts, no echo
42
+ /class byok # switch the session to run on it
43
+ ```
44
+
45
+ **4. Use it.**
46
+
47
+ ```bash
48
+ aegiscode # interactive session
49
+ aegiscode "why is the sky blue" # one-shot, prints the answer and the tokens
50
+ ```
51
+
16
52
  ## Names: one name, `aegiscode`
17
53
 
18
54
  This host and the CLI used to be two names for two packages. They are one
@@ -30,7 +66,7 @@ Publishing this host as `aegiscode` moves the `latest` dist-tag for that name
30
66
  onto it. The previous line (`aegiscode@5.x`, the `aegisinfo/aegiscode` agent) is
31
67
  still installable and immutable on the registry — pin `aegiscode@5` for it.
32
68
 
33
- ## Install
69
+ ## Installation
34
70
 
35
71
  ```bash
36
72
  npm install -g aegiscode
@@ -58,7 +94,7 @@ That one file is shared: the MCP plugin and AEGIS Desktop read the same store, s
58
94
  signing in here signs you in everywhere (see [One memory, shared with AEGIS
59
95
  Desktop](#one-memory-shared-with-aegis-desktop)).
60
96
 
61
- ## Use
97
+ ## Launch options
62
98
 
63
99
  ```bash
64
100
  aegiscode # interactive session
@@ -149,7 +185,7 @@ folder you just refused to vouch for is not read, edited or executed in.
149
185
  Preferences survive a restart: model, effort, theme and vim mode are restored on
150
186
  launch, and an explicit flag (`-m`, `--light`) always outranks the stored value.
151
187
 
152
- ## Use
188
+ ## Commands
153
189
 
154
190
  In a session, plain text is a prompt. `/help` lists commands, grouped by
155
191
  category, the way `aegiscodex-dev` does. The registry is that client's, ported
@@ -159,9 +195,9 @@ command for command — 75 entries across nine categories:
159
195
  |---|---|
160
196
  | Session & context | `/clear` `/compact` `/cost` `/exit` `/new` `/recap` `/resume` `/rewind` `/agents` `/status` `/teleport` `/version` `/clone` `/schedule` |
161
197
  | Workspace | `/run` `/build` `/cd` `/copy` `/init` `/review` `/prs` |
162
- | Model & behavior | `/model` `/effort` `/thinking` `/theme` `/vim` `/router` `/confirm` `/yolo` `/permissions` `/hooks` `/skills` `/mcp` |
198
+ | Model & behavior | `/model` `/models` `/class` `/effort` `/thinking` `/theme` `/vim` `/router` `/confirm` `/yolo` `/permissions` `/hooks` `/skills` `/mcp` |
163
199
  | Data | `/context` `/export` `/tokens` `/sync` |
164
- | Auth | `/key` `/login` `/logout` `/credentials` `/byok` `/byok-set` `/byok-rm` |
200
+ | Auth | `/key` `/login` `/logout` `/credentials` `/byok` `/byok-set` `/byok-rm` `/byok-key` `/byok-rm-key` |
165
201
  | Support | `/help` `/doctor` `/troubleshooting` `/feedback` `/bug` `/issue` `/onboarding` `/benchmark` `/release-notes` `/billing` `/cloud` |
166
202
  | Aegis plugin | `/aegis-ask` `/aegis-status` `/aegis-recall` `/aegis-remember` `/memory` `/aegis-council` `/aegis-multi` `/aegis-print` `/aegis-import` `/tool` |
167
203
  | Fun | `/radio` `/waifu` |
@@ -178,6 +214,261 @@ the project and writes `AEGIS.md`, `/export` writes the transcript out,
178
214
  `/resume` and `/rewind` read the session store, `/cd` moves the working
179
215
  directory, `/doctor` runs diagnostics.
180
216
 
217
+ ## Model selection
218
+
219
+ Three layers, from broadest to narrowest. You only need the first one.
220
+
221
+ **1. The class — which route the turn takes.**
222
+
223
+ ```bash
224
+ /class # show the picker
225
+ /class aegis # pooled AEGIS Cloud (the default)
226
+ /class byok # your own provider key, relayed by AEGIS
227
+ /class custom # your own endpoint, called by aegiscode directly
228
+ ```
229
+
230
+ A class is *whose credential pays and who talks to the vendor*, not a model.
231
+ Switching applies to your **next** turn and leaves the conversation intact. The
232
+ choice is written to `~/.aegiscode/config.json` (`modelClass`), so it survives a
233
+ restart.
234
+
235
+ | Class | Route | Who pays |
236
+ |---|---|---|
237
+ | `aegis` *(default)* | the AEGIS pool — one id, `nexus-brain` (alias `aegis-brain`), auto-routed server-side across whichever providers are live | your AEGIS account balance |
238
+ | `byok` | your provider key, relayed via `POST /api/v1/byok/chat/completions` | your provider direct, **plus** a small AEGIS handling fee on your account |
239
+ | `custom` | your own base URL, called **directly** by aegiscode — nothing is relayed | your provider direct. No AEGIS fee, no margin, no account balance |
240
+
241
+ **2. The model id — what to pin.**
242
+
243
+ ```bash
244
+ /models # what you can pin, for the class you are on
245
+ /model # open the picker
246
+ /model nexus-brain # pin it
247
+ /model - # clear the pin, back to the class default
248
+ ```
249
+
250
+ `/models` is class-aware: it answers from the pool catalogue under `aegis`, from
251
+ the models your saved keys actually unlock under `byok`, and from the entries you
252
+ added with `/model add` under `custom`. A pin is **cleared with a reason** if you
253
+ switch to a class it does not belong to, instead of failing later at the route.
254
+
255
+ Under `byok` every id is compound — `provider:model`:
256
+
257
+ ```bash
258
+ /models # e.g. anthropic:claude-sonnet-4-5
259
+ /model anthropic:claude-sonnet-4-5
260
+ ```
261
+
262
+ Under `custom` the id is whatever you named the entry:
263
+
264
+ ```bash
265
+ /models # e.g. local-llama, work-gateway
266
+ /model local-llama
267
+ ```
268
+
269
+ ```bash
270
+ aegiscode -m nexus-brain -p "…" # pin at launch
271
+ aegiscode -m anthropic:claude-sonnet-4-5 -p "…" # a BYOK id at launch
272
+ aegiscode -m local-llama -p "…" # a custom id at launch
273
+ ```
274
+
275
+ **3. Effort — how hard it reasons.**
276
+
277
+ ```bash
278
+ /effort # show
279
+ /effort low|medium|high
280
+ ```
281
+
282
+ Effort scales the token budget the provider is given, so it is the dial that
283
+ actually changes reasoning depth on a reasoning model (see the root README for
284
+ the per-provider mechanics).
285
+
286
+ > **A `byok` turn is single-shot.** The relay takes no `tools` parameter, so the
287
+ > agentic tool loop is off by construction — no file edits, no shell, no
288
+ > subagents, no approval cards. `/class` says so rather than letting you discover
289
+ > it mid-task. **`custom` does not have this limit** — aegiscode calls your
290
+ > endpoint itself, so the full tool loop works normally.
291
+
292
+ ## Custom models — your endpoint, called directly
293
+
294
+ `/model add` teaches aegiscode about an endpoint AEGIS never sees. There is no
295
+ relay, no handling fee and no margin: the request goes straight from your machine
296
+ to the base URL you gave, with the key you gave.
297
+
298
+ ```bash
299
+ /model add local-llama "Local Llama" llama-3.3-70b http://localhost:11434/v1
300
+ /model add work-gw "Work gateway" gpt-4o https://gw.corp/v1 openai
301
+ /model key local-llama # set or replace the key later (prompted, masked)
302
+ /class custom # route turns through these
303
+ /model local-llama # pin one
304
+ /model remove local-llama # drop the entry and its key
305
+ ```
306
+
307
+ The wire protocol is detected from the base URL — `anthropic.com` gets the
308
+ Messages API, everything else the OpenAI-compatible one — or you can pass
309
+ `openai` / `anthropic` explicitly to override it.
310
+
311
+ Where things are stored, and why it is split:
312
+
313
+ | What | Where | Why |
314
+ |---|---|---|
315
+ | name, model, base URL, wire | `~/.aegiscode/config.json` | it is configuration, and it is not secret |
316
+ | the API key | `~/.aegiscode/settings.json` (mode `0600`) | secrets belong in the file we chmod, keyed `custom:<id>` |
317
+
318
+ The key is never written into `config.json`. A local endpoint that needs no key
319
+ is fine — omit it and no `Authorization` header is sent.
320
+
321
+ ## Bring your own key
322
+
323
+ Two lanes. The one people mix up is which key goes where, so state it plainly:
324
+ **`/byok-set` stores on your AEGIS account; `/byok-key` stores on this machine.**
325
+
326
+ | | `/byok-set <provider>` | `/byok-key <provider>` |
327
+ |---|---|---|
328
+ | Key lives | on your AEGIS account, encrypted server-side | in `~/.aegiscode/settings.json` (mode `0600`) |
329
+ | Follows you to other machines | yes | no |
330
+ | Reaches the vendor via | AEGIS, server-side | AEGIS's BYOK relay |
331
+ | Needed for `/class byok`? | no | **yes** — this is the one the relay reads |
332
+
333
+ ### Save a key on this machine
334
+
335
+ ```bash
336
+ /byok # list every provider, and which are already set
337
+ /byok-key openai # prompts, no echo, never enters history
338
+ /byok-key openai sk-… # scriptable form
339
+ /byok-rm-key openai # forget it
340
+ ```
341
+
342
+ The first command is the one to run when you don't know a provider id. The
343
+ catalogue is server-side and grows, so `/byok` is the authority — each row names
344
+ the provider, the models its key unlocks, where the vendor issues it, and the
345
+ prefix a valid key starts with. A typo'd or wrong-vendor key is caught before it
346
+ is stored.
347
+
348
+ ### Save a key on your account
349
+
350
+ ```bash
351
+ /byok-set anthropic # prompts, no echo
352
+ /byok-rm anthropic # remove it
353
+ ```
354
+
355
+ ### What a BYOK turn costs
356
+
357
+ Bringing your own key does not make the turn free, and it is not meant to. AEGIS
358
+ pays the vendor nothing on this lane, so there is no provider cost to take a
359
+ margin on — the account is charged a flat **handling fee** per 1k tokens
360
+ instead, for the routing, prompt assembly, caching, tool bridging and uptime
361
+ that still happen server-side. It is deliberately well under the pooled price
362
+ for the same traffic, so BYOK stays the cheaper lane; it just is not the free
363
+ one.
364
+
365
+ The figure is published by the server (`GET /api/v1/byok/providers` returns
366
+ `fee`) and never hardcoded in this client, so what you see is what is charged.
367
+ Two consequences worth knowing:
368
+
369
+ - A BYOK turn needs an **AEGIS account key** as well as your provider key — that
370
+ is where the fee is billed. Without one the relay refuses up front and says so,
371
+ rather than running the turn and dropping the charge.
372
+ - If a fee is ever configured to zero the lane is genuinely free, and nothing in
373
+ this client needs to change to reflect that.
374
+
375
+ Removing a key is the only thing that stops the key being sent; unsetting
376
+ `/class byok` switches the route but leaves the key on disk.
377
+
378
+ ## Command manual
379
+
380
+ Copy-paste, in the order you actually need them.
381
+
382
+ ### Install and sign in
383
+
384
+ ```bash
385
+ npm install -g aegiscode # requires Node 18+
386
+ aegiscode login # prompts for your AEGIS key, no echo
387
+ aegiscode key status # verify: masked key + which source is in use
388
+ aegiscode # start a session
389
+ ```
390
+
391
+ No AEGIS key yet? Get one at <https://aegiscloud.org>. To run entirely on your
392
+ own provider key instead, skip `login` and see
393
+ [Bring your own key](#bring-your-own-key) — note that lane still bills its fee to
394
+ an AEGIS account.
395
+
396
+ ### Day one in a repo
397
+
398
+ ```bash
399
+ cd ~/my-project
400
+ aegiscode # first run asks you to trust the folder
401
+ /init # sniff the project, write AEGIS.md
402
+ /status # key, class, model, effort, cwd — one panel
403
+ ```
404
+
405
+ Then just type. Plain text is a prompt.
406
+
407
+ ### Ask one question and leave
408
+
409
+ ```bash
410
+ aegiscode "explain this stack trace"
411
+ aegiscode -p "summarise docs/design.md" --json
412
+ echo "why is the sky blue" | aegiscode -p -
413
+ ```
414
+
415
+ `--json` emits the answer plus the usage object, token total and balance.
416
+
417
+ ### Switch how you're paying
418
+
419
+ ```bash
420
+ /class # see every route and who pays
421
+ /class byok # use your own key
422
+ /byok-key openai # …save one first if it says you have none
423
+ /models # what that key unlocks
424
+ /model openai:gpt-4o # pin one
425
+ /class aegis # back to the pool
426
+
427
+ /model add local-llama "Local Llama" llama-3.3-70b http://localhost:11434/v1
428
+ /class custom # or call your own endpoint directly
429
+ ```
430
+
431
+ ### Control the budget
432
+
433
+ ```bash
434
+ /effort low # cheaper, shallower
435
+ /effort high # deeper reasoning
436
+ /cost # this session
437
+ /balance # tokens beside € on every ledger row
438
+ /billing # spend and plan
439
+ ```
440
+
441
+ ### Keep the work
442
+
443
+ ```bash
444
+ /compact # shrink the context, keep the thread
445
+ /export markdown ~/notes/session.md
446
+ /resume # pick up a saved session
447
+ /rewind 3 # back up three turns
448
+ /sync # push pending, then pull
449
+ ```
450
+
451
+ ### When something is wrong
452
+
453
+ ```bash
454
+ /doctor # diagnostics, in one panel
455
+ /status # key + class + model actually in effect
456
+ /byok # which provider keys are set
457
+ /troubleshooting
458
+ ```
459
+
460
+ ### Unattended work
461
+
462
+ ```bash
463
+ aegiscode autonomous add "fix the flaky retry test" --cwd ~/repo
464
+ aegiscode autonomous list
465
+ aegiscode autonomous proceed --commit
466
+ ```
467
+
468
+ Queued tasks always run on the pooled brain (`nexus-brain`); a task naming
469
+ another model is refused where you can still see it. `--commit` commits only the
470
+ paths that task's own tool layer wrote.
471
+
181
472
  ## Account key and cloud sync
182
473
 
183
474
  Three ways in, one store: `aegiscode login <key>`, `/key <api_key>` (or a bare
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "aegiscode",
3
3
  "productName": "AEGIS Code",
4
- "version": "6.7.5",
4
+ "version": "6.7.7",
5
5
  "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.",
6
6
  "author": {
7
7
  "name": "AEGIS Code",
@@ -61,6 +61,19 @@ const FILES = [
61
61
  'desktop/lib/local/shell.js',
62
62
  'desktop/lib/local/agents.js',
63
63
  'desktop/lib/local/prompt.js',
64
+ // The direct-provider transport (openaiCompatible + anthropicMessages) the
65
+ // desktop injects into the engine for its custom-endpoint classes. The CLI's
66
+ // `custom` class (src/engine.js, the /model add catalog) now injects the same
67
+ // real transport instead of the throwing stub it used to, so a user's own
68
+ // base URL + key is called directly with the full tool loop — so this file
69
+ // must ship. Pure node builtins (fetch), stages cleanly.
70
+ 'desktop/lib/local/providers.js',
71
+ // The provider-config store: one row per provider (base URL + key), and the
72
+ // row the 'byok' class reads for a per-provider key. The CLI now selects that
73
+ // class (src/engine.js), so it needs the same store the desktop writes —
74
+ // created without a safeStorage argument, which the store already supports
75
+ // (base64 at rest, file mode 0600). Pure node builtins, so it stages cleanly.
76
+ 'desktop/lib/settings.js',
64
77
  // engine.js requires all three at load time (turn-guard -> git-scope, and
65
78
  // worktree-lock), so leaving them out stages a vendor tree whose engine
66
79
  // throws MODULE_NOT_FOUND before it can answer anything — which is what
package/src/app.js CHANGED
@@ -22,7 +22,7 @@ const readline = require('node:readline');
22
22
  const os = require('node:os');
23
23
  const { randomUUID } = require('node:crypto');
24
24
  const { createTools, createClient, usageTokens, buildSystemPrompt } = require('./deps.js');
25
- const { createEngine } = require('./engine.js');
25
+ const { createEngine, HOST_CLASSES, DEFAULT_CLASS, byokNamespace } = require('./engine.js');
26
26
  const { GLYPH, VERBS, themeOf, RESET, THEME_TABLE } = require('./theme.js');
27
27
  const { LiveRegion, termWidth, w } = require('./screen.js');
28
28
  const { editPreview } = require('./diff.js');
@@ -40,6 +40,7 @@ const {
40
40
  const credentials = require('./credentials.js');
41
41
  const cloudsync = require('./cloudsync.js');
42
42
  const { readSecret } = require('./secret.js');
43
+ const customModelsCatalog = require('./custommodels.js');
43
44
  const { normalizeModelCatalog, pickerEntries, catalogIds } = require('./models.js');
44
45
  const { appendHistory, readSessionTranscript, readOwnSessions } = require('./history.js');
45
46
  const { snapshotCheckpoint } = require('./checkpoint.js');
@@ -126,6 +127,10 @@ function createApp(options = {}) {
126
127
  options.engine ||
127
128
  createEngine({
128
129
  client,
130
+ // The live class — read per turn rather than captured, for the same
131
+ // reason confirmMode is a callback: a captured value made `/class`
132
+ // cosmetic, changing the panel and not what the next turn ran on.
133
+ getClass: () => commandCtx.modelClass,
129
134
  getConfirmMode: () => {
130
135
  if (options.confirmMode !== undefined) return confirmMode;
131
136
  try {
@@ -135,6 +140,14 @@ function createApp(options = {}) {
135
140
  }
136
141
  },
137
142
  });
143
+ // How a class is named in every surface that shows one (the status line, the
144
+ // class panel, the model picker's title). One definition, because the engine
145
+ // owns the label table (CLASS_LABELS) and re-spelling it here would let the
146
+ // picker and /class disagree about what the user is about to run on. Guarded
147
+ // because an injected engine (tests, embedding) may predate the class surface.
148
+ const classLabelOf = (cls) =>
149
+ typeof engine.classLabel === 'function' ? engine.classLabel(cls) : String(cls || '');
150
+
138
151
  // Set by runInteractive: a question/answer channel for the engine's
139
152
  // tool-approval requests. Left null in one-shot (-p) runs, where there is
140
153
  // no one to ask — see the approval branch in ask() below.
@@ -149,6 +162,10 @@ function createApp(options = {}) {
149
162
  const commandCtx = {
150
163
  light: opts.light,
151
164
  model: opts.model,
165
+ // Which class the next turn runs on. 'aegis' is the default because it is
166
+ // the one class an account key alone can run — BYOK additionally needs a
167
+ // provider key, so defaulting to it would break a fresh install.
168
+ modelClass: DEFAULT_CLASS,
152
169
  // `null` = "auto": send no effort, so the server sizes the turn from the
153
170
  // ask. This is the *budget* control on the pooled class (aegis1 sizes the
154
171
  // token ladder from it), which is why it is not defaulted to a rung here —
@@ -443,6 +460,108 @@ function createApp(options = {}) {
443
460
  // providers without a client release.
444
461
  const MODEL_CACHE_MS = 5 * 60_000;
445
462
  const modelCache = { at: 0, models: [] };
463
+ // The BYOK half of the same question. A BYOK model id is `provider:model`
464
+ // (the engine's splitByokModel), built from the server's provider catalog
465
+ // plus the provider rows this machine actually holds a key for — so this list
466
+ // is per-machine, not per-account, and cannot be served by the pooled catalog.
467
+ const byokCache = { at: 0, models: [] };
468
+
469
+ async function loadByokModels({ force = false } = {}) {
470
+ const fresh = byokCache.models.length && Date.now() - byokCache.at < MODEL_CACHE_MS;
471
+ if (!force && fresh) return byokCache.models;
472
+ // An injected engine (tests, embedding) may predate the class surface; an
473
+ // empty list is the honest answer then, not a fabricated one.
474
+ if (typeof engine.listModels !== 'function') return [];
475
+ const res = await engine.listModels('byok');
476
+ // The engine's row is `{id: "provider:model", label, provider, configured}`.
477
+ // `note` is added here because it is the field both renderers actually paint
478
+ // (the picker draws `m.note || m.model`, /models draws `m.note || m.label`)
479
+ // and because "openai:gpt-4o" alone does not say whether this machine holds
480
+ // the key the relay would ask for — a row without one is a turn that 400s,
481
+ // so it names the command that fixes it.
482
+ byokCache.models = ((res && res.models) || []).map((m) => ({
483
+ ...m,
484
+ note: m.configured ? 'key on this machine' : `no key — /byok-key ${m.provider}`,
485
+ }));
486
+ byokCache.at = Date.now();
487
+ return byokCache.models;
488
+ }
489
+
490
+ /**
491
+ * The ids pinnable on one class — the ONE function `/model`, alt+p and
492
+ * `/models` all read, so the picker cannot offer something the class the turn
493
+ * runs on would reject. Both branches swallow their failure into "nothing to
494
+ * offer": a catalog is a convenience, and an offline client must still be
495
+ * able to chat on the server's own default.
496
+ */
497
+ async function loadCustomModels() {
498
+ // The `custom` catalog is local (config.json + the 0600 key store), so this
499
+ // never touches the network and needs no cache. The engine already returns
500
+ // the picker/`/models` shape ({id, label, note, configured, wire}).
501
+ if (typeof engine.listModels !== 'function') return [];
502
+ const res = await engine.listModels('custom');
503
+ return (res && res.models) || [];
504
+ }
505
+
506
+ async function listModelsFor(cls) {
507
+ const want = HOST_CLASSES.includes(cls) ? cls : commandCtx.modelClass;
508
+ try {
509
+ if (want === 'byok') return await loadByokModels();
510
+ if (want === 'custom') return await loadCustomModels();
511
+ return await loadModels();
512
+ } catch {
513
+ return [];
514
+ }
515
+ }
516
+
517
+ /**
518
+ * Whether a pinned id can run on `cls`, decided synchronously (switchClass is
519
+ * not async). byok ids are `provider:model`; custom ids are the catalog's
520
+ * own (config.json, read sync); aegis takes anything that is neither — the
521
+ * pooled catalog is validated separately, at launch, by validatePinnedModel.
522
+ */
523
+ function pinBelongsToClass(cls, id) {
524
+ const s = String(id == null ? '' : id);
525
+ if (cls === 'byok') return s.includes(':');
526
+ if (cls === 'custom') return Boolean(customModelsCatalog.getCustom(s));
527
+ // aegis: not a byok id and not a custom-catalog id.
528
+ return !s.includes(':') && !customModelsCatalog.getCustom(s);
529
+ }
530
+
531
+ /**
532
+ * Switch the live class. Refuses anything this host cannot run (engine.js's
533
+ * HOST_CLASSES is the authority — the local/custom classes stay stubs).
534
+ *
535
+ * A pin is cleared when it does not belong to the class being entered: a
536
+ * pooled id pinned under byok would be parsed as provider `<pooled id>` and
537
+ * fail at the relay with a confusing "no key saved for …" instead of here,
538
+ * with a reason. Symmetrically, `anthropic:claude-…` under aegis is an id the
539
+ * pooled catalog does not advertise, which is the silent-fallback case
540
+ * validatePinnedModel exists to prevent. The `custom` class owns its own id
541
+ * space (the /model add catalog, resolvable synchronously from config.json),
542
+ * so a pin belongs to it exactly when it is one of those ids.
543
+ */
544
+ function switchClass(next) {
545
+ const want = String(next == null ? '' : next).trim().toLowerCase();
546
+ if (!HOST_CLASSES.includes(want)) {
547
+ return { ok: false, error: `unknown class "${next}" — classes: ${HOST_CLASSES.join(', ')}` };
548
+ }
549
+ const prev = commandCtx.modelClass;
550
+ commandCtx.modelClass = want;
551
+ let cleared = null;
552
+ if (prev !== want && commandCtx.model) {
553
+ if (!pinBelongsToClass(want, commandCtx.model)) {
554
+ cleared = commandCtx.model;
555
+ commandCtx.model = null;
556
+ }
557
+ }
558
+ updateConfig({
559
+ modelClass: want,
560
+ model: commandCtx.model,
561
+ currentModelId: commandCtx.model,
562
+ });
563
+ return { ok: true, class: want, prev, cleared };
564
+ }
446
565
 
447
566
  /**
448
567
  * Fetch (or return the cached) model catalog. Rejects when the account cannot
@@ -474,6 +593,48 @@ function createApp(options = {}) {
474
593
  async function validatePinnedModel() {
475
594
  const pinned = commandCtx.model;
476
595
  if (!pinned) return null;
596
+ // A BYOK pin is validated by shape, not by the pooled catalog: the catalog
597
+ // can never contain a `provider:model` id, so checking it here would clear
598
+ // every legitimate BYOK pin on every launch.
599
+ if (commandCtx.modelClass === 'byok') {
600
+ if (String(pinned).includes(':')) return null;
601
+ commandCtx.model = null;
602
+ updateConfig({ model: null, currentModelId: null });
603
+ emit(
604
+ render.renderNotice(
605
+ ctx(),
606
+ 'warn',
607
+ `pinned model "${pinned}" belongs to the pooled class — on BYOK an id is ` +
608
+ '"<provider>:<model>"; pin cleared, /models lists what this machine can relay.'
609
+ )
610
+ );
611
+ return pinned;
612
+ }
613
+ // A custom pin is validated against the local catalog, never the pooled one:
614
+ // its ids are the user's own (from /model add) and the pool has never heard
615
+ // of them, so checking the pooled catalog would clear every custom pin on
616
+ // launch. An empty catalog clears nothing (offline-safe like the pooled path).
617
+ if (commandCtx.modelClass === 'custom') {
618
+ let customModels;
619
+ try {
620
+ customModels = await loadCustomModels();
621
+ } catch {
622
+ return null;
623
+ }
624
+ if (!customModels.length) return null;
625
+ if (customModels.some((m) => m.id === pinned)) return null;
626
+ commandCtx.model = null;
627
+ updateConfig({ model: null, currentModelId: null });
628
+ emit(
629
+ render.renderNotice(
630
+ ctx(),
631
+ 'warn',
632
+ `pinned model "${pinned}" is not in your custom catalog — pin cleared; ` +
633
+ '/models lists your endpoints, /model add registers one.'
634
+ )
635
+ );
636
+ return pinned;
637
+ }
477
638
  let models;
478
639
  try {
479
640
  models = await loadModels();
@@ -895,6 +1056,7 @@ function createApp(options = {}) {
895
1056
  return {
896
1057
  version: VERSION,
897
1058
  model: commandCtx.model || 'server default',
1059
+ class: commandCtx.modelClass,
898
1060
  effort: commandCtx.effort,
899
1061
  thinking: commandCtx.thinking,
900
1062
  theme: commandCtx.light ? 'light' : 'dark',
@@ -918,13 +1080,15 @@ function createApp(options = {}) {
918
1080
  permissions: { mode: rules.defaultMode, rules },
919
1081
  // The selectable (pickable) catalog, not the raw payload: alias tiers are
920
1082
  // dropped, live ids only (see models.js pickerEntries).
921
- models: pickerEntries(modelCache.models),
1083
+ // Whichever class is live decides what is pinnable — the pooled ids the
1084
+ // server advertises, or the `provider:model` ids this machine can relay.
1085
+ models: pickerEntries(commandCtx.modelClass === 'byok' ? byokCache.models : modelCache.models),
922
1086
  commands: visibleCommands(),
923
1087
  transcript: transcript.slice(),
924
1088
  sessions: [],
925
1089
  memory: {},
926
1090
  lastRecap: commandCtx.lastRecap,
927
- backend: 'aegis',
1091
+ backend: commandCtx.modelClass,
928
1092
  url: client.apiBase,
929
1093
  };
930
1094
  }
@@ -977,7 +1141,7 @@ function createApp(options = {}) {
977
1141
  let lines = null;
978
1142
  if (o.type === 'panel') lines = o.lines;
979
1143
  else if (o.type === 'palette') lines = overlays.renderPalette(visibleCommands(), { query: o.query || '', sel: o.sel || 0 }, W, rows);
980
- else if (o.type === 'model') lines = overlays.renderModelPicker(o.items || [], o.sel || 0, W, rows, o.current != null ? o.current : commandCtx.model);
1144
+ else if (o.type === 'model') lines = overlays.renderModelPicker(o.items || [], o.sel || 0, W, rows, o.current != null ? o.current : commandCtx.model, o.cls || commandCtx.modelClass, classLabelOf);
981
1145
  else if (o.type === 'effort') lines = overlays.renderEffortPicker(o.sel || 0, W, commandCtx.effort);
982
1146
  else if (o.type === 'resume') lines = overlays.renderResumeList(o.items || [], o.sel || 0, W, rows);
983
1147
  else if (o.type === 'confirm') lines = render.renderApproval(ctx(), o.info || {}, W).map((s) => [spanRow(s)]);
@@ -1042,10 +1206,26 @@ function createApp(options = {}) {
1042
1206
  runPrompt: (text) => runPrompt(text),
1043
1207
  ask: (text) => ask(text),
1044
1208
  runTool: (name, args) => runTool(name, args),
1045
- // The AEGIS catalog fetch `/model` and alt+p expect (see loadModels).
1046
- // Wired on the app's context so the chatflow's `Object.assign`-based
1047
- // context inherits it too — one definition, both hosts.
1048
- loadModels: (o) => loadModels(o),
1209
+ // The catalog `/model` and alt+p expect. Routed through listModelsFor so
1210
+ // it follows the LIVE class: on the pooled class that is the server's
1211
+ // catalog (loadModels), on byok the `provider:model` ids this machine can
1212
+ // relay. Wired on the app's context so the chatflow's `Object.assign`
1213
+ // based context inherits it too — one definition, both hosts, and the
1214
+ // picker can never offer something the class would reject.
1215
+ loadModels: () => listModelsFor(commandCtx.modelClass),
1216
+ // The provider-key store (`byok:<provider>` rows) /byok-key writes. Read
1217
+ // through a function, not captured, because an injected engine may not
1218
+ // carry one.
1219
+ settings: () => engine.settings || null,
1220
+ // The one spelling of a provider's settings row, shared with the engine
1221
+ // that reads it (`byok:<provider>`) — see engine.js byokNamespace.
1222
+ byokNamespace: (p) => byokNamespace(p),
1223
+ // The class surface: /class switches, /models lists for whichever class
1224
+ // is live (the frozen state carries the current one as c.ctx.modelClass).
1225
+ listModelsFor: (cls) => listModelsFor(cls),
1226
+ switchClass: (cls) => switchClass(cls),
1227
+ classLabel: (cls) => classLabelOf(cls),
1228
+ classes: () => (typeof engine.listClasses === 'function' ? engine.listClasses() : []),
1049
1229
  refreshSpend: () => refreshSpend(),
1050
1230
  state: () => buildState(),
1051
1231
  setInput: () => {},
@@ -1567,6 +1747,9 @@ function createApp(options = {}) {
1567
1747
  } catch {
1568
1748
  return;
1569
1749
  }
1750
+ // The class first: a stored BYOK pin is only meaningful under byok, and the
1751
+ // pin check right after this reads whichever class won.
1752
+ if (HOST_CLASSES.includes(cfg.modelClass)) commandCtx.modelClass = cfg.modelClass;
1570
1753
  if (!opts.model && cfg.model) commandCtx.model = cfg.model;
1571
1754
  // `null` in the config is "auto" and is deliberately not assigned over the
1572
1755
  // default — there is nothing to restore, because nothing is pinned.
package/src/chatflow.js CHANGED
@@ -870,7 +870,15 @@ async function runSession(host) {
870
870
  if (overlay.type === 'palette') {
871
871
  ol = overlays.renderPalette(host.visibleCommands(), { query: paletteQuery(overlay.query), sel: overlay.sel }, cols, termRows);
872
872
  } else if (overlay.type === 'model') {
873
- ol = overlays.renderModelPicker(overlay.items || [], overlay.sel || 0, cols, termRows, overlay.current);
873
+ // The class rides on the overlay (set where it was opened, commands.js
874
+ // /model) with the live ctx as the fallback, and the label comes from the
875
+ // engine's table via the host — so this path and app.js's renderOverlay
876
+ // paint the same title, subtitle and row semantics for the same overlay.
877
+ ol = overlays.renderModelPicker(
878
+ overlay.items || [], overlay.sel || 0, cols, termRows, overlay.current,
879
+ overlay.cls || ctx.modelClass,
880
+ typeof host.classLabel === 'function' ? host.classLabel : null
881
+ );
874
882
  } else if (overlay.type === 'effort') {
875
883
  ol = overlays.renderEffortPicker(overlay.sel || 0, cols, ctx.effort);
876
884
  } else if (overlay.type === 'resume') {