scalemax 0.1.15 → 0.1.16

package/README.md

@@ -114,15 +114,15 @@ For clients without a stable official config file, the installer writes a ScaleM
 
 ### Claude Code
 
-ScaleMax updates `~/.claude/settings.json` with `ANTHROPIC_BASE_URL=https://api.scalemax.pro`, the stored key as `ANTHROPIC_AUTH_TOKEN`, and gateway model discovery. The Anthropic base URL intentionally has no `/v1` suffix because Claude Code adds `/v1/messages` itself. The CLI preserves unrelated settings, selects a live model from the authenticated catalog (preferring `claude-opus-4-8`), and verifies a one-token Messages request. If verification fails, it removes only the ScaleMax-managed changes. Claude Code picker aliases such as `claude-opus-4-8[1m]` are normalized by the gateway.
+ScaleMax updates `~/.claude/settings.json` with `ANTHROPIC_BASE_URL=https://api.scalemax.pro`, gateway model discovery, and a cached `apiKeyHelper` that reads a private `~/.claude/scalemax.key` file. The raw key is not stored in the settings JSON. The Anthropic base URL intentionally has no `/v1` suffix because Claude Code adds `/v1/messages` itself. The CLI preserves unrelated settings, selects a live main model from the authenticated catalog (preferring `claude-opus-4-8`), pins authenticated Haiku for lightweight background work when available, and verifies a one-token Messages request. If verification fails, it removes only the ScaleMax-managed changes. Claude Code picker aliases such as `claude-opus-4-8[1m]` are normalized by the gateway.
 
 ### OpenCode
 
-ScaleMax merges a named `scalemax` provider into `~/.config/opencode/opencode.json` (or the platform-equivalent config directory). It uses `https://api.scalemax.pro/v1`, keeps unrelated providers and the user's non-ScaleMax default model, and loads every model available to the authenticated key. Each generated model has an explicit output limit of at most 4096 tokens so OpenCode does not send an unsupported default limit.
+ScaleMax merges a named `scalemax` provider into `~/.config/opencode/opencode.json` (or the platform-equivalent config directory). It uses `https://api.scalemax.pro/v1`, reads its credential from the private `~/.config/opencode/scalemax.key` file through OpenCode's `{file:...}` substitution, keeps unrelated providers and the user's non-ScaleMax default model, and loads every model available to the authenticated key. A fresh ScaleMax setup uses authenticated Haiku as `small_model` for quicker lightweight work. Each generated model has an explicit output limit of at most 4096 tokens so OpenCode does not send an unsupported default limit.
 
 ### OpenClaw
 
-ScaleMax merges a native `anthropic-messages` provider into `~/.openclaw/openclaw.json`, using the Anthropic origin `https://api.scalemax.pro`. It adds every authenticated model to the provider and agent allowlist, caps generated output limits at 4096 tokens, and preserves unrelated providers and agent settings. Legacy ScaleMax artifacts are removed only when they carry the ScaleMax managed marker.
+ScaleMax merges a native `anthropic-messages` provider into `~/.openclaw/openclaw.json`, using the Anthropic origin `https://api.scalemax.pro`. The API key and the compatibility User-Agent are both OpenClaw file-backed SecretRefs stored in private `0600` files under `~/.openclaw/secrets/`; neither value is embedded in the provider JSON. The migration removes exact plaintext ScaleMax key copies from generated agent model registries. It adds every authenticated model to the provider and agent allowlist, uses authenticated Haiku for utility work when ScaleMax is the active provider, caps generated output limits at 4096 tokens, explicitly denies private-network routing for the public gateway, and preserves unrelated providers and agent settings. Legacy ScaleMax artifacts are removed only when they carry the ScaleMax managed marker.
 
 ### Hermes
 
@@ -153,6 +153,7 @@ npx scalemax models
 ```
 
 The model list is fetched live from `https://api.scalemax.pro/v1/models` every time, so disabled or unsupported models disappear immediately without manual cache cleanup.
+Key metadata and the authenticated model catalog are fetched concurrently on the normal path. Safe GET checks receive one short, jittered retry on transient network, rate-limit, or server failures; model-generation POST requests are never retried by the installer.
 
 Run diagnostics:
 
@@ -274,7 +275,11 @@ Never publish over an existing npm version. Use semantic versioning for every re
 
 - Existing client configuration files are backed up before writes.
 - Writes are atomic.
+- Identical configurations are not rewritten or backed up again.
+- Invalid JSON/JSON5 client files fail closed instead of being replaced; valid JSON5 values are merged safely.
+- Backup directories are user-only and backup files are written with private permissions.
 - API keys are masked in terminal output.
+- Claude Code, OpenCode, OpenClaw, and Hermes keep generated client credentials in private files rather than shared provider configuration blocks.
 - The published npm package contains only runtime files: `dist/`, `README.md`, `LICENSE`, and `package.json`.
 - Tests, TypeScript source, scripts, local caches, `.env` files, tarballs, and `node_modules` are excluded from the published package.
 

package/dist/configure/claude.js

@@ -1,57 +1,98 @@
 import fs from 'fs-extra';
 import crypto from 'node:crypto';
+import path from 'node:path';
 import { atomicWrite, backupFile } from '../utils/fs.js';
 import { clientConfigPath } from './paths.js';
 import { writeMergedJsonConfig } from './common.js';
 import { GENERATED_HEADER } from '../constants.js';
-import { anthropicOrigin, modelIds, preferredModel } from './models.js';
+import { redactApiKey } from '../utils/apiKey.js';
+import { anthropicOrigin, fastModel, modelIds, preferredModel } from './models.js';
+import { removeClientSecret, rollbackClientSecret, verifyClientSecret, writeClientSecret } from './client-secret.js';
 const id = 'claude';
 const name = 'Claude Code';
 const discoveryKey = 'CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY';
-const managedEnvKeys = ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL', 'ANTHROPIC_MODEL', discoveryKey];
+const fastModelKey = 'ANTHROPIC_DEFAULT_HAIKU_MODEL';
+const helperTtlKey = 'CLAUDE_CODE_API_KEY_HELPER_TTL_MS';
+const managedEnvKeys = ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL', 'ANTHROPIC_MODEL', discoveryKey, fastModelKey, helperTtlKey];
+function secretPath(home) { return path.join(home, '.claude', 'scalemax.key'); }
+function helperCommand(home, platform) {
+    const file = secretPath(home);
+    if (platform === 'win32')
+        return `powershell -NoProfile -Command "Get-Content -Raw -LiteralPath '${file.replace(/'/g, "''")}'"`;
+    return `cat '${file.replace(/'/g, `'\\''`)}'`;
+}
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
 export async function configure(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
     const model = preferredModel(ctx);
+    const quick = fastModel(ctx);
     const baseUrl = anthropicOrigin(ctx.baseUrl);
-    const result = await writeMergedJsonConfig(ctx, id, name, file, existing => {
-        const env = asRecord(existing.env);
-        const oldMetadata = asRecord(existing.scalemax);
-        const previousEnv = oldMetadata.managedBy === 'ScaleMax CLI'
-            ? asRecord(oldMetadata.previousEnv)
-            : Object.fromEntries(managedEnvKeys.filter(key => Object.prototype.hasOwnProperty.call(env, key)).map(key => [key, env[key]]));
-        return JSON.stringify({
-            ...existing,
-            env: {
+    const apiKeyHelper = helperCommand(ctx.home, ctx.platform);
+    const secret = await writeClientSecret(secretPath(ctx.home), ctx);
+    let result;
+    try {
+        result = await writeMergedJsonConfig(ctx, id, name, file, existing => {
+            const env = asRecord(existing.env);
+            const oldMetadata = asRecord(existing.scalemax);
+            const previousEnv = oldMetadata.managedBy === 'ScaleMax CLI'
+                ? asRecord(oldMetadata.previousEnv)
+                : Object.fromEntries(managedEnvKeys.filter(key => Object.prototype.hasOwnProperty.call(env, key)).map(key => [key, env[key]]));
+            const previousApiKeyHelper = oldMetadata.managedBy === 'ScaleMax CLI'
+                ? oldMetadata.previousApiKeyHelper ?? null
+                : Object.prototype.hasOwnProperty.call(existing, 'apiKeyHelper') ? existing.apiKeyHelper : null;
+            const nextEnv = {
                 ...env,
-                ANTHROPIC_AUTH_TOKEN: ctx.apiKey,
                 ANTHROPIC_BASE_URL: baseUrl,
                 ANTHROPIC_MODEL: model,
-                [discoveryKey]: '1'
-            },
-            'scalemax.managedBy': GENERATED_HEADER,
-            scalemax: {
-                managedBy: 'ScaleMax CLI',
-                anthropicModel: model,
-                anthropicBaseUrl: baseUrl,
-                gatewayDiscovery: '1',
-                authTokenSha256: crypto.createHash('sha256').update(ctx.apiKey).digest('hex'),
-                previousEnv
-            }
-        }, null, 2) + '\n';
-    });
-    return { ...result, message: `configured Anthropic Messages routing with ${model} and gateway model discovery` };
+                [discoveryKey]: '1',
+                [helperTtlKey]: '900000'
+            };
+            delete nextEnv.ANTHROPIC_AUTH_TOKEN;
+            delete nextEnv.ANTHROPIC_API_KEY;
+            if (quick)
+                nextEnv[fastModelKey] = quick;
+            else
+                delete nextEnv[fastModelKey];
+            return JSON.stringify({
+                ...existing,
+                apiKeyHelper,
+                env: nextEnv,
+                'scalemax.managedBy': GENERATED_HEADER,
+                scalemax: {
+                    managedBy: 'ScaleMax CLI',
+                    anthropicModel: model,
+                    anthropicBaseUrl: baseUrl,
+                    gatewayDiscovery: '1',
+                    fastModel: quick || null,
+                    helperTtl: '900000',
+                    apiKeyHelper,
+                    authTokenSha256: crypto.createHash('sha256').update(ctx.apiKey).digest('hex'),
+                    previousEnv,
+                    previousApiKeyHelper
+                }
+            }, null, 2) + '\n';
+        });
+    }
+    catch (error) {
+        await rollbackClientSecret(secretPath(ctx.home), ctx, secret);
+        throw error;
+    }
+    return { ...result, changed: result.changed || secret.changed, message: `configured Anthropic Messages routing with ${model}, file-backed authentication, and gateway discovery${quick ? `; ${quick} handles background work` : ''}` };
 }
 export async function verify(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
     const settings = await fs.readJson(file);
     const env = asRecord(settings?.env);
     const model = String(env.ANTHROPIC_MODEL || '');
-    if (!modelIds(ctx).includes(model) || env.ANTHROPIC_BASE_URL !== anthropicOrigin(ctx.baseUrl) || env.ANTHROPIC_AUTH_TOKEN !== ctx.apiKey || env[discoveryKey] !== '1') {
+    if (!modelIds(ctx).includes(model) || env.ANTHROPIC_BASE_URL !== anthropicOrigin(ctx.baseUrl) || settings.apiKeyHelper !== helperCommand(ctx.home, ctx.platform) || env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || env[discoveryKey] !== '1') {
         throw new Error('Claude Code settings do not match the authenticated ScaleMax model catalog.');
     }
+    await verifyClientSecret(secretPath(ctx.home), ctx);
+    const quick = fastModel(ctx);
+    if (quick && env[fastModelKey] !== quick)
+        throw new Error('Claude Code background model does not match the fastest authenticated model.');
     const response = await fetch(`${anthropicOrigin(ctx.baseUrl)}/v1/messages`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${ctx.apiKey}`, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
@@ -65,14 +106,16 @@ export async function verify(ctx) {
             message = body?.error?.message || message;
         }
         catch { }
-        throw new Error(`Claude Messages verification failed: ${message}`);
+        throw new Error(`Claude Messages verification failed: ${redactApiKey(message, ctx.apiKey)}`);
     }
     return { id, name, changed: false, path: file, message: `verified Anthropic Messages with ${model}` };
 }
 export async function remove(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
-    if (!(await fs.pathExists(file)))
-        return { id, name, changed: false, path: file, message: 'no ScaleMax configuration found' };
+    if (!(await fs.pathExists(file))) {
+        const removed = await removeClientSecret(secretPath(ctx.home), ctx);
+        return { id, name, changed: removed, path: file, message: removed ? 'removed orphaned ScaleMax Claude Code credential' : 'no ScaleMax configuration found' };
+    }
     const settings = await fs.readJson(file).catch(() => undefined);
     if (!settings || settings?.scalemax?.managedBy !== 'ScaleMax CLI')
         return { id, name, changed: false, path: file, message: 'left unmanaged configuration unchanged' };
@@ -91,8 +134,22 @@ export async function remove(ctx) {
         restore('ANTHROPIC_MODEL');
     if (env[discoveryKey] === managed.gatewayDiscovery)
         restore(discoveryKey);
+    if (env[fastModelKey] === managed.fastModel)
+        restore(fastModelKey);
+    if (env[helperTtlKey] === managed.helperTtl)
+        restore(helperTtlKey);
+    if (!Object.prototype.hasOwnProperty.call(env, 'ANTHROPIC_AUTH_TOKEN'))
+        restore('ANTHROPIC_AUTH_TOKEN');
+    if (!Object.prototype.hasOwnProperty.call(env, 'ANTHROPIC_API_KEY'))
+        restore('ANTHROPIC_API_KEY');
     if (typeof env.ANTHROPIC_AUTH_TOKEN === 'string' && crypto.createHash('sha256').update(env.ANTHROPIC_AUTH_TOKEN).digest('hex') === managed.authTokenSha256)
         restore('ANTHROPIC_AUTH_TOKEN');
+    if (settings.apiKeyHelper === managed.apiKeyHelper) {
+        if (managed.previousApiKeyHelper === null || managed.previousApiKeyHelper === undefined)
+            delete settings.apiKeyHelper;
+        else
+            settings.apiKeyHelper = managed.previousApiKeyHelper;
+    }
     if (Object.keys(env).length)
         settings.env = env;
     else
@@ -104,5 +161,6 @@ export async function remove(ctx) {
         await atomicWrite(file, JSON.stringify(settings, null, 2) + '\n', 0o600, ctx.platform);
     else
         await fs.remove(file);
-    return { id, name, changed: true, path: file, message: 'removed only ScaleMax Claude Code settings' };
+    await removeClientSecret(secretPath(ctx.home), ctx);
+    return { id, name, changed: true, path: file, message: 'removed only ScaleMax Claude Code settings and credential' };
 }

package/dist/configure/client-secret.d.ts

@@ -0,0 +1,11 @@
+import { ConfigureContext } from '../types/client.js';
+export declare function writeClientSecret(file: string, ctx: ConfigureContext): Promise<{
+    changed: boolean;
+    backup?: string;
+}>;
+export declare function rollbackClientSecret(file: string, ctx: ConfigureContext, change: {
+    changed: boolean;
+    backup?: string;
+}): Promise<void>;
+export declare function verifyClientSecret(file: string, ctx: ConfigureContext): Promise<void>;
+export declare function removeClientSecret(file: string, ctx: ConfigureContext): Promise<boolean>;

package/dist/configure/client-secret.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { sanitizeApiKey } from '../utils/apiKey.js';
+import { atomicWrite, backupFile } from '../utils/fs.js';
+export async function writeClientSecret(file, ctx) {
+    const content = `${sanitizeApiKey(ctx.apiKey)}\n`;
+    const current = await fs.readFile(file, 'utf8').catch(() => '');
+    await fs.ensureDir(path.dirname(file), 0o700);
+    await fs.chmod(path.dirname(file), 0o700).catch(() => undefined);
+    if (current === content) {
+        await fs.chmod(file, 0o600).catch(() => undefined);
+        return { changed: false };
+    }
+    const backup = await backupFile(file, ctx.home);
+    await atomicWrite(file, content, 0o600, ctx.platform);
+    return { changed: true, backup };
+}
+export async function rollbackClientSecret(file, ctx, change) {
+    if (!change.changed)
+        return;
+    if (change.backup) {
+        const previous = await fs.readFile(change.backup, 'utf8');
+        await atomicWrite(file, previous, 0o600, ctx.platform);
+        return;
+    }
+    await fs.remove(file).catch(() => undefined);
+}
+export async function verifyClientSecret(file, ctx) {
+    const content = await fs.readFile(file, 'utf8').catch(() => '');
+    if (sanitizeApiKey(content) !== sanitizeApiKey(ctx.apiKey))
+        throw new Error('ScaleMax client credential is missing or does not match the authenticated key.');
+    if (ctx.platform !== 'win32') {
+        const mode = (await fs.stat(file)).mode & 0o777;
+        if (mode !== 0o600)
+            throw new Error(`ScaleMax client credential permissions are ${mode.toString(8)}; expected 600.`);
+    }
+}
+export async function removeClientSecret(file, ctx) {
+    if (!(await fs.pathExists(file)))
+        return false;
+    const content = await fs.readFile(file, 'utf8').catch(() => '');
+    if (sanitizeApiKey(content) !== sanitizeApiKey(ctx.apiKey))
+        return false;
+    await backupFile(file, ctx.home);
+    await fs.remove(file);
+    return true;
+}

package/dist/configure/common.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
-import { atomicWrite, backupFile, listBackups, readJson } from '../utils/fs.js';
+import JSON5 from 'json5';
+import { atomicWrite, backupFile, listBackups } from '../utils/fs.js';
 import { GENERATED_HEADER } from '../constants.js';
 export function isScaleMaxManagedText(text) {
     return text.includes(GENERATED_HEADER) || text.includes('"scalemax.managedBy"') || text.includes('"managedBy": "ScaleMax CLI generated file"');
@@ -11,6 +12,10 @@ export async function writeManagedConfig(ctx, id, name, file, content) {
         const current = await fs.readFile(file, 'utf8');
         if (!isScaleMaxManagedText(current))
             throw new Error(`Refusing to overwrite unmanaged configuration: ${file}`);
+        if (current === content) {
+            await fs.chmod(file, 0o600).catch(() => undefined);
+            return { id, name, changed: false, path: file, message: 'already current' };
+        }
     }
     const backup = await backupFile(file, ctx.home);
     await atomicWrite(file, content, 0o600, ctx.platform);
@@ -18,9 +23,30 @@ export async function writeManagedConfig(ctx, id, name, file, content) {
 }
 export async function writeMergedJsonConfig(ctx, id, name, file, build) {
     await fs.ensureDir(path.dirname(file));
-    const existing = await readJson(file, {});
+    const current = await fs.readFile(file, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return '';
+        throw error;
+    });
+    let existing = {};
+    if (current) {
+        try {
+            const parsed = JSON5.parse(current);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new Error('the root value must be an object');
+            existing = parsed;
+        }
+        catch (error) {
+            throw new Error(`Refusing to overwrite invalid JSON/JSON5 configuration at ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const content = build(existing);
+    if (current === content) {
+        await fs.chmod(file, 0o600).catch(() => undefined);
+        return { id, name, changed: false, path: file, message: 'already current' };
+    }
     const backup = await backupFile(file, ctx.home);
-    await atomicWrite(file, build(existing), 0o600, ctx.platform);
+    await atomicWrite(file, content, 0o600, ctx.platform);
     return { id, name, changed: true, path: file, message: backup ? `configured (backup: ${backup})` : 'configured' };
 }
 async function latestRestorableBackup(file, home) {

package/dist/configure/hermes.js

@@ -55,7 +55,8 @@ async function removeLegacyArtifact(ctx) {
 export async function configure(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
     const secrets = envPath(ctx.home);
-    await fs.ensureDir(path.dirname(file));
+    await fs.ensureDir(path.dirname(file), 0o700);
+    await fs.chmod(path.dirname(file), 0o700).catch(() => undefined);
     const originalConfig = await fs.readFile(file, 'utf8').catch(() => '');
     const originalEnv = await fs.readFile(secrets, 'utf8').catch(() => '');
     const doc = parseYaml(originalConfig);
@@ -76,10 +77,18 @@ export async function configure(ctx) {
     if (activatesScaleMax) {
         doc.set('model', { ...currentModel, provider: 'custom:scalemax', default: preferredModel(ctx), max_tokens: 4096 });
     }
+    const nextConfig = String(doc);
+    const nextEnv = managedEnv(originalEnv, ctx.apiKey);
+    if (originalConfig === nextConfig && originalEnv === nextEnv) {
+        await fs.chmod(file, 0o600).catch(() => undefined);
+        await fs.chmod(secrets, 0o600).catch(() => undefined);
+        await removeLegacyArtifact(ctx);
+        return { id, name, changed: false, path: file, message: `already current with ${modelIds(ctx).length} models and a private credential` };
+    }
     const backups = [await backupFile(file, ctx.home), await backupFile(secrets, ctx.home)].filter(Boolean);
     try {
-        await atomicWrite(file, String(doc), 0o600, ctx.platform);
-        await atomicWrite(secrets, managedEnv(originalEnv, ctx.apiKey), 0o600, ctx.platform);
+        await atomicWrite(file, nextConfig, 0o600, ctx.platform);
+        await atomicWrite(secrets, nextEnv, 0o600, ctx.platform);
         await removeLegacyArtifact(ctx);
     }
     catch (error) {

package/dist/configure/models.d.ts

@@ -1,6 +1,7 @@
 import { ConfigureContext } from '../types/client.js';
 export declare function modelIds(ctx: ConfigureContext): string[];
 export declare function preferredModel(ctx: ConfigureContext): string;
+export declare function fastModel(ctx: ConfigureContext): string | undefined;
 export declare function modelName(ctx: ConfigureContext, id: string): string;
 export declare function anthropicOrigin(baseUrl: string): string;
 export declare function openAiBaseUrl(baseUrl: string): string;

package/dist/configure/models.js

@@ -19,6 +19,11 @@ export function preferredModel(ctx) {
         return ids[0];
     throw new Error('No compatible models are available for this API key; the client was not changed.');
 }
+export function fastModel(ctx) {
+    const ids = modelIds(ctx);
+    return ids.find(id => id === 'claude-haiku-4-5-20251001')
+        || ids.find(id => /(^|-)haiku([-.]|$)/i.test(id));
+}
 export function modelName(ctx, id) {
     const model = (ctx.models || []).find(candidate => candidate.id === id);
     if (model?.display_name)

package/dist/configure/openclaw.js

@@ -3,9 +3,20 @@ import fs from 'fs-extra';
 import { atomicWrite, backupFile } from '../utils/fs.js';
 import { clientConfigPath } from './paths.js';
 import { isScaleMaxManagedText, writeMergedJsonConfig } from './common.js';
-import { anthropicOrigin, modelIds, modelName, preferredModel } from './models.js';
+import { anthropicOrigin, fastModel, modelIds, modelName, preferredModel } from './models.js';
+import { removeClientSecret, rollbackClientSecret, verifyClientSecret, writeClientSecret } from './client-secret.js';
 const id = 'openclaw';
 const name = 'OpenClaw';
+const secretProviderId = 'scalemax_cli';
+const secretConfigPath = '~/.openclaw/secrets/scalemax-api-key';
+const secretReference = { source: 'file', provider: secretProviderId, id: 'value' };
+const userAgentProviderId = 'scalemax_cli_user_agent';
+const userAgentConfigPath = '~/.openclaw/secrets/scalemax-user-agent';
+const userAgentValue = 'ScaleMax-OpenClaw/1.0';
+const userAgentReference = { source: 'file', provider: userAgentProviderId, id: 'value' };
+function secretPath(home) { return path.join(home, '.openclaw', 'secrets', 'scalemax-api-key'); }
+function userAgentPath(home) { return path.join(home, '.openclaw', 'secrets', 'scalemax-user-agent'); }
+function userAgentContext(ctx) { return { ...ctx, apiKey: userAgentValue }; }
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
@@ -33,54 +44,125 @@ async function removeLegacyArtifact(ctx) {
     await backupFile(legacy, ctx.home);
     await fs.remove(legacy);
 }
+async function scrubGeneratedPlaintextCredentials(ctx) {
+    const agentsDir = path.join(ctx.home, '.openclaw', 'agents');
+    const agents = await fs.readdir(agentsDir, { withFileTypes: true }).catch(() => []);
+    let changed = 0;
+    for (const agent of agents) {
+        if (!agent.isDirectory())
+            continue;
+        const file = path.join(agentsDir, agent.name, 'agent', 'models.json');
+        if (!(await fs.pathExists(file)))
+            continue;
+        const original = await fs.readFile(file, 'utf8').catch(() => '');
+        let data;
+        try {
+            data = JSON.parse(original);
+        }
+        catch {
+            continue;
+        }
+        const roots = [asRecord(data.providers), asRecord(asRecord(data.models).providers)];
+        let scrubbed = false;
+        for (const providers of roots) {
+            const provider = asRecord(providers.scalemax);
+            if (provider.baseUrl === anthropicOrigin(ctx.baseUrl) && provider.apiKey === ctx.apiKey) {
+                delete provider.apiKey;
+                scrubbed = true;
+            }
+        }
+        if (!scrubbed)
+            continue;
+        await backupFile(file, ctx.home);
+        await atomicWrite(file, JSON.stringify(data, null, 2) + '\n', 0o600, ctx.platform);
+        changed++;
+    }
+    return changed;
+}
 export async function configure(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
     const primary = `scalemax/${preferredModel(ctx)}`;
-    const result = await writeMergedJsonConfig(ctx, id, name, file, existing => {
-        const modelsRoot = asRecord(existing.models);
-        const providers = asRecord(modelsRoot.providers);
-        const agents = asRecord(existing.agents);
-        const defaults = asRecord(agents.defaults);
-        const allowlist = asRecord(defaults.models);
-        for (const modelId of modelIds(ctx))
-            allowlist[`scalemax/${modelId}`] = asRecord(allowlist[`scalemax/${modelId}`]);
-        const currentModel = defaults.model;
-        const currentPrimary = typeof currentModel === 'string' ? currentModel : asRecord(currentModel).primary;
-        const nextModel = !currentPrimary || String(currentPrimary).startsWith('scalemax/')
-            ? { ...asRecord(currentModel), primary }
-            : currentModel;
-        return JSON.stringify({
-            ...existing,
-            models: {
-                ...modelsRoot,
-                mode: modelsRoot.mode || 'merge',
-                providers: {
-                    ...providers,
-                    scalemax: {
-                        baseUrl: anthropicOrigin(ctx.baseUrl),
-                        apiKey: ctx.apiKey,
-                        api: 'anthropic-messages',
-                        maxTokens: 4096,
-                        models: entries(ctx)
+    const quick = fastModel(ctx);
+    let secret = { changed: false };
+    let userAgentSecret = { changed: false };
+    let result;
+    try {
+        secret = await writeClientSecret(secretPath(ctx.home), ctx);
+        userAgentSecret = await writeClientSecret(userAgentPath(ctx.home), userAgentContext(ctx));
+        result = await writeMergedJsonConfig(ctx, id, name, file, existing => {
+            const modelsRoot = asRecord(existing.models);
+            const providers = asRecord(modelsRoot.providers);
+            const secretsRoot = asRecord(existing.secrets);
+            const secretProviders = asRecord(secretsRoot.providers);
+            const agents = asRecord(existing.agents);
+            const defaults = asRecord(agents.defaults);
+            const allowlist = asRecord(defaults.models);
+            for (const modelId of modelIds(ctx))
+                allowlist[`scalemax/${modelId}`] = asRecord(allowlist[`scalemax/${modelId}`]);
+            const currentModel = defaults.model;
+            const currentPrimary = typeof currentModel === 'string' ? currentModel : asRecord(currentModel).primary;
+            const activatesScaleMax = !currentPrimary || String(currentPrimary).startsWith('scalemax/');
+            const nextModel = activatesScaleMax
+                ? { ...asRecord(currentModel), primary }
+                : currentModel;
+            const currentUtility = typeof defaults.utilityModel === 'string' ? defaults.utilityModel : undefined;
+            const utilityModel = quick && (activatesScaleMax || currentUtility?.startsWith('scalemax/')) ? `scalemax/${quick}` : currentUtility;
+            return JSON.stringify({
+                ...existing,
+                secrets: {
+                    ...secretsRoot,
+                    providers: {
+                        ...secretProviders,
+                        [secretProviderId]: { source: 'file', path: secretConfigPath, mode: 'singleValue' },
+                        [userAgentProviderId]: { source: 'file', path: userAgentConfigPath, mode: 'singleValue' }
                     }
+                },
+                models: {
+                    ...modelsRoot,
+                    mode: modelsRoot.mode || 'merge',
+                    providers: {
+                        ...providers,
+                        scalemax: {
+                            baseUrl: anthropicOrigin(ctx.baseUrl),
+                            apiKey: secretReference,
+                            api: 'anthropic-messages',
+                            maxTokens: 4096,
+                            request: {
+                                headers: { 'User-Agent': userAgentReference },
+                                allowPrivateNetwork: false
+                            },
+                            models: entries(ctx)
+                        }
+                    }
+                },
+                agents: {
+                    ...agents,
+                    defaults: { ...defaults, model: nextModel, models: allowlist, ...(utilityModel ? { utilityModel } : {}) }
                 }
-            },
-            agents: {
-                ...agents,
-                defaults: { ...defaults, model: nextModel, models: allowlist }
-            }
-        }, null, 2) + '\n';
-    });
+            }, null, 2) + '\n';
+        });
+    }
+    catch (error) {
+        await rollbackClientSecret(userAgentPath(ctx.home), userAgentContext(ctx), userAgentSecret);
+        await rollbackClientSecret(secretPath(ctx.home), ctx, secret);
+        throw error;
+    }
     await removeLegacyArtifact(ctx);
-    return { ...result, message: `configured native Anthropic provider with ${modelIds(ctx).length} models` };
+    const scrubbed = await scrubGeneratedPlaintextCredentials(ctx);
+    return { ...result, changed: result.changed || secret.changed || userAgentSecret.changed || scrubbed > 0, message: `configured native Anthropic provider with ${modelIds(ctx).length} models and file-backed SecretRefs${quick ? `; ${quick} handles utility work` : ''}${scrubbed ? `; scrubbed ${scrubbed} generated credential ${scrubbed === 1 ? 'copy' : 'copies'}` : ''}` };
 }
 export async function verify(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
     const config = await fs.readJson(file);
     const provider = config?.models?.providers?.scalemax;
-    if (provider?.baseUrl !== anthropicOrigin(ctx.baseUrl) || provider?.apiKey !== ctx.apiKey || provider?.api !== 'anthropic-messages') {
+    const secretProvider = config?.secrets?.providers?.[secretProviderId];
+    const userAgentProvider = config?.secrets?.providers?.[userAgentProviderId];
+    const userAgent = provider?.request?.headers?.['User-Agent'];
+    if (provider?.baseUrl !== anthropicOrigin(ctx.baseUrl) || provider?.apiKey?.source !== secretReference.source || provider?.apiKey?.provider !== secretReference.provider || provider?.apiKey?.id !== secretReference.id || provider?.api !== 'anthropic-messages' || secretProvider?.source !== 'file' || secretProvider?.path !== secretConfigPath || secretProvider?.mode !== 'singleValue' || userAgent?.source !== userAgentReference.source || userAgent?.provider !== userAgentReference.provider || userAgent?.id !== userAgentReference.id || userAgentProvider?.source !== 'file' || userAgentProvider?.path !== userAgentConfigPath || userAgentProvider?.mode !== 'singleValue') {
         throw new Error('OpenClaw ScaleMax provider settings are incomplete.');
     }
+    await verifyClientSecret(secretPath(ctx.home), ctx);
+    await verifyClientSecret(userAgentPath(ctx.home), userAgentContext(ctx));
     const configured = new Set((Array.isArray(provider.models) ? provider.models : []).map((model) => model?.id));
     const missing = modelIds(ctx).filter(model => !configured.has(model));
     if (missing.length)
@@ -89,8 +171,11 @@ export async function verify(ctx) {
 }
 export async function remove(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
-    if (!(await fs.pathExists(file)))
-        return { id, name, changed: false, path: file, message: 'no ScaleMax configuration found' };
+    if (!(await fs.pathExists(file))) {
+        const removed = await removeClientSecret(secretPath(ctx.home), ctx);
+        const removedUserAgent = await removeClientSecret(userAgentPath(ctx.home), userAgentContext(ctx));
+        return { id, name, changed: removed || removedUserAgent, path: file, message: removed || removedUserAgent ? 'removed orphaned ScaleMax OpenClaw credentials' : 'no ScaleMax configuration found' };
+    }
     const config = await fs.readJson(file).catch(() => undefined);
     if (!config?.models?.providers?.scalemax || config.models.providers.scalemax.baseUrl !== anthropicOrigin(ctx.baseUrl)) {
         return { id, name, changed: false, path: file, message: 'left unmanaged configuration unchanged' };
@@ -115,15 +200,30 @@ export async function remove(ctx) {
         if (!Object.keys(defaults.model).length)
             delete defaults.model;
     }
+    if (typeof defaults?.utilityModel === 'string' && defaults.utilityModel.startsWith('scalemax/'))
+        delete defaults.utilityModel;
     if (defaults && !Object.keys(defaults).length)
         delete config.agents.defaults;
     if (config.agents && !Object.keys(config.agents).length)
         delete config.agents;
+    const secretProvider = config?.secrets?.providers?.[secretProviderId];
+    if (secretProvider?.source === 'file' && secretProvider?.path === secretConfigPath && secretProvider?.mode === 'singleValue') {
+        delete config.secrets.providers[secretProviderId];
+    }
+    const userAgentProvider = config?.secrets?.providers?.[userAgentProviderId];
+    if (userAgentProvider?.source === 'file' && userAgentProvider?.path === userAgentConfigPath && userAgentProvider?.mode === 'singleValue')
+        delete config.secrets.providers[userAgentProviderId];
+    if (config?.secrets?.providers && !Object.keys(config.secrets.providers).length)
+        delete config.secrets.providers;
+    if (config?.secrets && !Object.keys(config.secrets).length)
+        delete config.secrets;
     await backupFile(file, ctx.home);
     if (Object.keys(config).length)
         await atomicWrite(file, JSON.stringify(config, null, 2) + '\n', 0o600, ctx.platform);
     else
         await fs.remove(file);
+    await removeClientSecret(secretPath(ctx.home), ctx);
+    await removeClientSecret(userAgentPath(ctx.home), userAgentContext(ctx));
     await removeLegacyArtifact(ctx);
-    return { id, name, changed: true, path: file, message: 'removed only the ScaleMax provider and model entries' };
+    return { id, name, changed: true, path: file, message: 'removed only the ScaleMax provider, model entries, and credential' };
 }

package/dist/configure/opencode.js

@@ -1,10 +1,14 @@
+import path from 'node:path';
 import fs from 'fs-extra';
 import { atomicWrite, backupFile } from '../utils/fs.js';
 import { clientConfigPath } from './paths.js';
 import { writeMergedJsonConfig } from './common.js';
-import { modelIds, modelName, openAiBaseUrl, preferredModel } from './models.js';
+import { fastModel, modelIds, modelName, openAiBaseUrl, preferredModel } from './models.js';
+import { removeClientSecret, rollbackClientSecret, verifyClientSecret, writeClientSecret } from './client-secret.js';
 const id = 'opencode';
 const name = 'OpenCode';
+const secretReference = '{file:~/.config/opencode/scalemax.key}';
+function secretPath(home) { return path.join(home, '.config', 'opencode', 'scalemax.key'); }
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
@@ -22,31 +26,45 @@ function providerConfig(ctx) {
     return {
         npm: '@ai-sdk/openai-compatible',
         name: 'ScaleMax',
-        options: { baseURL: openAiBaseUrl(ctx.baseUrl), apiKey: ctx.apiKey },
+        options: { baseURL: openAiBaseUrl(ctx.baseUrl), apiKey: secretReference },
         models
     };
 }
 export async function configure(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
     const selected = `scalemax/${preferredModel(ctx)}`;
-    return writeMergedJsonConfig(ctx, id, name, file, existing => {
-        const providers = asRecord(existing.provider);
-        const currentModel = typeof existing.model === 'string' ? existing.model : undefined;
-        return JSON.stringify({
-            ...existing,
-            $schema: typeof existing.$schema === 'string' ? existing.$schema : 'https://opencode.ai/config.json',
-            provider: { ...providers, scalemax: providerConfig(ctx) },
-            model: !currentModel || currentModel.startsWith('scalemax/') ? selected : currentModel
-        }, null, 2) + '\n';
-    });
+    const quick = fastModel(ctx);
+    const secret = await writeClientSecret(secretPath(ctx.home), ctx);
+    let result;
+    try {
+        result = await writeMergedJsonConfig(ctx, id, name, file, existing => {
+            const providers = asRecord(existing.provider);
+            const currentModel = typeof existing.model === 'string' ? existing.model : undefined;
+            const currentSmallModel = typeof existing.small_model === 'string' ? existing.small_model : undefined;
+            const activatesScaleMax = !currentModel || currentModel.startsWith('scalemax/');
+            return JSON.stringify({
+                ...existing,
+                $schema: typeof existing.$schema === 'string' ? existing.$schema : 'https://opencode.ai/config.json',
+                provider: { ...providers, scalemax: providerConfig(ctx) },
+                model: activatesScaleMax ? selected : currentModel,
+                ...(quick && (activatesScaleMax || currentSmallModel?.startsWith('scalemax/')) ? { small_model: `scalemax/${quick}` } : {})
+            }, null, 2) + '\n';
+        });
+    }
+    catch (error) {
+        await rollbackClientSecret(secretPath(ctx.home), ctx, secret);
+        throw error;
+    }
+    return { ...result, changed: result.changed || secret.changed, message: `${result.message}; file-backed credential${quick ? `; ${quick} handles lightweight work` : ''}` };
 }
 export async function verify(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
     const config = await fs.readJson(file);
     const provider = config?.provider?.scalemax;
-    if (provider?.npm !== '@ai-sdk/openai-compatible' || provider?.options?.baseURL !== openAiBaseUrl(ctx.baseUrl) || provider?.options?.apiKey !== ctx.apiKey) {
+    if (provider?.npm !== '@ai-sdk/openai-compatible' || provider?.options?.baseURL !== openAiBaseUrl(ctx.baseUrl) || provider?.options?.apiKey !== secretReference) {
         throw new Error('OpenCode ScaleMax provider settings are incomplete.');
     }
+    await verifyClientSecret(secretPath(ctx.home), ctx);
     const configured = Object.keys(asRecord(provider.models));
     const missing = modelIds(ctx).filter(model => !configured.includes(model));
     if (missing.length)
@@ -55,8 +73,10 @@ export async function verify(ctx) {
 }
 export async function remove(ctx) {
     const file = clientConfigPath(id, ctx.home, ctx.platform);
-    if (!(await fs.pathExists(file)))
-        return { id, name, changed: false, path: file, message: 'no ScaleMax configuration found' };
+    if (!(await fs.pathExists(file))) {
+        const removed = await removeClientSecret(secretPath(ctx.home), ctx);
+        return { id, name, changed: removed, path: file, message: removed ? 'removed orphaned ScaleMax OpenCode credential' : 'no ScaleMax configuration found' };
+    }
     const config = await fs.readJson(file).catch(() => undefined);
     if (!config?.provider?.scalemax || config.provider.scalemax.name !== 'ScaleMax' || config.provider.scalemax.options?.baseURL !== openAiBaseUrl(ctx.baseUrl))
         return { id, name, changed: false, path: file, message: 'left unmanaged configuration unchanged' };
@@ -65,7 +85,10 @@ export async function remove(ctx) {
         delete config.provider;
     if (typeof config.model === 'string' && config.model.startsWith('scalemax/'))
         delete config.model;
+    if (typeof config.small_model === 'string' && config.small_model.startsWith('scalemax/'))
+        delete config.small_model;
     await backupFile(file, ctx.home);
     await atomicWrite(file, JSON.stringify(config, null, 2) + '\n', 0o600, ctx.platform);
-    return { id, name, changed: true, path: file, message: 'removed only the ScaleMax provider' };
+    await removeClientSecret(secretPath(ctx.home), ctx);
+    return { id, name, changed: true, path: file, message: 'removed only the ScaleMax provider and credential' };
 }

package/dist/utils/api.js

@@ -1,5 +1,5 @@
 import { SCALEMAX_BASE_URL } from '../constants.js';
-import { sanitizeApiKey } from './apiKey.js';
+import { redactApiKey, sanitizeApiKey } from './apiKey.js';
 export function isAnthropicModel(model) {
     const provider = String(model.provider || model.owned_by || '').trim().toLowerCase();
     if (provider)
@@ -31,27 +31,48 @@ async function friendlyError(res) {
         return message || 'ScaleMax is temporarily unavailable. Please try again shortly.';
     return message || `HTTP ${res.status}`;
 }
-async function request(path, apiKey, init = {}) {
+function retryableStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+async function request(path, apiKey, init = {}, retryGet = false) {
     const headers = new Headers(init.headers);
     if (apiKey)
         headers.set('Authorization', `Bearer ${sanitizeApiKey(apiKey)}`);
     headers.set('Cache-Control', 'no-cache');
     if (!headers.has('Content-Type') && init.body)
         headers.set('Content-Type', 'application/json');
-    const timeout = AbortSignal.timeout(15000);
-    const signal = init.signal && typeof AbortSignal.any === 'function' ? AbortSignal.any([init.signal, timeout]) : timeout;
-    return fetch(`${SCALEMAX_BASE_URL}${path}`, { ...init, headers, signal });
+    const attempts = retryGet && (!init.method || init.method === 'GET') ? 2 : 1;
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const timeout = AbortSignal.timeout(15000);
+        const signal = init.signal && typeof AbortSignal.any === 'function' ? AbortSignal.any([init.signal, timeout]) : timeout;
+        try {
+            const response = await fetch(`${SCALEMAX_BASE_URL}${path}`, { ...init, headers, signal });
+            if (attempt + 1 === attempts || !retryableStatus(response.status))
+                return response;
+            await response.body?.cancel().catch(() => undefined);
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt + 1 === attempts)
+                throw error;
+        }
+        await new Promise(resolve => setTimeout(resolve, 125 + Math.floor(Math.random() * 126)));
+    }
+    throw lastError;
 }
 export async function validateApiKey(apiKey) {
     try {
-        const authCheck = await request('/usage', apiKey);
+        const [authCheck, modelsRes] = await Promise.all([
+            request('/usage', apiKey, {}, true),
+            request('/models', apiKey, {}, true)
+        ]);
         if (!authCheck.ok)
-            return { ok: false, models: [], error: await friendlyError(authCheck) };
+            return { ok: false, models: [], error: redactApiKey(await friendlyError(authCheck), apiKey) };
         const usage = await authCheck.json().catch(() => ({}));
         const keyMeta = { provider_scope: usage?.key?.provider_scope || 'both', mode: usage?.key?.mode, prefix: usage?.key?.prefix, label: usage?.key?.label };
-        const modelsRes = await request('/models', apiKey);
         if (!modelsRes.ok)
-            return { ok: false, models: [], key: keyMeta, error: await friendlyError(modelsRes) };
+            return { ok: false, models: [], key: keyMeta, error: redactApiKey(await friendlyError(modelsRes), apiKey) };
         const data = await modelsRes.json();
         const catalog = Array.isArray(data.data) ? data.data : [];
         const models = filterModelsForScope(catalog, keyMeta.provider_scope);
@@ -60,7 +81,7 @@ export async function validateApiKey(apiKey) {
         return { ok: true, models, key: keyMeta };
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
+        const message = redactApiKey(err instanceof Error ? err.message : String(err), apiKey);
         return { ok: false, models: [], error: /abort|timeout/i.test(message) ? 'ScaleMax request timed out after 15 seconds.' : message };
     }
 }
@@ -69,7 +90,7 @@ export async function testStreaming(apiKey, model) {
     try {
         const res = await request('/chat/completions', apiKey, { method: 'POST', body: JSON.stringify({ model: selected, stream: true, max_tokens: 8, messages: [{ role: 'user', content: 'Say OK' }] }) });
         if (!res.ok)
-            return { ok: false, error: await friendlyError(res) };
+            return { ok: false, error: redactApiKey(await friendlyError(res), apiKey) };
         const ct = res.headers.get('content-type') || '';
         if (!ct.includes('text/event-stream'))
             return { ok: false, error: `Expected event stream, got ${ct}` };

package/dist/utils/apiKey.d.ts

@@ -1 +1,2 @@
 export declare function sanitizeApiKey(input: unknown): string;
+export declare function redactApiKey(message: unknown, apiKey?: string): string;

package/dist/utils/apiKey.js

@@ -6,3 +6,8 @@ export function sanitizeApiKey(input) {
         .replace(ASCII_WHITESPACE_RE, '')
         .trim();
 }
+export function redactApiKey(message, apiKey) {
+    const text = String(message ?? '');
+    const key = apiKey ? sanitizeApiKey(apiKey) : '';
+    return key ? text.split(key).join('[REDACTED]') : text;
+}

package/dist/utils/fs.js

@@ -52,8 +52,10 @@ export async function backupFile(file, home) {
     if (!(await fs.pathExists(file)))
         return undefined;
     const dest = path.join(backupDir(home), `${timestamp()}__${backupNameFor(file)}`);
-    await fs.ensureDir(path.dirname(dest));
+    await fs.ensureDir(path.dirname(dest), 0o700);
+    await fs.chmod(path.dirname(dest), 0o700).catch(() => undefined);
     await fs.copy(file, dest, { overwrite: false, errorOnExist: true });
+    await fs.chmod(dest, 0o600).catch(() => undefined);
     return dest;
 }
 export async function listBackups(file, home) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scalemax",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Universal ScaleMax installer for AI coding clients",
   "type": "module",
   "bin": {
@@ -31,6 +31,7 @@
     "chalk": "^5.3.0",
     "execa": "^9.5.1",
     "fs-extra": "^11.2.0",
+    "json5": "^2.2.3",
     "ora": "^8.1.1",
     "yaml": "^2.9.0"
   },
@@ -39,7 +40,7 @@
     "@types/node": "^22.10.2",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.10"
   },
   "engines": {
     "node": ">=18.19"