@orbit-intelligence/orbit-agent 0.3.14 → 0.3.15

package/dist/src/cli/run.js

@@ -5,7 +5,7 @@ import { VERSION } from '../version.js';
 import { touchConfig, saveConfig } from '../config/index.js';
 import { EventBus } from '../core/events.js';
 import { buildProviders, resolveCandidates } from '../core/llm/index.js';
-import { resolvePickerRows } from '../tui/picker.js';
+import { resolveModelRows, resolveProviderRows } from '../tui/picker.js';
 import { AutoRouter } from '../core/llm/router.js';
 import { ContextManager } from '../core/context/context-manager.js';
 import { ToolRegistry } from '../core/tools/registry.js';
@@ -248,7 +248,7 @@ export async function main(argv) {
         onCommand,
         version: VERSION,
         models: router.order(),
-        pickRows: () => resolvePickerRows(),
+        pickRows: (stage, providerId, liveModels) => stage === 'providers' ? Promise.resolve(resolveProviderRows()) : resolveModelRows(providerId ?? '', liveModels),
     });
     app.store.skills = project.skills.map((s) => ({ name: s.name, summary: s.summary }));
     const resumeMessages = session.messages.filter((m) => m.role !== 'tool');

package/dist/src/core/agent/agent-loop.js

@@ -1,3 +1,4 @@
+import { sanitizeToken, sanitizeContent } from '../llm/sanitize.js';
 import { combineSignals } from '../../utils/signals.js';
 import { unifiedDiff, countChanges } from '../../utils/diff.js';
 import { readFile, stat } from 'node:fs/promises';
@@ -87,13 +88,15 @@ export class AgentLoop {
                     try {
                         for await (const ev of gen) {
                             if (ev.type === 'token') {
-                                asstMsg.content += ev.text;
-                                bus.emit('onToken', ev.text);
+                                const clean = sanitizeToken(ev.text);
+                                asstMsg.content += clean;
+                                bus.emit('onToken', clean);
                                 await throttle(this.opts.maxTokensPerSecond);
                             }
                             else if (ev.type === 'reasoning') {
-                                asstMsg.reasoning = (asstMsg.reasoning ?? '') + ev.text;
-                                bus.emit('onThinking', ev.text);
+                                const clean = sanitizeToken(ev.text);
+                                asstMsg.reasoning = (asstMsg.reasoning ?? '') + clean;
+                                bus.emit('onThinking', clean);
                             }
                             else if (ev.type === 'tool_call_start') {
                                 const call = {
@@ -153,6 +156,8 @@ export class AgentLoop {
             // TUI reveal the whole message (snap the typewriter to the end) so the
             // text sits above the tool rows BEFORE the tools start running — the
             // user should see "intent first, then action".
+            asstMsg.content = sanitizeContent(asstMsg.content);
+            asstMsg.reasoning = sanitizeContent(asstMsg.reasoning ?? '');
             bus.emit('onAssistantGenerationDone', asstMsg);
             asstMsg.streaming = false;
             asstMsg.reasoningOpen = (asstMsg.reasoning?.length ?? 0) > 0;

package/dist/src/core/llm/endpoints.js

@@ -0,0 +1,110 @@
+/**
+ * Custom OpenAI-compatible endpoint registry.
+ *
+ * Lets users add named endpoints (LM Studio, vLLM, a personal gateway, …)
+ * with a base URL and an OPTIONAL key. Persisted to the git-ignored
+ * `endpoints.json` (0600) next to keys.json. Base URLs are not secrets, but
+ * endpoint keys are — keeping both in one 0600 file matches the keys.json
+ * security posture (never config.json).
+ */
+import { readFileSync, existsSync, chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { endpointsPath, configDir } from '../../utils/platform.js';
+const CACHE_MS = 2000;
+let cache = null;
+function readFile() {
+    const now = Date.now();
+    if (cache && now - cache.at < CACHE_MS)
+        return cache.data;
+    const path = endpointsPath();
+    if (!existsSync(path)) {
+        cache = { data: [], at: now };
+        return [];
+    }
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        if (!Array.isArray(raw))
+            throw new Error('not an array');
+        const cleaned = raw.filter((e) => e && typeof e.name === 'string' && typeof e.baseUrl === 'string');
+        cache = { data: cleaned, at: now };
+        return cleaned;
+    }
+    catch {
+        cache = { data: [], at: now };
+        return [];
+    }
+}
+function write(list) {
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(endpointsPath(), JSON.stringify(list, null, 2), 'utf8');
+    try {
+        chmodSync(endpointsPath(), 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+    cache = { data: list, at: Date.now() };
+}
+export function loadEndpoints() {
+    return readFile();
+}
+export function findEndpoint(name) {
+    return readFile().find((e) => e.name === name) ?? null;
+}
+/** Upsert by name (case-sensitive). Returns an error string, or null on success. */
+export function saveEndpoint(ep) {
+    const trimmed = { ...ep, name: ep.name.trim(), baseUrl: ep.baseUrl.trim() };
+    if (!/^[a-z0-9][a-z0-9._-]{0,39}$/.test(trimmed.name)) {
+        return 'name must be 1-40 chars: lowercase letters, digits, . _ -';
+    }
+    if (!/^https?:\/\/\S+$/.test(trimmed.baseUrl)) {
+        return 'base URL must start with http:// or https://';
+    }
+    if (!trimmed.baseUrl.endsWith('/v1') && !/\/(v1|v1beta1)\/?$/.test(trimmed.baseUrl)) {
+        trimmed.baseUrl = `${trimmed.baseUrl.replace(/\/+$/, '')}/v1`;
+    }
+    const list = readFile();
+    const idx = list.findIndex((e) => e.name === trimmed.name);
+    if (idx >= 0)
+        list[idx] = trimmed;
+    else
+        list.push(trimmed);
+    write(list);
+    return null;
+}
+export function deleteEndpoint(name) {
+    write(readFile().filter((e) => e.name !== name));
+}
+/** Remember a model id the user actually picked for this endpoint. */
+export function rememberEndpointModel(name, model) {
+    const list = readFile();
+    const ep = list.find((e) => e.name === name);
+    if (!ep)
+        return;
+    const models = ep.models ?? [];
+    if (!models.includes(model)) {
+        ep.models = [...models, model].slice(-20);
+        write(list);
+    }
+}
+/** Probe the endpoint's live /v1/models list (fast-fail, short timeout). */
+export async function listEndpointModels(name) {
+    const ep = findEndpoint(name);
+    if (!ep)
+        return [];
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(new Error('endpoint probe timed out')), 3000);
+        const headers = { accept: 'application/json' };
+        if (ep.key)
+            headers.authorization = `Bearer ${ep.key}`;
+        const res = await fetch(`${ep.baseUrl.replace(/\/+$/, '')}/models`, { signal: ctrl.signal, headers });
+        clearTimeout(timer);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const json = (await res.json());
+        return (json.data ?? []).map((m) => m.id).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/core/llm/index.js

@@ -3,6 +3,7 @@ import { createOpenAiProvider } from './providers/openai-compat.js';
 import { createGeminiProvider } from './providers/gemini.js';
 import { createAnthropicProvider } from './providers/anthropic.js';
 import { createOllamaProvider } from './providers/ollama.js';
+import { loadEndpoints } from './endpoints.js';
 import { PROVIDER_CATALOGS, ORBITX_SERVE, modelsOf } from './models.js';
 export { PROVIDER_CATALOGS as PROVIDER_SPECS, ORBITX_SERVE, modelsOf };
 const ENDPOINTS = {
@@ -65,6 +66,21 @@ export function buildProviders(config) {
     }
     // Local Ollama is always offered: no key required, auto-detects the server.
     providers.ollama = createOllamaProvider();
+    // Named custom OpenAI-compatible endpoints (endpoints.json). Each is exposed
+    // as a provider keyed by its name so `<name>/<model>` routes to it.
+    for (const ep of loadEndpoints()) {
+        if (!ep || !ep.name || !ep.baseUrl)
+            continue;
+        const existing = providers[ep.name];
+        if (existing)
+            continue; // never shadow a real provider with a same-named endpoint
+        providers[ep.name] = createOpenAiProvider({
+            id: ep.name,
+            baseUrl: ep.baseUrl,
+            apiKey: ep.key ?? '',
+            models: (ep.models ?? []).filter(Boolean),
+        });
+    }
     return providers;
 }
 /** Candidate model ids (provider-prefixed) for the router. */

package/dist/src/core/llm/sanitize.js

@@ -0,0 +1,47 @@
+/**
+ * Streamed-content sanitizer.
+ *
+ * Some gateway models (gpt-oss family, Qwen cloud variants) leak control
+ * tokens into the visible content stream: `<|start|>functions.list_dir
+ * to=assistant<|message|>{...}` pensieve blocks, dangling `<|...|>` tags,
+ * and boundary boilerplate such as a lone `response` line or "Proceed to
+ * final answer." Strip those before the TUI renders or history commits them
+ * so the user sees the prose, not the plumbing.
+ */
+/** Control-rune tag, e.g. `<|start|>`, `<|message|>`, `<|end|>`. */
+const TAG_RE = /<\|[^|>]*\|>/g;
+/**
+ * Qwen/OSS pensieve header: `<|start|>functions.<name> to=assistant
+ * <|message|>` followed by a mangled JSON echo that model emits verbatim.
+ * Removes the header plus the leading portion of the echoed line up to the
+ * first blank line, which is where the real prose begins in practice.
+ */
+const PENSIVE_RE = /<\|start\|>\n?[\s\S]*?<\|message\|>[ \t]*[^\r\n]*\n/g;
+/** Lone boundary markers some cloud models insert before their answer. */
+const BOUNDARY_LINE_RE = /^[ \t]*(?:response|Proceed to final answer\.?)[ \t]*$/gm;
+/** Collapse 3+ consecutive blank lines down to two (post-strip tidy-up). */
+const BLANK_RUN_RE = /\n{3,}/g;
+/**
+ * Sanitize a single streamed token. idempotent; cheap enough to run per
+ * token. A `<|` opened mid-chunk but closed later is finished by
+ * `sanitizeContent` over the assembled text, so partial matches here are
+ * fine.
+ */
+export function sanitizeToken(text) {
+    let s = text.replace(PENSIVE_RE, '').replace(TAG_RE, '');
+    if (s.includes('response') || s.includes('Proceed to final answer')) {
+        s = s.replace(BOUNDARY_LINE_RE, '');
+    }
+    return s;
+}
+/** Sanitize a fully-assembled message/reasoning blob. */
+export function sanitizeContent(text) {
+    let s = text
+        .replace(PENSIVE_RE, '')
+        .replace(TAG_RE, '')
+        .replace(BOUNDARY_LINE_RE, '')
+        .replace(BLANK_RUN_RE, '\n\n')
+        .replace(/^\n+/, '')
+        .replace(/\n+$/, '');
+    return s;
+}

package/dist/src/core/llm/secrets.js

@@ -83,8 +83,9 @@ export function getProviderSecrets(provider) {
         return { provider, keys: envKeys, source: 'env' };
     const file = readKeysFile();
     const fileKeys = file[provider] ?? [];
-    if (fileKeys.length > 0)
-        return { provider, keys: fileKeys, source: 'file' };
+    const flat = fileKeys.map((k) => (typeof k === 'string' ? k : k.key)).filter(Boolean);
+    if (flat.length > 0)
+        return { provider, keys: flat, source: 'file' };
     return null;
 }
 export function hasAnySecrets() {
@@ -108,12 +109,30 @@ export function describeProvidersAvailable() {
     }
     return out;
 }
+export function describeProviderKey(provider) {
+    const s = getProviderSecrets(provider);
+    if (!s || !s.keys[0])
+        return { provider, available: false };
+    const named = readKeysFile()[provider]?.find((k) => typeof k === 'object');
+    return {
+        provider,
+        available: true,
+        masked: maskSecret(s.keys[0]),
+        source: s.source,
+        label: named?.name,
+    };
+}
 /**
  * Persist provider keys to the git-ignored keys.json (0600), merging over any
  * existing keys so a re-run of the wizard never wipes other providers.
  */
 export function writeKeys(provider, keys) {
-    const trimmed = keys.map((k) => k.trim()).filter(Boolean);
+    const trimmed = keys
+        .map((k) => {
+        const key = typeof k === 'string' ? k.trim() : { name: k.name.trim() || 'default', key: k.key.trim() };
+        return typeof key === 'string' ? key : { name: key.name, key: key.key };
+    })
+        .filter((k) => (typeof k === 'string' ? k : k.key) !== '');
     if (trimmed.length === 0)
         return 'no keys provided';
     const existing = readKeysFile();
@@ -129,3 +148,42 @@ export function writeKeys(provider, keys) {
         return err.message;
     }
 }
+/** Save (or update by label) a single named key for a provider. */
+export function saveNamedKey(provider, name, key) {
+    const clean = key.trim();
+    if (!clean)
+        return 'no key provided';
+    const label = name.trim() || 'default';
+    const existing = readKeysFile();
+    const list = existing[provider] ?? [];
+    const idx = list.findIndex((k) => typeof k === 'object' && k.name === label);
+    if (idx >= 0)
+        list[idx] = { name: label, key: clean };
+    else
+        list.push({ name: label, key: clean });
+    existing[provider] = list;
+    try {
+        mkdirSync(configDir(), { recursive: true });
+        writeFileSync(keysPath(), JSON.stringify(existing, null, 2), 'utf8');
+        chmodSync(keysPath(), 0o600);
+        invalidateKeysCache();
+        return null;
+    }
+    catch (err) {
+        return err.message;
+    }
+}
+/** Human "masked · source [label]" description for a provider's configured key. */
+export function describeKey(provider) {
+    const envKeys = fromEnv(provider);
+    if (envKeys.length > 0 && envKeys[0])
+        return { masked: maskSecret(envKeys[0]), source: 'env' };
+    const file = readKeysFile();
+    const entries = file[provider] ?? [];
+    const first = entries[0];
+    if (!first)
+        return null;
+    if (typeof first === 'string')
+        return { masked: maskSecret(first), source: 'file' };
+    return { masked: maskSecret(first.key), source: 'file', label: first.name };
+}

package/dist/src/tui/InkApp.js

@@ -33,7 +33,11 @@ export function InkApp({ controller }) {
     const theme = store.theme ?? buildTheme('tokyonight');
     const menuing = store.input.currentBuffer().startsWith('/');
     const menuLines = menuing ? store.slashMatches().length + 1 : 0;
-    const modelLines = store.modelPicker.open ? Math.min(store.pickRows.length, 12) + 3 : 0;
+    const modelLines = store.modelPicker.open
+        ? store.keyEntry
+            ? 8
+            : Math.min(store.pickRows.length, 12) + 3
+        : 0;
     const dockLines = store.dockOpen
         ? store.agents.size === 0
             ? 2

package/dist/src/tui/app.js

@@ -4,7 +4,10 @@ import { providerNames } from '../config/config-schema.js';
 import { makeTheme, THEME_NAMES } from './themes/index.js';
 import { AppStore, ASK_OPTIONS } from './store.js';
 import { InkApp } from './InkApp.js';
-import { findPickerIndex, isPickerHeader } from './picker.js';
+import { findPickerIndex, isPickerHeader, resolveModelRows, resolveProviderRows, } from './picker.js';
+import { saveNamedKey } from '../core/llm/secrets.js';
+import { saveEndpoint, rememberEndpointModel } from '../core/llm/endpoints.js';
+import { isImportableDirectly } from '../core/llm/secrets.js';
 export class TuiApp {
     store = new AppStore();
     theme;
@@ -87,28 +90,48 @@ export class TuiApp {
         this.models = [...list];
         this.store.models = [...list];
     }
-    /** Rebuild the grouped picker rows (e.g. after a provider/model switch). */
+    /**
+     * Rebuild the current picker stage's rows (providers, or models for the
+     * selected provider). The orbitx model list uses the LIVE routed models so
+     * offered == routable — this is the fix for "No model matches".
+     */
     async refreshModelPicker() {
-        if (!this.pickBuilder)
-            return;
+        const store = this.store;
+        const stage = store.pickStage;
+        const provider = store.pickProviderProviderId;
         try {
-            const rows = await this.pickBuilder();
-            this.store.pickRows = rows;
+            const rows = await (this.pickBuilder
+                ? this.pickBuilder(stage, provider, this.models)
+                : this.defaultRows(stage, provider));
+            store.pickRows = rows;
             if (rows.length === 0)
-                this.store.modelPicker.index = 0;
-            else if (this.store.modelPicker.index >= rows.length)
-                this.store.modelPicker.index = rows.length - 1;
+                store.modelPicker.index = 0;
+            else if (store.modelPicker.index >= rows.length)
+                store.modelPicker.index = rows.length - 1;
+            if (stage === 'providers') {
+                const cur = store.route?.provider;
+                const firstItem = rows.findIndex((r) => r.kind === 'item' && r.providerId === cur);
+                store.modelPicker.index = firstItem >= 0 ? firstItem : rows.findIndex((r) => r.kind === 'item');
+            }
         }
         catch {
-            this.store.pickRows = [];
+            store.pickRows = [];
         }
     }
-    /** Open the /model overlay, refreshing rows first so the list is current. */
+    defaultRows(stage, provider) {
+        if (stage === 'providers')
+            return Promise.resolve(resolveProviderRows());
+        return resolveModelRows(provider ?? '', this.models);
+    }
+    /** Open the /model overlay, starting at the provider (stage 1) list. */
     async openModelPicker() {
-        await this.refreshModelPicker();
         const store = this.store;
-        if (store.pickRows.length === 0 && store.models.length > 0) {
-            // Fallback when no builder: derive item rows from the routed models.
+        store.pickStage = 'providers';
+        store.pickProviderProviderId = null;
+        store.keyEntry = null;
+        await this.refreshModelPicker();
+        const rows = store.pickRows;
+        if (rows.length === 0) {
             const seen = new Set();
             for (const m of store.models) {
                 const provider = m.split('/')[0] ?? 'orbitx';
@@ -118,7 +141,6 @@ export class TuiApp {
                 store.pickRows.push({ kind: 'item', label: m, id: m, provider });
             }
         }
-        store.modelPicker.index = findPickerIndex(store.pickRows, store.route?.model, this.config.model.primary);
         store.modelPicker.open = true;
         store.refresh();
     }
@@ -519,6 +541,11 @@ export class TuiApp {
     }
     handleModelPickerKey(input, key) {
         const store = this.store;
+        // Inline key/custom-endpoint entry box: capture text, Enter advances.
+        if (store.keyEntry) {
+            this.handleKeyEntryKey(input, key);
+            return;
+        }
         const rows = store.pickRows;
         if (rows.length === 0) {
             store.modelPicker.open = false;
@@ -526,6 +553,13 @@ export class TuiApp {
             return;
         }
         if (key.escape) {
+            if (store.pickStage === 'models') {
+                // Back to provider list (stage 1), re-enter the source-of-truth rows.
+                store.pickStage = 'providers';
+                store.pickProviderProviderId = null;
+                void this.refreshModelPicker().then(() => store.refresh());
+                return;
+            }
             store.modelPicker.open = false;
             store.refresh();
             return;
@@ -547,6 +581,10 @@ export class TuiApp {
                 store.refresh();
                 return;
             }
+            if (store.pickStage === 'providers') {
+                void this.enterProviderScope(row);
+                return;
+            }
             store.modelPicker.open = false;
             store.refresh();
             void this.selectPickerModel(row);
@@ -555,6 +593,215 @@ export class TuiApp {
         if (input && !key.ctrl && !key.meta)
             store.refresh();
     }
+    /**
+     * Stage 1 Enter: open the chosen provider's key-entry (if missing a required
+     * key) or advance to its model list (stage 2).
+     */
+    async enterProviderScope(row) {
+        const store = this.store;
+        const providerRow = row;
+        const providerId = providerRow.providerId;
+        // Add-a-custom-endpoint flow.
+        if (providerId === '__add_custom__') {
+            store.keyEntry = { kind: 'endpoint-name', provider: '', value: '', cursorPos: 0, hint: 'name for this endpoint (e.g. lmstudio)' };
+            store.refresh();
+            return;
+        }
+        // Named key flows: provider needs a key and none is configured.
+        if (providerRow.needsKey) {
+            const p = providerId;
+            if (!isImportableDirectly(p)) {
+                this.note(`Provider "${providerId}" needs a key. Run \`orbit setup\` or set the env var.`);
+                return;
+            }
+            store.keyEntry = { kind: 'key-label', provider: p, value: '', cursorPos: 0, hint: `label for this ${p} key (e.g. "work")` };
+            store.refresh();
+            return;
+        }
+        await this.enterModelStage(providerId);
+    }
+    /** Advance to stage 2 (model list) for a provider, rebuilding rows live. */
+    async enterModelStage(providerId) {
+        const store = this.store;
+        store.pickStage = 'models';
+        store.pickProviderProviderId = providerId;
+        const rows = await (this.pickBuilder
+            ? this.pickBuilder('models', providerId, this.models)
+            : resolveModelRows(providerId, this.models));
+        // Custom endpoint with no discoverable models: let the user type the id.
+        if (providerId.startsWith('custom:') &&
+            rows.length === 1 &&
+            rows[0]?.kind === 'header' &&
+            /no models found/.test(rows[0].label)) {
+            const name = providerId.slice('custom:'.length);
+            store.keyEntry = {
+                kind: 'endpoint-fallback-model',
+                provider: name,
+                value: '',
+                cursorPos: 0,
+                hint: `model id served by ${name} (no live /v1/models response)`,
+            };
+            store.pickRows = rows;
+            store.refresh();
+            return;
+        }
+        store.pickRows = rows;
+        store.modelPicker.index = findPickerIndex(rows, store.route?.model, this.config.model.primary);
+        store.refresh();
+    }
+    /** Inline text boxes (key label/value, endpoint name/url/key, fallback model). */
+    handleKeyEntryKey(input, key) {
+        const store = this.store;
+        const e = store.keyEntry;
+        if (!e)
+            return;
+        const max = e.kind === 'key-value' ? 256 : 128;
+        if (key.escape) {
+            store.keyEntry = null;
+            store.refresh();
+            return;
+        }
+        if (key.return) {
+            void this.commitKeyEntry(e);
+            return;
+        }
+        if (key.backspace && e.value.length > 0) {
+            const pos = Math.max(0, e.cursorPos - 1);
+            e.value = e.value.slice(0, pos) + e.value.slice(e.cursorPos);
+            e.cursorPos = pos;
+            store.refresh();
+            return;
+        }
+        if (key.delete && e.cursorPos < e.value.length) {
+            e.value = e.value.slice(0, e.cursorPos) + e.value.slice(e.cursorPos + 1);
+            store.refresh();
+            return;
+        }
+        if (key.leftArrow) {
+            e.cursorPos = Math.max(0, e.cursorPos - 1);
+            store.refresh();
+            return;
+        }
+        if (key.rightArrow) {
+            e.cursorPos = Math.min(e.value.length, e.cursorPos + 1);
+            store.refresh();
+            return;
+        }
+        if (key.home) {
+            e.cursorPos = 0;
+            store.refresh();
+            return;
+        }
+        if (key.end) {
+            e.cursorPos = e.value.length;
+            store.refresh();
+            return;
+        }
+        if (key.ctrl && input === 'u') {
+            e.value = '';
+            e.cursorPos = 0;
+            store.refresh();
+            return;
+        }
+        if (input && !key.ctrl && !key.meta) {
+            if (e.value.length >= max) {
+                store.refresh();
+                return;
+            }
+            e.value = e.value.slice(0, e.cursorPos) + input + e.value.slice(e.cursorPos);
+            e.cursorPos += input.length;
+            store.refresh();
+        }
+    }
+    async commitKeyEntry(e) {
+        const store = this.store;
+        const val = e.value.trim();
+        switch (e.kind) {
+            case 'key-label':
+                if (!val) {
+                    store.keyEntry = null;
+                    store.refresh();
+                    return;
+                }
+                store.keyEntry = {
+                    kind: 'key-value',
+                    provider: e.provider,
+                    value: '',
+                    cursorPos: 0,
+                    hint: `paste the ${e.provider} API key (${val})`,
+                    keyLabel: val,
+                };
+                store.refresh();
+                return;
+            case 'key-value': {
+                const p = e.provider;
+                const err = await saveNamedKey(p, e.keyLabel ?? '', val);
+                if (err) {
+                    this.note(`Could not save key: ${err}`);
+                    store.keyEntry = null;
+                    store.refresh();
+                    return;
+                }
+                store.keyEntry = null;
+                await this.enterModelStage(p);
+                return;
+            }
+            case 'endpoint-name':
+                if (!val) {
+                    store.keyEntry = null;
+                    store.refresh();
+                    return;
+                }
+                store.keyEntry = { kind: 'endpoint-url', provider: val, value: '', cursorPos: 0, hint: 'OpenAI-compatible base URL, e.g. http://127.0.0.1:1234/v1' };
+                store.refresh();
+                return;
+            case 'endpoint-url':
+                if (!val.startsWith('http')) {
+                    this.note('Endpoint base URL must start with http:// or https://');
+                    store.refresh();
+                    return;
+                }
+                store.keyEntry = { kind: 'endpoint-key', provider: e.provider, value: '', cursorPos: 0, hint: 'optional API key (Enter to skip)', baseUrl: val };
+                store.refresh();
+                return;
+            case 'endpoint-key': {
+                const name = e.provider;
+                const err = await saveEndpoint({ name, baseUrl: e.baseUrl ?? '', key: val || undefined });
+                if (err) {
+                    this.note(`Could not save endpoint: ${err}`);
+                    store.keyEntry = null;
+                    store.refresh();
+                    return;
+                }
+                store.keyEntry = null;
+                // Refresh provider rows so the new endpoint appears, then jump to its models.
+                store.pickStage = 'providers';
+                await this.refreshModelPicker();
+                await this.enterModelStage(`custom:${name}`);
+                return;
+            }
+            case 'endpoint-fallback-model': {
+                store.keyEntry = null;
+                const name = e.provider;
+                if (val) {
+                    rememberEndpointModel(name, val);
+                }
+                store.modelPicker.open = false;
+                store.refresh();
+                void this.selectEndpointModel(name, val);
+                return;
+            }
+        }
+    }
+    async selectEndpointModel(name, model) {
+        if (!model)
+            return;
+        const full = `${name}/${model}`;
+        rememberEndpointModel(name, model);
+        const result = await this.onCommand({ type: 'model', value: full });
+        if (result === null)
+            this.note(`Model → ${full}`);
+    }
     /** Step over the row list, skipping non-selectable header rows. */
     movePickerIndex(index, delta) {
         const rows = this.store.pickRows;
@@ -570,6 +817,13 @@ export class TuiApp {
         return index;
     }
     async selectPickerModel(item) {
+        // Custom endpoints: id is `<name>/<model>`; just switch the model (the
+        // endpoint's provider is registered by name). No provider switch needed.
+        if (item.provider.startsWith('custom:')) {
+            const name = item.provider.slice('custom:'.length);
+            await this.selectEndpointModel(name, item.id.slice(name.length + 1));
+            return;
+        }
         // Switching provider first lets the same Enter pick a model from a
         // provider that isn't active (e.g. gemini model while on openrouter).
         const currentProvider = this.store.route?.provider;

package/dist/src/tui/components/ModelPicker.js

@@ -1,9 +1,9 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 import { useStore } from '../context.js';
 import { themeColor } from '../colors.js';
 import { isPickerHeader } from '../picker.js';
-/** Model selector overlay (opened by /model). Height includes the border. */
+/** Model/provider selector overlay (opened by /model). Height includes border. */
 export function ModelPicker({ height }) {
     const store = useStore();
     const accent = store.theme ? themeColor(store.theme, 'accent') : '#7aa2f7';
@@ -13,8 +13,15 @@ export function ModelPicker({ height }) {
     const rows = store.pickRows;
     const idx = rows.length === 0 ? 0 : Math.min(Math.max(store.modelPicker.index, 0), rows.length - 1);
     const innerH = Math.max(1, height - 3); // border(2) + footer(1)
+    const stageLabel = store.pickStage === 'models' ? 'model' : 'provider';
+    // Inline key / custom-endpoint entry: show one prompt + the typed value.
+    if (store.keyEntry) {
+        const ke = store.keyEntry;
+        const display = ke.kind === 'key-value' ? (ke.value ? '••••••••'.slice(0, 8) : '') : ke.value;
+        return (_jsxs(Box, { borderStyle: "round", borderColor: accent, width: "100%", height: height, flexDirection: "column", paddingX: 1, children: [_jsx(Box, { children: _jsxs(Text, { color: attention, bold: true, wrap: "truncate-end", children: [ke.kind === 'key-label' && `${ke.provider} key — label`, ke.kind === 'key-value' && `${ke.provider} key — value`, ke.kind === 'endpoint-name' && 'custom endpoint — name', ke.kind === 'endpoint-url' && `custom endpoint — base URL`, ke.kind === 'endpoint-key' && `custom endpoint — optional key`, ke.kind === 'endpoint-fallback-model' && `custom endpoint — model id`] }) }), _jsx(Text, { color: muted, wrap: "truncate-end", children: ke.hint }), _jsxs(Box, { children: [_jsx(Text, { color: dim, children: "\u276F " }), _jsx(Text, { color: accent, children: display || ' ' }), _jsx(Text, { color: muted, children: "\u258F" })] }), _jsx(Text, { color: muted, children: "Enter accept \u00B7 Esc cancel" })] }));
+    }
     if (rows.length === 0) {
-        return (_jsxs(Box, { borderStyle: "round", borderColor: dim, width: "100%", height: height, flexDirection: "column", paddingX: 1, children: [_jsx(Text, { color: dim, children: "no models available \u2014 configure a provider key first" }), _jsx(Text, { color: muted, children: "Esc close" })] }));
+        return (_jsxs(Box, { borderStyle: "round", borderColor: dim, width: "100%", height: height, flexDirection: "column", paddingX: 1, children: [_jsxs(Text, { color: dim, children: ["no ", stageLabel, "s available \u2014 configure a provider key first"] }), _jsx(Text, { color: muted, children: "Esc back \u00B7 Esc close" })] }));
     }
     const start = Math.max(0, Math.min(idx, rows.length - innerH));
     const windowRows = rows.slice(start, start + innerH);
@@ -23,6 +30,7 @@ export function ModelPicker({ height }) {
                 if (isPickerHeader(r)) {
                     return (_jsx(Box, { children: _jsx(Text, { color: attention, bold: true, wrap: "truncate-end", children: r.label }) }, `h-${at}`));
                 }
-                return (_jsxs(Box, { children: [_jsx(Text, { color: at === idx ? accent : dim, children: at === idx ? '❯ ' : '  ' }), _jsx(Text, { color: at === idx ? accent : dim, wrap: "truncate-end", children: r.label })] }, r.id));
-            }), start + innerH < rows.length && (_jsxs(Text, { color: muted, children: ["\u25BC ", rows.length - start - innerH, " more\u2026"] })), _jsx(Text, { color: muted, children: "\u2191\u2193 select \u00B7 Enter switch \u00B7 Esc close" })] }));
+                const hint = r.hint;
+                return (_jsxs(Box, { children: [_jsx(Text, { color: at === idx ? accent : dim, children: at === idx ? '❯ ' : '  ' }), _jsx(Text, { color: at === idx ? accent : dim, wrap: "truncate-end", children: r.label }), hint && _jsxs(Text, { color: muted, children: ["  ", hint] })] }, r.id ?? `p-${at}`));
+            }), start + innerH < rows.length && (_jsxs(Text, { color: muted, children: ["\u25BC ", rows.length - start - innerH, " more\u2026"] })), _jsx(Text, { color: muted, children: store.pickStage === 'models' ? '↑↓ select · Enter switch · Esc back' : '↑↓ select · Enter next · Esc close' })] }));
 }

package/dist/src/tui/picker.js

@@ -1,59 +1,147 @@
 import { PROVIDER_SPECS, ORBITX_SERVE } from '../core/llm/index.js';
-import { describeProvidersAvailable } from '../core/llm/secrets.js';
+import { describeProviderKey } from '../core/llm/secrets.js';
 import { createOllamaProvider } from '../core/llm/providers/ollama.js';
+import { loadEndpoints, listEndpointModels } from '../core/llm/endpoints.js';
 export function isPickerHeader(row) {
     return row.kind === 'header';
 }
-export async function resolvePickerRows() {
+function specLabel(id) {
+    return PROVIDER_SPECS.find((p) => p.id === id)?.label ?? id;
+}
+/** Stage 1 — provider rows (sync; no probing here). */
+export function resolveProviderRows() {
     const rows = [];
-    const seen = new Set();
-    const avail = describeProvidersAvailable();
     for (const spec of PROVIDER_SPECS) {
         if (spec.id === 'ollama') {
-            const ollama = createOllamaProvider();
-            const local = await ollama.listModels();
-            if (local.length === 0) {
-                rows.push({ kind: 'header', label: 'Ollama (local) — server offline, run ollama serve' });
-                continue;
-            }
-            rows.push({ kind: 'header', label: `Ollama (local) — ${local.length} installed` });
-            for (const full of local) {
-                const name = full.slice('ollama/'.length);
-                if (seen.has(full))
-                    continue;
-                seen.add(full);
-                rows.push({ kind: 'item', label: name, id: full, provider: 'ollama' });
-            }
+            const keyInfo = describeProviderKey('ollama');
+            rows.push({
+                kind: 'item',
+                providerId: 'ollama',
+                label: 'Ollama (local)',
+                hint: 'auto-detects a local server · no key required',
+                keyInfo: keyInfo === null ? { provider: 'ollama', available: false } : keyInfo,
+            });
             continue;
         }
         if (spec.id === 'orbitx') {
-            rows.push({ kind: 'header', label: 'Orbit X (auto-routes Groq · Gemini · OpenRouter)' });
-            for (const bare of ORBITX_SERVE) {
-                const full = `orbitx/${bare}`;
-                if (seen.has(full))
-                    continue;
-                seen.add(full);
-                rows.push({
-                    kind: 'item',
-                    label: bare === 'auto' ? 'auto (backend routes across providers)' : bare,
-                    id: full,
-                    provider: 'orbitx',
-                });
-            }
+            const keyInfo = describeProviderKey('orbitx');
+            rows.push({
+                kind: 'item',
+                providerId: 'orbitx',
+                label: 'Orbit X (auto-routes Groq · Gemini · OpenRouter)',
+                hint: keyInfo?.available ? `token ${keyInfo.masked} · ${keyInfo.source}` : 'token optional — gateway auto-routes',
+                keyInfo: keyInfo === null ? { provider: 'orbitx', available: false } : keyInfo,
+            });
             continue;
         }
-        // Other providers: only when a key is configured.
-        const available = avail.some((a) => a.provider === spec.id);
-        if (!available)
-            continue;
-        rows.push({ kind: 'header', label: spec.label });
-        for (const m of spec.models) {
-            const full = `${spec.id}/${m.id}`;
+        const keyInfo = describeProviderKey(spec.id);
+        const needsKey = spec.requiresSecret && !keyInfo?.available;
+        rows.push({
+            kind: 'item',
+            providerId: spec.id,
+            label: spec.label,
+            hint: needsKey
+                ? 'no key — press Enter to add'
+                : keyInfo
+                    ? `key ${keyInfo.masked} · ${keyInfo.source}${keyInfo.label ? ` · ${keyInfo.label}` : ''}`
+                    : 'no key required',
+            needsKey,
+            keyInfo: keyInfo ?? null,
+        });
+    }
+    // Named custom OpenAI-compatible endpoints.
+    const endpoints = loadEndpoints();
+    rows.push({ kind: 'header', label: 'Custom endpoints (OpenAI-compatible)' });
+    for (const ep of endpoints) {
+        rows.push({
+            kind: 'item',
+            providerId: `custom:${ep.name}`,
+            label: ep.name,
+            hint: `${ep.baseUrl}${ep.key ? ' · key set' : ' · no key'}`,
+            keyInfo: { provider: ep.name, available: true, source: 'file' },
+        });
+    }
+    rows.push({
+        kind: 'item',
+        providerId: '__add_custom__',
+        label: '＋ add a custom endpoint',
+        hint: 'LM Studio · vLLM · any OpenAI-compatible server',
+        keyInfo: null,
+    });
+    return rows;
+}
+/** Stage 2 — model rows for a provider. */
+export async function resolveModelRows(providerId, liveModels) {
+    const rows = [];
+    if (providerId.startsWith('custom:')) {
+        const name = providerId.slice('custom:'.length);
+        const ep = loadEndpoints().find((e) => e.name === name);
+        if (!ep) {
+            rows.push({ kind: 'header', label: 'unknown custom endpoint' });
+            return rows;
+        }
+        rows.push({ kind: 'header', label: `${name} — ${ep.baseUrl}` });
+        const live = await listEndpointModels(name);
+        const saved = (ep.models ?? []).filter(Boolean);
+        const merged = [...new Set([...live, ...saved])];
+        if (merged.length === 0) {
+            rows.push({
+                kind: 'header',
+                label: 'no models found — type a model id below (or start the server)',
+            });
+        }
+        else {
+            for (const m of merged) {
+                rows.push({ kind: 'item', label: m, id: `${name}/${m}`, provider: `custom:${name}` });
+            }
+        }
+        return rows;
+    }
+    if (providerId === 'ollama') {
+        const local = await createOllamaProvider().listModels();
+        if (local.length === 0) {
+            rows.push({ kind: 'header', label: 'Ollama server offline — run `ollama serve`' });
+            return rows;
+        }
+        rows.push({ kind: 'header', label: `Ollama (local) — ${local.length} installed` });
+        for (const full of local) {
+            rows.push({ kind: 'item', label: full.slice('ollama/'.length), id: full, provider: 'ollama' });
+        }
+        return rows;
+    }
+    if (providerId === 'orbitx') {
+        rows.push({ kind: 'header', label: 'Orbit X (auto-routes Groq · Gemini · OpenRouter)' });
+        // Prefer the LIVE routable list so offered == routable (kills "No model
+        // matches"); fall back to the serve table only when no orbitx candidates.
+        const live = liveModels.filter((m) => m.startsWith('orbitx/'));
+        const serve = live.length > 0 ? live : ORBITX_SERVE.map((b) => `orbitx/${b}`);
+        const seen = new Set();
+        for (const full of serve) {
             if (seen.has(full))
                 continue;
             seen.add(full);
-            rows.push({ kind: 'item', label: m.label ?? m.id, id: full, provider: spec.id });
+            const bare = full.slice('orbitx/'.length);
+            rows.push({
+                kind: 'item',
+                label: bare === 'auto' ? 'auto (backend routes across providers)' : bare,
+                id: full,
+                provider: 'orbitx',
+            });
         }
+        return rows;
+    }
+    // Catalog provider.
+    const spec = PROVIDER_SPECS.find((p) => p.id === providerId);
+    if (!spec) {
+        rows.push({ kind: 'header', label: `unknown provider ${providerId}` });
+        return rows;
+    }
+    rows.push({ kind: 'header', label: spec.label });
+    for (const m of spec.models) {
+        rows.push({ kind: 'item', label: m.label ?? m.id, id: `${spec.id}/${m.id}`, provider: spec.id });
+    }
+    if (spec.supportsCustom) {
+        rows.push({ kind: 'header', label: '— or type a custom model id below' });
     }
     return rows;
 }

package/dist/src/tui/store.js

@@ -39,6 +39,12 @@ export class AppStore {
     cwd = '';
     models = [];
     modelPicker = { open: false, index: 0 };
+    /** Which stage of the /model overlay is showing rows: providers or models. */
+    pickStage = 'providers';
+    /** Provider whose model list is showing in the model stage. */
+    pickProviderProviderId = null;
+    /** Inline key/custom-endpoint entry overlay (two-stage picker). */
+    keyEntry = null;
     /** Grouped rows for the /model overlay (see picker.ts). */
     pickRows = [];
     agents = new Map();

package/dist/src/utils/platform.js

@@ -42,6 +42,9 @@ export function configPath() {
 export function keysPath() {
     return join(configDir(), 'keys.json');
 }
+export function endpointsPath() {
+    return join(configDir(), 'endpoints.json');
+}
 export function historyPath() {
     return join(dataDir(), 'history.json');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbit-intelligence/orbit-agent",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "description": "orbit — a premium pure-TypeScript coding agent for Termux and desktop terminals, powered by Orbit X.",
   "type": "module",
   "license": "UNLICENSED",