scalemax 0.1.21 → 0.1.23

package/README.md

@@ -113,13 +113,15 @@ 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. For example, `setup vs code roo extension for claude` detects or installs the official Roo Code extension, writes its ScaleMax Claude profile with the stored key, verifies the handoff, and reports each step. The language model never generates or executes shell commands; only fixed ScaleMax client detection, configuration, verification, rollback, and the official Roo Code extension installer 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,8 +1,10 @@
 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;
 export interface HelperBotArgs {
     question?: string;
     model?: string;
@@ -11,6 +13,11 @@ export interface HelperConnection {
     apiKey: string;
     baseUrl: string;
     model: string;
+    platform?: NodeJS.Platform;
+    providerScope?: 'openai' | 'anthropic' | 'both';
+    keyMode?: string;
+    availableModels?: string[];
+    modelCatalog?: ModelInfo[];
 }
 export type HelperCompletion = (options: ChatCompletionOptions) => Promise<ChatCompletionResult>;
 export interface HelperBotDependencies {
@@ -18,10 +25,22 @@ 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;
 export declare function isScaleMaxHelperQuestion(input: string, hasHistory?: boolean): boolean;
+export declare function isProviderIdentityOverride(value: string): boolean;
+export declare function helperRuntimeContext(connection: HelperConnection): string;
+export declare function helperConnectionSummary(connection: HelperConnection): string;
+/**
+ * Answer stable configuration questions locally. Besides being faster and free,
+ * this keeps provider-owned personas out of the installation path where exact
+ * field values matter more than generated prose.
+ */
+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,6 +1,9 @@
 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 { createChatCompletion, isAnthropicModel } from '../utils/api.js';
 import { redactApiKey } from '../utils/apiKey.js';
 import { loadApiKey } from '../utils/keyStore.js';
 import { homeDir } from '../utils/paths.js';
@@ -534,11 +537,35 @@ const CLEARLY_UNRELATED_PATTERN = /\b(?:homework|poem|story|roleplay|translate|t
 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 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 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)\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,
+    /\b(?:i\s+am|i['’]m)\s+(?:an?\s+)?(?:claude|chatgpt|codex)\b/i,
+    /\bas\s+(?:claude|chatgpt|codex)(?:\s+(?:ai|assistant|model))?\s*[,—-]/i,
+    /\b(?:i\s+am|i['’]m)\s+(?:an?\s+)?(?:ai[- ]powered\s+)?(?:development\s+environment|ai\s+assistant|assistant|language\s+model)\s+(?:made|built|created|developed)\s+by\s+(?:anthropic|openai)\b/i,
+    /\bi\s+(?:was|am)\s+(?:made|built|created|developed)\s+by\s+(?:anthropic|openai)\b/i,
+    /\b(?:i\s+am|i['’]m)\s+not\s+(?:the\s+)?(?:official\s+)?scalemax\s+helper\b/i,
+    /\bi\s+(?:cannot|can['’]?t|won['’]?t)\s+(?:become|act\s+as|identify\s+as)\s+(?:the\s+)?(?:official\s+)?scalemax\s+helper\b/i,
+    /\b(?:not|isn['’]?t)\s+(?:the\s+)?(?:official\s+)?scalemax\s+helper\b/i,
+    /\b(?:that|the|your|supplied)\s+(?:system\s+)?prompt\b.{0,120}\b(?:does\s+not|doesn['’]?t|cannot|can['’]?t|won['’]?t)\s+(?:override|change|replace)\b.{0,100}\b(?:identity|instructions?|role)\b/is,
+    /\bscalemax\b.{0,100}\b(?:does\s+not|doesn['’]?t)\s+(?:appear\s+to\s+)?(?:exist|be\s+real)\b/is
+];
+export const SCALEMAX_HELPER_INVALID_PROVIDER_RESPONSE = `ScaleMax Helper blocked an invalid provider response because it conflicted with the Helper's required identity.
+
+The requested ScaleMax task was not completed or verified. Run \`scalemax models\`, then retry with another available model using \`scalemax helper-bot --model <id> "your ScaleMax question"\`.`;
 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;
@@ -573,6 +600,91 @@ export function isScaleMaxHelperQuestion(input, hasHistory = false) {
         return false;
     return hasHistory || GREETING_PATTERN.test(value) || SCALEMAX_TOPIC_PATTERN.test(value) || TROUBLESHOOTING_PATTERN.test(value);
 }
+export function isProviderIdentityOverride(value) {
+    return PROVIDER_IDENTITY_OVERRIDE_PATTERNS.some(pattern => pattern.test(value));
+}
+function claudeDesktopGatewayBaseUrl(baseUrl) {
+    return baseUrl.trim().replace(/\/+$/, '').replace(/\/v1$/i, '');
+}
+function helperBillingMode(connection) {
+    return /\/token(?:\/|$)/i.test(connection.baseUrl) || /token/i.test(connection.keyMode || '') ? 'API token' : 'API credit';
+}
+function helperPlatformName(platform = process.platform) {
+    if (platform === 'win32')
+        return 'Windows';
+    if (platform === 'darwin')
+        return 'macOS';
+    if (platform === 'linux')
+        return 'Linux';
+    return platform;
+}
+export function helperRuntimeContext(connection) {
+    const models = (connection.availableModels || []).filter(Boolean);
+    return `# AUTHENTICATED SCALEMAX RUNTIME CONTEXT
+
+The ScaleMax CLI already verified these authoritative facts before starting this conversation:
+
+- Stored customer API key: present and authenticated. Never ask the user to paste, provide, repeat, or reveal it.
+- Billing mode: ${helperBillingMode(connection)}
+- OpenAI-compatible base URL: ${connection.baseUrl}
+- Claude Desktop gateway base URL: ${claudeDesktopGatewayBaseUrl(connection.baseUrl)}
+- Operating system: ${helperPlatformName(connection.platform)}
+- Provider scope: ${connection.providerScope || 'both'}
+- Active Helper model: ${connection.model}
+- Authenticated model catalog: ${models.length ? models.join(', ') : 'already validated by the CLI'}
+
+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. 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. 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}`;
+}
+/**
+ * Answer stable configuration questions locally. Besides being faster and free,
+ * this keeps provider-owned personas out of the installation path where exact
+ * field values matter more than generated prose.
+ */
+export function localHelperReply(question, connection) {
+    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.
+
+Configure Claude Desktop → Settings → Developer → Edit Config → Configure third-party inference with:
+
+- Connection: Gateway
+- Gateway base URL: ${gatewayBaseUrl}
+- Gateway API key: use the stored ScaleMax key (do not paste it into chat)
+- Authentication scheme: Bearer
+- Credential kind: Static API key
+- Model discovery: On
+
+Select Save Changes, then Apply Changes. Start a new Claude Desktop chat and send a short test message with one discovered model. The key and endpoint are verified; the Claude Desktop GUI is only verified after that test succeeds.`;
+    }
+    if (CODEX_CLI_PATTERN.test(question) && CLIENT_CONFIGURATION_PATTERN.test(question)) {
+        return `ScaleMax Helper already authenticated the stored ${helperBillingMode(connection)} key for ${helperPlatformName(connection.platform)}.
+
+You do not need to provide the API key or base URL again. This key uses:
+
+- Base URL: ${connection.baseUrl}
+- Provider scope: ${connection.providerScope || 'both'}
+
+Exit the Helper with \`/quit\`, then run:
+
+\`\`\`powershell
+scalemax update
+scalemax doctor
+codex
+\`\`\`
+
+\`scalemax update\` configures detected Codex CLI from the stored key, and \`scalemax doctor\` verifies the resulting ScaleMax connection before Codex starts.`;
+    }
+    return undefined;
+}
 export function selectHelperModel(models, requested) {
     if (requested) {
         const exact = models.find(model => model.id.toLowerCase() === requested.toLowerCase());
@@ -580,7 +692,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', '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)
@@ -596,20 +708,200 @@ export async function requestHelperReply(question, history, connection, complete
         throw new Error(`Please keep each helper request under ${MAX_USER_CHARS} characters.`);
     if (!isScaleMaxHelperQuestion(cleanQuestion, history.length > 0))
         return SCALEMAX_HELPER_REFUSAL;
+    const localReply = localHelperReply(cleanQuestion, connection);
+    if (localReply)
+        return localReply;
     const recentHistory = history.slice(-MAX_HISTORY_MESSAGES).map(message => ({ ...message, content: redactHelperSecrets(message.content, connection.apiKey) }));
     const result = await complete({
         apiKey: connection.apiKey,
         baseUrl: connection.baseUrl,
         model: connection.model,
         maxTokens: DEFAULT_MAX_TOKENS,
-        messages: [{ role: 'system', content: SCALEMAX_HELPER_SYSTEM_PROMPT }, ...recentHistory, { role: 'user', content: cleanQuestion }]
+        messages: [
+            { role: 'system', content: SCALEMAX_HELPER_SYSTEM_PROMPT },
+            { role: 'system', content: helperRuntimeContext(connection) },
+            ...recentHistory,
+            { role: 'user', content: cleanQuestion }
+        ]
     });
     if (!result.ok || !result.content)
         throw new Error(redactHelperSecrets(result.error || 'ScaleMax Helper did not return a response.', connection.apiKey));
-    return redactHelperSecrets(result.content, connection.apiKey);
+    const reply = redactHelperSecrets(result.content, connection.apiKey);
+    if (isProviderIdentityOverride(reply))
+        return SCALEMAX_HELPER_INVALID_PROVIDER_RESPONSE;
+    if (KNOWN_CONTEXT_REASK_PATTERN.test(reply)) {
+        return `ScaleMax Helper already authenticated the stored ${helperBillingMode(connection)} key. You do not need to provide the key, endpoint, operating system, or model catalog again.
+
+Verified base URL: ${connection.baseUrl}
+
+For automatic configuration, exit with \`/quit\`, run \`scalemax update\`, then run \`scalemax doctor\`.`;
+    }
+    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)\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\b/i }
+];
+function helperActionKind(question) {
+    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))
+        return 'all';
+    return HELPER_CLIENT_PATTERNS.find(candidate => candidate.pattern.test(question))?.id;
+}
+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 hasRooCodeExtension(paths) {
+    return paths.some(candidate => /^rooveterinaryinc\.roo-cline-/i.test(path.basename(candidate)));
+}
+async function installRooCodeExtension(ctx, client, write) {
+    let detection = await client.detect(ctx);
+    if (hasRooCodeExtension(detection.paths))
+        return;
+    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
+    };
+    write(`→ Detecting ${client.name}…`);
+    let detection = await client.detect(ctx);
+    if (kind === 'configure' && client.id === 'roo-code') {
+        await installRooCodeExtension(ctx, client, write);
+        detection = await client.detect(ctx);
+    }
+    if (!detection.installed)
+        throw new Error(`${client.name} was not detected. No configuration was changed.`);
+    write(`✓ ${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}`;
+    }
+    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 selected = target === 'all'
+        ? clientCatalog.filter(client => client.id !== 'cursor')
+        : clientCatalog.filter(client => client.id === target);
+    if (!selected.length)
+        throw new Error('The requested ScaleMax integration is not supported by this CLI build.');
+    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; /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 };
@@ -621,15 +913,29 @@ export async function helperBotCommand(args = [], home = homeDir(), dependencies
     if (!validation.ok || !validation.baseUrl)
         throw new Error(redactHelperSecrets(validation.error || 'Unable to validate the ScaleMax API key.', key));
     const model = selectHelperModel(validation.models, options.model);
-    const connection = { apiKey: key, baseUrl: validation.baseUrl, model };
+    const connection = {
+        apiKey: key,
+        baseUrl: validation.baseUrl,
+        model,
+        platform: process.platform,
+        providerScope: validation.key?.provider_scope || 'both',
+        keyMode: validation.key?.mode,
+        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)
         throw new Error('Interactive helper-bot requires a terminal. Pass a quoted question for non-interactive use.');
     deps.write(chalk.cyan('ScaleMax Helper'));
-    deps.write(chalk.dim(`Authenticated and ready with ${model}. Type /help or /quit.`));
+    deps.write(chalk.dim(helperConnectionSummary(connection)));
+    deps.write(chalk.dim('The stored customer key is reused for Helper requests; it will not be requested or displayed. Type /help or /quit.'));
     const reader = createInterface({ input: process.stdin, output: process.stdout });
     const history = [];
     try {
@@ -650,8 +956,12 @@ export async function helperBotCommand(args = [], home = homeDir(), dependencies
                 printSessionHelp(deps.write);
                 continue;
             }
+            if (/^\/?status$/i.test(input)) {
+                deps.write(helperConnectionSummary(connection));
+                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/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.21",
+  "version": "0.1.23",
   "description": "Universal ScaleMax installer for AI coding clients",
   "type": "module",
   "bin": {