@zergai/ztc 0.4.0-beta.1 → 0.4.1-dev.36919234045

package/dist/agent/backends/zrouter_stream.js

@@ -1,12 +1,14 @@
+import { modelContract, normalizeContractModel } from '@zerg/model-contracts';
+import { resolveRouterModel } from '../../utils/router_catalog.js';
 import { randomUUID } from 'node:crypto';
 import { measureResponse, measureStream } from './request_metrics.js';
 import { parseSSEEvents } from './sse.js';
 import { buildOpenAIMessages, buildOpenAIToolDefs } from './openai_format.js';
-import { buildKimiRequestParams, isKimiModel } from './kimi_params.js';
+import { isKimiModel } from './kimi_params.js';
 import { runtimeDiag } from '../../utils/debug_log.js';
 import { createZrouterEventMapper } from './zrouter_events.js';
 import { parseTokenUsage } from './token_usage.js';
-import { deepseekRequestParams, DEEPSEEK_FLASH_MAX_OUTPUT, isModalDeepSeekFlashModel, MODAL_DEEPSEEK_FLASH_MAX_OUTPUT, isDeepSeekFlashModel } from '../../utils/deepseek.js';
+import { DEEPSEEK_FLASH_MAX_OUTPUT, isModalDeepSeekFlashModel, MODAL_DEEPSEEK_FLASH_MAX_OUTPUT, isDeepSeekFlashModel } from '../../utils/deepseek.js';
 import { getVersion } from '../../utils/version.js';
 import { isTransportError } from './transport_errors.js';
 const ZROUTER_HEADERS_TIMEOUT_MS = 90_000;
@@ -23,19 +25,13 @@ const PINNABLE_DECORATION = /^[A-Za-z0-9._:-]{1,64}$/;
 function isPinnableDecoration(value) {
     return value !== undefined && PINNABLE_DECORATION.test(value);
 }
-// Transport reconnects must outlive a Router deploy or a Redis blip, not just a
-// lost packet: a Fly machine recycle RSTs every client's stream at once, so the
-// whole fleet sees "fetch failed" at the same moment. Three sub-second retries
-// used to hand a live turn back to the agent as a dead "Network error". Six
-// attempts with capped exponential backoff buy roughly 8-15s inside this
-// backend; the agent's own retry loop layers a second budget on top, and the
-// Router keeps buffering the producer under the same turn id the whole time, so
-// the reconnect resumes instead of restarting. Every knob is env-overridable
-// because a self-hosted Router may restart more slowly.
-const DEFAULT_RECONNECT_ATTEMPTS = 6;
-const DEFAULT_RECONNECT_BASE_MS = 500;
-const DEFAULT_RECONNECT_CAP_MS = 10_000;
-const MAX_RECONNECT_ATTEMPTS = 20;
+// Allow Router restarts to recover through bounded, cancellable retries. Each
+// reconnect reports progress and resumes the same turn/cursor. Hosts can tune
+// the attempt count and backoff through the environment.
+const DEFAULT_RECONNECT_ATTEMPTS = 120;
+const DEFAULT_RECONNECT_BASE_MS = 1_000;
+const DEFAULT_RECONNECT_CAP_MS = 30_000;
+const MAX_RECONNECT_ATTEMPTS = 120;
 const MAX_RECONNECT_MS = 300_000;
 function envBoundedInt(name, fallback, min, max) {
     const parsed = Number(process.env[name]);
@@ -59,6 +55,7 @@ function resolveReconnectPolicy() {
  * uses the unified chat endpoint so routing can fall back across providers.
  */
 export class ZRouterStreamBackend {
+    catalog;
     apiKey;
     proxyUrl;
     provider;
@@ -67,6 +64,7 @@ export class ZRouterStreamBackend {
     conversationId;
     clientName;
     constructor(config) {
+        this.catalog = config.catalog ? structuredClone(config.catalog) : undefined;
         this.apiKey = config.apiKey;
         this.proxyUrl = config.proxyUrl.replace(/\/+$/, '');
         this.provider = config.provider;
@@ -87,12 +85,45 @@ export class ZRouterStreamBackend {
     handlesTransportRetries() {
         return true;
     }
+    getModelCapabilities(model) {
+        return this.catalog?.version === 1
+            ? resolveRouterModel(this.catalog, this.provider, model)?.capabilities : undefined;
+    }
     buildOpenAIBody(request) {
-        // ZTC stores the model separately from its provider. Router's global model
+        if (this.catalog?.version === 1) {
+            const descriptor = resolveRouterModel(this.catalog, this.provider, request.model);
+            if (!descriptor?.capabilities?.chat)
+                throw new Error('This model is no longer in the Router chat catalog. Refresh /model.');
+            const caps = descriptor.capabilities;
+            if (request.codexEffort && caps.reasoning && !caps.reasoning.choices.includes(request.codexEffort)) {
+                throw new Error(`Unsupported reasoning effort: ${request.codexEffort}`);
+            }
+            if (request.maxTokens !== undefined && caps.max_output_tokens !== undefined && request.maxTokens > caps.max_output_tokens) {
+                throw new Error(`Max output tokens exceeds the advertised limit (${caps.max_output_tokens}).`);
+            }
+            if (caps.images === false && request.messages.some(message => Array.isArray(message.content)
+                && message.content.some(block => block.type === 'image' || block.type === 'video')))
+                throw new Error('This model does not support images.');
+            const prepared = caps.tools === false ? chatOnlyRequest(request) : request;
+            return { provider: descriptor.owned_by, model: descriptor.id,
+                ...(request.routePlan ? { route: request.routePlan } : {}),
+                ...(request.maxTokens === undefined ? {} : { max_output_tokens: request.maxTokens }),
+                ...(caps.reasoning && request.codexEffort ? { reasoning_effort: request.codexEffort } : {}),
+                messages: buildOpenAIMessages(prepared),
+                ...(prepared.tools.length ? { tools: buildOpenAIToolDefs(prepared.tools) } : {}),
+            };
+        }
+        // Legacy contract for older Routers only. ZTC stores the model separately from its provider. Router's global model
         // namespace is a wire concern; keep existing namespaced IDs compatible.
         if (this.provider === 'modal' && !/^modal\//i.test(request.model)) {
             request = { ...request, model: `modal/${request.model}` };
         }
+        // Router resolves the Fireworks upstream id from the NAMESPACED form:
+        // fireworksUpstreamModelId returns null without the prefix and provider-client
+        // then answers 400 before dispatch. ZTC stores the bare slug, so add it here.
+        if (this.provider === 'fireworks') {
+            request = { ...request, model: `fireworks/${normalizeContractModel('fireworks', request.model)}` };
+        }
         // Kimi deprecates max_tokens in favour of max_completion_tokens, same as the
         // o-series and GPT-5+; keep this in step with the direct backend so the token
         // field does not depend on how the user authenticated.
@@ -115,20 +146,42 @@ export class ZRouterStreamBackend {
             model: request.model,
             ...(request.routePlan ? { route: request.routePlan } : {}),
             ...tokenParam,
-            // Kimi honors a reasoning_effort the picker exposes; without this the same
-            // selection applied on a direct key and vanished through the proxy.
-            // No-op for every non-Kimi model.
-            // Modal uses Kimi's effort ladder but keeps its own max_tokens contract.
-            ...buildKimiRequestParams(this.provider === 'modal'
-                ? { ...request, model: request.model.slice('modal/'.length) }
-                : request),
-            ...deepseekRequestParams(request),
+            ...(request.codexEffort && modelContract(this.provider, request.model, 'chat_tools')?.reasoningEfforts.includes(request.codexEffort)
+                ? { reasoning_effort: request.codexEffort } : {}),
             messages: buildOpenAIMessages(request),
             ...(request.tools.length > 0 ? { tools: buildOpenAIToolDefs(request.tools) } : {})
         };
     }
-    buildBody(request) {
-        return this.buildOpenAIBody(request);
+    serializeBody(request, stream = false) {
+        const body = {
+            ...this.buildOpenAIBody(request),
+            ...(stream ? { stream: true } : {}),
+        };
+        const serialized = JSON.stringify(body);
+        // Funded DeepSeek admission scans at most 10,000 JSON values, independently
+        // of the model's token window. A longer text history is otherwise rejected
+        // as non-text trial input, and resumable streaming masks that as a 5xx.
+        // Signal context overflow locally so hosts compact and retry, including
+        // when an agent's tool loop crosses the limit before returning to idle.
+        if (body.model === 'modal/deepseek-v4.1-flash'
+            || body.model === 'fireworks/deepseek-v4p1-flash') {
+            // Count the serialized wire shape: undefined properties disappear, and
+            // tool calls/results expand into separate messages during encoding.
+            const pending = [JSON.parse(serialized)];
+            let values = 1;
+            while (pending.length > 0) {
+                const value = pending.pop();
+                if (value === null || typeof value !== 'object')
+                    continue;
+                for (const child of Object.values(value)) {
+                    if (++values > 10_000) {
+                        throw new Error('Prompt is too long for Router\'s context structure limit (10,000 JSON values). Compact the conversation before retrying.');
+                    }
+                    pending.push(child);
+                }
+            }
+        }
+        return serialized;
     }
     async buildHeaders(request) {
         const token = this.authTokenProvider
@@ -141,6 +194,7 @@ export class ZRouterStreamBackend {
         const conversationPin = this.conversationPin(request);
         return {
             'Content-Type': 'application/json',
+            ...(this.catalog?.version === 1 ? { 'X-Zerg-Model-Contract': '1' } : {}),
             'Authorization': `Bearer ${normalizedToken}`,
             'X-Zerg-Client': this.clientName,
             'X-Zerg-Client-Version': getVersion(),
@@ -183,7 +237,7 @@ export class ZRouterStreamBackend {
         return measureResponse(routedRequest, fetcher => this.generateResponse(routedRequest, fetcher));
     }
     async generateResponse(request, fetcher) {
-        const body = this.buildBody(request);
+        const body = this.serializeBody(request);
         const headers = await this.buildHeaders(request);
         // Proof-chain log: the exact router endpoint + model this turn dispatches to.
         runtimeDiag('info', `[ztc] zrouter dispatch ${JSON.stringify({
@@ -195,15 +249,19 @@ export class ZRouterStreamBackend {
         const response = await fetcher(this.endpointFor(), {
             method: 'POST',
             headers,
-            body: JSON.stringify(body),
+            body,
             signal: request.signal,
         });
         if (!response.ok) {
             const errorText = await response.text();
-            throw new Error(`ZRouter API error (${response.status}): ${errorText}`);
+            throw new Error(`ZRouter API error (${response.status}): ${errorText}${failureHeaderSuffix(response)}`);
         }
         const data = await response.json();
-        return this.parseOpenAIResponse(data);
+        const parsed = this.parseOpenAIResponse(data);
+        if (this.getModelCapabilities(request.model)?.tools === false && parsed.content.some(block => block.type === 'tool_use')) {
+            throw new Error('Chat-only model returned tools; execution is disabled.');
+        }
+        return parsed;
     }
     parseOpenAIResponse(data) {
         // ZRouter wraps OpenAI responses in OpenAI-compatible format
@@ -248,12 +306,15 @@ export class ZRouterStreamBackend {
         return measureStream(routedRequest, fetcher => this.streamResponse(routedRequest, fetcher));
     }
     async *streamResponse(request, fetcher) {
-        const body = { ...this.buildBody(request), stream: true };
+        const body = this.serializeBody(request, true);
         const mapEvent = createZrouterEventMapper();
         let resumeAfter;
         let emittedMappedEvent = false;
         let resumeSupported = false;
         const policy = resolveReconnectPolicy();
+        let reconnectStarted;
+        const budget = () => resumeAfter ? 300_000 : 30_000;
+        const remaining = () => budget() - (reconnectStarted === undefined ? 0 : Date.now() - reconnectStarted);
         for (let attempt = 1; attempt <= policy.attempts; attempt++) {
             try {
                 const headers = await this.buildHeaders(request);
@@ -262,12 +323,12 @@ export class ZRouterStreamBackend {
                 const response = await fetchWithHeadersTimeout(fetcher, this.endpointFor(), {
                     method: 'POST',
                     headers,
-                    body: JSON.stringify(body),
+                    body,
                     signal: request.signal,
-                }, ZROUTER_HEADERS_TIMEOUT_MS);
+                }, Math.min(ZROUTER_HEADERS_TIMEOUT_MS, Math.max(1, remaining())));
                 if (!response.ok) {
                     const errorText = await response.text();
-                    throw new Error(`ZRouter API error (${response.status}): ${errorText}`);
+                    throw new Error(`ZRouter API error (${response.status}): ${errorText}${failureHeaderSuffix(response)}`);
                 }
                 if (!response.body) {
                     throw new Error('ZRouter API error: no response body for streaming request');
@@ -298,6 +359,9 @@ export class ZRouterStreamBackend {
                         throw new Error(`ZRouter API error (${status}): ${JSON.stringify(ev.body ?? {})}`);
                     }
                     const mapped = mapEvent(ev);
+                    if (this.getModelCapabilities(request.model)?.tools === false && mapped.some(event => event.type.startsWith('tool_use'))) {
+                        throw new Error('Chat-only model returned tools; execution is disabled.');
+                    }
                     if (mapped.length > 0) {
                         // Heartbeats are liveness, not model output. A drop while only
                         // heartbeats have arrived cannot duplicate visible text, so it
@@ -328,15 +392,22 @@ export class ZRouterStreamBackend {
                     // second copy of the turn, so fail the attempt instead.
                     throw error;
                 }
-                if (attempt === policy.attempts)
+                reconnectStarted ??= Date.now();
+                const attempts = resumeAfter ? policy.attempts : Math.min(6, policy.attempts);
+                if (attempt >= attempts || remaining() <= 0)
                     throw error;
                 // The Router keeps producing under this turn id, so waiting costs the
                 // turn nothing: the next attempt resumes from the cursor, not from zero.
-                const delayMs = reconnectDelay(policy, attempt);
+                const delayMs = Math.min(reconnectDelay(policy, attempt), remaining());
                 const reason = error instanceof Error ? error.message : String(error);
                 runtimeDiag('warn', `[ztc] zrouter stream dropped (${reason}); reconnecting in ${delayMs}ms (attempt ${attempt + 1}/${policy.attempts})`);
-                request.onTransportRetry?.({ attempt, maxAttempts: policy.attempts, delayMs, reason });
+                const publicReason = isRetryableResumeStatus(error)
+                    ? `Router temporarily unavailable ${reason.match(/\(\d{3}\)/)?.[0] ?? ''}. Resuming the response.`
+                    : reason;
+                request.onTransportRetry?.({ attempt, maxAttempts: attempts, delayMs, reason: publicReason });
                 await waitForReconnect(delayMs, request.signal);
+                if (remaining() <= 0)
+                    throw error;
             }
         }
     }
@@ -387,6 +458,27 @@ async function waitForReconnect(delayMs, signal) {
         signal?.addEventListener('abort', abort, { once: true });
     });
 }
+/**
+ * Diagnostics that survive a body-less failure.
+ *
+ * A gateway that throws before it can classify anything often answers with a
+ * bare `Server Error` and puts the identifying information in the headers
+ * instead. Fly (Router's host) stamps a request id on every response; carrying
+ * it into the error is the only way to correlate a client-visible 500 with the
+ * server-side exception, since the body has nothing to correlate on.
+ *
+ * Bounded and header-only: never reads the body (already consumed), and caps
+ * each value so a hostile/proxied header cannot bloat an error message.
+ */
+function failureHeaderSuffix(response) {
+    const parts = [];
+    for (const name of ['fly-request-id', 'x-request-id', 'cf-ray', 'x-zerg-error-code']) {
+        const value = response.headers.get(name)?.trim();
+        if (value && value.length <= 128 && !/[\r\n\0]/.test(value))
+            parts.push(`${name}=${value}`);
+    }
+    return parts.length > 0 ? ` [${parts.join(' ')}]` : '';
+}
 /**
  * True for a `ZRouter API error (NNN)` a resume is worth retrying: a gateway or
  * rate-limit failure that is expected to clear. Kept separate from
@@ -415,3 +507,15 @@ function normalizeHeaderValue(value, label, maxLength) {
     }
     return normalized;
 }
+/** A wire-only projection: saved tool history remains byte-for-byte intact. */
+function chatOnlyRequest(request) {
+    return { ...request, tools: [], messages: request.messages.map(message => ({ ...message,
+            content: typeof message.content === 'string' ? message.content : message.content.map(block => {
+                if (block.type === 'tool_use')
+                    return { type: 'text', text: `Previous tool call ${block.name} (${block.id}): ${JSON.stringify(block.input)}` };
+                if (block.type === 'tool_result')
+                    return { type: 'text', text: `Previous tool result (${block.tool_use_id}): ${typeof block.content === 'string' ? block.content : block.content.map(part => part.type === 'text' ? part.text : '[image]').join('\n')}` };
+                return block;
+            }),
+        })) };
+}

package/dist/agent/commands/compact.js

@@ -1,5 +1,5 @@
 import { compactConversation, describeCompaction, smartSummarizer, localSummarizer } from '../../utils/compaction.js';
-import { getContextStatus, contextStatusFromUsed, formatTokenCount } from '../../utils/context.js';
+import { estimateConversationTokens, getContextStatus, contextStatusFromUsed, formatTokenCount } from '../../utils/context.js';
 import { MAX_COMPACTION_TARGET_PERCENT, MIN_COMPACTION_TARGET_PERCENT, resolveCompactionSettings, resolveCompactionTargetPercent, resolveContextTokenBudget, tokenTriggerActive, } from '../../config/compaction.js';
 export const compactCommand = {
     name: 'compact',
@@ -18,9 +18,10 @@ export const compactCommand = {
         // The "before" percentage should match the context bar (the real provider
         // token count); fall back to the char/4 estimate only before the first call.
         const realUsed = ctx.getContextTokens?.() ?? 0;
+        const catalogWindow = ctx.config.getModelContextWindow?.(model);
         const status = realUsed > 0
-            ? contextStatusFromUsed(realUsed, model, ctx.getContextWindow?.())
-            : getContextStatus(messages, model);
+            ? contextStatusFromUsed(realUsed, model, catalogWindow !== undefined ? catalogWindow : ctx.getContextWindow?.())
+            : getContextStatus(messages, model, catalogWindow);
         // An explicit argument wins; otherwise the configured target applies, so
         // /compact and auto-compaction aim at the same place.
         const targetPercent = args[0] ? parseInt(args[0], 10) : resolveCompactionTargetPercent(ctx.config.get());
@@ -55,7 +56,7 @@ export const compactCommand = {
                 ? resolveContextTokenBudget(ctx.config.get())
                 : undefined;
             const targetTokens = budget === undefined
-                ? undefined
+                ? (catalogWindow === undefined ? undefined : Math.max(1, Math.floor((catalogWindow ?? estimateConversationTokens(messages)) * targetPercent / 100)))
                 : Math.floor(budget * (targetPercent / 100));
             const result = await compactConversation(messages, model, {
                 method: compaction.method,
@@ -74,7 +75,7 @@ export const compactCommand = {
                     ...(msg.metadata ? { metadata: msg.metadata } : {}),
                 });
             }
-            const newStatus = getContextStatus(result.messages, model);
+            const newStatus = getContextStatus(result.messages, model, catalogWindow);
             // Reactively shrink the context bar to the compacted size — the backend
             // won't report this until the next turn, and the bar would otherwise stay
             // stuck at the pre-compaction (larger) value.

package/dist/agent/commands/config.js

@@ -894,7 +894,10 @@ Usage: /config context-progress-bar <enabled|accent|warning|critical|track|reset
                 return;
             }
             case 'effort': {
-                const EFFORT_LEVELS = CODEX_REASONING_EFFORTS;
+                const catalog = ctx.config.getRoutedModelCatalog?.();
+                const EFFORT_LEVELS = catalog?.version === 1
+                    ? catalog.models.find(row => row.owned_by === ctx.config.getProvider() && row.id === getEffectiveModel(ctx))?.capabilities?.reasoning?.choices ?? []
+                    : CODEX_REASONING_EFFORTS;
                 const CLEAR_WORDS = ['clear', 'default', 'unset', 'reset'];
                 const config = ctx.config.get();
                 const activeEffort = () => `Active (${config.provider} · ${config.model}): ${formatReasoningEffort(resolveCodexEffort(ctx.config.get(), config.provider, config.model))}`;

package/dist/agent/commands/context.js

@@ -55,7 +55,12 @@ export const contextCommand = {
         const estimated = realTokens <= 0;
         const usedTokens = estimated ? estimateConversationTokens(messages) : realTokens;
         // Use the provider-reported window the bar used (Codex) so /context agrees.
-        const status = contextStatusFromUsed(usedTokens, model, estimated ? undefined : ctx.getContextWindow?.());
+        const catalogWindow = ctx.config.getModelContextWindow?.(model);
+        const status = contextStatusFromUsed(usedTokens, model, catalogWindow !== undefined ? catalogWindow : estimated ? undefined : ctx.getContextWindow?.());
+        if (status.total === 0) {
+            ctx.addMessage({ role: 'system', content: `Context: ${formatTokens(usedTokens)} tokens${estimated ? ' (estimated)' : ''}. Context limit is unknown for this Router model.` });
+            return;
+        }
         const total = status.total;
         const usedPct = status.percentage;
         const freeTokens = Math.max(0, total - usedTokens);

package/dist/agent/commands/effort.js

@@ -1,15 +1,23 @@
 import { CODEX_REASONING_EFFORTS } from '../../config/types.js';
 import { resolveCodexEffort } from '../../config/defaults.js';
 import { getSupportedCodexReasoningEfforts } from '../../utils/models.js';
-import { formatReasoningEffort, parseReasoningSelection } from '../../utils/reasoning.js';
+import { formatReasoningEffort, parseReasoningSelection, reasoningCommandChoices } from '../../utils/reasoning.js';
+import { resolveRouterModel } from '../../utils/router_catalog.js';
 async function configureReasoning(kind, args, ctx) {
     const config = ctx.config.get();
     const provider = ctx.config.getProvider?.() || config.provider || 'anthropic';
     const model = ctx.config.getModel?.() || config.model;
-    const current = resolveCodexEffort(config, provider, model);
-    const supported = getSupportedCodexReasoningEfforts(model, provider);
+    const surface = ctx.config.getReasoningWireSurface?.(provider, model)
+        ?? (config.authMode === 'zrouter' || provider === 'openai_compatible' ? 'chat_tools' : 'native_api');
+    const catalog = ctx.config.getRoutedModelCatalog?.();
+    const capabilities = catalog?.version === 1 ? resolveRouterModel(catalog, provider, model)?.capabilities : undefined;
+    const current = resolveCodexEffort(config, provider, model, capabilities ?? surface);
+    const supported = catalog?.version === 1 ? capabilities?.reasoning?.choices ?? [] : getSupportedCodexReasoningEfforts(model, provider, surface);
+    const contract = ctx.config.getReasoningContract?.(provider, model)
+        ?? (catalog?.version === 1 ? capabilities?.reasoning ?? [] : surface);
+    const thinkingChoices = reasoningCommandChoices('thinking', provider, model, contract);
     const status = () => {
-        const effective = resolveCodexEffort(ctx.config.get(), provider, model);
+        const effective = resolveCodexEffort(ctx.config.get(), provider, model, capabilities ?? surface);
         // A startup flag is this process's value, never the saved default, so say
         // where an effort that came from one is coming from.
         const processEffort = ctx.config.getCodexEffortOverride?.();
@@ -20,7 +28,7 @@ async function configureReasoning(kind, args, ctx) {
         ctx.addMessage({ role: 'system', content: status() +
                 (supported?.length === 0 ? '\nThis model does not support a reasoning-effort setting.' :
                     `\nSupported: ${(supported ?? CODEX_REASONING_EFFORTS).join(', ')}. /effort default inherits provider/global defaults.`) +
-                (supported?.includes('none') ? '\n/thinking off disables reasoning; /thinking on enables it.' : '') });
+                (thinkingChoices.length ? `\nThinking settings: ${thinkingChoices.join(', ')}.` : '') });
         return;
     }
     if (args.length !== 1) {
@@ -29,7 +37,7 @@ async function configureReasoning(kind, args, ctx) {
     }
     let level;
     try {
-        level = parseReasoningSelection(provider, model, current, { [kind]: args[0] });
+        level = parseReasoningSelection(provider, model, current, { [kind]: args[0] }, contract);
     }
     catch (error) {
         ctx.addMessage({ role: 'system', content: error.message });

package/dist/agent/commands/model.js

@@ -6,10 +6,20 @@ const MODEL_SUBCOMMANDS = ['list', 'latest', 'set'];
 export const modelCommand = {
     name: 'model',
     description: 'Select provider and model, or set a model on the current provider',
-    usage: '<provider> [model] | zergrouter <provider> [model] | <model-id> | list [provider] | latest [provider] | set <model-id>',
+    usage: '<provider> [model] | zergrouter <provider> [model] | <model-id> | list [provider] | latest [provider] | set <model-id> | refresh',
     agentRunnable: true,
     category: 'config',
-    handler: (args, ctx) => {
+    handler: async (args, ctx) => {
+        if (args[0] === 'refresh' && ctx.models.catalog) {
+            try {
+                const catalog = await ctx.models.catalog(undefined, { refresh: true });
+                ctx.addMessage({ role: 'system', content: `${catalog.authRequired ? 'Router authentication rejected. Run ztc auth login again. Showing cached catalog' : catalog.cached ? 'Router unavailable. Showing cached catalog' : 'Router catalog refreshed'}: ${catalog.models.length} models. Active responses continue with their current selection.` });
+            }
+            catch (error) {
+                ctx.addMessage({ role: 'system', content: `Could not refresh Router models: ${error.message}` });
+            }
+            return;
+        }
         if (args.length > 0 && MODEL_SUBCOMMANDS.includes(args[0].toLowerCase())) {
             return modelsCommand.handler(args, ctx);
         }

package/dist/agent/commands/profile.js

@@ -6,12 +6,13 @@ const USAGE = [
     '  /profile <name>              switch this session to an existing profile',
     '  /profile use <name>          same as above',
     '  /profile create <name>       create and switch to a custom profile',
+    '  /profile duplicate [name]    copy the active profile and switch to the copy',
 ].join('\n');
 const OLD_BENCHMARK_COMMANDS = new Set(['show', 'gates', 'command', 'run', 'optimize', 'sweep']);
 export const profileCommand = {
     name: 'profile',
-    description: 'List and switch configuration profiles',
-    usage: '[list|<name>|use <name>|create <name>]',
+    description: 'List, switch, create, and duplicate configuration profiles',
+    usage: '[list|<name>|use <name>|create <name>|duplicate [name]]',
     handler: async (args, ctx) => {
         const [action, ...rest] = args;
         if (!action || action === 'list' || action === 'configs' || action === 'help') {
@@ -31,6 +32,24 @@ export const profileCommand = {
             ctx.addMessage({ role: 'system', content: `Config profiles (* active):\n${lines.join('\n')}${!action ? `\n\n${USAGE}` : ''}` });
             return;
         }
+        if (action === 'duplicate' || action === 'copy' || action === 'clone') {
+            if (rest.length > 1) {
+                ctx.addMessage({ role: 'system', content: USAGE });
+                return;
+            }
+            const source = activeProfile();
+            const target = rest[0] ?? `${source}-copy`;
+            try {
+                if (!ctx.duplicateProfile)
+                    throw new Error('This renderer cannot switch config profiles in place.');
+                const name = await ctx.duplicateProfile(target, source);
+                ctx.addMessage({ role: 'system', content: `Duplicated config profile ${source} to ${name} and switched to it.` });
+            }
+            catch (error) {
+                ctx.addMessage({ role: 'system', content: `Profile duplicate failed: ${error.message}` });
+            }
+            return;
+        }
         if (OLD_BENCHMARK_COMMANDS.has(action)) {
             ctx.addMessage({ role: 'system', content: 'Use /emulation to inspect prompt modes. Profile benchmark gates remain available through npm run profiles:baseline.' });
             return;

package/dist/agent/commands/provider_selection.js

@@ -4,6 +4,7 @@ import { applyRuntimeModelSelection, getEffectiveModel } from './runtime_model.j
 import { canRouteThroughRouter, canonicalProvider } from './provider_choices.js';
 import { resolveModelAndProvider } from '../../panes/model_catalog.js';
 import { getDefaultModel } from '../../utils/models.js';
+import { resolveRouterModel } from '../../utils/router_catalog.js';
 /** Apply a provider and optional model in one validated config transition. */
 export async function selectProviderModel(args, ctx) {
     const values = args.filter(Boolean);
@@ -27,11 +28,23 @@ export async function selectProviderModel(args, ctx) {
     const authMode = routed ? 'zrouter' : 'direct';
     const defaultModel = provider === 'inception' ? getDefaultModel(provider) : getDefaultModelForProvider(provider);
     const explicitModel = values[choice === 'zergrouter' ? 2 : 1];
-    const model = explicitModel || (provider === current ? getEffectiveModel(ctx)
+    let model = explicitModel || (provider === current ? getEffectiveModel(ctx)
         : provider === 'openai_compatible'
             ? (ctx.config.getOpenAICompatibleSettings?.().defaultModel || getDefaultModelForProvider(provider))
             : resolveModelAndProvider(defaultModel, provider).model);
     try {
+        if (routed && ctx.models.catalog) {
+            const catalog = await ctx.models.catalog().catch(() => undefined);
+            if (catalog?.version === 1) {
+                const models = catalog.models.filter(row => row.owned_by === provider && row.capabilities?.chat);
+                if (!explicitModel)
+                    model = models.find(row => row.is_default)?.id ?? models[0]?.id ?? '';
+                const selected = resolveRouterModel(catalog, provider, model);
+                if (!selected?.capabilities?.chat)
+                    throw new Error('Model is not in the Router catalog. Refresh /model.');
+                model = selected.id;
+            }
+        }
         const llm = ctx.config.resolveLLMBackendConfig({ provider, model,
             config: { ...ctx.config.get(), provider, model, authMode } });
         if (llm.authMode !== authMode) {

package/dist/agent/commands/settings.js

@@ -1,3 +1,6 @@
+import { parseReasoningSelection } from '../../utils/reasoning.js';
+import { resolveRouterModel } from '../../utils/router_catalog.js';
+import { getSupportedCodexReasoningEfforts } from '../../utils/models.js';
 import { resolveExecutionSettings } from '../../config/execution.js';
 import { accountsCommand } from './accounts.js';
 import { authCommand } from './auth.js';
@@ -132,6 +135,8 @@ export async function buildSettingsCategories(ctx) {
     const routerSignedIn = routerCredentials !== null && Date.parse(routerCredentials.expiresAt) > Date.now();
     const provider = ctx.config.getProvider();
     const model = ctx.config.getModel?.() || config.model;
+    const reasoningEfforts = getSupportedCodexReasoningEfforts(model, provider, ctx.config.getReasoningWireSurface?.(provider, model)
+        ?? (config.authMode === 'zrouter' || provider === 'openai_compatible' ? 'chat_tools' : 'native_api'));
     const claudeCliInstalled = isClaudeCliAvailable();
     const claudeCodeTokenPresent = Boolean(process.env.CLAUDE_CODE_OAUTH_TOKEN?.trim());
     const claudeCodeReady = hasUsableClaudeCodeCliAuth();
@@ -168,6 +173,15 @@ export async function buildSettingsCategories(ctx) {
         modelOptions = models.slice(0, 20).map(m => ({ value: m, label: m }));
     }
     catch { /* fallback: no pre-fetched options, user can type manually */ }
+    const routerCatalog = ctx.config.getRoutedModelCatalog?.();
+    const routerDescriptor = routerCatalog?.version === 1
+        ? resolveRouterModel(routerCatalog, provider, model) : undefined;
+    if (routerCatalog?.version === 1)
+        modelOptions = routerCatalog.models.filter(row => row.owned_by === provider && row.capabilities?.chat)
+            .map(row => ({ value: row.id, label: `${row.display_name || row.id}${row.capabilities?.tools === false ? ' (chat only)' : ''}${row.available === false ? ' (access unavailable)' : ''}` }));
+    const reasoningChoices = routerCatalog?.version === 1 ? routerDescriptor?.capabilities?.reasoning?.choices ?? []
+        : reasoningEfforts ?? CODEX_REASONING_EFFORTS;
+    const effortSupported = config.codexEffort === undefined || reasoningChoices.includes(config.codexEffort);
     const sections = [
         {
             name: 'Config Scope',
@@ -242,7 +256,8 @@ export async function buildSettingsCategories(ctx) {
                     // option matches a canonical PROVIDERS value instead of nothing.
                     value: normalizeProviderId(provider),
                     type: 'select',
-                    options: PROVIDERS,
+                    options: routerCatalog?.version === 1 ? [...new Map(routerCatalog.models.filter(row => row.capabilities?.chat)
+                            .map(row => [row.owned_by, { value: row.owned_by, label: row.provider_display_name || row.owned_by }])).values()] : PROVIDERS,
                 },
                 {
                     name: 'model',
@@ -258,13 +273,15 @@ export async function buildSettingsCategories(ctx) {
                     value: config.maxTokens === undefined ? 'provider default' : String(config.maxTokens),
                     type: 'text',
                     placeholder: 'provider default',
-                    description: 'Maximum output tokens, including reasoning tokens. Enter a positive whole number, or "provider default" to clear the limit.',
+                    description: `Maximum output tokens, including reasoning tokens. ${routerDescriptor?.capabilities?.max_output_tokens ? `Router limit: ${routerDescriptor.capabilities.max_output_tokens.toLocaleString()}. ` : ''}Enter a positive whole number, or "provider default" to clear the limit.`,
                 },
                 {
                     name: 'codexEffort', label: 'Default reasoning effort',
-                    value: config.codexEffort ?? 'provider default', type: 'select',
-                    options: [{ value: 'provider default', label: 'provider default' }, ...CODEX_REASONING_EFFORTS.map(level => ({ value: level, label: level }))],
-                    description: 'Global default. Model and provider overrides take precedence.',
+                    value: effortSupported ? config.codexEffort ?? 'provider default' : 'provider default', type: 'select',
+                    options: [{ value: 'provider default', label: 'provider default' }, ...reasoningChoices.map(level => ({ value: level, label: level }))],
+                    description: reasoningChoices.length === 0
+                        ? `This model takes no reasoning-effort setting (${provider} · ${model}).`
+                        : `Levels supported by ${provider} · ${model}. Model and provider overrides take precedence.`,
                 },
                 {
                     name: 'codexFastMode', label: 'Fast mode', value: String(config.codexFastMode === true), type: 'select',
@@ -1058,6 +1075,18 @@ function applySettingChange(ctx, setting, value) {
     }
     switch (setting) {
         case 'provider':
+            {
+                const catalog = ctx.config.getRoutedModelCatalog?.();
+                if (catalog?.version === 1) {
+                    const rows = catalog.models.filter(row => row.owned_by === value && row.capabilities?.chat);
+                    const selected = rows.find(row => row.is_default) ?? rows[0];
+                    if (!selected)
+                        throw new Error('Provider is not in the Router chat catalog.');
+                    ctx.config.setProvider(value);
+                    ctx.config.set('model', selected.id);
+                    break;
+                }
+            }
             ctx.config.setProvider(value);
             {
                 const resetModel = resolveModelForProviderChange(value, getEffectiveModel(ctx));
@@ -1082,10 +1111,19 @@ function applySettingChange(ctx, setting, value) {
             break;
         }
         case 'codexEffort':
-            if (value !== 'provider default' && !CODEX_REASONING_EFFORTS.includes(value)) {
+            const catalog = ctx.config.getRoutedModelCatalog?.();
+            const choices = catalog?.version === 1 ? resolveRouterModel(catalog, ctx.config.getProvider(), getEffectiveModel(ctx))?.capabilities?.reasoning?.choices ?? [] : CODEX_REASONING_EFFORTS;
+            if (value !== 'provider default' && !choices.includes(value)) {
                 throw new Error(`Unknown reasoning effort: ${value}`);
             }
-            ctx.config.set('codexEffort', value === 'provider default' ? undefined : value);
+            const activeConfig = ctx.config.get();
+            const activeProvider = ctx.config.getProvider();
+            const activeModel = ctx.config.getModel?.() || activeConfig.model;
+            const selectedEffort = parseReasoningSelection(activeProvider, activeModel, undefined, { effort: value === 'provider default' ? 'default' : value }, catalog?.version === 1
+                ? resolveRouterModel(catalog, activeProvider, activeModel)?.capabilities?.reasoning?.choices ?? []
+                : ctx.config.getReasoningWireSurface?.(activeProvider, activeModel)
+                    ?? (activeConfig.authMode === 'zrouter' || activeProvider === 'openai_compatible' ? 'chat_tools' : 'native_api'));
+            ctx.config.set('codexEffort', selectedEffort ?? undefined);
             break;
         case 'codexFastMode':
             ctx.config.set('codexFastMode', value === 'true');