aegis-desktop 0.7.7 → 0.8.0

package/lib/local/engine.js

@@ -45,6 +45,7 @@ const os = require('node:os');
 
 const toolsModule = require('./tools.js');
 const promptModule = require('./prompt.js');
+const localTransport = require('./local.js');
 const { ShellSession } = require('./shell.js');
 const { agentSystemPrompt, agentRoleLabel } = require('./agents.js');
 // Cooperative working-tree sharing (see each module's header). The lock
@@ -57,6 +58,24 @@ const { agentSystemPrompt, agentRoleLabel } = require('./agents.js');
 const { beginTurnGuard, recordWrite, blocksDestructive } = require('./turn-guard.js');
 const { acquireWorktreeLock, releaseWorktreeLock } = require('./worktree-lock.js');
 
+// `~/.aegiscode/.env` — the shared key file both hosts load at startup, so
+// "put your key in the env file" is the whole setup instruction for either app.
+// Optional by design, and resolved the same two ways this repo resolves every
+// shared module: repo-relative in a checkout AND in the CLI's mirrored vendor
+// tree (cli/vendor/client/env-file.js), then the staged app-dir copy a packaged
+// desktop build carries. Absent in all three, `envFile` stays null and byok
+// reads the encrypted store alone — exactly the behaviour before this file.
+let envFile = null;
+try {
+  envFile = require('../../../client/env-file.js');
+} catch {
+  try {
+    envFile = require('../../vendor/env-file.js');
+  } catch {
+    envFile = null;
+  }
+}
+
 /**
  * How long a turn waits for the working-tree lock before running anyway.
  *
@@ -70,9 +89,6 @@ const { acquireWorktreeLock, releaseWorktreeLock } = require('./worktree-lock.js
  */
 const WORKTREE_LOCK_WAIT_MS = 1500;
 
-/** Classes whose transport is a user-supplied endpoint + credential. */
-const CUSTOM_CLASSES = Object.freeze(['openai-compat', 'anthropic']);
-
 /**
  * Depth at which the task tool stops being offered. The main chat (depth 0)
  * and subagents down to depth MAX_SUBAGENT_DEPTH - 1 can all delegate, so
@@ -82,20 +98,31 @@ const CUSTOM_CLASSES = Object.freeze(['openai-compat', 'anthropic']);
  */
 const MAX_SUBAGENT_DEPTH = 4;
 
+// The three shipping classes — kept in lockstep with the CLI's HOST_CLASSES
+// (cli/src/engine.js). 'anthropic'/'openai'/'deepseek' still appear in this
+// file as BYOK *provider* ids: upstream names, never model classes.
+//
+//   aegis — pooled relay; the account key pays the pool's margin.
+//   byok  — relayed with the caller's provider key; AEGIS bills a handling fee.
+//   local — a model on hardware the user owns, reached over loopback. Bills
+//           nobody because there is no vendor: the compute was already bought.
+//           Fenced by local.js `remoteRefusal()` — a remote URL here would be
+//           an unpaid turn, which is why that gate exists and fails closed.
 const CLASSES = [
   { class: 'aegis', label: 'Aegis Cloud', kind: 'cloud' },
-  { class: 'ollama', label: 'Ollama (local)', kind: 'local' },
-  { class: 'openai-compat', label: 'Custom OpenAI-compatible', kind: 'custom' },
-  { class: 'anthropic', label: 'Anthropic-compatible', kind: 'custom' },
   { class: 'byok', label: 'Bring your own key', kind: 'cloud' },
+  { class: 'local', label: 'Local model', kind: 'local' },
 ];
 
-/** Local settings namespace for one BYOK provider's key. A `byok:` prefix
- *  keeps this out of the 'anthropic'/'openai-compat' CUSTOM_CLASSES' own
- *  namespaces, which are a different feature (a self-hosted/compatible
- *  endpoint's base URL + key) — same store, deliberately separate rows. */
+/** Local settings namespace for one BYOK provider's key. The `byok:` prefix
+ *  keeps a provider key (e.g. 'anthropic' the *provider*) in its own row out
+ *  of every model class's row in the same store — one flat 'byok' row could
+ *  not hold two providers' keys at once. Named once here because two callers
+ *  now need to take the provider back OUT of a row name. */
+const BYOK_NAMESPACE_PREFIX = 'byok:';
+
 function byokNamespace(providerId) {
-  return `byok:${providerId}`;
+  return `${BYOK_NAMESPACE_PREFIX}${providerId}`;
 }
 
 /** Split a byok model id ("anthropic:claude-sonnet-5") into its provider and
@@ -109,6 +136,28 @@ function splitByokModel(compound) {
   return { provider: s.slice(0, i), model: s.slice(i + 1) };
 }
 
+/**
+ * The BYOK key an environment variable supplies for a provider, if any — from
+ * `~/.aegiscode/.env` (loaded into the environment at host startup via
+ * `client/env-file.js`) or an explicit shell export. '' when neither has one,
+ * which leaves the encrypted store the only source, exactly as before.
+ *
+ * Read HERE and not inside lib/settings.js on purpose. The store's contract is
+ * "what I persisted": its tests assert `configured === false` after a
+ * remove(), and a store that silently answered from the environment would break
+ * that — and would make a provider look configured to code that never learns
+ * where the key came from. The resolution chain (store first, environment
+ * second) belongs to the class that spends the key, which is this one.
+ */
+function providerKeyFromEnv(provider) {
+  if (!envFile || typeof envFile.providerKeyFromEnv !== 'function') return '';
+  try {
+    return envFile.providerKeyFromEnv(provider).key || '';
+  } catch {
+    return '';
+  }
+}
+
 /**
  * Mirrors aegiscodex-dev's src/backend.js DEEPSEEK_REASONING_MODEL_RE +
  * EFFORT_TOKEN_BUDGET verbatim. DeepSeek's reasoning models (deepseek-flash,
@@ -130,12 +179,6 @@ function splitByokModel(compound) {
 const DEEPSEEK_REASONING_MODEL_RE = /^deepseek-(v4(\.\d+)?-(flash|pro)|flash|pro|reasoner)$/;
 const EFFORT_TOKEN_BUDGET = { low: 8192, medium: 16384, high: 32768 };
 
-/** The one class whose wire format REQUIRES a stated `max_tokens`: Anthropic's
- *  Messages API 400s without it, so that field is derived from the effort rung
- *  rather than invented by the transport (which is what a blanket
- *  `max_tokens: maxTokens || 4096` did — see providers.anthropicMessages). */
-const REQUIRES_STATED_BUDGET = new Set(['anthropic']);
-
 /**
  * Idle-stream budget for a pooled brain call ("work autonomously"). The
  * generic watchdog in vendor/aegis.js kills a stream that goes 60s without a
@@ -170,8 +213,7 @@ const AUTONOMOUS_IDLE_TIMEOUT_MS = 15 * 60_000;
  *      so a caller asking for 1024 silently ran on 32768.
  *   2. with nothing stated, a model that reasons against its own output budget
  *      (DeepSeek bills hidden chain-of-thought against the SAME budget as the
- *      answer) or a class whose wire format REQUIRES the field (Anthropic's
- *      Messages API) gets the Effort rung. This is why the renderer's
+ *      answer) gets the Effort rung. This is why the renderer's
  *      max-tokens dropdown was removed rather than fixed: at its 4k default a
  *      reasoning model spent the entire budget thinking and finished empty —
  *      no error, no tool call, just a "completed" turn with nothing in it.
@@ -183,10 +225,10 @@ const AUTONOMOUS_IDLE_TIMEOUT_MS = 15 * 60_000;
  * doubled-budget retry plus emptyTurnError — rather than by inflating the
  * caller's ceiling up front.
  */
-function reasoningBudget(cls, model, maxTokens, effort) {
+function reasoningBudget(model, maxTokens, effort) {
   const stated = Number(maxTokens);
   if (Number.isFinite(stated) && stated > 0) return stated;
-  if (DEEPSEEK_REASONING_MODEL_RE.test(String(model || '')) || REQUIRES_STATED_BUDGET.has(cls)) {
+  if (DEEPSEEK_REASONING_MODEL_RE.test(String(model || ''))) {
     const eff = effort === 'low' || effort === 'medium' ? effort : 'high';
     return EFFORT_TOKEN_BUDGET[eff];
   }
@@ -390,7 +432,18 @@ function emptyTurnError({ cls, model, maxTokens, finishReason }) {
   return err;
 }
 
-function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBuilder, env, getConfirmMode }) {
+function createLocalEngine({
+  aegis,
+  settings,
+  tools,
+  promptBuilder,
+  env,
+  getConfirmMode,
+  // Injectable for tests; defaults to the real transport so every existing
+  // caller (desktop/main.js, the CLI's deps.js) wires the local class by
+  // simply existing.
+  localTransport: localT = localTransport,
+}) {
   const controllers = new Map(); // sessionId -> AbortController
   const T = tools || toolsModule;
   const buildSystemPrompt = (promptBuilder && promptBuilder.buildSystemPrompt) || promptModule.buildSystemPrompt;
@@ -652,42 +705,44 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     return guardedExecute(name, args, toolCtx);
   }
 
-  /**
-   * Custom endpoints are only usable when they are actually configured:
-   * a base URL is mandatory for both, and Anthropic additionally needs its own
-   * key (the wire format authenticates with x-api-key). Reporting them as
-   * always-ready made chat() POST to `${undefined}/v1/…` (defect #2).
-   */
-  function customStatus(cls) {
-    const cfg = settings.get(cls) || {};
-    const baseURL = typeof cfg.baseURL === 'string' ? cfg.baseURL.trim() : '';
-    const hasBase = Boolean(baseURL);
-    const hasKey = Boolean(cfg.configured);
-    return {
-      configured: cls === 'anthropic' ? hasBase && hasKey : hasBase,
-      baseURL,
-      keyMask: cfg.keyMask || null,
-    };
-  }
-
   async function listClasses() {
-    const status = await ollama.probe().catch(() => ({ running: false }));
     return CLASSES.map((c) => {
-      if (c.class === 'ollama') return { ...c, configured: Boolean(status.running) };
       if (c.class === 'aegis') {
         return { ...c, configured: Boolean(aegis.apiKey) };
       }
       if (c.class === 'byok') {
-        // Configured means "at least one provider has a locally-stored key",
-        // not a single baseURL+key pair like the CUSTOM_CLASSES below — byok
-        // holds one row per provider (byokNamespace), so customStatus's shape
-        // does not apply here.
-        const anyConfigured = (settings.list() || []).some(
-          (s) => s && typeof s.provider === 'string' && s.provider.startsWith('byok:') && s.configured
-        );
+        // Configured means "this host could actually spend a key for at least
+        // one provider" — byok holds one row per provider (byokNamespace), so
+        // there is no single baseURL+key pair to report. A row whose key lives
+        // in `~/.aegiscode/.env` counts: that is the whole point of reading the
+        // file, and calling it unconfigured would send the user to a Settings
+        // row they do not need. A stored key still short-circuits, so an install
+        // with no env file pays one lookup per stored row and nothing else.
+        //
+        // The authoritative per-provider answer is `listModels`, which has the
+        // server's catalog and so can name a provider the user has never opened
+        // Settings for. This one can only see providers with a stored row.
+        const rows = settings.list() || [];
+        const anyConfigured = rows.some((s) => {
+          if (!s || typeof s.provider !== 'string' || !s.provider.startsWith('byok:')) return false;
+          if (s.configured) return true;
+          return Boolean(providerKeyFromEnv(s.provider.slice(BYOK_NAMESPACE_PREFIX.length)));
+        });
         return { ...c, configured: anyConfigured };
       }
-      return { ...c, ...customStatus(c.class) };
+      if (c.class === 'local') {
+        // Always "configured": this class needs no credential at all, which is
+        // the entire reason it is free. Whether a daemon is actually listening
+        // is a different question, asked where the answer belongs — in
+        // listModels, next to the model list the user is looking at, so the
+        // state reads "start the daemon" instead of "go and configure
+        // something", which is what an unconfigured row would say.
+        return { ...c, configured: true };
+      }
+      // Unreachable while CLASSES lists only aegis + byok + local; kept so a
+      // future class added without a status rule reads as unconfigured rather
+      // than silently appearing ready (the "no saved key" fallback shape).
+      return { ...c, configured: false };
     });
   }
 
@@ -707,28 +762,43 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       const data = await aegis.listModels();
       return { class: cls, models: filterAegisCatalog(normalizeCatalog(data && data.models)) };
     }
-    if (cls === 'ollama') {
-      const tags = await ollama.listTags();
-      return { class: cls, models: tags.map((t) => ({ id: t.id })) };
-    }
     if (cls === 'byok') {
       // The server's catalog names every provider it accepts a key for, the
       // models each unlocks, and whether an AEGIS account key is even needed
-      // to ask (it is not — see byokProviders' own docstring). Deliberately
-      // NOT gated on aegis.apiKey the way the pooled class above is: BYOK's
-      // whole point is a caller who brings their own credential, and the
-      // catalog itself answers to an anonymous request.
+      // to ask (it is not — the catalog answers an anonymous request).
+      // Deliberately NOT gated on aegis.apiKey the way the pooled class above
+      // is: BYOK's whole point is a caller who brings their own credential, and
+      // hiding the catalog would hide the answer to "which key do I go and get"
+      // from exactly the person deciding whether to bother. Nothing here
+      // enforces billing either: the desktop is one client of a route that is
+      // unauthenticated by design, so refusing in this process would stop
+      // exactly one host out of many. The relay owns that decision, and reports
+      // it via `fee.require_balance` below.
       let providers = [];
+      let fee = null;
       try {
         const data = await aegis.byokProviders();
         providers = (data && data.providers) || [];
+        // The handling fee AEGIS adds on top of the caller's vendor bill. It is
+        // the server's own published rate (services/pricing.price_byok_call) and
+        // is passed through untouched — never re-derived here, because a client
+        // that hardcodes a fee is a client that can disagree with the ledger.
+        // Absent until the server publishes one, and the UI must then say
+        // nothing rather than show a guess.
+        fee = (data && data.fee) || null;
       } catch {
         providers = [];
       }
       const models = [];
       for (const p of providers) {
         if (!p || !p.id) continue;
-        const local = settings.get(byokNamespace(p.id)) || {};
+        const rowCfg = settings.get(byokNamespace(p.id)) || {};
+        // A key from `~/.aegiscode/.env` makes the provider usable, so it must
+        // read as configured here — this is the flag `needsProviderKey` is built
+        // on, and the one the renderer's per-provider rows mirror. Reporting it
+        // unconfigured while `chat()` happily spends the env key is exactly the
+        // "no saved key" contradiction this file removes.
+        const fromEnv = providerKeyFromEnv(p.id);
         const rawModels = Array.isArray(p.models) ? p.models : [];
         for (const m of rawModels) {
           const modelId = typeof m === 'string' ? m : m && m.id;
@@ -737,25 +807,53 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
             id: `${p.id}:${modelId}`,
             label: `${p.label || p.id} — ${modelId}`,
             provider: p.id,
-            configured: Boolean(local.configured),
+            configured: Boolean(rowCfg.configured || fromEnv),
           });
         }
       }
       return {
         class: cls, models, providers,
         needsProviderKey: models.length > 0 && !models.some((m) => m.configured),
+        needsAegisKey: !aegis.apiKey,
+        fee,
       };
     }
-    // Custom endpoints: the model id is the *user's* choice — a provider model
-    // name, never a URL. Offering the configured base URL as an `id` meant that
-    // leaving the default selection POSTed `model: "https://api.openai.com/v1"`,
-    // an upstream 400 invalid-model on every call (defect B). There is nothing
-    // to enumerate, so the list stays empty and `needsModelId` tells the
-    // renderer to prompt for a typed id instead. The base URL still travels
-    // along for display only.
-    const cfg = settings.get(cls) || {};
-    const baseURL = typeof cfg.baseURL === 'string' ? cfg.baseURL.trim() : '';
-    return { class: cls, models: [], needsModelId: true, baseURL };
+    if (cls === 'local') {
+      // No credential to check, so the only question is whether anything is
+      // listening. The probe never throws (local.js), so a machine with no
+      // daemon reports a STATE and the renderer invites the user to start one —
+      // the same shape as the pooled class's `needsKey` above, and for the same
+      // reason: an install in its default state must be told what unblocks it,
+      // not shown a transport error.
+      const cfg = settings.get('local') || {};
+      const baseURL = cfg.baseURL || localT.DEFAULT_BASE;
+      const status = await localT.probe(baseURL);
+      if (!status.running) {
+        return { class: cls, models: [], baseURL: status.baseURL, needsDaemon: true };
+      }
+      // The daemon is up. Its tag list is Ollama's native endpoint, so a
+      // non-Ollama server on the same box (llama.cpp, LM Studio, vLLM) answers
+      // 404 here — recoverable, and it must not cost the class its usability:
+      // the renderer falls back to letting the user type a model name, and the
+      // transport itself never needs this call.
+      let tags = [];
+      let listed = true;
+      try {
+        tags = await localT.listTags(baseURL);
+      } catch {
+        listed = false;
+      }
+      return { class: cls, models: tags, baseURL: status.baseURL, listed };
+    }
+    // Unreachable by construction: CLASSES lists only 'aegis', 'byok' and
+    // 'local', all returned above. Thrown rather than falling through to an
+    // empty list, because "no models" is a state the renderer renders as a
+    // normal empty picker — an unknown class would look like a
+    // configured-but-empty account instead of the bug it is. Same shape as
+    // dispatch's tail.
+    throw new Error(
+      `listModels: unknown model class ${JSON.stringify(cls)} — this build ships 'aegis', 'byok' and 'local' only`
+    );
   }
 
   /**
@@ -919,19 +1017,6 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       });
     }
 
-    if (cls === 'ollama') {
-      return ollama.chat({
-        model: opts.model,
-        prompt: opts.prompt,
-        system: opts.system,
-        messages: opts.messages,
-        maxTokens: opts.maxTokens,
-        signal: opts.signal,
-        onDelta: opts.onDelta,
-        ...(opts.tools.length ? { tools: opts.tools, toolChoice: opts.toolChoice } : {}),
-      });
-    }
-
     if (cls === 'byok') {
       // opts.model is still the compound "provider:model" id here — the
       // relay wants them split (a `provider` field plus a bare `model`).
@@ -941,35 +1026,84 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       // automatically by byokChatCompletion() as X-AEGIS-Key so the account
       // gets billed the handling fee; see client/aegis.js.
       const { provider, model: bareModel } = splitByokModel(opts.model);
-      return aegis.byokChatCompletion({
-        provider,
-        model: bareModel,
-        providerKey: opts.apiKey,
-        prompt: opts.prompt,
-        system: opts.system,
-        messages: opts.messages,
-        maxTokens: opts.maxTokens,
-        stream: true,
-        onStream: opts.onDelta,
-        signal: opts.signal,
-      });
+      try {
+        return await aegis.byokChatCompletion({
+          provider,
+          model: bareModel,
+          providerKey: opts.apiKey,
+          prompt: opts.prompt,
+          system: opts.system,
+          messages: opts.messages,
+          maxTokens: opts.maxTokens,
+          stream: true,
+          onStream: opts.onDelta,
+          signal: opts.signal,
+        });
+      } catch (e) {
+        // The relay's own balance gate (aegis1 `AEGIS_BYOK_REQUIRE_BALANCE`,
+        // app.py `byok_chat_completions`) answers 402 with a body aimed at an
+        // API consumer — "Insufficient balance. Top up to continue using
+        // BYOK." Shown raw in a chat transcript that reads as a crash rather
+        // than a bill, so the one thing the user has to DO is said here, in the
+        // hosts' own voice. The status is preserved so every existing caller
+        // (the CLI's error painter, the desktop turn guard) still sees a 402.
+        //
+        // The provider key is untouched by this: it is the caller's own and it
+        // is still valid. What ran out is the AEGIS balance the handling fee
+        // is billed against, which is the whole reason this lane has a fee.
+        if (e && e.status === 402) {
+          const err = new Error(
+            'byok: this account has no AEGIS balance left, and the BYOK handling fee is ' +
+              'billed there — your provider key is still valid, this is not a key problem. ' +
+              'Top up the account, then try again (or /class aegis to use the pooled lane).'
+          );
+          err.status = 402;
+          throw err;
+        }
+        throw e;
+      }
     }
 
-    const common = {
-      baseURL: opts.cfg.baseURL,
-      apiKey: opts.apiKey,
-      model: opts.model,
-      prompt: opts.prompt,
-      system: opts.system,
-      messages: opts.messages,
-      maxTokens: opts.maxTokens,
-      signal: opts.signal,
-      onDelta: opts.onDelta,
-      ...(opts.tools.length ? { tools: opts.tools, toolChoice: opts.toolChoice } : {}),
-    };
+    if (cls === 'local') {
+      // The one class whose turn leaves this machine for hardware the user
+      // owns. `baseURL` comes from the 'local' settings row and is re-checked
+      // by the transport on every call (local.js `remoteRefusal`), so a row
+      // hand-edited to a public address after it was saved still cannot be
+      // dialed — the engine is not the only gate, it is the first one.
+      const baseURL = (opts.cfg && opts.cfg.baseURL) || localT.DEFAULT_BASE;
+      const call = (useTools) =>
+        localT.chat({
+          baseURL,
+          model: opts.model,
+          prompt: opts.prompt,
+          system: opts.system,
+          messages: opts.messages,
+          maxTokens: opts.maxTokens,
+          signal: opts.signal,
+          onDelta: opts.onDelta,
+          ...(useTools && opts.tools.length ? { tools: opts.tools, toolChoice: opts.toolChoice } : {}),
+        });
+      try {
+        return await call(true);
+      } catch (e) {
+        // An older daemon 400s on `tools` it does not understand. Sending none
+        // gets the turn answered — without tool access, which is worse than the
+        // full loop and far better than a 400 the user cannot act on. Retried
+        // once, and only for that one status: a 400 about the model name or the
+        // message shape is not fixed by dropping schemas, and retrying it would
+        // send the same broken turn twice.
+        if (opts.tools.length && e && e.status === 400) return call(false);
+        throw e;
+      }
+    }
 
-    if (cls === 'anthropic') return providers.anthropicMessages(common);
-    return providers.openaiCompatible(common);
+    // Unreachable by construction: CLASSES lists only 'aegis', 'byok' and
+    // 'local', all returned above. Thrown rather than falling through to a
+    // default transport, because a class that silently borrows another's wire
+    // format is this file's recurring failure mode.
+    throw new Error(
+      `dispatch: unknown model class ${JSON.stringify(cls)} — this build ships 'aegis', 'byok' and 'local' only`
+    );
   }
 
   async function chat(payload, onDelta) {
@@ -982,7 +1116,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     // gets no stated budget, which is exactly the "hidden CoT ate the whole
     // default and returned nothing" failure this budget exists to prevent.
     const reasoningModelId = cls === 'byok' ? splitByokModel(model).model : model;
-    const maxTokens = reasoningBudget(cls, reasoningModelId, payload && payload.maxTokens, payload && payload.effort);
+    const maxTokens = reasoningBudget(reasoningModelId, payload && payload.maxTokens, payload && payload.effort);
     // The caller's OWN number, kept apart from `maxTokens` above. That one
     // collapses two different facts into a single value — "the caller stated
     // 4096" and "effort implies 32768" — and the pooled path must treat them
@@ -1038,8 +1172,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     // build a prompt promising tool access the transport silently drops —
     // the model would reason about exec/readFile and never see a result.
     const toolsEnabled = cls !== 'byok' && !(payload && payload.tools === false);
-    const wire = cls === 'anthropic' ? 'anthropic' : 'openai';
-    const toolSchemas = toolsEnabled ? T.toolsFor(wire, { includeSubagent: depth < MAX_SUBAGENT_DEPTH }) : [];
+    const toolSchemas = toolsEnabled ? T.toolsFor({ includeSubagent: depth < MAX_SUBAGENT_DEPTH }) : [];
     const toolChoice = (payload && payload.toolChoice) || null;
 
     const system = (payload && payload.system) || buildSystemPrompt(envFor(payload));
@@ -1069,14 +1202,22 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       // under the literal class name — one flat 'byok' row could not hold
       // more than one provider's key at a time.
       const byokParts = cls === 'byok' ? splitByokModel(model) : null;
+      // aegis carries its own credential on the `aegis` client; byok is the
+      // only class whose key comes out of the settings store, and it comes from
+      // the provider named in the model id.
       const cfg =
-        cls === 'aegis' || cls === 'ollama' ? {}
-        : cls === 'byok' ? settings.get(byokNamespace(byokParts.provider)) || {}
-        : settings.get(cls) || {};
-      const apiKey =
-        cls === 'aegis' || cls === 'ollama' ? null
-        : cls === 'byok' ? settings.rawKey(byokNamespace(byokParts.provider))
-        : settings.rawKey(cls);
+        cls === 'byok' ? settings.get(byokNamespace(byokParts.provider)) || {}
+        : cls === 'local' ? settings.get('local') || {}
+        : {};
+      // Where a byok key comes from, in order: the encrypted store (a key saved
+      // through the app), then the shared `~/.aegiscode/.env` (client/env-file.js,
+      // read into process.env at start-up). The store wins when it holds one, so
+      // removing a key there still means removed — the file is the convenience,
+      // not a second authority.
+      const storedKey = cls === 'byok' ? settings.rawKey(byokNamespace(byokParts.provider)) : null;
+      const apiKey = cls !== 'byok'
+        ? null
+        : (storedKey || providerKeyFromEnv(byokParts.provider));
 
       if (cls === 'byok' && (!byokParts.provider || !byokParts.model)) {
         const err = new Error(
@@ -1088,24 +1229,49 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       }
       if (cls === 'byok' && !apiKey) {
         const err = new Error(
-          `byok: no key saved for "${byokParts.provider}" — add one before chatting with this model.`
+          `No key for "${byokParts.provider}" yet. Easiest fix: /class aegis (uses your AEGIS key, ` +
+            `no setup) — or add this provider's own key: /byok-key ${byokParts.provider} <key>.`
         );
         err.status = 400;
         throw err;
       }
-
-      // Custom classes carry no enumerable model list (see listModels), so a
-      // blank id here means the user never typed one. Fail loudly in-process
-      // instead of shipping `model: undefined` upstream (defect B).
-      if (CUSTOM_CLASSES.includes(cls) && (typeof model !== 'string' || !model.trim())) {
+      // …and the AEGIS account key is what makes the turn BILLABLE at all. The
+      // relay authenticates on the provider key and resolves the payer
+      // separately, from X-AEGIS-Key (app.py `_byok_identify_user`): with no
+      // account key the server can attribute the handling fee to no one, so it
+      // is logged against user 0 as uncollected — an anonymous free ride the
+      // fee exists to close. Require the account key here so EVERY BYOK turn is
+      // attributed and every caller pays the handling fee: a funded balance is
+      // debited immediately, an unfunded one records the fee as owed
+      // (token_bank.charge_byok clamps to zero and never refuses), and nobody
+      // is served free. Balance is the server's own concern, not this gate's —
+      // with a balance or without one, the account still pays. `listModels`
+      // still answers anonymously (the catalog is how a user finds out which
+      // key to get), so this refuses only the send, and only until a key lands.
+      if (cls === 'byok' && !aegis.apiKey) {
         const err = new Error(
-          `${cls}: a model id is required — type the provider's model name ` +
-            '(the base URL is not a model).'
+          'No AEGIS key connected yet. Easiest fix: /class aegis (skips BYOK entirely) — ' +
+            'or add your AEGIS key with /login, then try again.'
         );
-        err.status = 400;
+        err.status = 401;
         throw err;
       }
 
+      // The direct-dial gate, restored for the one class that legitimately
+      // dials. It policed a lane that could reach ANY user-supplied URL, which
+      // billed nobody — no pooled margin, no BYOK handling fee, no account key
+      // attached — so a remote URL there was an unpaid turn to refuse rather
+      // than meter. That open-ended lane is gone for good. `local` is the case
+      // its own reasoning carved out: a model on a machine the user owns, where
+      // there is no vendor to pay in the first place, so there is nothing to
+      // bill and nobody being cheated. Checked here before any byte goes out,
+      // and again inside the transport, because a settings row can be edited on
+      // disk after it was written. Anything not local is refused, not metered —
+      // remote models belong on `aegis` or `byok`, both of which bill.
+      if (cls === 'local') {
+        const refusal = localT.remoteRefusal(cfg.baseURL || localT.DEFAULT_BASE);
+        if (refusal) throw refusal;
+      }
       const base = {
         cls, model, mode: payload && payload.mode, maxTokens, statedMaxTokens, autonomous, sessionId, signal, onDelta, cfg, apiKey, toolChoice,
         effort: payload && payload.effort,
@@ -1320,16 +1486,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         // clear it explicitly, being re-dispatches inside round 1).
         const opts = { ...base, system, messages: history, prompt, tools: toolSchemas, recallDeep: base.recallDeep && round === 1 };
         let res;
-        try {
-          res = await dispatch(cls, opts);
-        } catch (e) {
-          // Ollama's OpenAI shim rejects `tools` on older builds. Retrying once
-          // without them keeps local chat working instead of turning an
-          // unadvertised capability into a hard failure.
-          const retriable = cls === 'ollama' && toolSchemas.length && e && (e.status === 400 || /tool/i.test(e.message || ''));
-          if (!retriable) throw e;
-          res = await dispatch(cls, { ...opts, tools: [] });
-        }
+        res = await dispatch(cls, opts);
         addUsage(res);
 
         // A cancelled turn is over. Both recoveries below exist for "the model
@@ -1419,7 +1576,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         foldPromptIntoHistory();
 
         // Thread the assistant turn (its tool_calls) and each result back in
-        // the shapes both wire formats accept (providers.js normalises them).
+        // the OpenAI shape the relay accepts.
         history.push({
           role: 'assistant',
           content: assistantText(res),