scalemax 0.1.22 → 0.1.24

package/README.md

@@ -113,13 +113,17 @@ Or ask one small question and exit:
 npx scalemax@latest helper-bot "Why is my ScaleMax API key rejected in Codex?"
 ```
 
-The helper uses the same stored key as the installer, verifies authentication, detects the API-credit or token-pack base URL automatically, and selects a model available to that key. Each response is capped at 512 tokens and interactive history is bounded to the latest two turns. To choose a specific model from `scalemax models`, use:
+The helper uses the same stored key as the installer, verifies authentication, and detects the API-credit or token-pack base URL automatically. General support questions default to `gpt-5.4` when that model is available to the key; each response is capped at 512 tokens and interactive history is bounded to the latest two turns. To choose a different model from `scalemax models`, use:
 
 ```bash
 npx scalemax@latest helper-bot --model fable-5 "Help me configure ScaleMax in Cursor"
 ```
 
-The helper is restricted to ScaleMax tasks, refuses unrelated requests, redacts ScaleMax-style secrets before requests and output, and never receives local shell or filesystem tools. Use `/help` inside the session for commands and `/quit` to exit.
+Recognized setup, repair, and verification requests execute the CLI's allowlisted client operations directly. Requests such as `setup all providers`, `fix Hermes request failed`, `configure Claude Code`, `verify OpenCode`, and `setup vs code roo extension for claude` are handled by the controller before any model request. The controller detects the relevant client, runs a safe installer when the client has one, verifies existing ScaleMax configuration, repairs ScaleMax-managed files when verification fails, re-verifies, and reports each step.
+
+For Roo Code, helper-bot can install VS Code on Windows with the fixed Microsoft winget package, install the official Roo Code extension, write OpenAI and Claude ScaleMax profiles when the key exposes both families, and verify the import handoff. For general troubleshooting that cannot be completed by a fixed client action, helper-bot sends a small `gpt-5.4` request grounded with bundled ScaleMax documentation about stored authentication, credit/token base URLs, provider scope, client setup, and common errors. The language model never generates or executes shell commands; only fixed ScaleMax client detection, installation, configuration, verification, and rollback operations are available to the controller.
+
+The helper refuses unrelated requests and redacts ScaleMax-style secrets from prompts, provider output, errors, and progress notifications. Use `/status` for non-secret connection details, `/help` for commands, and `/quit` to exit.
 
 ## Supported clients
 

package/dist/commands/helper-bot.d.ts

@@ -1,6 +1,7 @@
 import { type ChatCompletionOptions, type ChatCompletionResult, type ChatMessage, type ModelInfo } from '../utils/api.js';
 import { loadApiKey } from '../utils/keyStore.js';
 import { validateApiKey } from '../utils/api.js';
+import type { ClientDefinition } from '../types/client.js';
 export declare const SCALEMAX_HELPER_REFUSAL: string;
 export declare const SCALEMAX_HELPER_SYSTEM_PROMPT: string;
 export declare const SCALEMAX_HELPER_INVALID_PROVIDER_RESPONSE: string;
@@ -16,6 +17,7 @@ export interface HelperConnection {
     providerScope?: 'openai' | 'anthropic' | 'both';
     keyMode?: string;
     availableModels?: string[];
+    modelCatalog?: ModelInfo[];
 }
 export type HelperCompletion = (options: ChatCompletionOptions) => Promise<ChatCompletionResult>;
 export interface HelperBotDependencies {
@@ -23,6 +25,7 @@ export interface HelperBotDependencies {
     validateKey: typeof validateApiKey;
     complete: HelperCompletion;
     write: (message: string) => void;
+    clientCatalog: ClientDefinition[];
 }
 export declare function parseHelperBotArgs(args: string[]): HelperBotArgs;
 export declare function redactHelperSecrets(value: unknown, activeKey?: string): string;
@@ -38,4 +41,6 @@ export declare function helperConnectionSummary(connection: HelperConnection): s
 export declare function localHelperReply(question: string, connection: HelperConnection): string | undefined;
 export declare function selectHelperModel(models: ModelInfo[], requested?: string): string;
 export declare function requestHelperReply(question: string, history: ChatMessage[], connection: HelperConnection, complete?: HelperCompletion): Promise<string>;
+/** Execute only narrowly allowlisted ScaleMax client actions; never model-generated shell commands. */
+export declare function executeHelperAction(question: string, connection: HelperConnection, home: string, clientCatalog?: ClientDefinition[], write?: (message: string) => void): Promise<string | undefined>;
 export declare function helperBotCommand(args?: string[], home?: string, dependencies?: Partial<HelperBotDependencies>): Promise<void>;

package/dist/commands/helper-bot.js

@@ -1,10 +1,15 @@
 import chalk from 'chalk';
+import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
-import { createChatCompletion } from '../utils/api.js';
+import { execa } from 'execa';
+import { clients } from '../clients.js';
+import { helperDocsContext } from './helper-docs.js';
+import { createChatCompletion, isAnthropicModel } from '../utils/api.js';
 import { redactApiKey } from '../utils/apiKey.js';
 import { loadApiKey } from '../utils/keyStore.js';
 import { homeDir } from '../utils/paths.js';
 import { validateApiKey } from '../utils/api.js';
+import { commandExists } from '../utils/exec.js';
 export const SCALEMAX_HELPER_REFUSAL = `I am the official ScaleMax Helper.
 
 I can only assist with installing, configuring, repairing, verifying, and troubleshooting ScaleMax.
@@ -292,6 +297,8 @@ Never stop after only giving instructions if you can continue solving the issue.
 
 Always prefer automatic configuration.
 
+When bundled ScaleMax documentation is supplied in the conversation, use it for exact ScaleMax configuration facts before relying on general model knowledge.
+
 Only ask the user to perform manual actions when automation is impossible.
 
 If multiple configuration methods exist:
@@ -531,13 +538,17 @@ const DEFAULT_MAX_TOKENS = 512;
 const SECRET_PATTERN = /\b(?:sm_(?:live|test)_[A-Za-z0-9_-]{8,}|sk-[A-Za-z0-9_-]{12,})\b/g;
 const PROMPT_INJECTION_PATTERN = /\b(?:ignore|override|bypass|disable|reveal|show|print|expose)\b.{0,80}\b(?:system|hidden|previous|developer|instruction|prompt|rule|secret)\b/i;
 const CLEARLY_UNRELATED_PATTERN = /\b(?:homework|poem|story|roleplay|translate|translation|medical|legal|politics|religion|dating|entertainment|game|malware|hacking|reverse\s+engineering|weather|sports|recipe|joke)\b/i;
-const SCALEMAX_TOPIC_PATTERN = /\b(?:scalemax|api\s*key|base\s*url|endpoint|provider|model|token|credit|billing|pricing|authentication|configuration|configure|install|update|repair|verify|health\s*check|environment\s*variable|vscode|visual\s+studio\s+code|cursor|codex(?:\s+cli)?|claude(?:\s+code)?|opencode|openclaw|roo\s+code|continue|windsurf|hermes|cherry\s+studio|api\s+code)\b/i;
+const SCALEMAX_TOPIC_PATTERN = /\b(?:scalemax|api\s*key|stored\s+key|customer\s+key|base\s*url|endpoint|provider|openai|anthropic|model|fable|token|credit|billing|pricing|authentication|login|log\s+in|configuration|configure|setup|set\s*up|install|update|repair|verify|health\s*check|environment\s*variable|vscode|visual\s+studio\s+code|vs\s*code\s+extension|cursor|codex(?:\s+cli)?|claude(?:\s+code)?|opencode|openclaw|roo(?:\s+code|\s+extension)?|continue|windsurf|hermes|cherry\s+studio|api\s+code)\b/i;
 const TROUBLESHOOTING_PATTERN = /\b(?:error|failed?|failure|broken|not\s+working|doesn['’]?t\s+work|cannot|can['’]?t|timeout|invalid|unauthorized|forbidden|help)\b/i;
 const GREETING_PATTERN = /^(?:hi|hello|hey|help|what can you do)[!.?\s]*$/i;
 const CLAUDE_DESKTOP_PATTERN = /\bclaude\s+desktop\b/i;
 const CLAUDE_DESKTOP_CONFIGURATION_PATTERN = /\b(?:configur(?:e|ation)|setup|set\s*up|gateway|base\s*url|api\s*key|connect(?:ion)?|third[- ]party|inference|field|install|verify)\b/i;
 const CODEX_CLI_PATTERN = /\bcodex(?:\s+cli)?\b/i;
 const CLIENT_CONFIGURATION_PATTERN = /\b(?:configur(?:e|ation)|setup|set\s*up|base\s*url|api\s*key|connect(?:ion)?|provider|install|repair|verify|update)\b/i;
+const STORED_KEY_EXPLAIN_PATTERN = /\b(?:why\s+(?:did\s+)?i\s+(?:login|log\s+in)|helper\b.{0,80}\b(?:customer|stored)\s+key|(?:customer|stored)\s+key\b.{0,80}\bhelper|does\s+(?:it|helper)\s+use\s+(?:my\s+)?(?:api\s+)?key)\b/i;
+const HELPER_MUTATION_PATTERN = /(?:^|\b(?:please|can\s+you|could\s+you|help\s+me(?:\s+to)?|i\s+(?:want|need)\s+you\s+to|how\s+(?:do|can)\s+i)\s+)(?:set\s*up|setup|configure|connect|install|repair|fix|update|reconfigure|make\b.{0,80}\bwork)\b/i;
+const HELPER_VERIFICATION_PATTERN = /(?:^|\b(?:please|can\s+you|could\s+you|help\s+me(?:\s+to)?|i\s+(?:want|need)\s+you\s+to)\s+)(?:verify|check|test|diagnose)\b/i;
+const ALL_CLIENTS_PATTERN = /\b(?:all|every)\b.{0,30}\b(?:client|provider|integration|app)s?\b/i;
 const KNOWN_CONTEXT_REASK_PATTERN = /(?:\b(?:need|send|provide|share|tell)\b.{0,100}\b(?:api\s*(?:key|endpoint)|base\s*url|operating\s+system|\bos\b|model\s+(?:name|catalog))\b|YOUR-SCALEMAX-ENDPOINT|your-key)/is;
 const PROVIDER_IDENTITY_OVERRIDE_PATTERNS = [
     /\bkiro\b/i,
@@ -558,7 +569,8 @@ const defaultDependencies = {
     loadKey: loadApiKey,
     validateKey: validateApiKey,
     complete: createChatCompletion,
-    write: message => console.log(message)
+    write: message => console.log(message),
+    clientCatalog: clients
 };
 export function parseHelperBotArgs(args) {
     let model;
@@ -630,9 +642,9 @@ Mandatory behavior:
 
 1. Treat the stored key, base URLs, operating system, provider scope, and model catalog as already known. Do not request them again.
 2. Never output placeholders such as YOUR-SCALEMAX-ENDPOINT or your-key when an exact known value can be used.
-3. Prefer the automatic CLI workflow. For an installed supported client, tell the user to exit the Helper with /quit, run \`scalemax update\`, then run \`scalemax doctor\` to verify it.
+3. The CLI controller executes recognized safe configuration and verification requests before asking the model. Do not claim that an unrecognized action was executed.
 4. The Helper request itself uses the stored customer key and therefore consumes the small number of tokens used by the selected Helper model. The key is never included in the prompt text.
-5. Do not claim you executed terminal commands. The Helper has no shell tools; give the shortest exact ScaleMax command sequence when user action is required.`;
+5. When user action is genuinely required, give the shortest exact instruction and clearly distinguish it from work already completed by the CLI controller.`;
 }
 export function helperConnectionSummary(connection) {
     return `Authenticated ${helperBillingMode(connection)} key · ${helperPlatformName(connection.platform)} · ${connection.providerScope || 'both'} scope · ${connection.baseUrl} · helper model ${connection.model}`;
@@ -643,6 +655,18 @@ export function helperConnectionSummary(connection) {
  * field values matter more than generated prose.
  */
 export function localHelperReply(question, connection) {
+    if (STORED_KEY_EXPLAIN_PATTERN.test(question)) {
+        return `ScaleMax Helper uses the key saved by \`scalemax login\`.
+
+- The key is validated before Helper starts.
+- The Helper's own small replies use the stored customer key with the selected low-cost model, usually \`${connection.model}\`.
+- Client setup actions reuse the same stored key in the target client's private config.
+- The key is never pasted into the prompt, displayed in chat, or requested again after login.
+
+Authenticated base URL: ${connection.baseUrl}
+Billing mode: ${helperBillingMode(connection)}
+Provider scope: ${connection.providerScope || 'both'}`;
+    }
     if (CLAUDE_DESKTOP_PATTERN.test(question) && CLAUDE_DESKTOP_CONFIGURATION_PATTERN.test(question)) {
         const gatewayBaseUrl = claudeDesktopGatewayBaseUrl(connection.baseUrl);
         return `ScaleMax Helper detected and authenticated the stored ${helperBillingMode(connection)} key.
@@ -685,7 +709,7 @@ export function selectHelperModel(models, requested) {
             throw new Error(`Model "${requested}" is not available to this API key. Run \`scalemax models\` to see available models.`);
         return exact.id;
     }
-    const preferred = ['gpt-5.6-luna', 'claude-haiku-4-5-20251001', 'fable-5', 'gpt-5.6-terra', 'gpt-5.6-sol'];
+    const preferred = ['gpt-5.4', 'gpt-5.4-mini', 'claude-haiku-4-5-20251001', 'gpt-5.6-luna', 'fable-5', 'gpt-5.6-terra', 'gpt-5.6-sol'];
     for (const id of preferred) {
         const match = models.find(model => model.id.toLowerCase() === id);
         if (match)
@@ -705,6 +729,7 @@ export async function requestHelperReply(question, history, connection, complete
     if (localReply)
         return localReply;
     const recentHistory = history.slice(-MAX_HISTORY_MESSAGES).map(message => ({ ...message, content: redactHelperSecrets(message.content, connection.apiKey) }));
+    const docsContext = helperDocsContext(cleanQuestion);
     const result = await complete({
         apiKey: connection.apiKey,
         baseUrl: connection.baseUrl,
@@ -713,6 +738,7 @@ export async function requestHelperReply(question, history, connection, complete
         messages: [
             { role: 'system', content: SCALEMAX_HELPER_SYSTEM_PROMPT },
             { role: 'system', content: helperRuntimeContext(connection) },
+            ...(docsContext ? [{ role: 'system', content: docsContext }] : []),
             ...recentHistory,
             { role: 'user', content: cleanQuestion }
         ]
@@ -731,8 +757,260 @@ For automatic configuration, exit with \`/quit\`, run \`scalemax update\`, then
     }
     return reply;
 }
+const HELPER_CLIENT_PATTERNS = [
+    { id: 'roo-code', pattern: /\b(?:roo(?:\s+code)?|roo\s+(?:extension|plugin)|vscode\s+roo|vs\s+code\s+roo|vs\s*code\s+extension|visual\s+studio\s+code\s+extension)\b/i },
+    { id: 'openclaw', pattern: /\bopen\s*claw\b/i },
+    { id: 'opencode', pattern: /\bopen\s*code\b/i },
+    { id: 'cherry-studio', pattern: /\bcherry\s*studio\b/i },
+    { id: 'api-code', pattern: /\bapi\s*code\b/i },
+    { id: 'trae-solo', pattern: /\btrae(?:\s+solo)?\b/i },
+    { id: 'cursor', pattern: /\bcursor\b/i },
+    { id: 'hermes', pattern: /\bhermes\b/i },
+    { id: 'codex', pattern: /\bcodex(?:\s+cli)?\b/i },
+    { id: 'claude', pattern: /\bclaude(?:\s+code|\s+cli)?\b/i }
+];
+function helperActionKind(question) {
+    if (/\b(?:repair|fix|troubleshoot|diagnose|not\s+working|doesn['’]?t\s+work|broken|failed?|invalid|timeout|rate\s*limit(?:ed)?)\b/i.test(question))
+        return 'repair';
+    if (HELPER_MUTATION_PATTERN.test(question))
+        return 'configure';
+    if (HELPER_VERIFICATION_PATTERN.test(question))
+        return 'verify';
+    return undefined;
+}
+function helperActionTarget(question) {
+    if (CLAUDE_DESKTOP_PATTERN.test(question))
+        return undefined;
+    if (ALL_CLIENTS_PATTERN.test(question) || /\b(?:all|every)\b.{0,30}\bproviders?\b/i.test(question))
+        return 'all';
+    const explicit = HELPER_CLIENT_PATTERNS.find(candidate => candidate.pattern.test(question))?.id;
+    if (explicit)
+        return explicit;
+    if (/\b(?:clients?|integrations?|apps?|providers?)\b/i.test(question) && /\b(?:scalemax|configure|setup|set\s*up|repair|fix|update)\b/i.test(question))
+        return 'all';
+    return undefined;
+}
+function requestedProviderScope(question, target) {
+    if (/\b(?:both|openai\s*\+\s*claude|claude\s*\+\s*openai)\b/i.test(question))
+        return 'both';
+    if (/\b(?:claude|anthropic)\b/i.test(question))
+        return 'anthropic';
+    if (/\b(?:openai|chatgpt|gpt)\b/i.test(question) || target === 'codex')
+        return 'openai';
+    return undefined;
+}
+function actionModels(connection, requestedScope) {
+    const catalog = connection.modelCatalog?.length
+        ? connection.modelCatalog
+        : (connection.availableModels || []).map(id => ({ id }));
+    if (!requestedScope || requestedScope === 'both')
+        return catalog;
+    return catalog.filter(model => requestedScope === 'anthropic' ? isAnthropicModel(model) : !isAnthropicModel(model));
+}
+function helperClientAllowedForModels(clientId, models) {
+    if (!models.length)
+        return false;
+    const crossProtocolClients = new Set(['claude', 'cursor', 'roo-code', 'opencode', 'openclaw', 'hermes', 'cherry-studio', 'api-code']);
+    if (crossProtocolClients.has(clientId))
+        return true;
+    return models.some(model => !isAnthropicModel(model));
+}
+function hasRooCodeExtension(paths) {
+    return paths.some(candidate => /^rooveterinaryinc\.roo-cline-/i.test(path.basename(candidate)));
+}
+function pathEnvKey(env) {
+    return Object.keys(env).find(key => key.toLowerCase() === 'path') || 'PATH';
+}
+function windowsVSCodeBinPaths(ctx) {
+    const localAppData = ctx.env.LOCALAPPDATA || path.win32.join(ctx.home, 'AppData', 'Local');
+    const programFiles = ctx.env.ProgramFiles || 'C:\\Program Files';
+    const programFilesX86 = ctx.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
+    return [
+        path.win32.join(localAppData, 'Programs', 'Microsoft VS Code', 'bin'),
+        path.win32.join(programFiles, 'Microsoft VS Code', 'bin'),
+        path.win32.join(programFilesX86, 'Microsoft VS Code', 'bin')
+    ];
+}
+function refreshWindowsVSCodePath(ctx) {
+    if (ctx.platform !== 'win32')
+        return;
+    const key = pathEnvKey(ctx.env);
+    const delimiter = ';';
+    const existing = new Set((ctx.env[key] || '').split(delimiter).filter(Boolean).map(item => item.toLowerCase()));
+    const additions = windowsVSCodeBinPaths(ctx).filter(candidate => !existing.has(candidate.toLowerCase()));
+    if (additions.length)
+        ctx.env[key] = [...additions, ctx.env[key] || ''].filter(Boolean).join(delimiter);
+}
+async function installVSCodeOnWindows(ctx, write) {
+    if (ctx.platform !== 'win32')
+        return;
+    refreshWindowsVSCodePath(ctx);
+    if (await commandExists('code', ctx.env))
+        return;
+    if (!(await commandExists('winget', ctx.env))) {
+        throw new Error('VS Code and the Roo Code extension were not detected. Install VS Code first, then retry this request.');
+    }
+    write('→ VS Code was not detected; installing Microsoft Visual Studio Code with winget…');
+    const result = await execa('winget', [
+        'install',
+        '--id',
+        'Microsoft.VisualStudioCode',
+        '--exact',
+        '--accept-package-agreements',
+        '--accept-source-agreements',
+        '--silent'
+    ], {
+        env: ctx.env,
+        reject: false,
+        all: true
+    });
+    if (result.exitCode !== 0)
+        throw new Error(`VS Code installation failed: ${result.all?.trim() || `winget exited with ${result.exitCode}`}`);
+    refreshWindowsVSCodePath(ctx);
+    if (!(await commandExists('code', ctx.env)))
+        throw new Error('VS Code installed, but the code command was not detected. Restart the terminal and retry this request.');
+    write('✓ VS Code installed and detected.');
+}
+async function installRooCodeExtension(ctx, client, write) {
+    let detection = await client.detect(ctx);
+    if (hasRooCodeExtension(detection.paths))
+        return;
+    if (!detection.executable && ctx.platform === 'win32') {
+        await installVSCodeOnWindows(ctx, write);
+        detection = await client.detect(ctx);
+    }
+    if (!detection.executable)
+        throw new Error('VS Code and the Roo Code extension were not detected. Install VS Code first, then retry this request.');
+    write('→ Installing the official Roo Code extension in VS Code…');
+    const result = await execa('code', ['--install-extension', 'RooVeterinaryInc.roo-cline', '--force'], {
+        env: ctx.env,
+        reject: false,
+        all: true
+    });
+    if (result.exitCode !== 0)
+        throw new Error(`Roo Code extension installation failed: ${result.all?.trim() || `code exited with ${result.exitCode}`}`);
+    detection = await client.detect(ctx);
+    if (!hasRooCodeExtension(detection.paths))
+        throw new Error('VS Code reported a successful Roo Code installation, but the extension could not be detected afterward. Restart VS Code and retry.');
+    write('✓ Roo Code extension installed and detected.');
+}
+async function runOneHelperClientAction(kind, client, connection, home, requestedScope, write) {
+    const models = actionModels(connection, requestedScope);
+    if (!models.length)
+        throw new Error(`The authenticated key does not expose ${requestedScope === 'anthropic' ? 'Claude' : requestedScope === 'openai' ? 'OpenAI' : 'compatible'} models for ${client.name}. No configuration was changed.`);
+    if (client.id === 'codex' && models.every(isAnthropicModel))
+        throw new Error('Codex requires an OpenAI-compatible model, but this key exposes only Claude models. No configuration was changed.');
+    if (client.id === 'cursor' && connection.platform !== 'darwin')
+        throw new Error(`Automatic Cursor configuration is currently verified on macOS only. ${helperPlatformName(connection.platform)} was not modified.`);
+    const ctx = {
+        home,
+        platform: connection.platform || process.platform,
+        env: { ...process.env },
+        apiKey: connection.apiKey,
+        baseUrl: connection.baseUrl,
+        providerScope: requestedScope || connection.providerScope || 'both',
+        models,
+        interactive: false,
+        allowAppModification: false
+    };
+    if (kind !== 'verify' && client.install) {
+        write(`→ Checking ${client.name} installer…`);
+        const installed = await client.install({ home, platform: ctx.platform, env: ctx.env, interactive: Boolean(process.stdin.isTTY) });
+        write(`✓ ${client.name} ${installed.message}`);
+    }
+    write(`→ Detecting ${client.name}…`);
+    let detection = await client.detect(ctx);
+    if ((kind === 'configure' || kind === 'repair') && client.id === 'roo-code') {
+        await installRooCodeExtension(ctx, client, write);
+        detection = await client.detect(ctx);
+    }
+    if (!detection.installed && client.id !== 'api-code')
+        throw new Error(`${client.name} was not detected. No configuration was changed.`);
+    write(client.id === 'api-code' && !detection.installed ? `✓ ${client.name} output path is available.` : `✓ ${client.name} detected.`);
+    if (kind === 'verify') {
+        if (!client.verify) {
+            if (!detection.configured)
+                throw new Error(`${client.name} is installed but its ScaleMax configuration was not detected.`);
+            return `✓ ${client.name} ScaleMax configuration is present.`;
+        }
+        write(`→ Verifying ${client.name}…`);
+        const verified = await client.verify(ctx);
+        return `✓ ${client.name} ${verified.message}`;
+    }
+    if (kind === 'repair' && client.verify) {
+        write(`→ Diagnosing ${client.name} configuration…`);
+        try {
+            const verified = await client.verify(ctx);
+            return `✓ ${client.name} is already healthy: ${verified.message}`;
+        }
+        catch (error) {
+            write(`→ ${client.name} verification failed; repairing ScaleMax-managed configuration…`);
+        }
+    }
+    write(`→ Configuring ${client.name} with the authenticated stored key…`);
+    const configured = await client.configure(ctx);
+    write(`✓ ${client.name} ${configured.message}`);
+    if (client.verify) {
+        write(`→ Verifying ${client.name} configuration…`);
+        try {
+            const verified = await client.verify(ctx);
+            write(`✓ ${client.name} ${verified.message}`);
+        }
+        catch (error) {
+            if (configured.changed) {
+                write(`→ Verification failed; removing the incomplete ScaleMax-managed ${client.name} configuration…`);
+                await client.remove(ctx).catch(() => undefined);
+            }
+            throw error;
+        }
+    }
+    else {
+        detection = await client.detect(ctx);
+        if (!detection.configured)
+            throw new Error(`${client.name} configuration was written but could not be detected afterward.`);
+        write(`✓ ${client.name} configuration detected after write.`);
+    }
+    const activation = client.id === 'roo-code' ? ' Reload VS Code once so Roo Code imports the verified ScaleMax profile.' : '';
+    return `✅ Successfully completed: ${client.name} is configured and locally verified.${activation}`;
+}
+/** Execute only narrowly allowlisted ScaleMax client actions; never model-generated shell commands. */
+export async function executeHelperAction(question, connection, home, clientCatalog = clients, write = message => console.log(message)) {
+    const cleanQuestion = redactHelperSecrets(question.trim(), connection.apiKey);
+    if (!isScaleMaxHelperQuestion(cleanQuestion))
+        return undefined;
+    const kind = helperActionKind(cleanQuestion);
+    const target = helperActionTarget(cleanQuestion);
+    if (!kind || !target)
+        return undefined;
+    const scope = requestedProviderScope(cleanQuestion, target);
+    const scopedModels = actionModels(connection, scope);
+    const selected = target === 'all'
+        ? clientCatalog.filter(client => client.id !== 'cursor' && helperClientAllowedForModels(client.id, scopedModels))
+        : clientCatalog.filter(client => client.id === target);
+    if (!selected.length)
+        throw new Error('The requested ScaleMax integration is not supported by this CLI build.');
+    if (target !== 'all' && !helperClientAllowedForModels(selected[0].id, scopedModels))
+        throw new Error(`The authenticated key does not expose models compatible with ${selected[0].name}. No configuration was changed.`);
+    write(`✓ Stored ${helperBillingMode(connection)} key is authenticated; secrets remain hidden.`);
+    const completed = [];
+    const failures = [];
+    for (const client of selected) {
+        try {
+            completed.push(await runOneHelperClientAction(kind, client, connection, home, scope, write));
+        }
+        catch (error) {
+            const message = redactHelperSecrets(error instanceof Error ? error.message : String(error), connection.apiKey);
+            if (target !== 'all')
+                throw new Error(message);
+            failures.push(`${client.name}: ${message}`);
+        }
+    }
+    if (!completed.length)
+        throw new Error(`No ScaleMax client action completed.\n${failures.map(item => `- ${item}`).join('\n')}`);
+    return `${completed.join('\n')}${failures.length ? `\n\nSkipped or failed:\n${failures.map(item => `- ${item}`).join('\n')}` : ''}`;
+}
 function printSessionHelp(write) {
-    write('Commands: /help shows this help; /status shows the authenticated non-secret connection details; /quit exits. Ask only ScaleMax installation, configuration, authentication, or troubleshooting questions.');
+    write('Commands: /help shows this help; /status shows the authenticated non-secret connection details; /quit exits. Setup, repair, and verification requests for supported clients are executed automatically with progress notifications.');
 }
 export async function helperBotCommand(args = [], home = homeDir(), dependencies = {}) {
     const deps = { ...defaultDependencies, ...dependencies };
@@ -751,10 +1029,15 @@ export async function helperBotCommand(args = [], home = homeDir(), dependencies
         platform: process.platform,
         providerScope: validation.key?.provider_scope || 'both',
         keyMode: validation.key?.mode,
-        availableModels: validation.models.map(item => item.id)
+        availableModels: validation.models.map(item => item.id),
+        modelCatalog: validation.models
+    };
+    const respond = async (question, history) => {
+        const action = await executeHelperAction(question, connection, home, deps.clientCatalog, deps.write);
+        return action || requestHelperReply(question, history, connection, deps.complete);
     };
     if (options.question) {
-        deps.write(await requestHelperReply(options.question, [], connection, deps.complete));
+        deps.write(await respond(options.question, []));
         return;
     }
     if (!process.stdin.isTTY)
@@ -787,7 +1070,7 @@ export async function helperBotCommand(args = [], home = homeDir(), dependencies
                 continue;
             }
             try {
-                const reply = await requestHelperReply(input, history, connection, deps.complete);
+                const reply = await respond(input, history);
                 deps.write(reply);
                 if (reply !== SCALEMAX_HELPER_REFUSAL) {
                     history.push({ role: 'user', content: redactHelperSecrets(input, key) }, { role: 'assistant', content: reply });

package/dist/commands/helper-docs.d.ts

@@ -0,0 +1,9 @@
+export interface HelperDocSection {
+    id: string;
+    title: string;
+    keywords: string[];
+    content: string;
+}
+export declare const HELPER_DOC_SECTIONS: HelperDocSection[];
+export declare function selectHelperDocs(question: string, limit?: number): HelperDocSection[];
+export declare function helperDocsContext(question: string): string | undefined;

package/dist/commands/helper-docs.js

@@ -0,0 +1,70 @@
+export const HELPER_DOC_SECTIONS = [
+    {
+        id: 'stored-auth',
+        title: 'Stored ScaleMax authentication',
+        keywords: ['login', 'authenticate', 'authentication', 'stored key', 'api key', 'customer key', 'why login', 'base url'],
+        content: `After scalemax login succeeds, the CLI stores the customer's ScaleMax API key privately and validates it before helper-bot starts. The helper must not ask the user to paste the key, base URL, operating system, or model catalog again. The helper uses the stored customer key for its own small ScaleMax model requests and for supported client configuration files. The key is never inserted into prompts or displayed in chat.`
+    },
+    {
+        id: 'credit-token-urls',
+        title: 'API credit and API token base URLs',
+        keywords: ['credit', 'token', 'base url', 'endpoint', 'renew', 'billing', 'api credit', 'api token'],
+        content: `ScaleMax API credit keys use https://api.scalemax.pro/v1. ScaleMax API token budget keys use https://api.scalemax.pro/token/v1. Claude Desktop gateway configuration removes the trailing /v1, so credit keys use https://api.scalemax.pro and token keys use https://api.scalemax.pro/token. Do not mix credit and token base URLs; the authenticated key validation result is authoritative.`
+    },
+    {
+        id: 'provider-scope',
+        title: 'Provider scope and visible models',
+        keywords: ['provider', 'scope', 'openai', 'claude', 'anthropic', 'both', 'models', 'fable'],
+        content: `A ScaleMax key may be OpenAI only, Claude only, or both. OpenAI-only keys should configure OpenAI-compatible models only. Claude-only keys should configure Claude-compatible models only. Both-scope keys may configure both model families in clients that can switch profiles. Fable 5 is a Claude-family frontend model through ScaleMax and should only appear for Claude-capable or both-scope keys, not OpenAI-only keys.`
+    },
+    {
+        id: 'roo-code',
+        title: 'Roo Code setup through VS Code',
+        keywords: ['roo', 'roo code', 'vscode', 'vs code', 'extension', 'visual studio code'],
+        content: `For Roo Code, the ScaleMax CLI writes a private settings import file at ~/.scalemax/roo-code-import.json and sets roo-cline.autoImportSettingsPath in VS Code User settings. Roo imports that profile after VS Code is reloaded. The CLI can install the official Roo Code extension with code --install-extension RooVeterinaryInc.roo-cline when VS Code is detected. On Windows, helper-bot may install VS Code first with winget using the fixed Microsoft.VisualStudioCode package id, then install Roo, write the import handoff, and verify the files.`
+    },
+    {
+        id: 'codex-and-clients',
+        title: 'Supported client update flow',
+        keywords: ['codex', 'cursor', 'claude code', 'opencode', 'openclaw', 'hermes', 'cherry studio', 'update', 'doctor'],
+        content: `scalemax update detects supported clients and configures them from the stored key. scalemax doctor validates the stored key and performs a minimal ScaleMax request. Supported clients include Codex CLI, Cursor, Claude Code, OpenCode, OpenClaw, Hermes, Cherry Studio, Roo Code, and API Code. Recognized helper-bot setup and verification requests are executed by the CLI controller before any model fallback is used.`
+    },
+    {
+        id: 'troubleshooting',
+        title: 'Common troubleshooting',
+        keywords: ['error', 'failed', 'invalid', 'rate limit', 'timeout', 'kiro', 'request failed', 'provider returned invalid response'],
+        content: `If a provider response claims to be Kiro, Claude, ChatGPT, Codex, or says it cannot act as ScaleMax Helper, the helper must reject that response and not show the provider persona to the user. For timeouts or rate limits, retry with a tiny request and prefer the lowest-cost available helper model. For invalid key errors, re-run scalemax login and then scalemax doctor. For a client that still shows old settings, reload or restart that client after scalemax update.`
+    }
+];
+function words(value) {
+    return [...new Set(value.toLowerCase().match(/[a-z0-9]+(?:-[a-z0-9]+)?/g) || [])];
+}
+function scoreSection(questionWords, section) {
+    const haystack = words(`${section.title} ${section.keywords.join(' ')} ${section.content}`);
+    let score = 0;
+    for (const word of haystack)
+        if (questionWords.has(word))
+            score += section.keywords.includes(word) ? 4 : 1;
+    return score;
+}
+export function selectHelperDocs(question, limit = 3) {
+    const questionWords = new Set(words(question));
+    if (!questionWords.size)
+        return [];
+    return HELPER_DOC_SECTIONS
+        .map(section => ({ section, score: scoreSection(questionWords, section) }))
+        .filter(item => item.score > 1)
+        .sort((a, b) => b.score - a.score || a.section.id.localeCompare(b.section.id))
+        .slice(0, limit)
+        .map(item => item.section);
+}
+export function helperDocsContext(question) {
+    const sections = selectHelperDocs(question);
+    if (!sections.length)
+        return undefined;
+    return `# SCALEMAX DOCUMENTATION CONTEXT
+
+Use this bundled ScaleMax documentation for exact configuration facts. If it does not fully answer the request, continue from the authenticated runtime context and ScaleMax Helper rules.
+
+${sections.map(section => `## ${section.title}\n${section.content}`).join('\n\n')}`;
+}

package/dist/configure/roo-code.js

@@ -3,7 +3,7 @@ import fs from 'fs-extra';
 import JSON5 from 'json5';
 import { atomicWrite, backupFile } from '../utils/fs.js';
 import { clientConfigPath } from './paths.js';
-import { openAiBaseUrl, preferredChatCompletionsModel } from './models.js';
+import { anthropicModelIds, openAiBaseUrl, openAiModelIds, preferredAnthropicModel, preferredChatCompletionsModel, preferredOpenAiModel } from './models.js';
 import { isAnthropicModel } from '../utils/api.js';
 const id = 'roo-code';
 const name = 'Roo Code (VS Code)';
@@ -14,13 +14,31 @@ const claudeProfileName = 'ScaleMax Claude';
 const codexProfileId = 'scalemax-codex';
 const claudeProfileId = 'scalemax-claude';
 function importPath(home) { return path.join(home, '.scalemax', 'roo-code-import.json'); }
-function profileFor(ctx) {
+function fallbackProfileFor(ctx) {
     const model = preferredChatCompletionsModel(ctx);
     const metadata = (ctx.models || []).find(candidate => candidate.id === model) || { id: model };
     return isAnthropicModel(metadata)
         ? { name: claudeProfileName, id: claudeProfileId, model }
         : { name: codexProfileName, id: codexProfileId, model };
 }
+function profilesFor(ctx) {
+    const scope = ctx.providerScope || 'both';
+    const profiles = [];
+    if (scope !== 'anthropic' && openAiModelIds(ctx).length) {
+        profiles.push({ name: codexProfileName, id: codexProfileId, model: preferredOpenAiModel(ctx) });
+    }
+    if (scope !== 'openai' && anthropicModelIds(ctx).length) {
+        profiles.push({ name: claudeProfileName, id: claudeProfileId, model: preferredAnthropicModel(ctx) });
+    }
+    return profiles.length ? profiles : [fallbackProfileFor(ctx)];
+}
+function currentProfileFor(ctx, profiles = profilesFor(ctx)) {
+    if (ctx.providerScope === 'anthropic')
+        return profiles.find(profile => profile.id === claudeProfileId) || profiles[0];
+    if (ctx.providerScope === 'openai')
+        return profiles.find(profile => profile.id === codexProfileId) || profiles[0];
+    return profiles.find(profile => profile.id === codexProfileId) || profiles[0];
+}
 function parseSettings(text, file) {
     if (!text)
         return {};
@@ -35,21 +53,21 @@ function parseSettings(text, file) {
     }
 }
 function handoff(ctx) {
-    const profile = profileFor(ctx);
+    const profiles = profilesFor(ctx);
+    const current = currentProfileFor(ctx, profiles);
+    const apiConfigs = Object.fromEntries(profiles.map(profile => [profile.name, {
+            id: profile.id,
+            apiProvider: 'openai',
+            openAiBaseUrl: openAiBaseUrl(ctx.baseUrl),
+            openAiApiKey: ctx.apiKey,
+            openAiModelId: profile.model,
+            openAiStreamingEnabled: true,
+            includeMaxTokens: true
+        }]));
     return JSON.stringify({
         providerProfiles: {
-            currentApiConfigName: profile.name,
-            apiConfigs: {
-                [profile.name]: {
-                    id: profile.id,
-                    apiProvider: 'openai',
-                    openAiBaseUrl: openAiBaseUrl(ctx.baseUrl),
-                    openAiApiKey: ctx.apiKey,
-                    openAiModelId: profile.model,
-                    openAiStreamingEnabled: true,
-                    includeMaxTokens: true
-                }
-            },
+            currentApiConfigName: current.name,
+            apiConfigs,
             modeApiConfigs: {}
         },
         globalSettings: {}
@@ -90,14 +108,19 @@ export async function verify(ctx) {
     const profileFile = importPath(ctx.home);
     const settings = parseSettings(await fs.readFile(settingsFile, 'utf8'), settingsFile);
     const profile = await fs.readJson(profileFile).catch(() => undefined);
-    const expected = profileFor(ctx);
-    const config = profile?.providerProfiles?.apiConfigs?.[expected.name];
-    if (settings[importSetting] !== importSettingValue || profile?.providerProfiles?.currentApiConfigName !== expected.name
-        || config?.id !== expected.id || config?.apiProvider !== 'openai' || config?.openAiBaseUrl !== openAiBaseUrl(ctx.baseUrl)
-        || config?.openAiApiKey !== ctx.apiKey || config?.openAiModelId !== expected.model || config?.openAiStreamingEnabled !== true
-        || config?.includeMaxTokens !== true) {
+    const expectedProfiles = profilesFor(ctx);
+    const current = currentProfileFor(ctx, expectedProfiles);
+    if (settings[importSetting] !== importSettingValue || profile?.providerProfiles?.currentApiConfigName !== current.name) {
         throw new Error('Roo Code auto-import handoff is incomplete.');
     }
+    for (const expected of expectedProfiles) {
+        const config = profile?.providerProfiles?.apiConfigs?.[expected.name];
+        if (config?.id !== expected.id || config?.apiProvider !== 'openai' || config?.openAiBaseUrl !== openAiBaseUrl(ctx.baseUrl)
+            || config?.openAiApiKey !== ctx.apiKey || config?.openAiModelId !== expected.model || config?.openAiStreamingEnabled !== true
+            || config?.includeMaxTokens !== true) {
+            throw new Error('Roo Code auto-import handoff is incomplete.');
+        }
+    }
     if (ctx.platform !== 'win32' && ((await fs.stat(profileFile)).mode & 0o077) !== 0)
         throw new Error('Roo Code import handoff permissions are too broad.');
     return { id, name, changed: false, path: profileFile, message: 'verified supported auto-import handoff (runtime activation requires a VS Code reload)' };

package/dist/index.js

@@ -34,7 +34,7 @@ function welcome() {
 }
 function printHelp(command) {
     if (command === 'helper-bot') {
-        console.log('Usage: scalemax helper-bot [--model <id>] ["question"]\n\nOpen the ScaleMax-only installation, configuration, authentication, and troubleshooting assistant.');
+        console.log('Usage: scalemax helper-bot [--model <id>] ["question"]\n\nExecute safe ScaleMax setup and verification actions, or open the ScaleMax-only troubleshooting assistant.');
         return;
     }
     const details = { update: 'Revalidate the API key and reconfigure every detected client.', remove: 'Restore backups or remove only ScaleMax-managed client configuration.', doctor: 'Validate the API key and verify detected client configuration.', models: 'List models available to the stored API key.', login: 'Store or replace the ScaleMax API key.', logout: 'Remove the locally stored ScaleMax API key.' };
@@ -52,7 +52,7 @@ Commands:
   scalemax logout     Remove API key
   scalemax doctor     Run diagnostics
   scalemax models     List available models
-  scalemax helper-bot Open the ScaleMax Helper
+  scalemax helper-bot Execute setup actions or open the ScaleMax Helper
   scalemax update     Reconfigure detected clients
   scalemax remove     Remove ScaleMax-generated configs
   scalemax --version  Show installed version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scalemax",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Universal ScaleMax installer for AI coding clients",
   "type": "module",
   "bin": {