scalix 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to Scalix Coder will be documented in this file.
 
+## [1.5.0] - 2026-08-02
+
+### Added
+- **BYOK — bring your own key and models.** New provider layer (`src/providers/`): the agent now runs against any **OpenAI-compatible endpoint** (OpenAI, OpenRouter, Ollama, LM Studio, Together, vLLM, LiteLLM, ...) with your own key. Setup wizard gained a provider step (Scalix stays the zero-config default/recommended); env config via `SCALIX_PROVIDER=openai` + `OPENAI_BASE_URL` + `OPENAI_API_KEY`. Endpoint roots are accepted with or without `/v1`. No default third-party endpoint — BYOK is fully opt-in.
+- Provider-scoped behavior: BYOK endpoints stream every turn (native tool-call deltas), skip the Scalix-only `max_tokens` clamp, and never receive the Scalix `thinking_level` extension; Scalix Cloud platform tools are gated to the Scalix provider. Per-provider credential slots in the OS keychain; legacy `/v1`-suffixed Scalix bases keep working.
+- BYOK model discovery reads whichever context-window field the endpoint actually reports (`context_length`, `max_model_len`, `max_context_length`, `context_window`, top level or under `top_provider`). A model that reports none is left without one rather than inheriting a borrowed number, and the wizard pre-fills a conservative 128K instead of a 1M figure almost no third-party model can honour.
+- BYOK streams ask for `stream_options.include_usage`, so `/cost`, the status bar and the context meter carry real numbers instead of sitting on zero. Dropped for the session if the endpoint rejects the field.
+- **Real cost tracking** — non-streaming responses read the platform's `x-scalix-cost-cents` estimate into `usage.cost`; `/cost` shows it as "Est. cost" with a pointer to console billing. No client-side price tables, nothing fabricated.
+- 429/503 responses honor the server's `Retry-After` (capped at 60s) instead of blind exponential backoff, and the wait is now visible while it happens instead of the turn sitting silently on "Thinking...".
+- `/status` shows the active provider; provider selection round-trips through config validation (whitelisted).
+- A benchmark suite (`bench/`, repo only — not in the package): seven coding tasks graded by held-out verifiers that never exist in the workspace the agent sees, with protected paths and mutation-graded test writing. Runs against `bin/scalix.js`, the same entrypoint npm installs. `npm run bench` for the deterministic tier, `npm run bench:live` against a real model.
+
+### Fixed
+- **Responses no longer truncate mid-answer** — every request on the Scalix path sends an explicit `max_tokens`, and the ceiling is now 16,384 (matching the platform's own cap) rather than 4,000. Omitting the field lets the platform apply a much smaller default. The ceiling is per session: the client asks for 16,384 and falls back to 4,000 for the rest of the session if the endpoint rejects it, so older deployments keep working without configuration.
+- **Tool calling against the Scalix platform** — agentic turns are no longer forced non-streaming. The client asks `/v1/ai/models` what the deployment supports and streams tool calls only where `streaming_tool_calls` is advertised; anything older, or unreachable, falls back to the non-streaming path that returns tool calls intact.
+- The Scalix identity probe (`/v1/me`) is no longer sent on BYOK sessions. It was posting your provider key to a route that does not exist on OpenRouter/Ollama/vLLM and turning the resulting 404 into a "Scalix Cloud unavailable" warning on a session that never involved Scalix Cloud.
+- Keychain reads and writes time out instead of hanging. A macOS keychain prompt nobody can see used to block the setup wizard's final keypress for ~20s with no feedback. When the keychain refuses outright and a secret has to stay in `config.json`, the app now says so instead of failing silently.
+- Token and cost reporting: totals are derived when a server sends only prompt/completion halves; a resumed session no longer prints "12,000 (0 prompt + 0 completion)"; and a session that spent tokens but received no cost header says where the real figure lives instead of implying it was free.
+- Terminal rendering: headings no longer arrive with their literal `##` attached, and emphasis inside list items is styled rather than printed as raw asterisks. Tool results are summarised to a readable line instead of a raw JSON envelope that buried the output and truncated the exit code. The banner is dropped rather than sliced in short or narrow terminals.
+- `/help` and the `/` typeahead are generated from one catalog and can no longer disagree — `/update` was reachable but unlisted, while `/fork`, `/permissions`, `/resume` and `/skills` were listed but missing from `/help`.
+- The setup wizard no longer opens its model step showing "At least one model is required" before anything has been typed.
+- Replay files are written with owner-only permissions (0600), matching sessions/config.
+
+### Fixed (VS Code extension)
+- A tool that failed is shown as failed. Every tool reports failure the same way and the panel was marking them all with a success check, on live and replayed sessions alike.
+- A model spec entered in the panel now reaches the engine: it is written to the shared config and pushed into the running process, where previously it affected no request at all.
+- Responses can no longer be lost between the final stream delta and the end of a turn, which left an empty reply bubble on tool-heavy turns.
+- Deleting a session asks first; the connection indicator can no longer read green while the engine is down; the thinking indicator stops when a turn ends without text; and the send button announces what it actually does when it becomes an abort button.
+- Keyboard shortcut help is generated from the extension manifest, so it cannot drift from the real bindings. `Scalix Coder: Open` renamed to `Scalix Coder: Open Chat Panel`.
+
+### Changed
+- System prompt's Scalix Platform section corrected to real products and behavior: Scalix Run (via `scalix-cloud` CLI) for deploys, ScalixNova for databases, Scalix Sandboxes for code execution, exact `scalix-lumio-*` model ids, no "automatic model routing" claim, and an explicit provider-non-disclosure rule.
+- Legacy public model ids in saved configs (`scalix-lite`, `scalix-balanced`, `scalix-max`, `scalix-embed`, `scalix-world-ai`, `scalix-advanced`) are normalized to their current Lumio ids on load.
+- Chat completions now send `x-client-type: cli` (parity with the models/cloud endpoints).
+- IPC `ready` event includes the engine `version` so the VS Code extension can detect engine/extension drift.
+
 ## [1.4.0] - 2026-07-05
 
 ### Added

package/README.md

@@ -1,12 +1,12 @@
 # Scalix Coder
 
-AI-powered coding agent for the terminal and VS Code — built by [Scalix World](https://scalix.world).
+AI-powered coding agent for the terminal and [VS Code](https://marketplace.visualstudio.com/items?itemName=scalix.scalix) — built by [Scalix World](https://scalix.world).
 
 ![Version](https://img.shields.io/badge/version-1.4.0-blue)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-green)
 ![License](https://img.shields.io/badge/license-EULA-orange)
 
-Scalix Coder is a full-featured AI coding assistant that runs in your terminal or as a VS Code extension. It connects to the Scalix API (or your own compatible endpoint) and gives AI direct access to your codebase through 31 built-in tools — file editing, shell execution, search, git, web access, browser automation, vision, voice input, and more.
+Scalix Coder is a full-featured AI coding assistant that runs in your terminal and in your editor — the extension is live on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=scalix.scalix) and [Open VSX](https://open-vsx.org/extension/scalix/scalix) (Cursor/Windsurf/VSCodium). It connects to the Scalix API (or your own compatible endpoint) and gives AI direct access to your codebase through 40 built-in tools — file editing, shell execution, search, git, web access, browser automation, vision, voice input, and more.
 
 ## One agent for your whole cloud
 
@@ -16,15 +16,34 @@ With a Scalix account, the agent is more than a coder: on start it fetches your
 - `/cloud` shows your connection, plan, and available tools; `/cloud refresh` re-fetches the catalog
 - No account (or catalog unreachable)? The agent says so once and runs in **local-only mode** with the built-in tools — nothing is faked
 
+## Bring your own key (BYOK)
+
+Scalix is the zero-config default, but the agent also runs against **any OpenAI-compatible endpoint** with your own key — OpenAI, OpenRouter, Ollama, LM Studio, Together, vLLM, LiteLLM, and friends. Pick "OpenAI-compatible endpoint" in the setup wizard (`scalix` → provider step, or `/setup`), or configure via env:
+
+```bash
+export SCALIX_PROVIDER=openai
+export OPENAI_BASE_URL=http://localhost:11434   # with or without /v1
+export OPENAI_API_KEY=sk-...
+export SCALIX_MODEL=llama3
+scalix
+```
+
+Notes:
+- There is **no default third-party endpoint** — BYOK is fully opt-in and the endpoint URL is always yours.
+- Scalix Cloud platform tools (database, deploys, storage, ...) are Scalix-only and are skipped on BYOK providers.
+- On BYOK endpoints the agent streams every turn (tool calls included) and lets the server govern output limits; model context/output specs come from your `customModels` config when you want exact windows.
+- Credentials are stored per provider (OS keychain / 0600 config), never shared between providers.
+- Anthropic, Vertex, and Bedrock native adapters are specced follow-ups (see MULTI-PROVIDER-ADAPTER-SPEC.md).
+
 ## Features
 
 - **Terminal UI** — Rich React/Ink interface with magenta-themed prompt, scrollable chat, streaming responses, and keyboard shortcuts
-- **VS Code Extension** — Sidebar chat panel with inline diffs, tab completion, inline chat (Cmd+I), codebase search, model picker, checkpoints, and session history
-- **31 Built-in Tools** — Shell, file read/write/edit, search (ripgrep), git, web fetch/search, directory tree, notebooks, browser automation, vision, voice input, sub-agents
+- **[VS Code Extension](https://marketplace.visualstudio.com/items?itemName=scalix.scalix)** — Sidebar chat panel with inline diffs, tab completion, inline chat (Cmd+I), codebase search, model picker, checkpoints, and session history
+- **40 Built-in Tools** — Shell, file read/write/edit, search (ripgrep), git, web fetch/search, directory tree, notebooks, browser automation, vision, voice input, sub-agents, task board
 - **Security Sandbox** — Path traversal prevention, symlink detection, command blocklist, injection detection, SSRF protection
 - **4 Permission Modes** — `plan` (read-only) / `default` (ask) / `auto` (auto-approve) / `yolo` (full autonomy)
 - **Context Management** — Auto-compression, sliding window, per-model context limits
-- **Dynamic Model Registry** — Models fetched from your Scalix account with exact context windows
+- **Dynamic Model Registry** — Models fetched from your Scalix account; context windows applied when the platform supplies them (sensible defaults otherwise, or set exact limits per model in config)
 - **Session Persistence** — Save, load, and resume conversations
 - **Project Intelligence** — Auto-detects tech stack, conventions, git context
 - **Plugin System** — Custom tools via `.scalix/plugins/`
@@ -199,14 +218,14 @@ Config is stored in `~/.scalix-coder/config.json`.
 
 | Setting                | Default   | Description                                   |
 | ---------------------- | --------- | --------------------------------------------- |
-| `maxSteps`             | 200       | Tool-call rounds per request                  |
-| `maxMessages`          | 200       | History size                                  |
+| `maxSteps`             | 500       | Tool-call rounds per request                  |
+| `maxMessages`          | 500       | History size                                  |
 | `maxContextTokens`     | 1,000,000 | Context window (tokens)                       |
-| `compressionThreshold` | 0.75      | Auto-compress when context exceeds this ratio |
-| `maxToolResultTokens`  | 10,000    | Truncate tool results (tokens)                |
-| `commandTimeoutMs`     | 60,000    | Shell command timeout (ms)                    |
-| `bgCleanupMs`          | 300,000   | Background process auto-cleanup (5 min)       |
-| `readFileMaxSize`      | 10 MB     | Max file size for read operations             |
+| `compressionThreshold` | 0.80      | Auto-compress when context exceeds this ratio |
+| `maxToolResultTokens`  | 50,000    | Truncate tool results (tokens)                |
+| `commandTimeoutMs`     | 120,000   | Shell command timeout (ms)                    |
+| `bgCleanupMs`          | 600,000   | Background process auto-cleanup (10 min)      |
+| `readFileMaxSize`      | 50 MB     | Max file size for read operations             |
 
 ### Project Files
 
@@ -222,6 +241,14 @@ Config is stored in `~/.scalix-coder/config.json`.
 
 ## VS Code Extension
 
+Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=scalix.scalix) — or from [Open VSX](https://open-vsx.org/extension/scalix/scalix) if you use Cursor, Windsurf, or VSCodium:
+
+```bash
+code --install-extension scalix.scalix
+```
+
+Or build from source with the steps below.
+
 Full-featured sidebar assistant with streaming chat, tab completion, inline chat, inline diffs, codebase search, and checkpoints.
 
 See [vscode-extension/README.md](vscode-extension/README.md) for setup and usage.

package/dist/agent-replay.js

@@ -110,7 +110,8 @@ export class AgentReplay {
     async save() {
         await fs.mkdir(REPLAYS_DIR, { recursive: true });
         const filePath = path.join(REPLAYS_DIR, `${this.session.id}.json`);
-        await fs.writeFile(filePath, JSON.stringify(this.session, null, 2), 'utf-8');
+        // Replay files carry conversation content — same owner-only mode as sessions.
+        await fs.writeFile(filePath, JSON.stringify(this.session, null, 2), { encoding: 'utf-8', mode: 0o600 });
         return filePath;
     }
     static async load(sessionId) {

package/dist/agent.js

@@ -1,10 +1,10 @@
-import { ScalixClient, ApiError } from './api-client.js';
+import { ApiError } from './api-client.js';
 import { EventEmitter } from 'eventemitter3';
 import { randomUUID } from 'node:crypto';
 import { getToolPermissionWithArgs } from './sandbox.js';
 import { logger } from './logger.js';
-import { DEFAULT_MODELS as FALLBACK_MODELS, DEFAULT_INSTRUCTIONS, DEFAULT_BASE_URL, AGENT_DEFAULTS, TOOL_DEFAULTS, BACKOFF_DEFAULTS, modelSupportsVision, getModelSpec } from './constants.js';
-import { estimateMessageTokens as estimateTokenCount } from './token-counter.js';
+import { DEFAULT_MODELS as FALLBACK_MODELS, DEFAULT_INSTRUCTIONS, DEFAULT_BASE_URL, AGENT_DEFAULTS, TOOL_DEFAULTS, BACKOFF_DEFAULTS, CONTEXT_DEFAULTS, modelSupportsVision, getModelSpec, maxOutputTokensForRequest, hasExplicitModelSpec } from './constants.js';
+import { estimateMessageTokens as estimateTokenCount, estimateTokens } from './token-counter.js';
 import { ContextManager } from './context-manager.js';
 import { zodToJsonSchema } from './tool-helper.js';
 import { ToolSelector } from './tool-selector.js';
@@ -20,6 +20,14 @@ import { RETRIEVAL_DEFAULTS } from './context-retriever.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fetchCloudTools, callCloudTool } from './cloud.js';
+import { createChatClient, capabilitiesFor } from './providers/index.js';
+/**
+ * Marks an error that Agent has already announced through the 'error' event.
+ * `send()` emits and then rethrows, so a caller that also prints from its catch
+ * block renders every failure twice — once with the model name and a recovery
+ * hint, then again bare. Callers should check this before printing.
+ */
+export const REPORTED_ERROR = Symbol.for('scalix.coder.reportedError');
 function transformToolsForApi(tools) {
     return tools
         // type:'mcp' entries are decorative config for user-registered external
@@ -137,6 +145,8 @@ export class Agent extends EventEmitter {
     modelIndex = 0;
     log;
     contextManager;
+    /** The context window the user configured, if any. See syncContextLimit(). */
+    configuredContextTokens;
     toolSelector = null;
     _aborted = false;
     _thinkingActive = false;
@@ -165,12 +175,20 @@ export class Agent extends EventEmitter {
     outputFormatInstructionIndex = null;
     cloudProjectId;
     cloudStatus = { state: 'no-key', toolCount: 0 };
+    providerId;
+    capabilities;
+    streamingToolCallsResolved;
     constructor(config) {
         super();
         this.agentId = config.agentId ?? generateAgentId();
         this.parentAgentId = config.parentAgentId ?? null;
         this.agentDescription = config.agentDescription ?? 'main';
-        this.client = new ScalixClient(config.baseUrl || DEFAULT_BASE_URL, config.apiKey);
+        this.providerId = config.provider ?? 'scalix';
+        this.capabilities = capabilitiesFor(this.providerId);
+        if (this.providerId !== 'scalix' && !config.baseUrl) {
+            throw new Error(`Provider '${this.providerId}' requires an explicit baseUrl — there is no default third-party endpoint.`);
+        }
+        this.client = createChatClient(this.providerId, config.baseUrl || DEFAULT_BASE_URL, config.apiKey);
         this.log = logger.child();
         const resolvedModels = Array.isArray(config.model)
             ? (config.model.length > 0 ? config.model : FALLBACK_MODELS)
@@ -198,6 +216,9 @@ export class Agent extends EventEmitter {
         };
         this.cloudProjectId = config.cloudProjectId ?? process.env.SCALIX_PROJECT ?? undefined;
         this.contextManager = new ContextManager(config.contextManager);
+        // Kept separately because syncContextLimit() overwrites the manager's own
+        // value on every read and would otherwise have nothing to fall back to.
+        this.configuredContextTokens = config.contextManager?.maxContextTokens;
         if (config.dynamicToolSelection) {
             this.toolSelector = new ToolSelector();
             this.toolSelector.index(this.config.tools);
@@ -214,6 +235,7 @@ export class Agent extends EventEmitter {
         setAgentToolConfig({
             apiKey: config.apiKey,
             baseUrl: config.baseUrl,
+            provider: this.providerId,
             models: this.config.models,
             permissionMode: this.config.permissionMode,
             confirmToolCall: this.config.confirmToolCall,
@@ -260,6 +282,39 @@ export class Agent extends EventEmitter {
         this.modelIndex = (startIdx + 1) % this.config.models.length;
         return this.config.models[startIdx % this.config.models.length];
     }
+    /** Provider-scoped max_tokens policy. Scalix: always send, clamped to the
+     *  platform cap (omitting it lets the platform apply a much smaller default
+     *  and truncate the answer mid-sentence). OpenAI-compatible BYOK: send only a
+     *  user/API-registered ceiling — generic endpoints reject values above the
+     *  target model's real limit. */
+    maxTokensField(model) {
+        if (this.capabilities.maxTokensPolicy === 'clamped') {
+            return { max_tokens: maxOutputTokensForRequest(model) };
+        }
+        return hasExplicitModelSpec(model)
+            ? { max_tokens: getModelSpec(model).maxOutputTokens }
+            : {};
+    }
+    /**
+     * Whether an agentic turn can stream against this endpoint. BYOK endpoints
+     * speak the OpenAI wire and always stream tool-call deltas, so the static
+     * capability answers for them. The Scalix path is a version question, not a
+     * provider one: routers that predate streamed tool calls drop `tools` on the
+     * stream and answer in prose, and a published CLI does not choose which
+     * deployment it is pointed at. There is no version header on the inference
+     * path, so it asks /models, which advertises what the deployment can do.
+     * Resolved once per session; an unreachable or older endpoint answers "no"
+     * and the turn goes non-streaming, exactly as before.
+     */
+    async streamsToolCalls() {
+        if (this.capabilities.streamingToolCalls)
+            return true;
+        if (this.streamingToolCallsResolved === undefined) {
+            const caps = await this.client.endpointCapabilities();
+            this.streamingToolCallsResolved = caps.streaming_tool_calls === true;
+        }
+        return this.streamingToolCallsResolved;
+    }
     shouldFallbackToNext(err) {
         const e = err;
         const message = (e?.message || e?.error?.message || '').toLowerCase();
@@ -328,6 +383,14 @@ export class Agent extends EventEmitter {
     setInstructions(instructions) { this.config.instructions = instructions; }
     getPermissionMode() { return this.config.permissionMode; }
     setPermissionMode(mode) { this.config.permissionMode = mode; }
+    getProvider() { return this.providerId; }
+    /**
+     * Whether this session's inference endpoint is the Scalix gateway, and so
+     * can answer /v1/me and serve the account's platform-tool catalog. Callers
+     * must check this before probing those endpoints: on BYOK the base URL is a
+     * third-party host that has no such routes.
+     */
+    supportsPlatformTools() { return this.capabilities.platformTools; }
     getThinking() { return this.config.thinkingMode; }
     setThinking(mode) { this.config.thinkingMode = mode; }
     async compact() {
@@ -345,6 +408,7 @@ export class Agent extends EventEmitter {
             const result = await this.client.chatComplete({
                 model,
                 messages: apiMessages,
+                ...this.maxTokensField(model),
                 stream: false,
             }, this._abortController?.signal);
             const summary = result.choices?.[0]?.message?.content?.trim() || '';
@@ -368,8 +432,64 @@ export class Agent extends EventEmitter {
             return `Compaction failed: ${err.message}`;
         }
     }
+    /**
+     * Point the context manager at the active model's real input budget. The
+     * manager starts on a generic 1M default, so until this runs every reader —
+     * /status, /context, the editor's context ring — quotes a window the model
+     * does not have. It used to run only inside the send loop, which meant a
+     * fresh session reported 1M until the first reply landed.
+     *
+     * Precedence: a registered spec (user-defined or fetched from the endpoint)
+     * is per-model truth and wins. Without one, getModelSpec() hands back a
+     * generic 200K/64K guess — and a guess must not overwrite a window the user
+     * typed into the setup wizard. It did, which is why a BYOK 8K local model was
+     * still being treated as a 134K one: nothing compressed until the endpoint
+     * itself started rejecting the oversized request. The untouched 1M default
+     * isn't a choice, so it stays out of the way of the guess.
+     */
+    syncContextLimit(model = this.config.models[this.modelIndex % this.config.models.length]) {
+        const configured = this.configuredContextTokens;
+        const userChoseLimit = configured != null
+            && configured > 0
+            && configured !== CONTEXT_DEFAULTS.maxContextTokens;
+        if (userChoseLimit && !hasExplicitModelSpec(model)) {
+            this.contextManager.setMaxContextTokens(configured);
+            return;
+        }
+        const spec = getModelSpec(model);
+        const inputBudget = spec.contextWindow - spec.maxOutputTokens;
+        if (inputBudget > 0)
+            this.contextManager.setMaxContextTokens(inputBudget);
+    }
     getContextUsage() {
-        return this.contextManager.getTokenUsage(this.messages);
+        this.syncContextLimit();
+        const usage = this.contextManager.getTokenUsage(this.messages);
+        // messagesToApi() prepends the instructions at request time, so the system
+        // prompt is never in this.messages — but it is sent on every request and
+        // occupies the window like anything else. Counting it keeps /context,
+        // /status and the editor's context ring honest instead of quietly low.
+        const tokens = usage.tokens + estimateTokens(this.config.instructions || '');
+        return {
+            tokens,
+            maxTokens: usage.maxTokens,
+            percentage: Math.round((tokens / usage.maxTokens) * 100),
+        };
+    }
+    /**
+     * Per-role token split of the current context. estimateMessageTokens() is
+     * additive per message, so grouping by role and summing the groups gives
+     * exactly getContextUsage().tokens — these are measured, not apportioned.
+     */
+    getContextBreakdown() {
+        const bucket = { system: [], user: [], assistant: [], tool: [] };
+        for (const m of this.messages)
+            bucket[m.role]?.push(m);
+        return {
+            system: estimateTokens(this.config.instructions || '') + estimateTokenCount(bucket.system),
+            user: estimateTokenCount(bucket.user),
+            assistant: estimateTokenCount(bucket.assistant),
+            tools: estimateTokenCount(bucket.tool),
+        };
     }
     async autoCompress(reqLog) {
         if (!this.contextManager.shouldCompress(this.messages)) {
@@ -400,6 +520,7 @@ export class Agent extends EventEmitter {
                     { role: 'system', content: 'You compress conversation history. Preserve every file path, function name, error message, code change, command, config value, and user instruction verbatim. Omit greetings and filler only. This output replaces the original — anything omitted is permanently lost.' },
                     { role: 'user', content: prompt },
                 ],
+                ...this.maxTokensField(model),
                 stream: false,
             }, this._abortController?.signal);
             const summary = result.choices?.[0]?.message?.content?.trim() || '';
@@ -462,6 +583,13 @@ export class Agent extends EventEmitter {
      * status carries the real error for a single honest notice; no retries.
      */
     async refreshCloudTools() {
+        // Platform tools live on the Scalix gateway (/v1/me, /api/v1/mcp). Never
+        // probe a BYOK third-party endpoint for them.
+        if (!this.capabilities.platformTools) {
+            this.config.tools = this.config.tools.filter((t) => !this.isCloudTool(t));
+            this.cloudStatus = { state: 'no-key', toolCount: 0 };
+            return { ...this.cloudStatus };
+        }
         if (!this.config.apiKey) {
             this.config.tools = this.config.tools.filter((t) => !this.isCloudTool(t));
             this.cloudStatus = { state: 'no-key', toolCount: 0 };
@@ -731,13 +859,24 @@ export class Agent extends EventEmitter {
         catch (err) {
             this.deregisterFromRegistry('failed');
             const error = err instanceof Error ? err : new Error(String(err));
+            const status = err.status ?? err.statusCode;
+            // 401 is an onboarding problem, not a request problem — point at the fix.
+            // Which fix depends on whose key was rejected: on BYOK the request went to
+            // the user's own endpoint, so sending them to the Scalix console to mint a
+            // platform key is a dead end that doesn't touch the credential that failed.
+            if (status === 401 && !error.message.includes('console.scalix.world') && !error.message.includes('/setup')) {
+                error.message += this.capabilities.platformTools
+                    ? ' — API key rejected. Create a new key at https://console.scalix.world/org/keys and update it via /setup.'
+                    : ` — API key rejected by ${this.client.baseURL}. Check the key for your provider and update it via /setup.`;
+            }
             error.metadata = {
                 model: this.config.models[this.modelIndex % this.config.models.length],
-                status: err.status ?? err.statusCode,
+                status,
                 error: err.error,
                 requestId,
             };
             reqLog.error('Agent send failed', { error: error.message });
+            error[REPORTED_ERROR] = true;
             this.emit('error', error);
             throw error;
         }
@@ -750,6 +889,7 @@ export class Agent extends EventEmitter {
         let turnCount = 0;
         let retryAttempt = 0;
         let emptyTurnCount = 0;
+        const MAX_EMPTY_TURNS = 5;
         let disableTools = false;
         let forceNonStreaming = false;
         while (turnCount < this.config.maxSteps) {
@@ -764,13 +904,16 @@ export class Agent extends EventEmitter {
             const toolCalls = new Map();
             try {
                 // Sync context limit to the current model's actual context window
-                const modelSpec = getModelSpec(currentModel);
-                const inputBudget = modelSpec.contextWindow - modelSpec.maxOutputTokens;
-                if (inputBudget > 0) {
-                    this.contextManager.setMaxContextTokens(inputBudget);
-                }
+                this.syncContextLimit(currentModel);
                 await this.autoCompress(reqLog);
-                this.emit('context:usage', this.contextManager.getTokenUsage(this.messages));
+                // getContextUsage(), not contextManager.getTokenUsage(): the former adds
+                // the system prompt, and a listener that renders both this event and a
+                // getContextInfo() response must not see two different totals.
+                this.emit('context:usage', {
+                    ...this.getContextUsage(),
+                    messageCount: this.messages.length,
+                    breakdown: this.getContextBreakdown(),
+                });
                 let toolsForRequest = this.config.tools;
                 if (this.toolSelector) {
                     const lastUserMsg = [...this.messages].reverse().find((m) => m.role === 'user');
@@ -807,13 +950,20 @@ export class Agent extends EventEmitter {
                 const apiMessages = messagesToApi(this.messages, effectiveInstructions, vision);
                 const thinkingLevel = this.config.thinkingMode !== 'off' ? this.config.thinkingMode : undefined;
                 const hasToolMessages = this.messages.some(m => m.role === 'tool' || (m.role === 'assistant' && m.tool_calls && m.tool_calls.length > 0));
-                const useStreaming = !hasToolMessages && !forceNonStreaming;
+                // An endpoint that does not carry tool calls over SSE would answer an
+                // agentic turn in prose and lose the calls, so those turns go
+                // non-streaming there and the user watches a spinner instead of output.
+                // Text-only turns stream either way.
+                const useStreaming = !forceNonStreaming && (await this.streamsToolCalls()
+                    ? true
+                    : (!apiTools || apiTools.length === 0) && !hasToolMessages);
                 if (useStreaming) {
                     const stream = await this.client.chatComplete({
                         model: currentModel,
                         messages: apiMessages,
                         tools: apiTools && apiTools.length > 0 ? apiTools : undefined,
                         temperature: 0.7,
+                        ...this.maxTokensField(currentModel),
                         stream: true,
                         ...(thinkingLevel && { thinking_level: thinkingLevel }),
                     }, this._abortController.signal);
@@ -869,6 +1019,7 @@ export class Agent extends EventEmitter {
                         messages: apiMessages,
                         tools: apiTools && apiTools.length > 0 ? apiTools : undefined,
                         temperature: 0.7,
+                        ...this.maxTokensField(currentModel),
                         stream: false,
                         ...(thinkingLevel && { thinking_level: thinkingLevel }),
                     }, this._abortController.signal);
@@ -928,10 +1079,21 @@ export class Agent extends EventEmitter {
                         disableTools = true;
                         reqLog.warn('Disabling tools due to repeated empty turns — model may not support function calling');
                     }
-                    if (emptyTurnCount >= 5) {
+                    if (emptyTurnCount >= MAX_EMPTY_TURNS) {
                         reqLog.error('Too many empty turns, aborting');
                         return '[no response]';
                     }
+                    // Re-asking used to be entirely silent: from the TUI this is several
+                    // seconds of spinner followed, on the last attempt, by nothing at
+                    // all. Reuse the retry event so the transcript says what happened.
+                    // Emitted after the bail check, so the count only ever describes
+                    // retries that actually happen.
+                    this.emit('retry', {
+                        attempt: emptyTurnCount,
+                        maxAttempts: MAX_EMPTY_TURNS - 1,
+                        delayMs: 0,
+                        reason: 'Model returned an empty response',
+                    });
                     continue;
                 }
                 emptyTurnCount = 0;
@@ -1063,6 +1225,26 @@ export class Agent extends EventEmitter {
                                 const args = tool?.source === 'scalix-cloud'
                                     ? parsedArgs
                                     : normalizeArgs(parsedArgs);
+                                // Validate against the very schema the model was shown. Nothing
+                                // checked this before, so a hallucinated parameter name reached
+                                // the tool body and came back as a Node internals message —
+                                // read_file called with {path} instead of {filePath} answered
+                                // 'The "paths[1]" argument must be of type string. Received
+                                // undefined', which tells the model nothing it can act on. Args
+                                // are passed through unchanged on success rather than swapped
+                                // for the parsed copy, since z.object() strips unknown keys and
+                                // some tools read fields their schema doesn't declare.
+                                const schema = tool?.function?.inputSchema ?? tool?.inputSchema;
+                                if (schema && typeof schema.safeParse === 'function') {
+                                    const check = schema.safeParse(args);
+                                    if (!check.success) {
+                                        const issues = (check.error?.issues ?? [])
+                                            .slice(0, 4)
+                                            .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+                                            .join('; ');
+                                        throw new Error(`Invalid arguments for ${call.name} — ${issues || 'schema validation failed'}`);
+                                    }
+                                }
                                 reqLog.debug('Executing tool', { tool: call.name });
                                 const toolTimeout = (typeof args?.timeout === 'number' && args.timeout > 0)
                                     ? Math.min(args.timeout, TOOL_DEFAULTS.maxCommandTimeoutMs)
@@ -1236,11 +1418,21 @@ export class Agent extends EventEmitter {
                 if (this.shouldFallbackToNext(err) && retryAttempt < this.config.maxRetries && turnCount < this.config.maxSteps) {
                     retryAttempt++;
                     forceNonStreaming = false;
-                    const delay = backoffDelay(retryAttempt);
+                    // Honor the server's Retry-After on 429/503 (capped at 60s) instead
+                    // of a blind exponential guess; fall back to backoff otherwise.
+                    const serverWait = err instanceof ApiError ? err.retryAfterMs : undefined;
+                    const delay = serverWait !== undefined ? Math.min(serverWait, 60_000) : backoffDelay(retryAttempt);
                     reqLog.warn(`Retrying after ${Math.round(delay)}ms (attempt ${retryAttempt}/${this.config.maxRetries})`, {
                         model: currentModel,
                         error: err.message,
                     });
+                    this.emit('retry', {
+                        attempt: retryAttempt,
+                        maxAttempts: this.config.maxRetries,
+                        delayMs: Math.round(delay),
+                        status: err instanceof ApiError ? err.status : undefined,
+                        reason: err.message,
+                    });
                     await sleep(delay);
                     currentModel = this.pickModel();
                     continue;