@zergai/ztc 0.5.0-beta.1 → 0.6.0-beta.1

package/dist/agent/commands/config.js

@@ -1,19 +1,27 @@
+import { resolveAutoCompactThreshold, resolveCompactionTriggerMode, resolveContextTokenBudget } from '../../config/compaction.js';
 import { DEFAULT_SPINNER_VERBS, formatSpinnerVerbs, parseSpinnerVerbs } from '../../utils/spinner_verbs.js';
 import { CODEX_REASONING_EFFORTS, } from '../../config/types.js';
 import { runOpenAICompatibleWizard } from './openai_compat_wizard.js';
 import { openFactoryResetConfirmation, settingsCommand } from './settings.js';
 import { contextProgressBarConfig, normalizeBarColor, publishContextProgressBar, withBarColor, } from './context_progress_bar.js';
-import { compatEndpoint, DEFAULT_CONTEXT_PROGRESS_BAR } from '../../config.js';
+import { compatEndpoint, DEFAULT_CONTEXT_PROGRESS_BAR, maskApiKey } from '../../config.js';
 import { parseGoalTurnCap } from './goal.js';
 import { getSupportedCodexReasoningEfforts, isCodexReasoningEffortSupported, unsupportedEffortMessage, } from '../../utils/models.js';
-import { resolveModelForProviderChange } from './provider_model_defaults.js';
+import { modelForProviderSwitch, resolveModelForProviderChange } from './provider_model_defaults.js';
 import { applyRuntimeModelSelection, getEffectiveModel } from './runtime_model.js';
 import { shutdownAndClearWorkflowRegistry } from '../../workflows/registry_handle.js';
-import { canonicalProvider, isLocalSubscription } from './provider_choices.js';
+import { formatRate } from '../../utils/openrouter_prices.js';
+import { API_KEY_PROVIDER_CHOICES, canonicalProvider, describeKeySource, isLocalSubscription, PROVIDER_CHOICES, } from './provider_choices.js';
+import { canAskForCredential, manageApiKey, promptForMissingDirectKey, removeApiKey, savedKeyNotes, useApiKeyVariable, } from './direct_credential_prompt.js';
+import { looksLikeApiKeyEnvName } from '../../config/provider_api_key_env.js';
+import { offerKeyedProviderSwitch } from './provider_selection.js';
+import { connectionStatusLines } from './credential_status.js';
+import { normalizeProviderId } from '../backends/provider_ids.js';
 import { resolveCodexEffort } from '../../config/defaults.js';
 import { formatReasoningEffort } from '../../utils/reasoning.js';
 import { DEFAULT_MESSAGE_DISPLAY, MIN_TOOL_OUTPUT_LINES, parseToolOutputLines, resolveMessageDisplaySettings, } from '../../config/message_display.js';
 import { DEFAULT_STATUS_LINE_SETTINGS, STATUS_LINE_ITEMS, STATUS_LINE_ITEM_DESCRIPTIONS, STATUS_LINE_VARIANTS, compactStatusLineVariants, formatStatusLineSettings, normalizeStatusLineSeparator, parseStatusLineItems, parseStatusLineVariant, resolveStatusLineSettings, resolveStatusLineVariants, statusLineSettingsForStorage, } from '../../ui/status_line_config.js';
+import { offerReasoningPicker } from './reasoning_picker.js';
 /**
  * Whether a resolved provider/model selection can actually build a backend right
  * now. Mirrors the factory's buildable arms (see agent/factory.ts): a usable
@@ -38,17 +46,21 @@ export function isBuildableResolvedConfig(resolved) {
 /** Actionable error shown when a provider/model switch can't build a backend. */
 export function unbuildableSelectionMessage(provider) {
     if (provider === 'modal' || provider === 'zergrouter') {
-        return `Can't switch to ${provider}: run /auth login for Zerg Router. Keeping the current selection.`;
+        return `Can't switch to ${provider}: it runs through Zerg Router. Log in with ZergAI (/auth login). Keeping the current selection.`;
     }
     if (isLocalSubscription(provider)) {
         return `Can't switch to ${provider}: sign in through /accounts. Keeping the current selection.`;
     }
-    return `✗ Can't switch to ${provider}: no usable credentials found (provider API key, platform login, or ZRouter). `
-        + `Set one with \`/config key ${provider} <api-key>\` or \`/login\`, then try again. Keeping the current selection.`;
+    if (provider === 'openai_compatible') {
+        return "Can't switch to openai_compatible: set up the endpoint with /config openai-compat first. Keeping the current selection.";
+    }
+    return `✗ Can't switch to ${provider}: it has no API key. `
+        + `Add one with \`/config key ${provider}\`, or log in with ZergAI (\`/login\`), then try again. Keeping the current selection.`;
 }
 export function parseConfigKeyArgs(args, currentProvider) {
     const provider = canonicalProvider(args[0] || '');
-    if (args.length > 1 && provider) {
+    // A lone provider name asks for that provider's key; it is never the key.
+    if (provider) {
         return {
             provider,
             apiKey: args.slice(1).join(' '),
@@ -113,14 +125,147 @@ const STATUS_LINE_USAGE = [
     '  /config statusline colors <on|off>',
     '  /config statusline <on|off|reset>',
 ].join('\n');
+/**
+ * `/config key` alone: ask which provider the key is for, then offer that
+ * provider's key choices. False when nobody can answer.
+ */
+function pickKeyProvider(ctx) {
+    if (!canAskForCredential(ctx))
+        return false;
+    const options = API_KEY_PROVIDER_CHOICES.map(choice => ({
+        value: choice.id, label: choice.label, description: describeKeySource(ctx.config.getApiKeySource(choice.id)),
+    }));
+    ctx.select.showSelect({ title: 'Add an API key', question: 'Which provider is the key for?', type: 'select', options }, value => {
+        // Escape is announced by the widget.
+        if (typeof value !== 'string' || !options.some(option => option.value === value))
+            return;
+        manageApiKey(value, ctx, change => useKeyChange(value, ctx, change));
+    });
+    return true;
+}
+/**
+ * Put a key just saved to use: the running agent rebuilds when it belongs to
+ * the active provider; otherwise, with no model connected, ZTC offers to
+ * switch to that provider.
+ */
+function useSavedKey(provider, ctx) {
+    if (normalizeProviderId(provider) === normalizeProviderId(ctx.config.getProvider()))
+        ctx.reloadAgent();
+    else
+        offerKeyedProviderSwitch(provider, ctx);
+}
+/**
+ * After the key choices of `/config key`: a key or a set variable is put to
+ * use; a removal, or a variable not set yet, only drops a stale agent built
+ * with the old key.
+ */
+function useKeyChange(provider, ctx, change) {
+    if (!change)
+        return;
+    if (change.kind === 'saved' || change.kind === 'env')
+        return useSavedKey(provider, ctx);
+    if (normalizeProviderId(provider) === normalizeProviderId(ctx.config.getProvider()))
+        ctx.reloadAgent({ defer: true });
+}
+/**
+ * `/config provider <id>`. A direct provider without a key asks for one and,
+ * once it is saved, switches; `credentialPrompted` keeps that retry from asking twice.
+ */
+async function setConfigProvider(value, ctx, credentialPrompted = false) {
+    const provider = canonicalProvider(value) ?? value;
+    // Verify the target actually builds a backend BEFORE persisting — an
+    // unbuildable provider written to config.json makes the NEXT boot start
+    // agent-less. Probe the model this switch would land on. openai_compatible
+    // is exempt: it is configured by the wizard that runs right after this
+    // switch, so it has no credentials to probe yet.
+    const previousProvider = ctx.config.getProvider();
+    const currentModel = getEffectiveModel(ctx);
+    const model = modelForProviderSwitch(provider, previousProvider, currentModel);
+    if (provider !== 'openai_compatible') {
+        const llm = ctx.config.resolveLLMBackendConfig({ provider, model });
+        if (!isBuildableResolvedConfig(llm)) {
+            if (!credentialPrompted && promptForMissingDirectKey(llm, ctx, () => setConfigProvider(provider, ctx, true)))
+                return;
+            ctx.addMessage({ role: 'system', content: unbuildableSelectionMessage(provider) });
+            return;
+        }
+    }
+    const resetModel = resolveModelForProviderChange(provider, currentModel);
+    ctx.config.setProvider(provider);
+    ctx.config.set('model', model);
+    await ctx.config.save();
+    applyRuntimeModelSelection(ctx, provider, model);
+    ctx.addMessage({
+        role: 'system',
+        content: `✓ Provider updated: ${provider}${resetModel ? `\n  Model reset to ${resetModel} for Claude Code.` : ''}`
+    });
+    // Auto-launch the wizard the first time the user picks openai_compatible
+    // (Ollama / vLLM / LM Studio / custom). Skip if a base URL is already set
+    // — they can re-run via `/config openai-compat` to change anything.
+    if (provider === 'openai_compatible') {
+        const settings = ctx.config.getOpenAICompatibleSettings?.()
+            || { baseUrl: ctx.config.getOpenAICompatibleBaseUrl() };
+        if (!settings.baseUrl) {
+            ctx.addMessage({
+                role: 'system',
+                content: 'No endpoint configured yet — opening setup form. Run `/config openai-compat` later to change anything.',
+            });
+            runOpenAICompatibleWizard(ctx);
+        }
+    }
+}
+/**
+ * `/config model <id>` on the active provider. A missing direct key is asked
+ * for once, then the model is applied.
+ */
+async function setConfigModel(value, ctx, credentialPrompted = false) {
+    // Verify the selection builds a backend BEFORE persisting so an
+    // unbuildable choice never lands in config.json nor earns a false "✓".
+    const activeProvider = ctx.config.getProvider();
+    const llm = ctx.config.resolveLLMBackendConfig({ provider: activeProvider, model: value });
+    if (!isBuildableResolvedConfig(llm)) {
+        if (!credentialPrompted && promptForMissingDirectKey(llm, ctx, () => setConfigModel(value, ctx, true)))
+            return;
+        ctx.addMessage({ role: 'system', content: unbuildableSelectionMessage(activeProvider) });
+        return;
+    }
+    ctx.config.set('model', value);
+    await ctx.config.save();
+    applyRuntimeModelSelection(ctx, activeProvider, value);
+    const envPinnedModel = process.env.ZTC_MODEL || process.env.LLM_MODEL;
+    ctx.addMessage({
+        role: 'system',
+        content: `✓ Model updated: ${value} (${ctx.config.getConfigScope?.() || 'global'} scope)${envPinnedModel ? `\n  Deployment currently pins model=${envPinnedModel}; this override may reset on refresh or restart.` : ''}`
+    });
+    offerReasoningPicker(ctx);
+}
+/** `/config help`: the subcommands, most used first. */
+const CONFIG_HELP = [
+    '/config subcommands:',
+    '  /config                     Open settings on Connection (the ZergAI login and API keys)',
+    '  /config show                Show the provider, model, route, keys and other settings',
+    '  /config key [provider]      Set a provider API key in a hidden prompt, or name its variable',
+    '  /config key <provider> --remove        Forget the saved key or variable',
+    '  /config provider <id>       Choose the provider',
+    '  /config model <id>          Choose the model',
+    '  /config openai-compat       Set up a custom OpenAI-compatible endpoint',
+    '  /config routing <auto|direct|zrouter>   How ZTC reaches a model',
+    '  /config max-tokens <n|default>          Output cap',
+    '  /config effort <level|clear>            Default reasoning effort',
+    '  /config scope <session|global|clear>    Where changes are saved',
+    '  /config reset               Factory reset (asks first)',
+    'Any other word searches the settings, for example /config compaction.',
+].join('\n');
 export const configCommand = {
     name: 'config',
     description: 'Manage configuration',
-    usage: '[show|reset|scope|local|global|key|provider|endpoint|openai-compat|auth-mode|model|max-tokens|effort|display|spinner|statusline|goal-max-turns|manifests-dir|context-progress-bar|workflows] [value]',
+    usage: '[show|reset|scope|local|global|key|provider|endpoint|openai-compat|auth-mode|model|max-tokens|effort|display|spinner|statusline|goal-max-turns|manifests-dir|context-progress-bar|workflows|openrouter] [value]',
     agentRunnable: true,
     category: 'config',
     handler: async (args, ctx) => {
         let [subCmd, ...rest] = args;
+        // Subcommands and scopes match in any case, as command names do.
+        subCmd = subCmd?.toLowerCase();
         let value = rest.join(' ');
         if (subCmd === 'local' || subCmd === 'session') {
             if (!ctx.config.withConfigScope) {
@@ -201,20 +346,19 @@ Usage:
                     await ctx.config.refresh();
                 }
                 const config = ctx.config.get();
-                const effectiveModel = ctx.config.getModel?.() || config.model;
-                const authMode = ctx.config.getAuthMode?.() || config.authMode || 'auto';
                 // A startup --effort belongs to this process; report it as such instead
                 // of letting it read as the saved default it is not.
                 const processEffort = ctx.config.getCodexEffortOverride?.();
                 const configuredEffort = (ctx.config.getConfigWithoutEffortOverride?.() ?? config).codexEffort;
                 const lines = [
                     'Current configuration:',
-                    `  API Key: ${ctx.config.getMaskedApiKey()}`,
-                    `  Provider: ${ctx.config.getProvider()}`,
-                    `  Model: ${effectiveModel}`,
+                    `  Compaction threshold: ${ctx.config.getAutoCompactThreshold?.() ?? resolveAutoCompactThreshold(config)}%`,
+                    `  Compaction trigger: ${ctx.config.getCompactionTriggerMode?.() ?? resolveCompactionTriggerMode(config)}`,
+                    `  Compaction token budget: ${ctx.config.getContextTokenBudget?.() ?? resolveContextTokenBudget(config) ?? 'unset'}`,
+                    `  Idle compaction: ${ctx.config.getIdleCompaction?.() ?? config.idleCompaction !== false ? 'on' : 'off'}`,
+                    ...connectionStatusLines(ctx.config),
                     `  Max Tokens: ${config.maxTokens ?? 'provider default'}`,
                     `  Zerg Endpoint: ${config.zergEndpoint || '(not set)'}`,
-                    `  Auth Mode: ${authMode}`,
                     `  Context Progress Bar: ${formatContextProgressBar(config)}`,
                     `  Status Line: ${statusLineSummary(config.statusLine)}`,
                     `  Emulation: ${ctx.config.getEmulationId() || '(none)'}`,
@@ -300,28 +444,54 @@ Usage:
                 ctx.addMessage({ role: 'system', content: 'Usage: /config workflows <on|off|trigger-on|trigger-off>' });
                 return;
             }
-            case 'key':
+            case 'key': {
                 if (!value) {
+                    if (pickKeyProvider(ctx))
+                        return;
                     ctx.addMessage({
                         role: 'system',
-                        content: `Current API key: ${ctx.config.getMaskedApiKey()}\n\nUsage: /config key <your-api-key>`
+                        content: [
+                            `Current API key (${ctx.config.getProvider()}): ${ctx.config.getMaskedApiKey()}`,
+                            '',
+                            'Usage: /config key <provider>  (paste the key in a hidden prompt, or name its variable)',
+                            '       /config key <provider> --remove  (forget the saved key or variable)',
+                            `Providers: ${[...API_KEY_PROVIDER_CHOICES.map(choice => choice.id), 'openai_compatible'].join(', ')}`,
+                        ].join('\n'),
                     });
                     return;
                 }
                 const { provider, apiKey } = parseConfigKeyArgs(rest, ctx.config.getProvider());
                 if (provider === 'modal' || provider === 'zergrouter' || isLocalSubscription(provider)) {
                     ctx.addMessage({ role: 'system', content: provider === 'modal' || provider === 'zergrouter'
-                            ? `${provider} uses your Zerg Router login. Run /auth login; /config key cannot configure this provider.`
+                            ? `${provider} runs through Zerg Router with your ZergAI login. Run /auth login; /config key cannot configure this provider.`
                             : `${provider} uses subscription credentials. Sign in through /accounts; /config key cannot configure this provider.` });
                     return;
                 }
+                if (apiKey === '--remove') {
+                    await removeApiKey(provider, ctx, change => useKeyChange(provider, ctx, change));
+                    return;
+                }
                 if (!apiKey) {
+                    if (manageApiKey(provider, ctx, change => useKeyChange(provider, ctx, change)))
+                        return;
                     ctx.addMessage({
                         role: 'system',
                         content: 'Usage: /config key <provider> <api-key>'
                     });
                     return;
                 }
+                // A variable name is read as one, never saved as the key. A custom
+                // endpoint's placeholder key (e.g. EMPTY) stays a key unless written $NAME.
+                const namesVariable = provider === 'openai_compatible'
+                    ? apiKey.trim().startsWith('$') && looksLikeApiKeyEnvName(apiKey)
+                    : looksLikeApiKeyEnvName(apiKey);
+                if (namesVariable) {
+                    if (await useApiKeyVariable(provider, apiKey, ctx, change => useKeyChange(provider, ctx, change)))
+                        return;
+                    ctx.addMessage({ role: 'system', content: 'That looks like an environment variable name, not a key. '
+                            + `Run /config key ${provider} in an interactive session and choose "Use an environment variable".` });
+                    return;
+                }
                 if (provider === 'anthropic' && !apiKey.startsWith('sk-ant-')) {
                     ctx.addMessage({
                         role: 'system',
@@ -330,57 +500,30 @@ Usage:
                 }
                 ctx.config.setApiKey(apiKey, provider);
                 await ctx.config.save();
-                ctx.reloadAgent();
                 ctx.addMessage({
                     role: 'system',
-                    content: `✓ API key updated (${provider}): ${ctx.config.getMaskedApiKey()}\n  Saved to ${ctx.config.locationLabel || '~/.ztc/config.json'}`
+                    content: [
+                        `✓ API key updated (${provider}): ${maskApiKey(apiKey)}`,
+                        `  Saved to ${ctx.config.locationLabel || '~/.ztc/config.json'}`,
+                        ...savedKeyNotes(provider, apiKey, ctx),
+                        // A key typed after the command shows in the composer; the prompt hides it.
+                        provider === 'openai_compatible'
+                            ? '  Next time, Custom endpoint… in /keys takes the key in a hidden field.'
+                            : `  Next time, /config key ${provider} asks for the key in a hidden prompt.`,
+                    ].join('\n'),
                 });
+                useSavedKey(provider, ctx);
                 break;
+            }
             case 'provider': {
                 if (!value) {
                     ctx.addMessage({
                         role: 'system',
-                        content: `Current provider: ${ctx.config.getProvider()}\n\nUsage: /config provider <anthropic|claude_code|openai|codex_app_server|codex_legacy|gemini|inception|kimi|openai_compatible>\n\nNote: codex is a legacy alias for codex_legacy.`
+                        content: `Current provider: ${ctx.config.getProvider()}\n\nUsage: /config provider <${PROVIDER_CHOICES.map(choice => choice.id).join('|')}>\n\nNote: codex is a legacy alias for codex_legacy.`
                     });
                     return;
                 }
-                // Verify the target actually builds a backend BEFORE persisting — an
-                // unbuildable provider written to config.json makes the NEXT boot start
-                // agent-less. Probe the model this switch would land on. openai_compatible
-                // is exempt: it is configured by the wizard that runs right after this
-                // switch, so it has no credentials to probe yet.
-                if (value !== 'openai_compatible') {
-                    const candidateReset = resolveModelForProviderChange(value, getEffectiveModel(ctx));
-                    const probeModel = candidateReset || getEffectiveModel(ctx);
-                    if (!isBuildableResolvedConfig(ctx.config.resolveLLMBackendConfig({ provider: value, model: probeModel }))) {
-                        ctx.addMessage({ role: 'system', content: unbuildableSelectionMessage(value) });
-                        return;
-                    }
-                }
-                ctx.config.setProvider(value);
-                const resetModel = resolveModelForProviderChange(value, getEffectiveModel(ctx));
-                if (resetModel)
-                    ctx.config.set('model', resetModel);
-                await ctx.config.save();
-                applyRuntimeModelSelection(ctx, value, resetModel || getEffectiveModel(ctx));
-                ctx.addMessage({
-                    role: 'system',
-                    content: `✓ Provider updated: ${value}${resetModel ? `\n  Model reset to ${resetModel} for Claude Code.` : ''}`
-                });
-                // Auto-launch the wizard the first time the user picks openai_compatible
-                // (Ollama / vLLM / LM Studio / custom). Skip if a base URL is already set
-                // — they can re-run via `/config openai-compat` to change anything.
-                if (value === 'openai_compatible') {
-                    const settings = ctx.config.getOpenAICompatibleSettings?.()
-                        || { baseUrl: ctx.config.getOpenAICompatibleBaseUrl() };
-                    if (!settings.baseUrl) {
-                        ctx.addMessage({
-                            role: 'system',
-                            content: 'No endpoint configured yet — opening setup form. Run `/config openai-compat` later to change anything.',
-                        });
-                        runOpenAICompatibleWizard(ctx);
-                    }
-                }
+                await setConfigProvider(value, ctx);
                 break;
             }
             case 'openai-compat':
@@ -391,7 +534,7 @@ Usage:
             case 'zrouter-url':
             case 'zrouter':
                 if (!value) {
-                    ctx.addMessage({ role: 'system', content: `Current ZRouter URL: ${ctx.config.get().zergProxyUrl || '(not set)'}
+                    ctx.addMessage({ role: 'system', content: `Current Zerg Router URL: ${ctx.config.get().zergProxyUrl || '(not set)'}
 
 Usage: /config zrouter-url <url|clear>` });
                     return;
@@ -399,7 +542,7 @@ Usage: /config zrouter-url <url|clear>` });
                 ctx.config.set('zergProxyUrl', value === 'clear' ? undefined : value);
                 await ctx.config.save();
                 ctx.reloadAgent();
-                ctx.addMessage({ role: 'system', content: `✓ ZRouter URL ${value === 'clear' ? 'cleared' : `set: ${value}`} (${ctx.config.getConfigScope?.() || 'global'} scope)` });
+                ctx.addMessage({ role: 'system', content: `✓ Zerg Router URL ${value === 'clear' ? 'cleared' : `set: ${value}`} (${ctx.config.getConfigScope?.() || 'global'} scope)` });
                 break;
             case 'endpoint':
                 if (!value) {
@@ -436,7 +579,7 @@ Usage: /config zrouter-url <url|clear>` });
                     const authMode = ctx.config.getAuthMode?.() || ctx.config.get().authMode || 'auto';
                     ctx.addMessage({
                         role: 'system',
-                        content: `Current auth mode: ${authMode}\n\nUsage: /config auth-mode <auto|direct|zrouter>\n  direct  Use provider API key and ignore ZRouter\n  zrouter Use platform ZRouter when auth token is present\n  auto    Prefer ZRouter when available, otherwise use provider API key`
+                        content: `Current routing: ${authMode}\n\nUsage: /config routing <auto|direct|zrouter>\n  direct  Local API keys only; never Zerg Router\n  zrouter Zerg Router only, with your ZergAI login\n  auto    Zerg Router while you are logged in with ZergAI, except local logins and a Gemini API key;\n          otherwise local API keys`
                     });
                     return;
                 }
@@ -444,7 +587,7 @@ Usage: /config zrouter-url <url|clear>` });
                 if (!mode) {
                     ctx.addMessage({
                         role: 'system',
-                        content: 'Usage: /config auth-mode <auto|direct|zrouter>'
+                        content: 'Usage: /config routing <auto|direct|zrouter>'
                     });
                     return;
                 }
@@ -458,16 +601,19 @@ Usage: /config zrouter-url <url|clear>` });
                 ctx.reloadAgent();
                 const envOverride = process.env.ZTC_LLM_AUTH_MODE || process.env.ZERG_LLM_AUTH_MODE;
                 const detail = mode === 'direct'
-                    ? 'direct provider API key'
+                    ? 'local API keys'
                     : mode === 'zrouter'
-                        ? 'platform ZRouter'
-                        : 'auto routing';
+                        ? 'Zerg Router'
+                        : 'Zerg Router while logged in with ZergAI, otherwise local API keys';
                 ctx.addMessage({
                     role: 'system',
-                    content: `✓ Auth mode updated: ${mode} (${detail})${envOverride ? `\n  Environment override is set (${envOverride}); unset ZTC_LLM_AUTH_MODE/ZERG_LLM_AUTH_MODE for this config value to take effect.` : ''}`
+                    content: `✓ Routing updated: ${mode} (${detail})${envOverride ? `\n  Environment override is set (${envOverride}); unset ZTC_LLM_AUTH_MODE/ZERG_LLM_AUTH_MODE for this config value to take effect.` : ''}`
                 });
                 break;
             }
+            case 'openrouter':
+                await configureOpenRouter(rest, ctx);
+                return;
             case 'goal-max-turns':
             case 'goalmaxturns': {
                 const current = ctx.config.get().goalMaxTurns;
@@ -524,21 +670,7 @@ Usage: /config zrouter-url <url|clear>` });
                     });
                     return;
                 }
-                // Verify the selection builds a backend BEFORE persisting so an
-                // unbuildable choice never lands in config.json nor earns a false "✓".
-                const activeProvider = ctx.config.getProvider();
-                if (!isBuildableResolvedConfig(ctx.config.resolveLLMBackendConfig({ provider: activeProvider, model: value }))) {
-                    ctx.addMessage({ role: 'system', content: unbuildableSelectionMessage(activeProvider) });
-                    return;
-                }
-                ctx.config.set('model', value);
-                await ctx.config.save();
-                applyRuntimeModelSelection(ctx, activeProvider, value);
-                const envPinnedModel = process.env.ZTC_MODEL || process.env.LLM_MODEL;
-                ctx.addMessage({
-                    role: 'system',
-                    content: `✓ Model updated: ${value} (${ctx.config.getConfigScope?.() || 'global'} scope)${envPinnedModel ? `\n  Deployment currently pins model=${envPinnedModel}; this override may reset on refresh or restart.` : ''}`
-                });
+                await setConfigModel(value, ctx);
                 break;
             }
             case 'manifests-dir':
@@ -1012,9 +1144,183 @@ Usage: /config context-progress-bar <enabled|accent|warning|critical|track|reset
                 });
                 return;
             }
+            case 'help':
+                ctx.addMessage({ role: 'system', content: CONFIG_HELP });
+                return;
             default:
                 // No subcommand or unknown → open interactive settings menu
                 return settingsCommand.handler(subCmd ? [subCmd, ...rest] : [], ctx);
         }
     }
 };
+/** Quantizations OpenRouter routes by (https://openrouter.ai/docs/features/provider-routing). */
+const OPENROUTER_QUANTIZATIONS = ['int4', 'int8', 'fp4', 'fp6', 'fp8', 'fp16', 'bf16', 'fp32', 'unknown'];
+const OPENROUTER_ROUTES = { default: undefined, cheapest: 'floor', floor: 'floor', fastest: 'nitro', nitro: 'nitro' };
+/** Each numeric limit /config openrouter limit sets, with a range inside the one Router accepts, and whom it applies to. */
+const OPENROUTER_LIMITS = {
+    'max-input': { key: 'maxInputPrice', low: 0, high: 10_000, unit: 'USD per 1M input tokens' },
+    'max-output': { key: 'maxOutputPrice', low: 0, high: 10_000, unit: 'USD per 1M output tokens' },
+    'min-throughput': { key: 'minThroughput', low: 1, high: 100_000, unit: 'tokens per second' },
+    'max-latency': { key: 'maxLatency', low: 0.05, high: 600, unit: 'seconds to the first token' },
+    'min-uptime': { key: 'minUptime', low: 1, high: 100, unit: 'percent over the last day' },
+};
+/** The shares of a model's providers to beat the reasoning page offers, 0 for none. */
+const OPENROUTER_SHARES = [0, 25, 50, 75, 90];
+const OPENROUTER_SHARE_LIMITS = { 'faster-than': 'fasterThan', 'quicker-than': 'quickerThan' };
+const OPENROUTER_LIMIT_USAGE = 'Usage: /config openrouter limit faster-than|quicker-than <share>|default | min-uptime <percent>'
+    + ' | speed prefer|require (every model); max-input|max-output <usd> | min-throughput <tok/s> | max-latency <seconds> (this model); any clears a limit';
+/** Every model's limits, as `faster than 75% of providers · any latency · ≥ 99% uptime · speed preferred`. */
+function describeProfileLimits(limits) {
+    const share = (rank, verb, kind) => rank === undefined ? `Router's default ${kind} share`
+        : rank === 0 ? `any ${kind}` : `${verb} than ${rank}% of providers`;
+    return [share(limits?.fasterThan, 'faster', 'throughput'), share(limits?.quickerThan, 'quicker', 'latency'),
+        ...(limits?.minUptime === undefined ? [] : [`≥ ${limits.minUptime}% uptime`]),
+        `speed ${limits?.requireSpeed ? 'required' : 'preferred'}`].join(' · ');
+}
+/** One model's limits, as `≤ $1.10 out · ≥ 120 tok/s · ≤ 0.8s latency`, or none. */
+function describeModelLimits(limits) {
+    return [limits?.maxInputPrice === undefined ? '' : `≤ ${formatRate(limits.maxInputPrice)} in`,
+        limits?.maxOutputPrice === undefined ? '' : `≤ ${formatRate(limits.maxOutputPrice)} out`,
+        limits?.minThroughput === undefined ? '' : `≥ ${limits.minThroughput} tok/s`,
+        limits?.maxLatency === undefined ? '' : `≤ ${limits.maxLatency}s latency`].filter(Boolean).join(' · ') || 'none';
+}
+/**
+ * /config openrouter: the preferences ZTC sends with OpenRouter models through
+ * ZergRouter. Zero data retention and quantizations narrow the providers
+ * OpenRouter may pick; routing appends :floor (cheapest) or :nitro (fastest).
+ */
+async function configureOpenRouter(args, ctx) {
+    const current = ctx.config.get().openRouter ?? {};
+    const model = String(ctx.config.get().model ?? '');
+    const [setting, ...values] = args.map(arg => arg.trim()).filter(Boolean);
+    const save = async (next, message) => {
+        ctx.config.set('openRouter', next);
+        await ctx.config.save();
+        ctx.addMessage({ role: 'system', content: `✓ ${message}` });
+    };
+    const { zdr: _zdr, quantizations: _quantizations, variant: _variant, ...others } = current;
+    switch (setting?.toLowerCase()) {
+        case undefined: {
+            const route = current.variant === 'floor' ? 'cheapest' : current.variant === 'nitro' ? 'fastest' : 'OpenRouter default';
+            ctx.addMessage({ role: 'system', content: [
+                    'OpenRouter preferences (sent with openrouter/... models through ZergRouter)',
+                    `  Zero data retention: ${current.zdr ? 'on' : 'off'}`,
+                    `  Quantizations: ${current.quantizations?.length ? current.quantizations.join(', ') : 'any'}`,
+                    `  Routing: ${route}`,
+                    `  Limits for every model: ${describeProfileLimits(current.limits)}`,
+                    ...(model.startsWith('openrouter/') ? [`  Limits for ${model}: ${describeModelLimits(current.modelLimits?.[model])}`] : []),
+                    '',
+                    'Usage:',
+                    '  /config openrouter zdr on|off',
+                    `  /config openrouter quantizations <${OPENROUTER_QUANTIZATIONS.join('|')},...>|any`,
+                    '  /config openrouter routing default|cheapest|fastest',
+                    '  /config openrouter limit faster-than|quicker-than 0|25|50|75|90|default   (every model)',
+                    '  /config openrouter limit min-uptime <percent>|any, speed prefer|require   (every model)',
+                    '  /config openrouter limit max-input|max-output|min-throughput|max-latency <value>|any   (this model)',
+                    'The reasoning page (/effort) also sets routing, rules and limits.',
+                ].join('\n') });
+            return;
+        }
+        case 'zdr': {
+            const on = values[0]?.toLowerCase();
+            if (on !== 'on' && on !== 'off') {
+                ctx.addMessage({ role: 'system', content: 'Usage: /config openrouter zdr on|off' });
+                return;
+            }
+            const { variant, quantizations } = current;
+            await save({ ...others, ...(on === 'on' ? { zdr: true } : {}), ...(quantizations ? { quantizations } : {}), ...(variant ? { variant } : {}) }, on === 'on' ? 'OpenRouter: zero-data-retention providers only' : 'OpenRouter: any provider');
+            return;
+        }
+        case 'quantizations':
+        case 'quantization': {
+            const list = values.join(' ').split(/[\s,]+/).map(value => value.toLowerCase()).filter(Boolean);
+            const { zdr, variant } = current;
+            const keep = { ...others, ...(zdr ? { zdr } : {}), ...(variant ? { variant } : {}) };
+            if (list.length === 1 && list[0] === 'any') {
+                await save(keep, 'OpenRouter: any quantization');
+                return;
+            }
+            const unknown = list.filter(value => !OPENROUTER_QUANTIZATIONS.includes(value));
+            if (list.length === 0 || unknown.length > 0) {
+                ctx.addMessage({ role: 'system', content: `${unknown.length ? `Unknown quantization: ${unknown.join(', ')}. ` : ''}`
+                        + `Choose from ${OPENROUTER_QUANTIZATIONS.join(', ')}, or any.` });
+                return;
+            }
+            const chosen = [...new Set(list)];
+            await save({ ...keep, quantizations: chosen }, `OpenRouter quantizations: ${chosen.join(', ')}`);
+            return;
+        }
+        case 'routing': {
+            const name = values[0]?.toLowerCase() ?? '';
+            if (!(name in OPENROUTER_ROUTES)) {
+                ctx.addMessage({ role: 'system', content: 'Usage: /config openrouter routing default|cheapest|fastest' });
+                return;
+            }
+            const variant = OPENROUTER_ROUTES[name];
+            const { zdr, quantizations } = current;
+            await save({ ...others, ...(zdr ? { zdr } : {}), ...(quantizations ? { quantizations } : {}), ...(variant ? { variant } : {}) }, `OpenRouter routing: ${variant === 'floor' ? 'cheapest' : variant === 'nitro' ? 'fastest' : 'OpenRouter default'}`);
+            return;
+        }
+        case 'limit':
+        case 'limits': {
+            const [name = '', raw = ''] = values.map(value => value.toLowerCase());
+            const { limits: _limits, modelLimits: _modelLimits, ...rest } = current;
+            const profile = current.limits ?? {};
+            const saveProfile = async (limits) => save({ ...rest, ...(Object.keys(limits).length ? { limits } : {}),
+                ...(current.modelLimits ? { modelLimits: current.modelLimits } : {}) }, `OpenRouter limits for every model: ${describeProfileLimits(limits)}`);
+            if (name === 'speed') {
+                if (raw !== 'prefer' && raw !== 'require') {
+                    ctx.addMessage({ role: 'system', content: OPENROUTER_LIMIT_USAGE });
+                    return;
+                }
+                const { requireSpeed: _require, ...others } = profile;
+                await saveProfile(raw === 'require' ? { ...others, requireSpeed: true } : others);
+                return;
+            }
+            const share = OPENROUTER_SHARE_LIMITS[name];
+            if (share) {
+                const { [share]: _old, ...others } = profile;
+                if (raw === 'default') {
+                    await saveProfile(others);
+                    return;
+                }
+                const rank = Number(raw.replace(/%$/, ''));
+                if (!raw || !OPENROUTER_SHARES.includes(rank)) {
+                    ctx.addMessage({ role: 'system', content: `${name} takes ${OPENROUTER_SHARES.slice(0, -1).join(', ')} or ${OPENROUTER_SHARES.at(-1)}`
+                            + ' (percent of the model\'s providers to beat; 0 for none), or default.' });
+                    return;
+                }
+                await saveProfile({ ...others, [share]: rank });
+                return;
+            }
+            const limit = OPENROUTER_LIMITS[name];
+            if (!limit || !raw) {
+                ctx.addMessage({ role: 'system', content: OPENROUTER_LIMIT_USAGE });
+                return;
+            }
+            const value = raw === 'any' ? undefined : Number(raw.replace(/^\$/, '').replace(/(tok\/s|%|s)$/, ''));
+            if (value !== undefined && (!Number.isFinite(value) || value < limit.low || value > limit.high)) {
+                ctx.addMessage({ role: 'system', content: `${name} takes ${limit.unit}, between ${limit.low} and ${limit.high}.` });
+                return;
+            }
+            if (limit.key === 'minUptime') {
+                const { minUptime: _old, ...others } = profile;
+                await saveProfile(value === undefined ? others : { ...others, minUptime: value });
+                return;
+            }
+            // Price caps and fixed speed mean something only for one model: the current one.
+            if (!model.startsWith('openrouter/')) {
+                ctx.addMessage({ role: 'system', content: `${name} is set per OpenRouter model. Choose an OpenRouter model with /model first.` });
+                return;
+            }
+            const { [model]: own = {}, ...otherModels } = current.modelLimits ?? {};
+            const { [limit.key]: _old, ...kept } = own;
+            const next = value === undefined ? kept : { ...kept, [limit.key]: value };
+            const models = Object.keys(next).length ? { ...otherModels, [model]: next } : otherModels;
+            await save({ ...rest, ...(current.limits ? { limits: current.limits } : {}), ...(Object.keys(models).length ? { modelLimits: models } : {}) }, `OpenRouter limits for ${model}: ${describeModelLimits(next)}`);
+            return;
+        }
+        default:
+            ctx.addMessage({ role: 'system', content: 'Usage: /config openrouter [zdr on|off | quantizations <list>|any | routing default|cheapest|fastest | limit <name> <value>|any]' });
+    }
+}

package/dist/agent/commands/connect.d.ts

@@ -0,0 +1,20 @@
+import type { Command, CommandContext } from './types.js';
+export declare const connectCommand: Command;
+/**
+ * After a ZergAI logout that leaves no model reachable, ask how to connect
+ * again, as launch does; mid-session the choice can be closed. Without a
+ * person to ask, say so and point to /connect.
+ */
+export declare function offerConnectAfterLogout(ctx: CommandContext): void;
+/**
+ * Ask how to reach a model. `launch` is the prompt ZTC opens by itself at
+ * launch, and it must end in a choice: typing and Escape do not close it,
+ * Escape further on steps back towards it, and choosing ZergAI starts the
+ * login at once.
+ */
+export declare function showConnectPrompt(ctx: CommandContext, { launch, noBrowser, onFinished }?: {
+    launch?: boolean;
+    noBrowser?: boolean;
+    /** For the launch prompt: runs once when its flow has ended (see LaunchFlow). */
+    onFinished?: () => void;
+}): void;