scalix 1.5.0 → 1.5.2

package/dist/agent.js

@@ -1,17 +1,19 @@
 import { ApiError } from './api-client.js';
 import { EventEmitter } from 'eventemitter3';
 import { randomUUID } from 'node:crypto';
-import { getToolPermissionWithArgs } from './sandbox.js';
+import { getToolPermissionWithArgs, getMaxImageSize } 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, CONTEXT_DEFAULTS, modelSupportsVision, getModelSpec, maxOutputTokensForRequest, hasExplicitModelSpec } from './constants.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_DEPLOY_PLAYBOOK_SECTION, SCALIX_PLATFORM_PLAYBOOK_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';
 import { AgentReplay } from './agent-replay.js';
 import { loadHooks, runHooks } from './hooks.js';
+import { isWorkspaceTrusted } from './workspace-trust.js';
 import { setAgentToolConfig } from './tools-advanced.js';
 import { AgentRegistry, generateAgentId } from './agent-registry.js';
+import { getPreset } from './agent-presets.js';
 import { runVerification, VERIFY_DEFAULTS } from './auto-verify.js';
 import { ChangeTracker } from './change-tracker.js';
 import { detectPromptInjection, formatInjectionWarning } from './injection-detector.js';
@@ -19,8 +21,28 @@ 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';
+import { McpHub } from './mcp.js';
+import { BoardTurnRefresher } from './board-context.js';
+const SUPPORTED_PASTED_IMAGE_MIMES = new Set([
+    'image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/bmp', 'image/svg+xml',
+]);
+export function validatePastedImages(images) {
+    const maxSize = getMaxImageSize();
+    for (const image of images) {
+        const match = /^data:(image\/[a-z0-9.+-]+);base64,([a-z0-9+/=\s]+)$/i.exec(image);
+        if (!match || !SUPPORTED_PASTED_IMAGE_MIMES.has(match[1].toLowerCase())) {
+            throw new Error('Unsupported pasted image. Use PNG, JPEG, GIF, WebP, BMP, or SVG.');
+        }
+        const payload = match[2].replace(/\s/g, '');
+        const bytes = Math.floor(payload.length * 3 / 4)
+            - (payload.endsWith('==') ? 2 : payload.endsWith('=') ? 1 : 0);
+        if (bytes > maxSize) {
+            throw new Error(`Pasted image is too large (${Math.ceil(bytes / 1024 / 1024)}MB). Maximum is ${Math.floor(maxSize / 1024 / 1024)}MB.`);
+        }
+    }
+}
 /**
  * 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
@@ -30,11 +52,10 @@ import { createChatClient, capabilitiesFor } from './providers/index.js';
 export const REPORTED_ERROR = Symbol.for('scalix.coder.reportedError');
 function transformToolsForApi(tools) {
     return tools
-        // type:'mcp' entries are decorative config for user-registered external
-        // MCP servers and never reach the API. Scalix Cloud platform tools bypass
-        // this path entirely: they are plain function tools (CloudPlatformTool,
-        // registered by refreshCloudTools) whose `parameters` pass through as-is.
-        .filter((t) => !('type' in t && t.type === 'mcp'))
+        // Everything here is a function tool. Remotely-backed ones — Scalix Cloud
+        // platform tools and MCP tool proxies — carry a ready-made JSON Schema in
+        // `parameters` that passes through as-is; local tools carry a Zod
+        // `inputSchema` that gets converted below.
         .map((t) => {
         const local = t;
         const fn = local.function ?? local;
@@ -151,7 +172,10 @@ export class Agent extends EventEmitter {
     _aborted = false;
     _thinkingActive = false;
     replay;
+    boardRefresher;
+    boardPrimed;
     hooks = [];
+    hooksSkipped = 0;
     instructionLoader;
     _abortController = null;
     modelFailures = new Map();
@@ -175,8 +199,11 @@ export class Agent extends EventEmitter {
     outputFormatInstructionIndex = null;
     cloudProjectId;
     cloudStatus = { state: 'no-key', toolCount: 0 };
+    mcpHub = null;
     providerId;
     capabilities;
+    cloudApiKey;
+    cloudBaseUrl;
     streamingToolCallsResolved;
     constructor(config) {
         super();
@@ -189,6 +216,14 @@ export class Agent extends EventEmitter {
             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)
@@ -223,8 +258,28 @@ export class Agent extends EventEmitter {
             this.toolSelector = new ToolSelector();
             this.toolSelector.index(this.config.tools);
         }
+        // Crew board freshness (board-context.ts): baseline taken here, right
+        // after the system prompt embedded the board, so the first turnNote()
+        // only fires on real change. Fire-and-forget; send() awaits it.
+        this.boardRefresher = new BoardTurnRefresher(this.config.workspaceRoot ?? process.cwd());
+        this.boardPrimed = this.boardRefresher.prime().catch(() => { });
         this.replay = new AgentReplay(randomUUID().slice(0, 8), this.config.models[0]);
-        this.hooks = loadHooks();
+        // Hooks are shell commands read out of the project's own .scalix/hooks.json
+        // — exec surface, exactly like plugins and scoped rules, and named as such
+        // in workspace-trust.ts's own docstring. The gate existed; this call site
+        // just never asked. Parsing the file while untrusted is still fine and is
+        // what lets us say "3 hooks were skipped" instead of going quietly inert.
+        const projectHooks = loadHooks();
+        if (isWorkspaceTrusted()) {
+            this.hooks = projectHooks;
+        }
+        else {
+            this.hooks = [];
+            this.hooksSkipped = projectHooks.length;
+            if (projectHooks.length > 0) {
+                this.log.warn('Project hooks skipped — untrusted workspace', { count: projectHooks.length });
+            }
+        }
         this.instructionLoader = config.instructionLoader;
         if (config.autoVerify === true) {
             this.verifyConfig = { ...VERIFY_DEFAULTS };
@@ -268,7 +323,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;
@@ -335,6 +399,16 @@ export class Agent extends EventEmitter {
             message.includes('stream error') ||
             message.includes('try again'));
     }
+    setPreset(presetId) {
+        const preset = getPreset(presetId);
+        if (!preset)
+            throw new Error(`Unknown preset: ${presetId}`);
+        this.config.permissionMode = preset.permissionMode;
+        // We append the prompt to the base instructions
+        if (preset.systemPromptAdditions && !this.config.instructions.includes(preset.systemPromptAdditions)) {
+            this.config.instructions += '\n\n' + preset.systemPromptAdditions;
+        }
+    }
     isModelCircuitOpen(model) {
         const state = this.modelFailures.get(model);
         if (!state)
@@ -385,12 +459,18 @@ export class Agent extends EventEmitter {
     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.
+     * 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.capabilities.platformTools; }
+    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() {
@@ -447,7 +527,11 @@ export class Agent extends EventEmitter {
      * 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]) {
+    // 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
@@ -551,6 +635,64 @@ export class Agent extends EventEmitter {
         if (this.toolSelector)
             this.toolSelector.index(this.config.tools);
     }
+    // ─── MCP servers ───
+    isMcpTool(t) {
+        return 'source' in t && t.source === 'mcp';
+    }
+    /**
+     * Take ownership of a connected hub and register its tools. The entrypoint
+     * connects (so a slow server delays startup, not the first message) and hands
+     * the hub over; the agent needs it so `add_mcp_server` can connect at runtime
+     * and so `close()` can shut the child processes down.
+     */
+    attachMcpHub(hub) {
+        this.mcpHub = hub;
+        this.syncMcpTools();
+    }
+    /** Replace the registered MCP proxies with whatever the hub currently holds. */
+    syncMcpTools() {
+        this.config.tools = this.config.tools.filter((t) => !this.isMcpTool(t));
+        if (this.mcpHub) {
+            const taken = new Set(this.config.tools.map((t) => t.function?.name || t.name).filter(Boolean));
+            for (const t of this.mcpHub.tools()) {
+                // A namespaced mcp__ name colliding with a local tool means two servers
+                // share a label; keep the first and say so rather than shadowing.
+                if (taken.has(t.name)) {
+                    this.log.warn('MCP tool name already taken — skipping', { tool: t.name, server: t.serverLabel });
+                    continue;
+                }
+                taken.add(t.name);
+                this.config.tools.push(t);
+            }
+        }
+        if (this.toolSelector)
+            this.toolSelector.index(this.config.tools);
+    }
+    /**
+     * Connect one server and register its tools immediately. Creates the hub if
+     * the entrypoint never attached one, so a runtime `add_mcp_server` works even
+     * when no config file existed at startup.
+     */
+    async connectMcpServer(config) {
+        if (!this.mcpHub)
+            this.mcpHub = new McpHub();
+        const [status] = await this.mcpHub.connect([config]);
+        this.syncMcpTools();
+        return status;
+    }
+    getMcpStatus() {
+        return this.mcpHub?.status() ?? [];
+    }
+    getMcpTools() {
+        return this.config.tools.filter((t) => this.isMcpTool(t));
+    }
+    /** Disconnect every MCP server. Call on shutdown — stdio servers are children. */
+    async closeMcp() {
+        const hub = this.mcpHub;
+        this.mcpHub = null;
+        this.config.tools = this.config.tools.filter((t) => !this.isMcpTool(t));
+        await hub?.close();
+    }
     // ─── Scalix Cloud platform tools ───
     isCloudTool(t) {
         return 'source' in t && t.source === 'scalix-cloud';
@@ -559,8 +701,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',
@@ -581,26 +723,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() {
-        // 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) {
+    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;
@@ -613,14 +770,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 };
@@ -638,16 +807,57 @@ 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; }
     getHooks() { return this.hooks; }
+    /** How many project hooks the trust gate withheld. 0 when trusted. */
+    getSkippedHookCount() { return this.hooksSkipped; }
+    /**
+     * Re-read project hooks after the user trusts the workspace, so /trust picks
+     * them up in the same session rather than only after a restart. Returns the
+     * number now active.
+     */
+    reloadHooks() {
+        if (!isWorkspaceTrusted())
+            return 0;
+        this.hooks = loadHooks();
+        this.hooksSkipped = 0;
+        return this.hooks.length;
+    }
     getApiKey() { return this.config.apiKey; }
     getBaseUrl() { return this.client.baseURL; }
     getAgentId() { return this.agentId; }
@@ -820,6 +1030,8 @@ export class Agent extends EventEmitter {
     async send(content, images) {
         this._aborted = false;
         this.groundingNudgeCount = 0;
+        if (images?.length)
+            validatePastedImages(images);
         const hasFileRefs = /@(?:[\w./-]+\/)?[\w.-]+\.\w+/.test(content);
         const expandedContent = hasFileRefs ? await this.expandFileReferences(content) : content;
         let finalContent = expandedContent;
@@ -842,12 +1054,30 @@ export class Agent extends EventEmitter {
         this.emit('thinking:start');
         this.truncateMessages();
         this.replay.record('user_message', { content });
+        // Crew board turn-refresh: the system prompt is assembled once per
+        // session, so a board that moved since then would go stale mid-thread.
+        // Runs AFTER the push — send()'s synchronous contract (user message in
+        // history and message:user emitted before the first await) is what the
+        // IDE paints on — with the note spliced in BEFORE the user message, so
+        // the member still reads the news before the ask. One file read per
+        // turn; a workspace with no BOARD.md never produces a note.
+        try {
+            await this.boardPrimed;
+            const boardNote = await this.boardRefresher.turnNote();
+            if (boardNote) {
+                const boardMessage = { role: 'system', content: boardNote };
+                const idx = this.messages.lastIndexOf(userMessage);
+                this.messages.splice(idx < 0 ? this.messages.length : idx, 0, boardMessage);
+                this.replay.record('board_refresh', { chars: boardNote.length });
+            }
+        }
+        catch { }
         const requestId = randomUUID().slice(0, 8);
         const reqLog = logger.child(requestId);
         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') {
@@ -866,7 +1096,7 @@ export class Agent extends EventEmitter {
             // 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. Create a new key at https://console.scalix.world/org/keys?utm_source=scalix-coder&utm_medium=cli 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 = {
@@ -891,6 +1121,13 @@ export class Agent extends EventEmitter {
         let emptyTurnCount = 0;
         const MAX_EMPTY_TURNS = 5;
         let disableTools = false;
+        let _stepIndex = 0;
+        let _turnToolDurationMs = 0;
+        let _turnLlmStartMs = 0;
+        let _turnTtftMs = 0;
+        let _firstDeltaSeen = false;
+        let _turnInputTokens = 0;
+        let _turnOutputTokens = 0;
         let forceNonStreaming = false;
         while (turnCount < this.config.maxSteps) {
             if (this._aborted) {
@@ -946,6 +1183,27 @@ 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;
+                    }
+                    // Deploy-path and platform facts ride with the connection too —
+                    // outside the ALWAYS_ON guard so flipping that flag never drops them.
+                    effectiveInstructions += '\n\n' + SCALIX_DEPLOY_PLAYBOOK_SECTION + '\n\n' + SCALIX_PLATFORM_PLAYBOOK_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;
@@ -958,6 +1216,7 @@ export class Agent extends EventEmitter {
                     ? true
                     : (!apiTools || apiTools.length === 0) && !hasToolMessages);
                 if (useStreaming) {
+                    _turnLlmStartMs = Date.now();
                     const stream = await this.client.chatComplete({
                         model: currentModel,
                         messages: apiMessages,
@@ -977,6 +1236,10 @@ export class Agent extends EventEmitter {
                         if (choice?.delta) {
                             const delta = choice.delta;
                             if (delta.content) {
+                                if (!_firstDeltaSeen) {
+                                    _turnTtftMs = Date.now() - _turnLlmStartMs;
+                                    _firstDeltaSeen = true;
+                                }
                                 fullText += delta.content;
                                 this.emit('stream:delta', delta.content, fullText);
                             }
@@ -1000,6 +1263,8 @@ export class Agent extends EventEmitter {
                             const inTok = chunk.usage.prompt_tokens ?? 0;
                             const outTok = chunk.usage.completion_tokens ?? 0;
                             const totalTok = chunk.usage.total_tokens ?? (inTok + outTok);
+                            _turnInputTokens = inTok;
+                            _turnOutputTokens = outTok;
                             const cost = chunk.usage.cost ?? 0;
                             this.emit('usage', {
                                 prompt_tokens: inTok,
@@ -1013,6 +1278,7 @@ export class Agent extends EventEmitter {
                     }
                 }
                 else {
+                    _turnLlmStartMs = Date.now();
                     this.emit('stream:start');
                     const result = await this.client.chatComplete({
                         model: currentModel,
@@ -1027,6 +1293,8 @@ export class Agent extends EventEmitter {
                     this.recordModelSuccess(currentModel);
                     const choice = result.choices?.[0];
                     if (choice?.message) {
+                        _turnTtftMs = Date.now() - _turnLlmStartMs;
+                        _firstDeltaSeen = true;
                         if (choice.message.content) {
                             fullText = choice.message.content;
                             this.emit('stream:delta', fullText, fullText);
@@ -1045,6 +1313,8 @@ export class Agent extends EventEmitter {
                         const inTok = result.usage.prompt_tokens ?? 0;
                         const outTok = result.usage.completion_tokens ?? 0;
                         const totalTok = result.usage.total_tokens ?? (inTok + outTok);
+                        _turnInputTokens = inTok;
+                        _turnOutputTokens = outTok;
                         const cost = result.usage.cost ?? 0;
                         this.emit('usage', {
                             prompt_tokens: inTok,
@@ -1219,10 +1489,13 @@ export class Agent extends EventEmitter {
                         const execFn = tool?.function?.execute ?? tool?.execute;
                         if (tool && typeof execFn === 'function') {
                             try {
-                                // Cloud platform tools get the raw args: their JSON Schemas are
-                                // authoritative (snake_case) and the gateway validates them —
-                                // injecting camelCase duplicates could fail server-side validation.
-                                const args = tool?.source === 'scalix-cloud'
+                                // Remotely-schema'd tools get the raw args: their JSON Schemas
+                                // are authoritative (snake_case) and the far side validates
+                                // them — injecting camelCase duplicates could fail that
+                                // validation. True for the Scalix Cloud gateway and equally for
+                                // any MCP server, which validates against its own inputSchema.
+                                const src = tool?.source;
+                                const args = (src === 'scalix-cloud' || src === 'mcp')
                                     ? parsedArgs
                                     : normalizeArgs(parsedArgs);
                                 // Validate against the very schema the model was shown. Nothing
@@ -1249,6 +1522,8 @@ export class Agent extends EventEmitter {
                                 const toolTimeout = (typeof args?.timeout === 'number' && args.timeout > 0)
                                     ? Math.min(args.timeout, TOOL_DEFAULTS.maxCommandTimeoutMs)
                                     : this.config.toolTimeoutMs;
+                                const toolStart = Date.now();
+                                this.emit('step:start', { stepIndex: _stepIndex, name: call.name, args: parsedArgs, startedAt: toolStart });
                                 result = await withTimeout(execFn(args, {
                                     context: {},
                                     workspaceRoot: this.config.workspaceRoot ?? process.cwd(),
@@ -1262,8 +1537,21 @@ export class Agent extends EventEmitter {
                                         confirmToolCall: this.config.confirmToolCall,
                                     },
                                 }), toolTimeout, call.name);
+                                const toolDurationMs = Date.now() - toolStart;
+                                _turnToolDurationMs += toolDurationMs;
+                                this.emit('step:done', { stepIndex: _stepIndex, name: call.name, durationMs: toolDurationMs, success: !result?.error });
+                                _stepIndex++;
+                                // The tool only persists the entry to mcp-services.json. Connect
+                                // it here too, so the server's tools are usable in this same
+                                // session instead of only after a restart — and report the
+                                // outcome back through the tool result, since a server that
+                                // won't answer is something the model needs to know now.
                                 if (call.name === 'add_mcp_server' && result?.success) {
-                                    this.addTool({ type: 'mcp', serverLabel: args.label, serverUrl: args.url });
+                                    const connected = await this.connectMcpServer({
+                                        serverLabel: args.label,
+                                        serverUrl: args.url,
+                                    });
+                                    result = { ...result, connected: connected.state === 'connected', tools: connected.toolCount, ...(connected.error ? { connectError: connected.error } : {}) };
                                 }
                             }
                             catch (e) {
@@ -1272,11 +1560,19 @@ export class Agent extends EventEmitter {
                             }
                         }
                         else {
-                            const availableNames = this.config.tools
+                            const allNames = this.config.tools
                                 .map((t) => t.function?.name || t.name)
-                                .filter(Boolean)
-                                .slice(0, 20);
-                            result = { error: `Tool "${call.name}" does not exist. Available tools: ${availableNames.join(', ')}. Do not invent tool names — only use tools from the list above, or respond with text directly.` };
+                                .filter(Boolean);
+                            // Near-matches first: an invented "scalix_build_list" must surface
+                            // the real scalix_* names. Blindly listing the first 20 registry
+                            // entries hid every platform tool and read as "those don't exist" —
+                            // the model then invented workarounds instead of correcting the name
+                            // (seen 2026-08-09: a deploy derailed into "make the repo public").
+                            const stem = call.name.toLowerCase().split(/[_-]/)[0];
+                            const near = stem.length >= 3 ? allNames.filter((n) => n.toLowerCase().includes(stem)) : [];
+                            const shown = [...new Set([...near, ...allNames])].slice(0, Math.max(20, Math.min(near.length, 40)));
+                            const omitted = allNames.length - shown.length;
+                            result = { error: `Tool "${call.name}" does not exist.${near.length ? ` Did you mean one of: ${near.slice(0, 40).join(', ')}?` : ''} Available tools: ${shown.join(', ')}${omitted > 0 ? `, plus ${omitted} more registered but not listed here` : ''}. Do not invent tool names — only use tools from the list above, or respond with text directly.` };
                         }
                         let resultStr;
                         try {
@@ -1382,6 +1678,16 @@ export class Agent extends EventEmitter {
                     }
                     if (this._aborted)
                         return '[interrupted]';
+                    this.emit('turn:summary', {
+                        turnIndex: turnCount,
+                        steps: _stepIndex,
+                        llmDurationMs: Date.now() - _turnLlmStartMs,
+                        toolDurationMs: _turnToolDurationMs,
+                        ttftMs: _turnTtftMs,
+                        tokensPerSec: (Date.now() - _turnLlmStartMs) > 0 ? _turnOutputTokens / ((Date.now() - _turnLlmStartMs) / 1000) : 0,
+                        inputTokens: _turnInputTokens,
+                        outputTokens: _turnOutputTokens,
+                    });
                     continue;
                 }
                 if (this.groundingConfig?.enabled && this.groundingNudgeCount < this.groundingConfig.maxNudges) {
@@ -1401,6 +1707,16 @@ export class Agent extends EventEmitter {
                         }
                     }
                 }
+                this.emit('turn:summary', {
+                    turnIndex: turnCount,
+                    steps: _stepIndex,
+                    llmDurationMs: Date.now() - _turnLlmStartMs,
+                    toolDurationMs: _turnToolDurationMs,
+                    ttftMs: _turnTtftMs,
+                    tokensPerSec: (Date.now() - _turnLlmStartMs) > 0 ? _turnOutputTokens / ((Date.now() - _turnLlmStartMs) / 1000) : 0,
+                    inputTokens: _turnInputTokens,
+                    outputTokens: _turnOutputTokens,
+                });
                 return fullText;
             }
             catch (err) {