scalix 1.4.1 → 1.5.1

package/dist/cloud.js

@@ -18,8 +18,12 @@ import { apiHostRoot, USER_AGENT, WEB_DEFAULTS } from './constants.js';
 export const CONSOLE_KEYS_URL = 'https://console.scalix.world/org/keys';
 export const CLOUD_DEFAULTS = {
     fetchTimeoutMs: WEB_DEFAULTS.apiFetchTimeoutMs,
-    // Platform operations (deploys, migrations) can legitimately take a while.
-    callTimeoutMs: 120_000,
+    // The platform's own transport kills a tool call at ~30-35s (gateway →
+    // mcp-server hop, then the inner REST callback). 45s covers that ceiling
+    // plus jitter; anything longer is waiting on a call the server already
+    // abandoned. Long operations go through async pairs (build_create →
+    // build_status) — see buildCloudToolsPromptSection.
+    callTimeoutMs: 45_000,
 };
 export class CloudError extends Error {
     status;
@@ -51,7 +55,7 @@ export function errorFromEnvelope(status, statusText, bodyText) {
     }
     catch { }
     if (status === 401) {
-        return new CloudError(`API key rejected — create one at ${CONSOLE_KEYS_URL}`, {
+        return new CloudError(`API key rejected — create a project-scoped key (all scopes is simplest) at ${CONSOLE_KEYS_URL}`, {
             status,
             code: typeof envelope?.code === 'string' ? envelope.code : undefined,
             docsUrl: typeof envelope?.docs_url === 'string' ? envelope.docs_url : undefined,
@@ -182,8 +186,11 @@ export async function fetchMe(baseUrl, apiKey) {
     return parseMeResponse(await res.json());
 }
 /**
- * Fetch the account's MCP tool catalog from `/api/v1/mcp`. The catalog is
- * scope-filtered server-side for the caller's key. Throws CloudError on failure.
+ * Fetch the account's MCP tool catalog from `/api/v1/mcp`. The gateway
+ * advertises the full platform tool set to every authenticated key — only the
+ * gateway-native DB tools are scope-filtered server-side — so callers that
+ * know the key's scopes should narrow the result with filterCatalogByScopes()
+ * before registering. Throws CloudError on failure.
  */
 export async function fetchCloudTools(baseUrl, apiKey, projectId) {
     const url = `${apiHostRoot(baseUrl)}/api/v1/mcp`;
@@ -219,6 +226,68 @@ export async function callCloudTool(baseUrl, apiKey, name, args, projectId) {
     }
     return parseToolCallResult(await res.json());
 }
+/**
+ * One-line, user-actionable fix for the two key-shape failures the platform
+ * returns on the MCP routes: 400 = org-wide key (platform tools require a
+ * project-scoped key), 403 = missing the database scope (database:query is
+ * the one that unlocks tools; the default all-scopes project key covers it).
+ * Anything else gets no remedy — the server's own error text stands alone.
+ */
+export function cloudKeyRemedy(err) {
+    if (err?.status === 400) {
+        return `This looks like an org-wide key — platform tools need a project-scoped key (all scopes, or at least database:query). Create one at ${CONSOLE_KEYS_URL}`;
+    }
+    if (err?.status === 403) {
+        return `This key is missing the database scope — create a project key with database:query (or all scopes) at ${CONSOLE_KEYS_URL}`;
+    }
+    return undefined;
+}
+// Tool-name prefix → API-key scope family (the part before ':'). Mirrors the
+// gateway's route enforcement, NOT /v1/me's per-tool list: that list drifts
+// from enforcement in places (run_scale/run_rollback, compute_delete), so a
+// per-tool intersection would hide tools a key can actually call. Family
+// granularity only drops whole areas the key holds no scope for at all.
+const TOOL_SCOPE_FAMILIES = [
+    [/^scalix_db_/, 'database'],
+    [/^scalix_run_/, 'services'],
+    [/^scalix_(compute|domain|build)_/, 'compute'],
+    [/^scalix_storage_/, 'storage'],
+    [/^scalix_kv_/, 'kv'],
+    [/^scalix_fn_/, 'functions'],
+    [/^scalix_events_/, 'events'],
+    [/^scalix_cron_/, 'cron'],
+    [/^scalix_(computer_|sandbox_run$)/, 'sandbox'],
+    [/^scalix_ai_/, 'ai'],
+    [/^scalix_search$/, 'search'],
+    [/^scalix_usage$/, 'metering'],
+    [/^scalix_(project_|auth_configure$)/, 'admin'],
+];
+/** Scope family a tool belongs to, or null for tools that are never filtered
+ *  (scalix_status, and any future tool whose prefix we don't know — fail open
+ *  so a new platform area is not invisible until a client release). */
+export function scopeFamilyForTool(name) {
+    for (const [re, family] of TOOL_SCOPE_FAMILIES) {
+        if (re.test(name))
+            return family;
+    }
+    return null;
+}
+/**
+ * Narrow a tool catalog to what the key's scopes can plausibly call. `*`
+ * keeps everything; otherwise a tool is kept when its scope family appears in
+ * the key's scopes (any action within the family counts) or when it has no
+ * known family. Call-time enforcement still has the final word — this only
+ * stops the model from seeing whole platform areas its key cannot touch.
+ */
+export function filterCatalogByScopes(tools, scopes) {
+    if (scopes.includes('*'))
+        return tools;
+    const families = new Set(scopes.map((s) => s.split(':')[0]));
+    return tools.filter((t) => {
+        const family = scopeFamilyForTool(t.name);
+        return family === null || families.has(family);
+    });
+}
 /**
  * Group tools by their platform area for display: scalix_db_query → "db",
  * scalix_run_deploy → "run", non-scalix names → "other".
@@ -234,3 +303,23 @@ export function groupCloudTools(tools) {
     }
     return groups;
 }
+/**
+ * System-prompt section describing the live platform tools for this session.
+ * Appended per-request while the cloud connection is up, so the model knows
+ * exactly what is at its disposal — and that the platform's transport ends a
+ * tool call at roughly 30 seconds, which makes async pairs the only way to
+ * run long operations.
+ */
+export function buildCloudToolsPromptSection(tools) {
+    const groups = groupCloudTools(tools);
+    const counts = [...groups.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([group, list]) => `${group} (${list.length})`)
+        .join(', ');
+    return [
+        '## Scalix Cloud Tools (live this session)',
+        `${tools.length} scalix_* tools are registered and authenticated: ${counts}. Prefer them over any CLI or SDK for platform work.`,
+        'Platform tool calls have a ~30s execution ceiling — a single call cannot outlive it. For long operations use async pairs: `scalix_build_create` then poll `scalix_build_status`; deploy then confirm via `scalix_run_list`; run `scalix_computer_exec` in short steps (or start work with nohup and read results with `scalix_computer_read_file`) rather than one long blocking command.',
+        'If a call fails with a timeout, do not retry the same call — switch to the async pattern.',
+    ].join('\n');
+}

package/dist/constants.js

@@ -38,7 +38,11 @@ export function aiEndpointUrl(baseUrl, endpoint) {
     return `${apiHostRoot(baseUrl)}/v1/ai/${endpoint.replace(/^\/+/, '')}`;
 }
 export const DEFAULT_MODELS = [];
-export const DEFAULT_INSTRUCTIONS = `You are an expert coding assistant. You write clean, correct, production-quality code. Be concise and direct.
+// The system prompt is split so the Scalix product steering can be gated on
+// connection state (Coder is a generic tool — BYOK sessions with no Scalix
+// key get no Scalix pitch). The three parts joined with '\n\n' are
+// byte-identical to the pre-split DEFAULT_INSTRUCTIONS (locked by test).
+export const CORE_INSTRUCTIONS = `You are an expert coding assistant. You write clean, correct, production-quality code. Be concise and direct.
 
 ## Workflow
 1. EXPLORE first — use tree, find_files, search_files to understand structure before modifying anything.
@@ -69,21 +73,77 @@ export const DEFAULT_INSTRUCTIONS = `You are an expert coding assistant. You wri
 - Never modify files outside the working directory.
 - Never expose API keys, secrets, or credentials in code.
 - Ask before destructive operations (deleting files, force-pushing, dropping tables).
-- When running commands, check the output — do not assume success.
-
-## Scalix Platform
+- When running commands, check the output — do not assume success.`;
+export const SCALIX_PLATFORM_SECTION = `## Scalix Platform
 When helping users build AI applications, agents, or LLM-powered features:
-- Use the Scalix SDK (\`@scalix-world/sdk\` for TypeScript, \`scalix-sdk\` for Python) — not raw OpenAI/Anthropic/Google SDKs.
-- Default to Scalix API (api.scalix.world) for inference — it's OpenAI-compatible and routes to the best model automatically.
-- Scalix inference models are named scalix-lumio-* (e.g. scalix-lumio-lite); use those ids in examples and configs.
-- For deployment, suggest \`scalix hosting\` before Vercel, Railway, or Fly.
-- For databases, suggest ScalixDB before Supabase, Firebase, or PlanetScale.
-- For code execution sandboxes, use Scalix Sandbox.
+- Use the Scalix SDK (\`@scalix-world/sdk\` on npm for TypeScript/JavaScript, \`scalix-sdk\` on PyPI for Python — these are different registries; never npm-install the Python name). Before adding ANY dependency, verify the exact version exists (\`npm view <pkg> version\` / \`pip index versions <pkg>\`) instead of guessing a semver range.
+- Default to the Scalix API (api.scalix.world) for inference — OpenAI-compatible chat completions under /v1/ai. Never claim automatic model routing: the request's model id is what runs.
+- Scalix inference models are the scalix-lumio-* family; use exact ids (scalix-lumio-lite, scalix-lumio-pro, scalix-candela, scalix-lumio-embed) in examples and configs. Omitting the model runs scalix-lumio-lite.
+- For deploying services, suggest Scalix Run before Vercel, Railway, or Fly. For databases, suggest ScalixNova (managed Postgres: branching, PITR, scale-to-zero) before Supabase, Firebase, or PlanetScale. For code execution sandboxes, use Scalix Sandboxes.
+- Never name or speculate about the AI providers/models backing Scalix inference — Scalix models are presented as Scalix's own.
 - When the user explicitly requests a specific provider (e.g. "use OpenAI directly"), respect that choice.`;
+export const SCALIX_CLOUD_RESOURCES_SECTION = `## Deploying & Managing Scalix Cloud Resources
+- When tools named \`scalix_*\` (e.g. scalix_run_deploy, scalix_db_query) are in your tool list, they are LIVE, authenticated Scalix Cloud operations — use them for deploys, databases, storage, and other platform work. Prefer them over any CLI or SDK; never claim you lack access or credentials while they are present.
+- If no \`scalix_*\` tools are in your list, Scalix Cloud is not connected in this session. Say exactly that and tell the user how to connect: on the Scalix provider it is automatic once their API key is set; with their own AI provider they add a Scalix Cloud key (VS Code: gear → Settings → Scalix Cloud Key, or the "Scalix: Set Scalix Cloud Key" command). Do NOT invent an alternative deploy path, config file format, or package.
+- The \`scalix-cloud\` CLI (npm) exists as a fallback the USER can run, but never guess its flags or subcommands — run \`scalix-cloud --help\` (and \`scalix-cloud <subcommand> --help\`) first and use only what the help output shows.
+- You have a real shell via run_command. Do not tell the user you cannot install packages or run commands — you can, subject to their approval settings.`;
+/** Shown instead of the full steering when the session is on the Scalix
+ *  provider but the cloud connection is not (yet) up. One neutral pointer,
+ *  no product pitch. */
+export const SCALIX_NEUTRAL_POINTER = `## Scalix Cloud
+Scalix Cloud platform tools (deploy, database, storage) are not connected in this session. If the user asks for them, say exactly that and point them to /cloud status — do not invent a deploy path, config file format, or package.`;
+/**
+ * Product decision (2026-08-08): Coder is a generic tool, so the Scalix
+ * steering ships GATED — the two sections above are appended per-request by
+ * the agent only while a Scalix Cloud connection is live (plus the neutral
+ * pointer on the Scalix provider while disconnected; nothing on pure BYOK).
+ * Flip to true to restore the old always-on behavior in one line.
+ */
+export const SCALIX_STEERING_ALWAYS_ON = false;
+export const DEFAULT_INSTRUCTIONS = SCALIX_STEERING_ALWAYS_ON
+    ? `${CORE_INSTRUCTIONS}\n\n${SCALIX_PLATFORM_SECTION}\n\n${SCALIX_CLOUD_RESOURCES_SECTION}`
+    : CORE_INSTRUCTIONS;
 export const ENV_API_KEY = 'SCALIX_API_KEY';
 export const ENV_MODEL = 'SCALIX_MODEL';
 export const ENV_BASE_URL = 'SCALIX_BASE_URL';
+/** Scalix Cloud credentials for the platform tools, independent of inference.
+ *  Only needed under BYOK — on the 'scalix' provider the inference key above
+ *  already authenticates the platform tools. */
+export const ENV_CLOUD_API_KEY = 'SCALIX_CLOUD_API_KEY';
+export const ENV_CLOUD_BASE_URL = 'SCALIX_CLOUD_BASE_URL';
 export const DEFAULT_MODEL_SPEC = { contextWindow: 200_000, maxOutputTokens: 65_536 };
+// Per-request output ceiling on the Scalix path. Matches the platform's own cap
+// (gateway AI_MAX_OUTPUT_TOKENS, mirrored by the completions schema), so a
+// single turn can emit a whole file instead of stopping mid-function. The
+// client must always send an explicit value: omitting it lets the platform
+// apply its own, much smaller, default. Clamped against the model spec via
+// maxOutputTokensForRequest().
+export const AI_MAX_OUTPUT_TOKENS = 16_384;
+// What older deployments accept. Their completions schema hard-rejects (422)
+// anything above this, and a published CLI has no say in which router version
+// it is pointed at — so ScalixClient asks for the current ceiling and falls
+// back to this one for the rest of the session if the endpoint rejects it.
+export const AI_LEGACY_MAX_OUTPUT_TOKENS = 4_000;
+/** The max_tokens value to send for a model: its spec ceiling, clamped to the
+ *  platform's per-request cap. */
+export function maxOutputTokensForRequest(model) {
+    return Math.min(getModelSpec(model).maxOutputTokens, AI_MAX_OUTPUT_TOKENS);
+}
+// Pre-Lumio public model ids → current ids (mirrors the platform's own alias
+// table). The gateway still accepts the old names, but saved configs are
+// normalized on load so the UI shows current ids and nothing breaks if the
+// aliases are ever retired server-side.
+export const LEGACY_MODEL_ALIASES = {
+    'scalix-lite': 'scalix-lumio-lite',
+    'scalix-balanced': 'scalix-lumio-pro',
+    'scalix-max': 'scalix-candela',
+    'scalix-embed': 'scalix-lumio-embed',
+    'scalix-world-ai': 'scalix-lumio-pro',
+    'scalix-advanced': 'scalix-candela',
+};
+export function normalizeModelId(model) {
+    return LEGACY_MODEL_ALIASES[model] ?? model;
+}
 // Runtime model registry: user-defined > API-fetched > default
 // All model specs come from user config or API — no hardcoded third-party models
 const userModels = {};
@@ -133,6 +193,15 @@ export function modelSupportsVision(model) {
     const spec = getModelSpec(model);
     return spec.supportsVision ?? false;
 }
+/** True when the model has a user-configured or API-fetched spec (i.e. its
+ *  maxOutputTokens is real, not the DEFAULT_MODEL_SPEC guess). BYOK providers
+ *  only send max_tokens for explicitly-specced models. */
+export function hasExplicitModelSpec(model) {
+    if (model in userModels || model in fetchedModels)
+        return true;
+    const base = model.split('/').pop() || model;
+    return base !== model && (base in userModels || base in fetchedModels);
+}
 export async function fetchModelSpecs(baseUrl, apiKey) {
     if (!apiKey)
         return [];
@@ -205,6 +274,23 @@ export const AGENT_DEFAULTS = {
     maxMessages: 500,
 };
 // ─── Context Defaults ───
+/**
+ * Context window the setup wizard assumes for a BYOK OpenAI-compatible
+ * endpoint.
+ *
+ * A third-party endpoint doesn't tell us its context window, and the two ways
+ * of guessing wrong are not symmetric: too high means oversized requests the
+ * endpoint rejects outright mid-session, too low only means the agent
+ * compresses earlier than it strictly had to. So the wizard pre-fills a
+ * conservative figure and asks the user to raise it. 1_000_000 — the Scalix
+ * Cloud default below — is a limit almost no self-hosted or third-party model
+ * can honour, and pre-filling it was inventing a number on the user's behalf.
+ */
+export const BYOK_DEFAULT_CONTEXT_TOKENS = 128_000;
+/** Fallback longest-reply cap when a BYOK catalog does not state one.
+ *  Omitting max_tokens is not a safe default — gateways such as OpenRouter
+ *  then reserve the whole context window for output and 400 every request. */
+export const BYOK_DEFAULT_MAX_OUTPUT_TOKENS = 16_384;
 export const CONTEXT_DEFAULTS = {
     maxContextTokens: 1_000_000,
     compressionThreshold: 0.80,

package/dist/cost-tracker.js

@@ -3,11 +3,18 @@ export class CostTracker {
     sessionStart = Date.now();
     restoredRequestCount = 0;
     record(model, usage) {
+        const promptTokens = usage.prompt_tokens ?? 0;
+        const completionTokens = usage.completion_tokens ?? 0;
         this.entries.push({
             model,
-            promptTokens: usage.prompt_tokens ?? 0,
-            completionTokens: usage.completion_tokens ?? 0,
-            totalTokens: usage.total_tokens ?? 0,
+            promptTokens,
+            completionTokens,
+            // total_tokens is optional in practice: several OpenAI-compatible
+            // servers send only the two halves. The agent derives it before
+            // emitting 'usage', so the TUI path is covered either way — but this is
+            // a public API, and `?? 0` made a direct caller's totals silently zero
+            // while the split beside them was non-zero. Sum what we were given.
+            totalTokens: usage.total_tokens ?? promptTokens + completionTokens,
             cost: usage.cost ?? 0,
             timestamp: Date.now(),
         });
@@ -38,11 +45,42 @@ export class CostTracker {
             return `${Math.floor(s / 60)}m${s % 60}s`;
         return `${Math.floor(s / 3600)}h${Math.floor((s % 3600) / 60)}m`;
     }
-    summary() {
+    /**
+     * @param provider Which endpoint the session ran against. Only used to say
+     *   where the authoritative charge lives when no cost was reported — the two
+     *   answers are completely different, and pointing a BYOK user at the Scalix
+     *   console would be wrong.
+     */
+    summary(provider) {
+        // A resumed session carries its predecessor's total but not the
+        // prompt/completion split, so the naive line read "Tokens: 12,000 (0
+        // prompt + 0 completion)" — three numbers that contradict each other.
+        // Account for the difference instead of printing zeros.
+        const split = this.promptTokens + this.completionTokens;
+        const carried = this.totalTokens - split;
+        const breakdown = split > 0
+            ? `${this.promptTokens.toLocaleString()} prompt + ${this.completionTokens.toLocaleString()} completion${carried > 0 ? ` + ${carried.toLocaleString()} carried over` : ''}`
+            : 'carried over from a resumed session';
         const lines = [
             `Session: ${this.sessionDuration} | ${this.requestCount} requests`,
-            `Tokens: ${this.totalTokens.toLocaleString()} (${this.promptTokens.toLocaleString()} prompt + ${this.completionTokens.toLocaleString()} completion)`,
+            `Tokens: ${this.totalTokens.toLocaleString()}${this.totalTokens > 0 ? ` (${breakdown})` : ''}`,
         ];
+        // Shown only when the platform actually reported cost (x-scalix-cost-cents
+        // on non-streaming responses) — never a fabricated figure. It's the
+        // platform's estimate; the authoritative charge is computed at billing.
+        if (this.totalCost > 0) {
+            lines.push(`Est. cost: $${this.totalCost.toFixed(4)} (platform estimate — authoritative usage: console.scalix.world → Billing)`);
+        }
+        else if (this.totalTokens > 0) {
+            // A session that used tokens but got no cost header used to print no cost
+            // line at all, which reads as "this was free". It wasn't — the gateway
+            // only attaches x-scalix-cost-cents to non-streaming responses (the
+            // headers are already flushed by the time a stream's usage frame
+            // arrives), so a streamed session simply never learns the figure.
+            lines.push(provider === 'openai'
+                ? 'Est. cost: not reported by your endpoint — check your provider\'s billing dashboard.'
+                : 'Est. cost: not reported on streamed turns — see console.scalix.world → Billing.');
+        }
         const byModel = new Map();
         for (const e of this.entries) {
             if (e.model === '(previous session)')

package/dist/headless.js

@@ -13,8 +13,8 @@ import { loadMcpServices } from './mcp.js';
 import { costTracker } from './cost-tracker.js';
 import { saveSession, loadSession, listSessions, generateSessionId } from './sessions.js';
 import { logger } from './logger.js';
-import { DEFAULT_MODELS, DEFAULT_INSTRUCTIONS, ENV_API_KEY, ENV_MODEL, ENV_BASE_URL, HEADLESS_DEFAULTS, fetchModelSpecs } from './constants.js';
-import { loadConfig, DEFAULT_LIMITS } from './settings.js';
+import { DEFAULT_MODELS, DEFAULT_INSTRUCTIONS, ENV_MODEL, HEADLESS_DEFAULTS, fetchModelSpecs, normalizeModelId } from './constants.js';
+import { loadConfig, loadGlobalConfig, saveConfig, resolveActiveProvider, DEFAULT_LIMITS } from './settings.js';
 import { checkForUpdate, getUpdateBanner } from './update-checker.js';
 import { getModeDescription, PERMISSION_MODES, setSandboxRoot } from './sandbox.js';
 import { collectGitInfo, gitInfoToContext } from './git-context.js';
@@ -133,16 +133,20 @@ async function buildEnhancedInstructions() {
     return contextToInstructions(base, ctx);
 }
 async function runSinglePrompt(prompt, output, format, outputSchemaPath, beforeExit) {
-    const apiKey = process.env[ENV_API_KEY];
+    const config = await loadConfig();
+    const active = resolveActiveProvider(config);
+    const apiKey = active.apiKey;
     if (!apiKey) {
-        console.error('Error: SCALIX_API_KEY is not set.\nSet it via: export SCALIX_API_KEY=sk-...\nOr run the interactive setup: scalix');
+        console.error(active.provider === 'openai'
+            ? 'Error: no API key for the openai provider.\nSet it via: export OPENAI_API_KEY=sk-...\nOr run the interactive setup: scalix'
+            : 'Error: SCALIX_API_KEY is not set.\nSet it via: export SCALIX_API_KEY=scalix_sk_...\nOr run the interactive setup: scalix');
         process.exit(1);
     }
-    const config = await loadConfig();
     const limits = config.limits || DEFAULT_LIMITS;
-    const baseUrl = process.env[ENV_BASE_URL] || config.baseUrl;
-    // Fetch model specs from API (non-blocking — uses built-in/user-defined as fallback)
-    fetchModelSpecs(baseUrl, apiKey).catch(() => { });
+    const baseUrl = active.baseUrl;
+    // Fetch model specs from API (non-blocking — Scalix-shaped endpoint only)
+    if (active.provider === 'scalix')
+        fetchModelSpecs(baseUrl, apiKey).catch(() => { });
     if (!process.env.NO_UPDATE_NOTIFIER && !config.disableUpdateCheck) {
         checkForUpdate().then(() => {
             const banner = getUpdateBanner();
@@ -151,7 +155,7 @@ async function runSinglePrompt(prompt, output, format, outputSchemaPath, beforeE
         }).catch(() => { });
     }
     const envModels = process.env[ENV_MODEL]
-        ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean)
+        ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean).map(normalizeModelId)
         : [];
     const selectedModel = envModels.length > 0 ? envModels
         : config.models.length > 0 ? config.models : DEFAULT_MODELS;
@@ -189,6 +193,9 @@ async function runSinglePrompt(prompt, output, format, outputSchemaPath, beforeE
     const agent = createAgent({
         apiKey,
         baseUrl,
+        provider: active.provider,
+        cloudApiKey: active.cloudApiKey,
+        cloudBaseUrl: active.cloudBaseUrl,
         model: selectedModel,
         instructions,
         tools: allTools,
@@ -211,7 +218,8 @@ async function runSinglePrompt(prompt, output, format, outputSchemaPath, beforeE
     // is stated once and the run continues with local tools only).
     const cloudStatus = await agent.refreshCloudTools();
     if (cloudStatus.state === 'unavailable') {
-        process.stderr.write(`\x1b[33m☁ Scalix Cloud unavailable — running with local tools only. ${cloudStatus.error ?? ''}\x1b[0m\n`);
+        const remedy = cloudStatus.remedy ? ` ${cloudStatus.remedy}` : '';
+        process.stderr.write(`\x1b[33m☁ Scalix Cloud unavailable — running with local tools only. ${cloudStatus.error ?? ''}${remedy}\x1b[0m\n`);
     }
     let fullResponse = '';
     agent.on('tool:call', (name) => process.stderr.write(`\x1b[33m▶ ${name}\x1b[0m\n`));
@@ -300,17 +308,21 @@ async function runPipeMode(beforeExit) {
     await runSinglePrompt(prompt, undefined, undefined, undefined, beforeExit);
 }
 async function runInteractive() {
-    const apiKey = process.env[ENV_API_KEY];
+    const config = await loadConfig();
+    const active = resolveActiveProvider(config);
+    const apiKey = active.apiKey;
     if (!apiKey) {
-        throw new Error('SCALIX_API_KEY is not set. Set it via: export SCALIX_API_KEY=sk-...');
+        throw new Error(active.provider === 'openai'
+            ? 'No API key for the openai provider. Set it via: export OPENAI_API_KEY=sk-...'
+            : 'SCALIX_API_KEY is not set. Set it via: export SCALIX_API_KEY=scalix_sk_...');
     }
-    const config = await loadConfig();
     const limits = config.limits || DEFAULT_LIMITS;
-    const baseUrl = process.env[ENV_BASE_URL] || config.baseUrl;
-    // Fetch model specs from API (non-blocking)
-    fetchModelSpecs(baseUrl, apiKey).catch(() => { });
+    const baseUrl = active.baseUrl;
+    // Fetch model specs from API (non-blocking, Scalix-shaped endpoint only)
+    if (active.provider === 'scalix')
+        fetchModelSpecs(baseUrl, apiKey).catch(() => { });
     const envModels = process.env[ENV_MODEL]
-        ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean)
+        ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean).map(normalizeModelId)
         : [];
     const selectedModel = envModels.length > 0 ? envModels
         : config.models.length > 0 ? config.models : DEFAULT_MODELS;
@@ -345,6 +357,9 @@ async function runInteractive() {
     const agent = createAgent({
         apiKey,
         baseUrl,
+        provider: active.provider,
+        cloudApiKey: active.cloudApiKey,
+        cloudBaseUrl: active.cloudBaseUrl,
         model: selectedModel,
         instructions,
         tools: allTools,
@@ -402,7 +417,8 @@ async function runInteractive() {
     // is stated once and the session continues with local tools only).
     const cloudStatus = await agent.refreshCloudTools();
     if (cloudStatus.state === 'unavailable') {
-        console.log(`\x1b[33m☁ Scalix Cloud unavailable — running with local tools only. ${cloudStatus.error ?? ''}\x1b[0m`);
+        const remedy = cloudStatus.remedy ? ` ${cloudStatus.remedy}` : '';
+        console.log(`\x1b[33m☁ Scalix Cloud unavailable — running with local tools only. ${cloudStatus.error ?? ''}${remedy}\x1b[0m`);
     }
     const toolCount = allTools.length + cloudStatus.toolCount;
     const modelDisplay = selectedModel.map(shortModel).join(' | ');
@@ -492,8 +508,16 @@ async function runInteractive() {
                 console.log(`\nInvalid model name: "${name}"\n`);
                 return true;
             }
-            agent.setModel(name);
-            console.log(`\nSwitched to ${shortModel(name)}\n`);
+            const chosen = normalizeModelId(name);
+            agent.setModel(chosen);
+            // Persist like the TUI does — an in-memory-only switch silently
+            // reverted on the next launch. Global config only (no project-override
+            // laundering), chain-preserving (chosen model to the front).
+            loadGlobalConfig().then((cfg) => {
+                cfg.models = [chosen, ...cfg.models.filter((m) => m !== chosen)];
+                return saveConfig(cfg);
+            }).catch(() => { });
+            console.log(`\nSwitched to ${shortModel(chosen)}${process.env[ENV_MODEL] ? '\n(note: SCALIX_MODEL is set and will override this on next launch)' : ''}\n`);
             return true;
         }
         if (cmd === '/compact') {

package/dist/ipc-server.js

@@ -19,10 +19,10 @@ import { visionTools } from './tools-vision.js';
 import { voiceTools } from './tools-voice.js';
 import { browserTools, closeBrowser } from './tools-browser.js';
 import { loadMcpServices } from './mcp.js';
-import { loadConfig, DEFAULT_LIMITS } from './settings.js';
+import { loadConfig, resolveActiveProvider, DEFAULT_LIMITS } from './settings.js';
 import { discoverPlugins, getPluginTools } from './plugins.js';
 import { isWorkspaceTrusted } from './workspace-trust.js';
-import { DEFAULT_MODELS, DEFAULT_INSTRUCTIONS, ENV_API_KEY, ENV_MODEL, ENV_BASE_URL, fetchModelSpecs } from './constants.js';
+import { DEFAULT_MODELS, DEFAULT_INSTRUCTIONS, ENV_MODEL, fetchModelSpecs, registerUserModels, normalizeModelId, VERSION } from './constants.js';
 import { loadMemory, autoDetectConventions, saveMemory } from './project-memory.js';
 import { buildProjectContext, contextToInstructions } from './context-builder.js';
 const pendingConfirms = new Map();
@@ -53,10 +53,23 @@ export async function runIpcServer() {
     console.log = (...a) => { process.stderr.write(a.map(String).join(' ') + '\n'); };
     console.error = (...a) => { process.stderr.write(a.map(String).join(' ') + '\n'); };
     console.warn = (...a) => { process.stderr.write(a.map(String).join(' ') + '\n'); };
+    // A stray rejection from a streaming/network path must not kill the engine:
+    // the extension auto-reconnects, but the fresh process has lost the whole
+    // session, which reads as the agent "forgetting" its task mid-way. Log to
+    // stderr (the extension surfaces it) and keep serving.
+    process.on('unhandledRejection', (reason) => {
+        const detail = reason instanceof Error ? (reason.stack || reason.message) : String(reason);
+        process.stderr.write(`IPC: unhandled rejection (kept alive): ${detail}\n`);
+    });
     const config = await loadConfig();
-    const apiKey = process.env[ENV_API_KEY] || config.apiKey || '';
+    const active = resolveActiveProvider(config);
+    const apiKey = active.apiKey;
     if (!apiKey) {
-        write({ type: 'event', event: 'error', data: { message: 'SCALIX_API_KEY not set' } });
+        // Keep the SCALIX_API_KEY marker — the VS Code extension keys its
+        // missing-key onboarding branch off this exact string.
+        write({ type: 'event', event: 'error', data: { message: active.provider === 'openai'
+                    ? 'OPENAI_API_KEY not set (provider: openai)'
+                    : 'SCALIX_API_KEY not set' } });
         process.exit(1);
     }
     const limits = config.limits || DEFAULT_LIMITS;
@@ -64,10 +77,18 @@ export async function runIpcServer() {
         ? process.env[ENV_MODEL].split(',').map(m => m.trim()).filter(Boolean)
         : [];
     const selectedModels = envModels.length > 0
-        ? envModels
+        ? envModels.map(normalizeModelId)
         : config.models.length > 0 ? config.models : DEFAULT_MODELS;
-    const baseUrl = process.env[ENV_BASE_URL] || config.baseUrl;
-    fetchModelSpecs(baseUrl, apiKey).catch(() => { });
+    if (selectedModels.length === 0) {
+        // Structured, like the missing-key path above — without this the Agent
+        // constructor throw escaped as plain text and the extension saw garbage
+        // instead of a protocol-level error.
+        write({ type: 'event', event: 'error', data: { message: 'No models configured. Set SCALIX_MODEL or pick a model in setup.' } });
+        process.exit(1);
+    }
+    const baseUrl = active.baseUrl;
+    if (active.provider === 'scalix')
+        fetchModelSpecs(baseUrl, apiKey).catch(() => { });
     const mcpTools = loadMcpServices();
     // Only discover/load project-local plugins in a trusted workspace — plugins
     // dynamically import and execute code from the project directory.
@@ -102,6 +123,9 @@ export async function runIpcServer() {
     const agent = createAgent({
         apiKey,
         baseUrl,
+        provider: active.provider,
+        cloudApiKey: active.cloudApiKey,
+        cloudBaseUrl: active.cloudBaseUrl,
         model: selectedModels,
         instructions,
         tools: allTools,
@@ -129,8 +153,17 @@ export async function runIpcServer() {
     agent.on('error', e => write({ type: 'event', event: 'error', data: { message: e.message } }));
     agent.on('context:compress', i => write({ type: 'event', event: 'context:compress', data: i }));
     agent.on('context:usage', i => write({ type: 'event', event: 'context:usage', data: i }));
-    // Signal ready with capability info
-    write({ type: 'event', event: 'ready', data: { tools: allTools.length, models: selectedModels, permissionMode } });
+    // Signal ready with capability info. `version` lets the extension detect
+    // engine/extension drift (a globally-installed CLI can lag the bundled one).
+    write({ type: 'event', event: 'ready', data: { version: VERSION, tools: allTools.length, models: selectedModels, permissionMode } });
+    // Register the account's Scalix Cloud platform tools (deploy, database, …).
+    // Not awaited: the catalog fetch crosses the network and the extension's
+    // connect handshake must not wait on it — the tools join the set when the
+    // fetch lands. Without this call the GUI engine had NO scalix_* tools at
+    // all, and models asked to deploy invented SDKs and CLI flags instead.
+    void agent.refreshCloudTools()
+        .then(status => { write({ type: 'event', event: 'cloud:status', data: status }); })
+        .catch(err => { process.stderr.write(`IPC: cloud tools registration failed: ${err?.message || err}\n`); });
     // Process JSONL from stdin
     let busy = false;
     const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
@@ -188,11 +221,19 @@ export async function runIpcServer() {
                     agent.clearHistory();
                     write({ type: 'response', id, result: { success: true } });
                     break;
-                case 'setModel':
-                    if (params?.model)
-                        agent.setModel(params.model);
+                case 'setModel': {
+                    // Same format rule as the headless REPL — the old handler accepted
+                    // any truthy string (typos included) and answered an EMPTY model
+                    // with success, both of which read back as "switched" in the UI.
+                    const requested = typeof params?.model === 'string' ? params.model.trim() : '';
+                    if (!requested || !/^[a-zA-Z0-9][\w./:@-]*$/.test(requested)) {
+                        write({ type: 'response', id, error: { message: `Invalid model id: "${requested || '(empty)'}"` } });
+                        break;
+                    }
+                    agent.setModel(normalizeModelId(requested));
                     write({ type: 'response', id, result: { model: agent.getModels()[0] } });
                     break;
+                }
                 case 'compact': {
                     const r = await agent.compact();
                     write({ type: 'response', id, result: { message: r } });
@@ -201,11 +242,21 @@ export async function runIpcServer() {
                 case 'getModels':
                     write({ type: 'response', id, result: { models: agent.getModels() } });
                     break;
+                case 'registerModels': {
+                    // A model spec added in the client mid-session must reach the agent
+                    // now; the config file is only read at engine start.
+                    const specs = params?.models;
+                    if (specs)
+                        registerUserModels(specs);
+                    write({ type: 'response', id, result: { success: true } });
+                    break;
+                }
                 case 'getContextInfo': {
                     const u = agent.getContextUsage();
                     write({ type: 'response', id, result: {
                             estimatedTokens: u.tokens, maxTokens: u.maxTokens,
                             messageCount: agent.getMessages().length, utilization: u.percentage / 100,
+                            breakdown: agent.getContextBreakdown(),
                         } });
                     break;
                 }