aegis-desktop 0.7.7 → 0.7.8

package/README.md

@@ -5,26 +5,95 @@ with an **agentic tool loop**: the model can read, write, and edit files,
 list directories, glob, grep, run shell commands in a persistent session, and
 delegate whole sub-tasks to subagents. It does **not** require Claude Code.
 
+## Install
+
+Download a build from the
+[releases page](https://github.com/aegiscloud/aegiscode-desktop/releases), or
+install from npm:
+
 ```bash
-npm install -g aegis-desktop
-aegis
+npm install -g aegis-desktop     # requires Node 18+
+aegis                            # launch
 ```
 
+Either way, on first launch:
+
+1. Open **Settings** in the sidebar.
+2. Paste an AEGIS key into the **API key** row — get a free one at
+   <https://aegiscloud.org>. `AEGIS_API_KEY` is picked up from the environment
+   if you would rather not paste it.
+3. Pick a model class from the picker at the bottom of the composer.
+
+The published package is [`aegis-desktop`](https://www.npmjs.com/package/aegis-desktop)
+on npm; this repo is its source. No AEGIS account is needed for the **Ollama**
+class or a **local** custom endpoint — every other class bills your AEGIS
+account, either the pooled margin or the BYOK handling fee.
+
+## Using it
+
+Everything is in the window — there is no slash-command line to learn. Plain
+text in the composer is a prompt.
+
+| Where | What it does |
+|---|---|
+| **Composer** | Type and press `Enter`. `Shift+Enter` for a newline. |
+| **Class picker** | Bottom of the composer — switches the route mid-conversation, context intact. |
+| **Model dropdown** | Next to it — pins a model id for the selected class, or leaves it on "server default (auto)". |
+| **Settings** (sidebar) | API key, provider keys, tool-confirmation toggle. |
+| **Queue card** (sidebar) | The unattended work queue — same file the CLI drains. |
+| **Quick Launcher card** | Enable/rebind the global hotkey. |
+| **remember** (on any reply) | Pin that message to cross-machine cloud memory. |
+
+Approval cards appear inline before `exec`, `writeFile` or `editFile` runs:
+**Allow once**, **Allow for this session**, or **Deny**. Turn them off entirely
+with **Settings → "Confirm before running tools"** — on by default.
+
 ## Model classes
 
-Pick any of four transports from the model-class picker, switchable
+Pick any of five transports from the model-class picker, switchable
 mid-conversation with context intact:
 
-| Class | Transport | Key held in |
-|---|---|---|
-| **Aegis Cloud** | `aegiscloud.org` — one entry, **Nexus**; the pool auto-routes across whichever providers are live | main process |
-| **Ollama** | local `ollama` daemon | no key needed |
-| **Custom OpenAI-compatible** (LM Studio, OpenRouter, vLLM, …) | direct from the desktop app | main process — never sent to the renderer |
-| **Anthropic-compatible** (Claude, or any Messages-format gateway) | direct from the desktop app | main process |
-
-Get a free AEGIS key at **https://aegiscloud.org**, or use your own
-Ollama/OpenAI-compatible/Anthropic-compatible endpoint — no AEGIS account
-needed for those.
+| Class | Transport | Key held in | Billed? |
+|---|---|---|---|
+| **Aegis Cloud** | `aegiscloud.org` — one entry, **Nexus**; the pool auto-routes across whichever providers are live | main process | yes — pooled margin |
+| **Ollama** | local `ollama` daemon | no key needed | **no** — nothing leaves the machine |
+| **Custom OpenAI-compatible** (LM Studio, vLLM, llama.cpp, an Ollama shim) | direct from the desktop app, **local base URLs only** | main process — never sent to the renderer | **no** — free lane, local only |
+| **Anthropic-compatible** (a local Messages-format gateway — LiteLLM, claude-code-router) | direct from the desktop app, **local base URLs only** | main process | **no** — free lane, local only |
+| **Bring your own key** | your provider key, relayed by AEGIS — see below | main process | yes — flat AEGIS handling fee |
+
+Get a free AEGIS key at **https://aegiscloud.org**. The two custom classes are
+free because aegiscode talks straight to an endpoint on your own machine; point
+one at a hosted provider instead and there is nothing for AEGIS to meter, so
+those models live on the **Bring your own key** class, which does bill.
+
+### Bring your own key (BYOK)
+
+For the providers AEGIS does **not** run in its pool — bring your own key and
+the models that key unlocks appear as their own entries, one per provider.
+
+1. **Settings** → find the row named `BYOK: <Provider>` (OpenAI, Anthropic,
+   DeepSeek, Groq, xAI, Mistral, Gemini, OpenRouter, …).
+2. Paste your provider key and **Save**. There is no base-URL field on these
+   rows: a BYOK turn always talks to AEGIS's own relay
+   (`/api/v1/byok/chat/completions`), which is what attaches your AEGIS key.
+3. Select the **Bring your own key** class and pick a model.
+
+**What it costs.** AEGIS pays your provider nothing on this lane, so there is no
+provider cost to take a margin on — instead your AEGIS account is charged a flat
+**handling fee** per 1k tokens, for the routing, prompt assembly, caching, tool
+bridging and uptime that still happen server-side. The rate is the server's own
+(published on `GET /api/v1/byok/providers`) and is shown in Settings directly
+under the provider rows; it is never hardcoded here, so it cannot drift from the
+ledger that bills you. It is deliberately below the pooled price for the same
+traffic — BYOK stays the cheaper lane, it just is not the free one.
+
+**Two keys are needed.** Your provider key *and* an AEGIS account key: the
+handling fee has to be billed somewhere. With no AEGIS key connected the class
+shows every model but says exactly that, rather than failing opaquely.
+
+Note that a **BYOK turn is single-shot** — the relay takes no `tools` parameter,
+so the agentic tool loop below is off for these models. Use a pooled or direct
+class when you want file and shell access.
 
 ## Tools available to the model
 
@@ -180,7 +249,16 @@ The app registers an `aegis://` protocol handler:
 ## Run from source
 
 ```bash
-cd desktop
+git clone https://github.com/aegiscloud/aegiscode-desktop.git
+cd aegiscode-desktop
+npm install
+npm start
+```
+
+Or, from the monorepo checkout, run this directory directly:
+
+```bash
+cd aegiscode-plugin/desktop
 npm install
 npm start
 ```
@@ -217,6 +295,14 @@ bin/aegis.js         `aegis` CLI entry point for the global npm install
 This directory is part of the [aegiscode-plugin](../README.md) monorepo,
 which also ships a Claude Code plugin and the shared `client/aegis.js`
 transport over the same AEGIS backend — see the repo root for that fuller
-architecture picture. A read-only mirror of just this directory (for
-browsing or `git clone`) lives at
-[aegiscloud/aegiscode-desktop](https://github.com/aegiscloud/aegiscode-desktop).
+architecture picture, and [cli/README.md](../cli/README.md) for the terminal
+host over the same engine.
+
+**Two repos, one product.** This directory is the source of truth. The
+standalone repo at
+[aegiscloud/aegiscode-desktop](https://github.com/aegiscloud/aegiscode-desktop)
+is a `git subtree split` of it — same code, published separately so it can be
+cloned and built on its own. Edits land here and are synced out; nothing is
+authored there. The npm package
+[`aegis-desktop`](https://www.npmjs.com/package/aegis-desktop) is built from
+that standalone repo.

package/lib/local/endpoints.js

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * The direct-dial policy: which base URLs may reach a provider transport, and
+ * why that is the only free lane left.
+ *
+ * Both hosts that can talk to a user-supplied endpoint — the desktop app
+ * (settings pane → 'openai-compat' / 'anthropic' classes) and the CLI
+ * (src/engine.js prepareCustom, the `/model add` catalog) — share THIS file
+ * rather than a copy each. The CLI vendors `desktop/lib/local/` wholesale and
+ * resolves this module through src/sharedpaths.js, so the two hosts cannot
+ * drift apart about what "local" means or which error a remote URL gets. A
+ * second implementation is how one host would keep billing correctly while the
+ * other quietly served unpaid traffic.
+ *
+ * The rule: every lane that can bill does. `aegis` is the pooled route (the
+ * account key is attached and the pool takes its margin); `byok` is the relay
+ * (`services/pricing.price_byok_call` → `token_bank.charge_byok`, the AEGIS
+ * handling fee, charged against the account resolved from `X-AEGIS-Key`). The
+ * provider transports in providers.js bill NOTHING — they are a direct dial to
+ * whoever owns the URL — so the only usage they may carry is an endpoint on
+ * this machine, where there is no vendor to pay in the first place.
+ *
+ * That is why a remote base URL is refused rather than metered: the relay
+ * accepts a fixed catalog of provider ids (`services/nexus_provider/catalog.py`,
+ * upstream key read from `X-Provider-Key`), so an arbitrary remote URL has
+ * nothing to be billed against even if a client wanted to invoice it. Remote
+ * providers belong on BYOK, which bills. There is deliberately no flag or env
+ * var that re-opens the direct lane for a remote URL, because such a flag would
+ * be a billing bypass.
+ *
+ * Where the gate lives — the seams, not the transport:
+ *   · desktop/lib/settings.js   `set()` refuses to STORE a remote base URL, so
+ *                              the unusable configuration cannot be created.
+ *   · desktop/lib/local/engine.js  `chat()` refuses to DIAL one before any
+ *                              transport call (a row hand-edited into the
+ *                              settings file, or written before this policy
+ *                              existed, still cannot be used).
+ *   · cli/src/custommodels.js  refuses one at `/model add` and again at
+ *                              dispatch, for the same two reasons.
+ * providers.js itself stays policy-free: it is a wire-format function, and
+ * pinning the policy there would make it unreachable for the tests that check
+ * URL building. Same split the BYOK balance gate uses — the relay owns the
+ * decision, the client refuses to send.
+ */
+
+/** Host of a URL, lower-cased, or '' if it does not parse. */
+function hostOf(url) {
+  try {
+    return new URL(String(url)).host.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Whether a base URL addresses an endpoint on this machine — the gate that
+ * decides whether the free direct lane is available at all.
+ *
+ * True for: loopback (localhost, `*.localhost`, 127.0.0.0/8, `::1`), RFC1918
+ * private ranges (10/8, 172.16/12, 192.168/16), IPv6 unique-local fc00::/7,
+ * link-local (169.254/16, fe80::/10), the reserved local suffixes `.local`,
+ * `.internal`, `.lan`, and a bare dotless hostname (`ollama`, `gpu-box` — it
+ * can only resolve through this machine's own resolver).
+ *
+ * FAIL CLOSED: anything that does not parse, carries no host, is a public
+ * address or name, or is merely ambiguous is NOT local. That direction is the
+ * whole point — a false "local" is an unpaid turn, a false "remote" is a
+ * refusal the user can fix by pointing at a local address or by moving to the
+ * billed lane, which is the outcome we want in a tie.
+ */
+function isLocalEndpoint(url) {
+  let host = '';
+  let scheme = '';
+  try {
+    const parsed = new URL(String(url == null ? '' : url));
+    host = parsed.hostname.toLowerCase();
+    scheme = parsed.protocol.toLowerCase();
+  } catch {
+    return false;
+  }
+  // Only a base URL a transport can actually dial. The transports in
+  // providers.js append '/chat/completions' and fetch it, so anything that is
+  // not http(s) — or has no scheme at all — is not an endpoint, and is refused
+  // by the same fail-closed rule as an unparseable value. Checked before the
+  // host, so `ftp://box.local` cannot ride the local suffix to a pass.
+  if (scheme !== 'http:' && scheme !== 'https:') return false;
+  if (!host) return false;
+  // WHATWG keeps the brackets on an IPv6 hostname; strip them so one spelling
+  // covers both `[::1]` and a bare `::1`.
+  if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
+  if (!host || /[\s/\\@]/.test(host)) return false;
+
+  // Loopback by name, plus the reserved local suffixes. `.local`/`.internal`/
+  // `.lan` are the mDNS / split-DNS names an on-box service answers to. The
+  // suffix must END the name: `example.local.evil.com` is somebody else's host.
+  if (host === 'localhost' || host.endsWith('.localhost')) return true;
+  if (/\.(local|internal|lan)$/.test(host)) return true;
+
+  // IPv6 literals.
+  if (host.includes(':')) {
+    if (host === '::1' || host === '0:0:0:0:0:0:0:1') return true; // loopback
+    if (/^f[cd][0-9a-f]{2}:/.test(host)) return true; // fc00::/7 unique-local
+    if (/^fe[89ab][0-9a-f]:/.test(host)) return true; // fe80::/10 link-local
+    return false;
+  }
+
+  // IPv4 literals.
+  const quad = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (quad) {
+    const o = quad.slice(1).map(Number);
+    if (o.some((n) => n > 255)) return false; // not an address, and not local
+    const [a, b] = o;
+    if (a === 127) return true; // 127.0.0.0/8 loopback
+    if (a === 10) return true; // 10.0.0.0/8
+    if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
+    if (a === 192 && b === 168) return true; // 192.168.0.0/16
+    if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local
+    return false; // a real, routable address — remote, and billed
+  }
+
+  // A bare, dotless hostname is local by convention (`ollama`, `llama-box`):
+  // it can only resolve through this machine's own resolver or /etc/hosts.
+  // Anything with a dot is a DNS name for somebody else's machine.
+  return !host.includes('.');
+}
+
+/** What IS allowed here, in one sentence, shared by both hosts' refusals. */
+const ALLOWED_HINT =
+  'Allowed: localhost, 127.0.0.1, a private/LAN address (10.x, 172.16-31.x, 192.168.x), ' +
+  '*.local/.internal/.lan, or a dotless host like "ollama".';
+
+/**
+ * The refusal a non-local base URL gets, in the words the user needs in order
+ * to act: it names the offending URL, the kind of address that IS allowed, and
+ * the lane that replaces this one. `hint` is the host-specific half —
+ * `/class byok` in the terminal, the Bring-your-own-key Settings row in the
+ * GUI — while the policy half is shared, so the two hosts cannot describe the
+ * same rule differently.
+ */
+function remoteRefusal(baseURL, { subject = 'custom endpoints', hint = '' } = {}) {
+  const where = String(baseURL == null ? '' : baseURL);
+  const tail = hint || 'Remote providers are billed, so use the lane that bills them, or point this at a local address.';
+  return `${subject} must be LOCAL — remote base URL ${JSON.stringify(where)} is not offered on this lane. ` +
+    `${ALLOWED_HINT} ${tail}`;
+}
+
+/**
+ * Throw the refusal (as a 400-class error every caller already paints) unless
+ * the base URL is local. The one-line form of the gate for the dispatch and
+ * storage seams, so neither has to remember the status code.
+ *
+ * An EMPTY base URL is refused here like any other non-local value, because
+ * there is no endpoint to dial. The storage seam does not use this function
+ * directly for that reason — see allowsDirectDialRow below, which treats "no
+ * URL configured" as "nothing to gate".
+ */
+function ensureLocalEndpoint(baseURL, opts) {
+  if (isLocalEndpoint(baseURL)) return true;
+  const err = new Error(remoteRefusal(baseURL, opts));
+  err.status = 400;
+  err.code = 'CUSTOM_ENDPOINT_NOT_LOCAL';
+  throw err;
+}
+
+/**
+ * The settings-store rows whose base URL is dialled DIRECTLY by the transports
+ * in providers.js — i.e. the rows the gate above exists for.
+ *
+ *   'openai-compat', 'anthropic'  the desktop's two custom endpoints (its
+ *                                 Settings pane names them exactly so, and
+ *                                 engine.js's CUSTOM_CLASSES reads the row
+ *                                 under the class name).
+ *   'custom:*'                    the CLI's per-model namespace (src/
+ *                                 custommodels.js). The CLI keeps the base URL
+ *                                 in config.json `customModels` and stores only
+ *                                 the KEY here, so this prefix is a second lock
+ *                                 on a door that is already shut — deliberate:
+ *                                 a future writer that puts a URL in this row
+ *                                 must not silently reopen the lane.
+ *
+ * It matters that this is a NAMED list and not "every row". The same store
+ * holds the billed lanes' rows, and those legitimately carry remote values or
+ * nothing at all:
+ *   · `byok:<provider>` — always remote by definition (the provider's own API,
+ *     reached through AEGIS's relay, which is what bills it). The desktop's
+ *     Settings pane saves those rows with baseURL '' (the relay owns the URL),
+ *     and a blanket "must be local" rule would refuse even the empty string,
+ *     breaking BYOK configuration entirely.
+ *   · `aegis` — reserved namespace, never touched through this surface.
+ * So a gate keyed on the value alone is wrong; it is keyed on the ROW.
+ */
+const DIRECT_DIAL_ROWS = Object.freeze(['openai-compat', 'anthropic']);
+const DIRECT_DIAL_PREFIXES = Object.freeze(['custom:']);
+
+/** Whether a settings-store row's base URL is dialled directly (and so gated). */
+function isDirectDialRow(provider) {
+  const p = String(provider == null ? '' : provider);
+  if (DIRECT_DIAL_ROWS.includes(p)) return true;
+  return DIRECT_DIAL_PREFIXES.some((pre) => p.startsWith(pre));
+}
+
+/**
+ * Whether a row may STORE this base URL — the storage seam's question, which is
+ * not quite the dispatch seam's.
+ *
+ * A direct-dial row with no URL is fine to store: that is how a row is cleared,
+ * and how it looks before it is configured (`customStatus` reports it as
+ * unconfigured, so nothing dials it). What must never be stored is a NON-EMPTY
+ * remote URL, which would make the row look configured and usable.
+ */
+function allowsDirectDialRow(provider, baseURL) {
+  if (!isDirectDialRow(provider)) return true;
+  const url = String(baseURL == null ? '' : baseURL).trim();
+  if (!url) return true; // clearing the row, or a not-yet-configured one
+  return isLocalEndpoint(url);
+}
+
+module.exports = {
+  hostOf,
+  isLocalEndpoint,
+  remoteRefusal,
+  ensureLocalEndpoint,
+  isDirectDialRow,
+  allowsDirectDialRow,
+  ALLOWED_HINT,
+  DIRECT_DIAL_ROWS,
+};

package/lib/local/engine.js

@@ -45,6 +45,10 @@ const os = require('node:os');
 
 const toolsModule = require('./tools.js');
 const promptModule = require('./prompt.js');
+// The direct-dial policy: which base URLs may reach a provider transport, and
+// why a remote one is refused rather than metered. The same module the CLI
+// resolves (cli/src/custommodels.js), so both hosts answer with one rule.
+const { isLocalEndpoint, remoteRefusal } = require('./endpoints.js');
 const { ShellSession } = require('./shell.js');
 const { agentSystemPrompt, agentRoleLabel } = require('./agents.js');
 // Cooperative working-tree sharing (see each module's header). The lock
@@ -657,14 +661,26 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
    * 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).
+   *
+   * A stored REMOTE base URL is reported as not-configured rather than ready,
+   * plus `blocked` and the reason. This is the third face of the direct-dial
+   * gate (storage in settings.js set, dispatch in chat below): a row that
+   * predates the rule must not be OFFERED either, or the class list advertises
+   * a lane the turn then refuses. The reason travels so the UI can explain it
+   * instead of showing a dead row — and it is recoverable by design: saving a
+   * local URL (or clearing the field) makes the class usable again, which is
+   * what the refusal text tells the user to do.
    */
   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);
+    const blocked = hasBase && !isLocalEndpoint(baseURL);
     return {
-      configured: cls === 'anthropic' ? hasBase && hasKey : hasBase,
+      configured: !blocked && (cls === 'anthropic' ? hasBase && hasKey : hasBase),
+      blocked,
+      ...(blocked ? { blockedReason: remoteRefusal(baseURL, { subject: `the ${cls} endpoint` }) } : {}),
       baseURL,
       keyMask: cfg.keyMask || null,
     };
@@ -714,14 +730,27 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     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 = [];
       }
@@ -744,6 +773,8 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       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
@@ -755,7 +786,18 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     // 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 };
+    // Same reporting as customStatus: a stored remote URL is not a usable
+    // model list, and the reason has to reach the UI with it (see customStatus).
+    const blocked = Boolean(baseURL) && !isLocalEndpoint(baseURL);
+    return {
+      class: cls,
+      models: [],
+      needsModelId: true,
+      baseURL,
+      ...(blocked
+        ? { blocked: true, blockedReason: remoteRefusal(baseURL, { subject: `the ${cls} endpoint` }) }
+        : {}),
+    };
   }
 
   /**
@@ -941,18 +983,42 @@ 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 = {
@@ -1093,6 +1159,60 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         err.status = 400;
         throw err;
       }
+      // …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(
+          'byok: connect your AEGIS account key first — the BYOK handling fee is billed there. ' +
+            'Add it in the Status card (or run /login), then try again.'
+        );
+        err.status = 401;
+        throw err;
+      }
+
+      // THE DIRECT-DIAL GATE. A custom class talks to the user's base URL
+      // itself (providers.js openaiCompatible / anthropicMessages), and that
+      // transport bills NOBODY: no pooled margin, no BYOK handling fee, no
+      // account key attached. The only usage it may therefore carry is an
+      // endpoint on this machine, where there is no vendor to pay. A remote URL
+      // here is an unpaid turn, and it is refused rather than metered because
+      // there is nothing to meter it against — the relay accepts a fixed
+      // catalog of provider ids (services/nexus_provider/catalog.py), so an
+      // arbitrary remote URL cannot be billed there either.
+      //
+      // Checked at DISPATCH and not only at storage (settings.js set refuses
+      // the same URL): a row written before this rule existed, or hand-edited
+      // into settings.json, is still in the file, and reading it back happily
+      // would keep the lane open. Both seams, one rule — the message is
+      // endpoints.js's, so the desktop and the CLI say the same thing.
+      if (CUSTOM_CLASSES.includes(cls)) {
+        const raw = cfg && typeof cfg.baseURL === 'string' ? cfg.baseURL.trim() : '';
+        if (raw && !isLocalEndpoint(raw)) {
+          const err = new Error(
+            remoteRefusal(raw, {
+              subject: `the ${cls} endpoint`,
+              hint:
+                'This class dials your URL directly and bills nobody, so it is local-only. ' +
+                'Use a model on this machine, or move the provider to the BYOK card (/class byok), ' +
+                'which relays through AEGIS and charges the handling fee.',
+            })
+          );
+          err.status = 400;
+          err.code = 'CUSTOM_ENDPOINT_NOT_LOCAL';
+          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

package/lib/settings.js

@@ -17,6 +17,12 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+// The direct-dial policy (see that file): which rows may hold a remote base URL.
+// Enforced HERE, at the storage seam, so the unusable configuration cannot be
+// created by either host — the desktop's Settings pane or the CLI's `/model add`
+// — rather than only being refused at send time. Pure node builtins, so this
+// store stays loadable without Electron.
+const { isLocalEndpoint, remoteRefusal, isDirectDialRow } = require('./local/endpoints.js');
 
 const SETTINGS_FILE = 'settings.json';
 
@@ -124,8 +130,13 @@ function createSettingsStore({ dir, safeStorage } = {}) {
   function save(data) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const tmp = `${file}.tmp-${process.pid}`;
-    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    // 0600, written before the rename so the file is never briefly readable:
+    // this store holds provider keys, and both hosts are now able to write it
+    // (the CLI uses the same file, without Electron's safeStorage, so at-rest
+    // base64 is all the protection there is — file mode is the real control).
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
     fs.renameSync(tmp, file);
+    try { fs.chmodSync(file, 0o600); } catch {}
   }
 
   /** Provider CRUD must never touch a reserved (AEGIS-key) namespace. */
@@ -149,8 +160,38 @@ function createSettingsStore({ dir, safeStorage } = {}) {
     };
   }
 
+  /**
+   * Write a provider row.
+   *
+   * A direct-dial row ('openai-compat', 'anthropic', 'custom:*') may not hold a
+   * remote base URL: those classes talk to the URL themselves (providers.js),
+   * which bills nobody, so the only usage they may carry is an endpoint on this
+   * machine. Refusing at STORAGE — the earliest seam, shared by the desktop's
+   * Settings pane and the CLI — means a remote custom endpoint cannot be
+   * configured into existence in the first place; the engine's dispatch gate
+   * then covers the rows that predate this rule or were hand-edited into the
+   * file. Empty is allowed (that is how the row is cleared, and how a
+   * not-yet-configured row looks), and every other namespace is untouched:
+   * `byok:<provider>` rows are remote by definition and reach their provider
+   * through AEGIS's relay, which is what bills them.
+   */
   function set(provider, { baseURL, key } = {}) {
     assertNotReserved(provider);
+    if (baseURL !== undefined && isDirectDialRow(provider)) {
+      const next = String(baseURL == null ? '' : baseURL).trim();
+      if (next && !isLocalEndpoint(next)) {
+        const err = new Error(remoteRefusal(next, {
+          subject: `the ${provider} endpoint`,
+          hint:
+            'This lane is for a model running on this machine. To use a remote provider, ' +
+            'save it under Bring-your-own-key (the CLI\'s /class byok), where the AEGIS handling ' +
+            'fee bills the turn.',
+        }));
+        err.status = 400;
+        err.code = 'CUSTOM_ENDPOINT_NOT_LOCAL';
+        throw err;
+      }
+    }
     const data = load();
     const cfg = data[provider] || {};
     if (baseURL !== undefined) cfg.baseURL = baseURL;