scalix 1.4.1 → 1.5.1

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, SCALIX_PLATFORM_SECTION, SCALIX_CLOUD_RESOURCES_SECTION, SCALIX_NEUTRAL_POINTER, SCALIX_STEERING_ALWAYS_ON, 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';
@@ -19,7 +19,15 @@ import { extractCodeClaims, checkGrounding, formatGroundingNudge, GROUNDING_DEFA
 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 { fetchCloudTools, callCloudTool, fetchMe, filterCatalogByScopes, buildCloudToolsPromptSection, cloudKeyRemedy } 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,30 @@ export class Agent extends EventEmitter {
     outputFormatInstructionIndex = null;
     cloudProjectId;
     cloudStatus = { state: 'no-key', toolCount: 0 };
+    providerId;
+    capabilities;
+    cloudApiKey;
+    cloudBaseUrl;
+    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);
+        // Cloud tools follow their own credential pair. On the Scalix gateway the
+        // inference creds double as the cloud creds; on BYOK `config.baseUrl` is a
+        // third-party host with no /v1/me, so the cloud URL falls back to the
+        // Scalix default rather than inheriting it.
+        this.cloudApiKey = config.cloudApiKey?.trim()
+            || (this.capabilities.platformTools ? config.apiKey : '');
+        this.cloudBaseUrl = config.cloudBaseUrl?.trim()
+            || (this.capabilities.platformTools ? (config.baseUrl || DEFAULT_BASE_URL) : DEFAULT_BASE_URL);
         this.log = logger.child();
         const resolvedModels = Array.isArray(config.model)
             ? (config.model.length > 0 ? config.model : FALLBACK_MODELS)
@@ -198,6 +226,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 +245,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,
@@ -246,7 +278,16 @@ export class Agent extends EventEmitter {
             this.retrievalConfig = { ...RETRIEVAL_DEFAULTS, ...config.contextRetrieval };
         }
     }
-    pickModel() {
+    /**
+     * `fresh` — a NEW user turn: always start from the front of the list (the
+     * user's chosen model). The idx+1 bookkeeping below exists so RETRIES
+     * advance to the next model in the chain; without the fresh reset it also
+     * rotated the STARTING model, so with a failover chain configured,
+     * consecutive sends silently alternated models — a switch never "stuck".
+     */
+    pickModel(fresh = false) {
+        if (fresh)
+            this.modelIndex = 0;
         const startIdx = this.modelIndex;
         for (let i = 0; i < this.config.models.length; i++) {
             const idx = (startIdx + i) % this.config.models.length;
@@ -260,6 +301,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 +402,20 @@ 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 can reach a Scalix gateway that answers /v1/me and
+     * serves the account's platform-tool catalog. True when inference runs on
+     * the gateway, or when BYOK inference is paired with a separate Scalix Cloud
+     * key. False means no endpoint to probe — never probe the BYOK base URL.
+     */
+    supportsPlatformTools() { return this.cloudApiKey.length > 0; }
+    /** The Scalix Cloud endpoint platform tools talk to — the gateway, not the
+     *  inference base URL, which under BYOK is a third-party host. */
+    getCloudBaseUrl() { return this.cloudBaseUrl; }
+    /** The key platform tools authenticate with — equal to the inference key on
+     *  the 'scalix' provider, separate under BYOK, empty if unconfigured. */
+    getCloudApiKey() { return this.cloudApiKey; }
     getThinking() { return this.config.thinkingMode; }
     setThinking(mode) { this.config.thinkingMode = mode; }
     async compact() {
@@ -345,6 +433,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 +457,68 @@ 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.
+     */
+    // Default to models[0] — the model a fresh send will use. modelIndex points
+    // one PAST the last pick (retry bookkeeping), so dereferencing it here made
+    // idle-time context reads use the NEXT chain entry's budget, not the
+    // active model's.
+    syncContextLimit(model = this.config.models[0]) {
+        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 +549,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() || '';
@@ -438,8 +588,8 @@ export class Agent extends EventEmitter {
      *  Schema is passed to the model as-is via `parameters` (NOT `inputSchema`,
      *  which transformToolsForApi would run through the Zod converter). */
     makeCloudTool(ct) {
-        const baseUrl = this.client.baseURL;
-        const apiKey = this.config.apiKey;
+        const baseUrl = this.cloudBaseUrl;
+        const apiKey = this.cloudApiKey;
         const projectId = this.cloudProjectId;
         return {
             source: 'scalix-cloud',
@@ -460,19 +610,41 @@ export class Agent extends EventEmitter {
      * (/cloud refresh). On failure the previously registered cloud tools are
      * removed and the agent keeps running with local tools only — the returned
      * status carries the real error for a single honest notice; no retries.
+     *
+     * `identity`: pass a CloudIdentity to scope-filter the catalog without a
+     * second /v1/me round-trip (the TUI already fetched one); pass `null` when
+     * /v1/me was tried and failed so no doomed re-fetch happens; omit entirely
+     * (headless, IPC) and the identity is fetched best-effort here — on any
+     * /v1/me failure the catalog registers unfiltered, exactly as before.
      */
-    async refreshCloudTools() {
-        if (!this.config.apiKey) {
+    async refreshCloudTools(identity) {
+        // Platform tools live on the Scalix gateway (/v1/me, /api/v1/mcp), which
+        // is `cloudBaseUrl` — never the BYOK inference endpoint. No cloud key
+        // means nothing to fetch: on 'scalix' the user has no key at all, on BYOK
+        // they have not opted into pairing a Scalix Cloud key with their provider.
+        if (!this.cloudApiKey) {
             this.config.tools = this.config.tools.filter((t) => !this.isCloudTool(t));
             this.cloudStatus = { state: 'no-key', toolCount: 0 };
             return { ...this.cloudStatus };
         }
         try {
-            const catalog = await fetchCloudTools(this.client.baseURL, this.config.apiKey, this.cloudProjectId);
+            const catalog = await fetchCloudTools(this.cloudBaseUrl, this.cloudApiKey, this.cloudProjectId);
+            let me = identity;
+            if (me === undefined) {
+                try {
+                    me = await fetchMe(this.cloudBaseUrl, this.cloudApiKey);
+                }
+                catch {
+                    me = null;
+                }
+            }
+            const visible = me
+                ? filterCatalogByScopes(catalog.tools, me.permissions.scopes)
+                : catalog.tools;
             this.config.tools = this.config.tools.filter((t) => !this.isCloudTool(t));
             const localNames = new Set(this.config.tools.map((t) => t.function?.name || t.name).filter(Boolean));
             let registered = 0;
-            for (const ct of catalog.tools) {
+            for (const ct of visible) {
                 if (localNames.has(ct.name)) {
                     this.log.warn('Cloud tool name collides with a local tool — keeping the local tool', { tool: ct.name });
                     continue;
@@ -485,14 +657,26 @@ export class Agent extends EventEmitter {
             this.cloudStatus = {
                 state: 'connected',
                 toolCount: registered,
+                totalCount: catalog.tools.length,
                 platformAvailable: catalog.platformAvailable,
             };
+            // The platform binds MCP calls to the KEY's project; a configured
+            // project id cannot redirect them. Say so instead of silently differing.
+            const keyProject = me?.identity.projectId;
+            if (keyProject && this.cloudProjectId && keyProject !== this.cloudProjectId) {
+                this.cloudStatus.note = `API key is bound to project ${keyProject}; configured project ${this.cloudProjectId} is ignored for platform tools (the key's binding wins).`;
+            }
         }
         catch (err) {
             this.config.tools = this.config.tools.filter((t) => !this.isCloudTool(t));
             if (this.toolSelector)
                 this.toolSelector.index(this.config.tools);
-            this.cloudStatus = { state: 'unavailable', toolCount: 0, error: err?.message || String(err) };
+            this.cloudStatus = {
+                state: 'unavailable',
+                toolCount: 0,
+                error: err?.message || String(err),
+                remedy: cloudKeyRemedy(err),
+            };
             this.log.warn('Scalix Cloud tool catalog unavailable', { error: this.cloudStatus.error });
         }
         return { ...this.cloudStatus };
@@ -510,12 +694,39 @@ export class Agent extends EventEmitter {
         if (!this.config.models.includes(model))
             this.config.models.push(model);
     }
-    setModel(model) { this.config.models = [model]; }
+    setModel(model) {
+        // Mutate IN PLACE, never reassign: setAgentToolConfig captured this array
+        // by reference at construction, so a reassignment left sub-agents on the
+        // pre-switch model list forever. And keep the failover chain — replacing
+        // the whole list with [model] permanently destroyed a configured
+        // multi-model chain; the switched-to model just moves to the front.
+        const rest = this.config.models.filter((m) => m !== model);
+        this.config.models.splice(0, this.config.models.length, model, ...rest);
+        this.modelIndex = 0;
+        // A deliberate switch is a vote of confidence: clear this model's breaker
+        // so the next request actually tries it, and resize the context budget
+        // now instead of at the next lazy resync.
+        this.modelFailures.delete(model);
+        this.syncContextLimit(model);
+    }
     getModels() { return [...this.config.models]; }
+    /** Live-apply a limit. Returns true when the running agent honors the new
+     *  value immediately, false when it only takes effect on the next launch —
+     *  callers used to report "updated" unconditionally, which was a lie for
+     *  every key that lives outside AgentConfig (web/git/search timeouts, …). */
     updateLimit(key, value) {
+        // Context keys live nested under config.contextManager and on the live
+        // ContextManager, not as top-level AgentConfig fields.
+        if (key === 'maxContextTokens') {
+            this.configuredContextTokens = value;
+            this.contextManager.setMaxContextTokens(value);
+            return true;
+        }
         if (key in this.config) {
             this.config[key] = value;
+            return true;
         }
+        return false;
     }
     getReplay() { return this.replay; }
     getChangeTracker() { return this.changeTracker; }
@@ -719,7 +930,7 @@ export class Agent extends EventEmitter {
         reqLog.info('User message received', { length: content.length });
         this.registerInRegistry();
         try {
-            const initialModel = this.pickModel();
+            const initialModel = this.pickModel(true);
             reqLog.info('Starting agent loop', { model: initialModel, agentId: this.agentId });
             let result = await this.loopStreamingTurns(initialModel, reqLog);
             if (this.outputFormat !== 'text') {
@@ -731,13 +942,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 +972,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 +987,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');
@@ -803,17 +1029,42 @@ export class Agent extends EventEmitter {
                         }
                     }
                 }
+                // Scalix steering + live cloud-tools awareness, assembled here — the
+                // one point every frontend (TUI, headless, IPC) funnels through —
+                // and rebuilt per request so a /cloud refresh shows up on the next
+                // turn. Coder is a generic tool: the product steering only appears
+                // while a Scalix Cloud connection is live; on the Scalix provider
+                // without one a single neutral pointer; on pure BYOK nothing at all.
+                if (this.cloudStatus.state === 'connected') {
+                    if (!SCALIX_STEERING_ALWAYS_ON) {
+                        effectiveInstructions += '\n\n' + SCALIX_PLATFORM_SECTION + '\n\n' + SCALIX_CLOUD_RESOURCES_SECTION;
+                    }
+                    const liveCloudTools = this.getCloudTools();
+                    if (liveCloudTools.length > 0) {
+                        effectiveInstructions += '\n\n' + buildCloudToolsPromptSection(liveCloudTools);
+                    }
+                }
+                else if (!SCALIX_STEERING_ALWAYS_ON && this.providerId === 'scalix') {
+                    effectiveInstructions += '\n\n' + SCALIX_NEUTRAL_POINTER;
+                }
                 const vision = modelSupportsVision(currentModel);
                 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 +1120,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 +1180,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 +1326,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 +1519,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;