claude-autorouter 0.3.7 → 0.5.0

package/src/auto-routing.mjs

@@ -1,54 +1,214 @@
+import { modelCapabilities } from './model-catalog.mjs';
+import { prepareRequest } from './model-request.mjs';
+
 // Shared execution capabilities, not a replacement for Claude's permission
 // classifier. Keep the complete safeguards contract and signed history on wire.
-const MODELS = new Set(['claude-sonnet-5', 'claude-sonnet-5-5', 'claude-opus-5', 'claude-opus-5-5']);
 const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
-const SHARED_TOOLS = new Set(['custom', 'tool_search_tool_regex_20251119', 'tool_search_tool_bm25_20251119',
-  'bash_20250124', 'text_editor_20250728']);
 const CONTEXT_EDITS = new Set(['clear_thinking_20251015', 'clear_tool_uses_20250919']);
-const sharedTool = tool => object(tool) && (tool.type === undefined || SHARED_TOOLS.has(tool.type));
+// Reviewed 2026-10-05 against the Messages API/tool reference and context-edit
+// contract. These are semantic envelopes; input schemas/examples and document
+// data remain opaque and are never inspected or rewritten.
+// https://platform.claude.com/docs/en/api/beta/messages/create
+// https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages
+// https://github.com/anthropics/anthropic-sdk-typescript/blob/main/src/resources/beta/messages/messages.ts
+const CUSTOM_TOOL_FIELDS = new Set(['type', 'name', 'description', 'input_schema', 'cache_control',
+  'defer_loading', 'strict', 'input_examples', 'allowed_callers', 'eager_input_streaming']);
+const SEARCH_TOOL_FIELDS = new Set(['type', 'name', 'allowed_callers', 'cache_control', 'defer_loading', 'strict']);
+const BASH_TOOL_FIELDS = new Set([...SEARCH_TOOL_FIELDS, 'input_examples']);
+const EDITOR_TOOL_FIELDS = new Set([...BASH_TOOL_FIELDS, 'max_characters']);
+const TOOL_FIELDS = new Map([
+  ['custom', CUSTOM_TOOL_FIELDS], ['bash_20250124', BASH_TOOL_FIELDS],
+  ['text_editor_20250728', EDITOR_TOOL_FIELDS],
+  ['tool_search_tool_regex_20251119', SEARCH_TOOL_FIELDS], ['tool_search_tool_bm25_20251119', SEARCH_TOOL_FIELDS],
+]);
+const TOOL_CHOICE_FIELDS = new Map([
+  ['auto', new Set(['type', 'disable_parallel_tool_use'])], ['any', new Set(['type', 'disable_parallel_tool_use'])],
+  ['tool', new Set(['type', 'name', 'disable_parallel_tool_use'])], ['none', new Set(['type'])],
+]);
+const MESSAGE_FIELDS = new Set(['role', 'content', 'output_config', 'clear_at']);
+const THINKING_EDIT_FIELDS = new Set(['type', 'keep']);
+const TOOL_EDIT_FIELDS = new Set(['type', 'clear_at_least', 'clear_tool_inputs', 'exclude_tools', 'keep', 'trigger']);
+const EDIT_VALUE_FIELDS = new Set(['type', 'value']);
+const knownFields = (value, fields) => Object.keys(value).every(key => fields.has(key));
+const optionalEnvelope = (value, fields) => value == null || (object(value) && knownFields(value, fields));
+const sharedTool = tool => object(tool) && TOOL_FIELDS.has(tool.type ?? 'custom')
+  && knownFields(tool, TOOL_FIELDS.get(tool.type ?? 'custom')) && optionalEnvelope(tool.cache_control, CACHE_FIELDS);
+const sharedEdit = edit => object(edit) && CONTEXT_EDITS.has(edit.type)
+  && knownFields(edit, edit.type === 'clear_thinking_20251015' ? THINKING_EDIT_FIELDS : TOOL_EDIT_FIELDS)
+  && ['keep', 'trigger', 'clear_at_least'].every(key => !object(edit[key]) || knownFields(edit[key], EDIT_VALUE_FIELDS));
+const REQUEST_FIELDS = new Set(['model', 'messages', 'system', 'max_tokens', 'metadata', 'stream',
+  'stop_sequences', 'temperature', 'top_p', 'top_k', 'tools', 'tool_choice', 'thinking', 'output_config',
+  'context_management', 'speed', 'container', 'mcp_servers', 'compaction', 'safeguards', 'service_tier',
+  'inference_geo', 'cache_control']);
+const CONTENT_TYPES = new Set(['text', 'image', 'document', 'tool_use', 'tool_result', 'thinking',
+  'redacted_thinking', 'tool_reference', 'tool_search_tool_result', 'tool_search_tool_search_result',
+  'tool_addition', 'tool_removal']);
+// The beta API distinguishes semantic block envelopes from opaque payloads.
+// See its BetaContentBlockParam union and the matching official SDK types:
+// https://github.com/anthropics/anthropic-sdk-python/tree/main/src/anthropic/types/beta
+const CONTENT_FIELDS = Object.fromEntries(Object.entries({
+  text: ['type', 'text', 'cache_control', 'citations'],
+  image: ['type', 'source', 'cache_control', 'transformations'],
+  document: ['type', 'source', 'cache_control', 'citations', 'context', 'title'],
+  tool_use: ['type', 'id', 'input', 'name', 'cache_control', 'caller', 'toolset_name'],
+  tool_result: ['type', 'tool_use_id', 'content', 'is_error', 'cache_control', 'toolset_name'],
+  thinking: ['type', 'signature', 'thinking'],
+  redacted_thinking: ['type', 'data'],
+  tool_reference: ['type', 'tool_name', 'cache_control'],
+  tool_search_tool_result: ['type', 'content', 'tool_use_id', 'cache_control'],
+  tool_search_tool_search_result: ['type', 'tool_references'],
+  tool_search_tool_result_error: ['type', 'error_code', 'error_message'],
+  tool_addition: ['type', 'tool', 'cache_control'],
+  tool_removal: ['type', 'tool', 'cache_control'],
+}).map(([type, fields]) => [type, new Set(fields)]));
+const CACHE_FIELDS = new Set(['type', 'ttl']);
+const TRANSFORMATION_FIELDS = new Set(['oversized_image']);
+const TOOL_REFERENCE_FIELDS = new Set(['type', 'name']);
+const TOOL_DEFINITION_FIELDS = new Set(['type', 'definition']);
+const OUTPUT_FIELDS = new Set(['effort', 'format', 'task_budget']);
+const OUTPUT_FORMAT_FIELDS = new Set(['type', 'schema']);
+const TASK_BUDGET_FIELDS = new Set(['type', 'total', 'remaining']);
+const THINKING_BINDING_FIELDS = new Set(['prefix_mismatch_behavior']);
+const THINKING_FIELDS = new Map([
+  ['enabled', new Set(['type', 'budget_tokens', 'display', 'block_binding'])],
+  ['adaptive', new Set(['type', 'display', 'block_binding'])],
+  ['disabled', new Set(['type'])], ['between_tools', new Set(['type'])],
+]);
+const CALLER_FIELDS = new Map([
+  ['direct', new Set(['type'])], ['code_execution_20250825', new Set(['type', 'tool_id'])],
+  ['code_execution_20260120', new Set(['type', 'tool_id'])],
+]);
+// Claude's versioned classifier context is opaque permission-review data;
+// only its outer contract and version determine whether routing is supported.
+const SAFEGUARD_FIELDS = new Set(['type', 'classifier_context']);
+const compatible = Object.freeze({ compatible: true });
+const incompatible = reason => ({ compatible: false, reason });
 
 export function hasRoutableSafeguards(body) {
-  return MODELS.has(body.model) && Array.isArray(body.safeguards) && body.safeguards.length > 0
+  return modelCapabilities(body?.model)?.sharedAuto === true && Array.isArray(body.safeguards) && body.safeguards.length > 0
     && body.safeguards.every(entry => object(entry) && entry.type === 'dangerous_tool_use'
-      && object(entry.classifier_context) && entry.classifier_context.v === 1);
+      && knownFields(entry, SAFEGUARD_FIELDS) && object(entry.classifier_context) && entry.classifier_context.v === 1);
 }
 
 export function canRouteAutoRequest(body, target) {
-  if (!MODELS.has(body.model) || !MODELS.has(target)) return false;
-  if (body.safeguards !== undefined && !hasRoutableSafeguards(body)) return false;
-  if (body.max_tokens !== undefined && (!Number.isSafeInteger(body.max_tokens) || body.max_tokens < 1 || body.max_tokens > 128000)) return false;
+  return checkTarget(body, target, true).compatible;
+}
+
+/**
+ * Check a proposed model change after the same explicit thinking adaptation
+ * used by inference and token counting. Native same-model requests belong to
+ * the provider: this is a routing guard, not a replacement API validator.
+ * @returns {{compatible: boolean, reason?: string}}
+ */
+export function targetCompatibility(body, target, { autoMode = false } = {}) {
+  if (typeof target === 'string' && body?.model === target) return compatible;
+  return checkTarget(body, target, autoMode);
+}
+
+function checkTarget(body, target, autoMode) {
+  const sourceFacts = modelCapabilities(body?.model);
+  const targetFacts = modelCapabilities(target);
+  if (!sourceFacts || !targetFacts) return incompatible('unknown_model');
+  if (!object(body) || !Array.isArray(body.messages)) return incompatible('invalid_request_shape');
+  if (autoMode && (!sourceFacts.sharedAuto || !targetFacts.sharedAuto)) return incompatible('auto_model');
+  if (Object.keys(body).some(key => !REQUEST_FIELDS.has(key))) return incompatible('request_extension');
+  if (!optionalEnvelope(body.cache_control, CACHE_FIELDS)) return incompatible('request_extension');
+  if (body.safeguards !== undefined && (!sourceFacts.sharedAuto || !targetFacts.sharedAuto || !hasRoutableSafeguards(body))) return incompatible('safeguards');
+  if (body.max_tokens !== undefined && (!Number.isSafeInteger(body.max_tokens) || body.max_tokens < 0
+    || body.max_tokens > targetFacts.maxOutputTokens)) return incompatible('output_limit');
   // Retain model-specific execution facilities whose contracts differ between
   // models. Ordinary Claude Code tools and native context editing are shared.
-  if (body.speed !== undefined && body.speed !== 'standard') return false;
-  if (body.container !== undefined || body.mcp_servers !== undefined || body.compaction !== undefined) return false;
-  if (body.tools !== undefined && (!Array.isArray(body.tools) || !body.tools.every(sharedTool))) return false;
+  if (body.speed !== undefined && body.speed !== 'standard') return incompatible('speed');
+  if (body.container !== undefined || body.mcp_servers !== undefined || body.compaction !== undefined) return incompatible('execution_facility');
+  if (body.tools !== undefined && (!Array.isArray(body.tools) || !body.tools.every(sharedTool))) return incompatible('tool_type');
+  const contents = Array.isArray(body.system) ? [body.system] : [];
   for (const message of body.messages) {
+    if (!object(message)) return incompatible('invalid_request_shape');
+    if (!knownFields(message, MESSAGE_FIELDS)) return incompatible('content_extension');
+    if (message.role === 'system' && !targetFacts.midConversationSystem) return incompatible('system_message');
+    if (message.output_config != null && !targetFacts.perMessageEffort) return incompatible('message_effort');
+    if (message.output_config != null && (!object(message.output_config)
+      || Object.keys(message.output_config).some(key => key !== 'effort')
+      || (message.output_config.effort != null && !targetFacts.effortLevels.includes(message.output_config.effort)))) return incompatible('message_effort');
+    if (Array.isArray(message.content)) contents.push(message.content);
     if (message.role !== 'system' || !Array.isArray(message.content)) continue;
     for (const block of message.content) {
+      if (!object(block)) return incompatible('invalid_request_shape');
       if (!['tool_addition', 'tool_removal'].includes(block.type)) continue;
       const tool = block.tool;
       if (!object(tool) || (tool.type !== 'tool_reference'
-        && !(block.type === 'tool_addition' && tool.type === 'tool_definition' && sharedTool(tool.definition)))) return false;
+        && !(block.type === 'tool_addition' && tool.type === 'tool_definition' && sharedTool(tool.definition)))
+        || !knownFields(tool, tool.type === 'tool_reference' ? TOOL_REFERENCE_FIELDS : TOOL_DEFINITION_FIELDS)) return incompatible('inline_tool');
     }
   }
-  if (body.tool_choice !== undefined && (!object(body.tool_choice) || !['auto', 'none'].includes(body.tool_choice.type))) return false;
-  if (body.context_management !== undefined) {
+  // Inspect known content containers only; tool input and document payloads
+  // are opaque. Unknown block types retain their source model, never stripped.
+  while (contents.length) for (const block of contents.pop()) {
+    if (!object(block) || !CONTENT_TYPES.has(block.type) || !knownFields(block, CONTENT_FIELDS[block.type])) return incompatible('content_extension');
+    if (!optionalEnvelope(block.cache_control, CACHE_FIELDS)) return incompatible('content_extension');
+    if (block.type === 'tool_use' && block.caller !== undefined && (!object(block.caller)
+      || !CALLER_FIELDS.has(block.caller.type) || !knownFields(block.caller, CALLER_FIELDS.get(block.caller.type)))) return incompatible('content_extension');
+    if (block.type === 'image' && object(block.transformations)
+      && !knownFields(block.transformations, TRANSFORMATION_FIELDS)) return incompatible('content_extension');
+    if (block.type === 'tool_result' && Array.isArray(block.content)) contents.push(block.content);
+    if (block.type === 'tool_search_tool_result') {
+      const result = block.content;
+      if (!object(result) || !['tool_search_tool_search_result', 'tool_search_tool_result_error'].includes(result.type)
+        || !knownFields(result, CONTENT_FIELDS[result.type])) return incompatible('content_extension');
+      if (result.type === 'tool_search_tool_search_result') contents.push([result]);
+    }
+    if (block.type === 'tool_search_tool_search_result') {
+      if (!Array.isArray(block.tool_references)) return incompatible('content_extension');
+      contents.push(block.tool_references);
+    }
+  }
+  if (!targetFacts.assistantPrefill && body.messages.at(-1)?.role === 'assistant') return incompatible('assistant_prefill');
+  if (body.tool_choice !== undefined) {
+    if (!object(body.tool_choice) || !TOOL_CHOICE_FIELDS.has(body.tool_choice.type)
+      || !knownFields(body.tool_choice, TOOL_CHOICE_FIELDS.get(body.tool_choice.type))) return incompatible('tool_choice');
+    if (['any', 'tool'].includes(body.tool_choice.type) && (autoMode || !targetFacts.forcedToolChoice
+      || body.thinking?.type === 'enabled')) return incompatible('forced_tool_choice');
+  }
+  if (body.context_management != null) {
     const context = body.context_management;
-    if (!object(context) || Object.keys(context).some(key => key !== 'edits') || !Array.isArray(context.edits)
-      || context.edits.some(edit => !object(edit) || !CONTEXT_EDITS.has(edit.type))) return false;
+    if (!sourceFacts.sharedAuto || !targetFacts.sharedAuto || !object(context)
+      || Object.keys(context).some(key => key !== 'edits') || !Array.isArray(context.edits)
+      || !context.edits.every(sharedEdit)) return incompatible('context_management');
   }
   if (body.thinking !== undefined) {
     const thinking = body.thinking;
-    if (!object(thinking) || !['adaptive', 'disabled', 'between_tools'].includes(thinking.type)) return false;
+    if (!object(thinking) || (autoMode && !['adaptive', 'disabled', 'between_tools'].includes(thinking.type))) return incompatible('thinking_mode');
+    if (!THINKING_FIELDS.has(thinking.type) || !knownFields(thinking, THINKING_FIELDS.get(thinking.type))
+      || !optionalEnvelope(thinking.block_binding, THINKING_BINDING_FIELDS)) return incompatible('thinking_extension');
     // between_tools is Sonnet 5.5-specific. A routed Opus request uses
     // adaptive thinking; prepareRequest makes that explicit without touching
     // any prior thinking blocks or the conversation prefix they sign.
     if (thinking.type === 'between_tools' && (body.model !== 'claude-sonnet-5-5'
-      || Object.keys(thinking).some(key => key !== 'type') || target === 'claude-sonnet-5')) return false;
+      || Object.keys(thinking).some(key => key !== 'type') || target === 'claude-sonnet-5')) return incompatible('thinking_mode');
+    const adapted = prepareRequest(body, target).request.thinking;
+    if (!targetFacts.thinkingTypes.includes(adapted.type)) return incompatible('thinking_mode');
+    if (adapted.type === 'between_tools' && (Object.keys(adapted).length !== 1
+      || ['xhigh', 'max'].includes(body.output_config?.effort)
+      || body.messages.some(message => message.output_config?.effort !== undefined
+        && message.output_config.effort !== (body.output_config?.effort ?? 'high')))) return incompatible('thinking_effort');
+    if (target === 'claude-opus-5' && adapted.type === 'disabled'
+      && ['xhigh', 'max'].includes(body.output_config?.effort)) return incompatible('thinking_effort');
+  }
+  if (body.output_config !== undefined) {
+    const output = body.output_config;
+    if (!object(output) || Object.keys(output).some(key => !OUTPUT_FIELDS.has(key))) return incompatible('output_extension');
+    if (!optionalEnvelope(output.format, OUTPUT_FORMAT_FIELDS)
+      || (output.format != null && output.format.type !== 'json_schema')) return incompatible('output_extension');
+    if (!optionalEnvelope(output.task_budget, TASK_BUDGET_FIELDS)
+      || (output.task_budget != null && output.task_budget.type !== 'tokens')) return incompatible('task_budget');
+    if (output.effort != null && !targetFacts.effortLevels.includes(output.effort)) return incompatible('effort');
+    if (output.task_budget != null && !targetFacts.taskBudget) return incompatible('task_budget');
   }
-  // Sonnet 5 lacks mid-conversation system/tool/effort updates. Never flatten
-  // those messages into the top-level prompt: that invalidates signed history.
-  if (target === 'claude-sonnet-5' && (body.output_config?.task_budget !== undefined
-    || body.messages.some(message => message.role === 'system' || message.output_config !== undefined))) return false;
-  return true;
+  // Modern models reject non-default sampling. Shared modern source requests
+  // retain their own validation; upgrading an older model must not introduce
+  // this new restriction. Do not guess an undocumented numeric top_k default.
+  if (targetFacts.defaultSamplingOnly && !sourceFacts.defaultSamplingOnly
+    && ((body.temperature !== undefined && body.temperature !== 1)
+      || (body.top_p !== undefined && body.top_p !== 1) || body.top_k !== undefined)) return incompatible('sampling');
+  return compatible;
 }

package/src/bounded-json.mjs

@@ -0,0 +1,57 @@
+export const DECISION_RESPONSE_LIMIT = 64 * 1024;
+export const MODEL_METADATA_LIMIT = 1024 * 1024;
+
+// Cancellation is best effort and must never await an uncooperative body's
+// cancel promise. Fetch's signal remains responsible for its network request.
+export function cancelResponseBody(response, reason) {
+  try { Promise.resolve(response.body?.cancel(reason)).catch(() => {}); } catch {}
+}
+
+/**
+ * Read at most limit bytes, observing cancellation throughout body delivery.
+ * @param {Response} response
+ * @param {{signal?:AbortSignal,limit?:number}} [options]
+ */
+export async function readBoundedJson(response, { signal, limit = DECISION_RESPONSE_LIMIT } = {}) {
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new Error('classifier_invalid_response');
+  let reader;
+  let bytes;
+  let total = 0;
+  const cancel = () => {
+    try { Promise.resolve(reader?.cancel(signal?.reason)).catch(() => {}); } catch {}
+  };
+  try {
+    signal?.throwIfAborted();
+    reader = response.body?.getReader();
+    if (!reader) throw new Error('classifier_invalid_response');
+    signal?.addEventListener('abort', cancel, { once: true });
+    // Header sizes are only an early rejection. The streamed byte count is
+    // authoritative for chunked, compressed, absent or inaccurate lengths.
+    const length = response.headers?.get('content-length');
+    if (length && /^\d+$/.test(length) && Number(length) > limit) throw new Error('classifier_invalid_response');
+    while (true) {
+      signal?.throwIfAborted();
+      const { value, done } = await reader.read();
+      signal?.throwIfAborted();
+      if (done) break;
+      if (!(value instanceof Uint8Array) || value.byteLength > limit - total) throw new Error('classifier_invalid_response');
+      const next = total + value.byteLength;
+      // A single growable buffer also bounds metadata: a malicious one-byte
+      // chunk stream must not retain tens of thousands of Buffer objects.
+      if (!bytes || next > bytes.length) {
+        const capacity = Math.min(limit, Math.max(next, bytes ? bytes.length * 2 : Math.min(1024, limit)));
+        const grown = Buffer.allocUnsafe(capacity);
+        bytes?.copy(grown, 0, 0, total);
+        bytes = grown;
+      }
+      bytes.set(value, total);
+      total = next;
+    }
+    try { return JSON.parse(bytes?.toString('utf8', 0, total) ?? ''); }
+    catch { throw new Error('classifier_invalid_response'); }
+  } finally {
+    signal?.removeEventListener('abort', cancel);
+    if (reader) { cancel(); try { reader.releaseLock(); } catch {} }
+    else cancelResponseBody(response, signal?.reason);
+  }
+}

package/src/cli-help.mjs

@@ -0,0 +1,90 @@
+const commands = {
+  setup: `Usage: claude-autorouter setup [options]
+
+Configure the local Ollama evaluator (default) or TypeSafe Jev.
+  --auth-mode subscription|api-key   Default: subscription
+  --client-profile compatible|native|auto
+  --evaluator ollama|jev             Default: ollama (local); jev sends excerpts to TypeSafe
+  --ollama-model TAG                 Select a /v1/systemone model
+  --ollama-timeout-ms N              0 disables the routing deadline
+  --pull                            Download the selected missing Ollama model
+  --stop-hook-block-cap N            Optional Claude Stop-hook retry limit
+  --session-log-dir DIR              Opt in to private logs with prompt excerpts
+  --session-log-mode metadata|prompts Choose whether excerpts are included
+  --secret-store file|keychain       default on macOS for new setups; file is plaintext
+  --force                          Update an existing configuration
+  --replace                         Explicitly rebuild the saved configuration
+
+First setup reads environment settings and keys, or prompts for missing keys.
+--force retains saved defaults and applies explicit options; unrelated runtime
+overrides stay temporary. Explicit evaluator/auth selection accepts its supplied key.
+Examples: claude-autorouter setup --pull
+          claude-autorouter setup --evaluator jev`,
+  doctor: `Usage: claude-autorouter doctor [--evaluate-local] [--json]
+
+Check configuration, installed Claude, and local model availability.
+--evaluate-local explicitly tests synthetic routing cases on the existing
+Ollama model. No downloads, Anthropic/Jev calls, or configuration changes.
+--json returns the local evaluation report (requires --evaluate-local).
+
+Example: claude-autorouter doctor --evaluate-local`,
+  config: `Usage: claude-autorouter config show [--json] [--check-all]
+       claude-autorouter config set KEY VALUE
+       claude-autorouter config set KEY --stdin
+       claude-autorouter config unset KEY
+
+Show effective settings and their source; secrets are always redacted.
+--check-all also validates settings for the inactive evaluator.
+Set/unset changes only the named saved setting. Environment values still win.
+Secret keys require --stdin or a hidden prompt, never a command-line value.
+Setting AUTOROUTER_SECRET_STORE to keychain or file moves saved keys (macOS).
+
+Example: claude-autorouter config set AUTOROUTER_OLLAMA_TIMEOUT_MS 0`,
+  serve: `Usage: claude-autorouter serve
+
+Run a local Messages API gateway. Requires configured evaluator credentials,
+authentication, and AUTOROUTER_TOKEN (at least 16 characters).
+Use claude-autorouter claude for managed startup and cleanup.`,
+  sessions: `Usage: claude-autorouter sessions list [--json]
+       claude-autorouter sessions show ID [--json]
+
+Read optional local session logs from AUTOROUTER_SESSION_LOG_DIR.
+List prints the IDs used by show. History includes routing choices, observed
+models, request outcomes, latency, and API-equivalent savings coverage.
+Logging is off by default. To enable metadata-only history:
+  claude-autorouter config set AUTOROUTER_SESSION_LOG_MODE metadata
+  claude-autorouter config set AUTOROUTER_SESSION_LOG_DIR /path/to/private/logs`,
+  claude: `Usage: claude-autorouter claude [Claude Code arguments]
+
+Launch Claude with automatic routing and an AutoRouter status line.
+Example: claude-autorouter claude --permission-mode auto
+Auto mode switches between Sonnet and Opus on new human tasks.
+Claude owns permission checks and subscription authentication.
+--help and --version pass directly to Claude without starting the router.`,
+};
+
+export function helpText(command = 'help') {
+  return commands[command] ?? `AutoRouter — automatic model routing for Claude Code
+
+Usage: claude-autorouter <command> [options]
+
+  setup      Configure Jev or local Ollama; prompt for keys privately
+  doctor     Check configuration and local dependencies
+  config     Inspect or change saved settings without replacing them
+  sessions   Read optional local decision and outcome history
+  claude     Launch Claude Code with automatic routing
+  serve      Run the local gateway separately
+  --version  Print the AutoRouter version
+
+Start: claude-autorouter setup
+       claude-autorouter doctor
+       claude-autorouter claude --permission-mode auto
+
+Run claude-autorouter help <command> for options and examples.
+Local Ollama is the default evaluator and uses only the local /v1/systemone
+endpoint. Jev is optional; it receives bounded, redacted prompt excerpts. Complete requests go to Anthropic.
+Session logging is off unless AUTOROUTER_SESSION_LOG_DIR is configured.
+Environment variables override ~/.config/claude-autorouter/config.json.
+AUTOROUTER_CONFIG selects another file. Project .env files are not auto-loaded.
+Reference: docs/reference.md`;
+}

package/src/config-command.mjs

@@ -0,0 +1,158 @@
+import { readConfig, parseSessionLogDir, parseStopHookBlockCap } from './config.mjs';
+import { CONFIG_KEYS, SECRET_CONFIG_KEYS, SECRET_STORES, keychainRemovals, loadUserConfig, saveUserConfig } from './user-config.mjs';
+import { modelCapabilities } from './model-catalog.mjs';
+import { askSecret } from './onboarding.mjs';
+
+const secretKey = key => SECRET_CONFIG_KEYS.includes(key);
+const providerFor = key => key.startsWith('AUTOROUTER_OLLAMA_') ? 'ollama'
+  : key.startsWith('AUTOROUTER_JEV_') || key === 'AUTOROUTER_MIN_CONFIDENCE' || key === 'TYPESAFE_API_KEY' ? 'jev' : undefined;
+const safeText = value => String(value).replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, '');
+
+function effectiveValues(config, env) {
+  return {
+    AUTOROUTER_AUTH_MODE: config.authMode, AUTOROUTER_CLIENT_PROFILE: config.clientProfile,
+    AUTOROUTER_EVALUATOR: config.evaluator, AUTOROUTER_UPSTREAM_URL: config.upstream,
+    AUTOROUTER_HAIKU_MODEL: config.models.haiku, AUTOROUTER_SONNET_MODEL: config.models.sonnet,
+    AUTOROUTER_OPUS_MODEL: config.models.opus, AUTOROUTER_PORT: config.port,
+    AUTOROUTER_TOKEN_COUNT_TIMEOUT_MS: config.tokenCountTimeoutMs,
+    AUTOROUTER_JEV_URL: config.jevEndpoint, AUTOROUTER_JEV_MODEL: config.jevModel,
+    AUTOROUTER_JEV_TIMEOUT_MS: config.jevTimeoutMs, AUTOROUTER_MIN_CONFIDENCE: config.minConfidence,
+    AUTOROUTER_OLLAMA_URL: config.ollamaEndpoint, AUTOROUTER_OLLAMA_MODEL: config.ollamaModel,
+    AUTOROUTER_OLLAMA_TIMEOUT_MS: config.ollamaTimeoutMs, AUTOROUTER_OLLAMA_KEEP_ALIVE: config.ollamaKeepAlive,
+    AUTOROUTER_SESSION_LOG_DIR: config.sessionLogDir ?? null,
+    AUTOROUTER_SESSION_LOG_MODE: config.sessionLogMode,
+    CLAUDE_CODE_STOP_HOOK_BLOCK_CAP: config.stopHookBlockCap ?? null,
+    AUTOROUTER_STATUSLINE: env.AUTOROUTER_STATUSLINE !== '0',
+    AUTOROUTER_DEBUG: env.AUTOROUTER_DEBUG === '1', ENABLE_TOOL_SEARCH: env.ENABLE_TOOL_SEARCH ?? 'true',
+  };
+}
+
+/** Redacted effective configuration, independent of Claude launch arguments. */
+export function configReport(loaded, env, { checkAll = false } = {}) {
+  const config = readConfig(loaded.env);
+  const values = { ...effectiveValues(config, loaded.env), AUTOROUTER_SECRET_STORE: loaded.secretStore ?? 'file' };
+  const settings = {};
+  for (const key of CONFIG_KEYS) {
+    const saved = loaded.keychainSecrets?.includes(key) ? 'keychain' : 'file';
+    // The saved store setting governs saved secrets; the environment cannot redirect it.
+    const source = env[key] !== undefined && key !== 'AUTOROUTER_SECRET_STORE' ? 'environment'
+      : Object.hasOwn(loaded.values, key) ? saved : 'default';
+    const provider = providerFor(key);
+    const active = (!provider || provider === config.evaluator)
+      && (key !== 'ANTHROPIC_API_KEY' || config.authMode === 'api-key');
+    const secret = secretKey(key);
+    settings[key] = { source, active,
+      ...(source === 'environment' && Object.hasOwn(loaded.values, key) ? { overrides_file: true } : {}),
+      ...(source === 'environment' && loaded.unavailableSecrets?.includes(key) ? { keychain_unavailable: true } : {}),
+      ...(secret ? { secret: true, present: typeof loaded.env[key] === 'string' && Boolean(loaded.env[key].trim()) }
+        : { value: active ? values[key] ?? null : null }),
+    };
+  }
+  const warnings = [];
+  if (config.clientProfile === 'auto' && [config.models.sonnet, config.models.opus].some(model => !modelCapabilities(model)?.sharedAuto)) {
+    warnings.push('Auto permission eligibility does not guarantee automatic switching. Older targets can retain the incoming model for shared execution features.');
+  }
+  let valid = true, error;
+  if (checkAll) {
+    try { readConfig(loaded.env, { validateAll: true }); }
+    catch (failure) { valid = false; error = failure.message; }
+  }
+  return { schema_version: 1, config_path: loaded.path, config_exists: loaded.exists, valid,
+    checked: checkAll ? 'all_evaluators' : 'active_evaluator', settings, warnings,
+    ...(error ? { error } : {}),
+  };
+}
+
+async function stdinSecret(input) {
+  if (input.isTTY) throw new Error('Pipe the secret to --stdin, or omit --stdin to use the hidden prompt.');
+  const chunks = [];
+  let bytes = 0;
+  try {
+    for await (const chunk of input) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      bytes += buffer.length;
+      if (bytes > 16384) throw new Error('Secret input exceeds the supported size.');
+      chunks.push(buffer);
+    }
+  } catch { throw new Error('Could not read a bounded secret from stdin.'); }
+  return Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
+}
+
+function normalizedValue(key, value) {
+  if (typeof value !== 'string') throw new Error('Configuration values must be strings.');
+  if (secretKey(key)) {
+    const normalized = value.trim();
+    if (!normalized || /[\r\n\0]/.test(normalized)) throw new Error(`${key} must be a nonempty, single-line secret.`);
+    if (key === 'AUTOROUTER_TOKEN' && normalized.length < 16) throw new Error('AUTOROUTER_TOKEN must contain at least 16 characters.');
+    return normalized;
+  }
+  if (key === 'AUTOROUTER_SESSION_LOG_DIR') return parseSessionLogDir(value) ?? '';
+  if (key === 'CLAUDE_CODE_STOP_HOOK_BLOCK_CAP') return String(parseStopHookBlockCap(value));
+  if (key === 'AUTOROUTER_SECRET_STORE' && !SECRET_STORES.includes(value)) throw new Error('AUTOROUTER_SECRET_STORE must be file or keychain.');
+  if (/[\r\n\0\u001b]/.test(value)) throw new Error(`${key} must be a single-line setting.`);
+  return value;
+}
+
+export async function configCommand(args, {
+  env = process.env, write = console.log, input = process.stdin, promptSecret = askSecret, keychain,
+} = {}) {
+  const store = keychain ? { keychain } : {};
+  const [operation, ...rest] = args;
+  if (operation === 'show') {
+    if (rest.some(arg => !['--json', '--check-all'].includes(arg))) throw new Error('Usage: claude-autorouter config show [--json] [--check-all]');
+    let loaded, report;
+    try {
+      loaded = loadUserConfig(env, { allowMissing: true, ...store });
+      report = configReport(loaded, env, { checkAll: rest.includes('--check-all') });
+    }
+    catch (error) {
+      report = { schema_version: 1, ...(loaded ? { config_path: loaded.path, config_exists: loaded.exists } : {}), valid: false, error: error.message };
+    }
+    if (rest.includes('--json')) write(JSON.stringify(report, null, 2));
+    else {
+      if (loaded) write(`Config: ${loaded.path}${loaded.exists ? '' : ' (not saved)'}`);
+      for (const [key, setting] of Object.entries(report.settings ?? {})) {
+        const value = setting.secret ? setting.present ? '[set; hidden]' : '[unset]'
+          : !setting.active ? '[inactive]' : setting.value === null ? '[unset]' : safeText(setting.value);
+        write(`${key}=${value} [${setting.source}${setting.overrides_file ? '; overrides file' : ''}${!setting.active ? '; inactive' : ''}]`);
+      }
+      for (const warning of report.warnings ?? []) write(warning);
+      if (report.error) write(`FAIL  ${report.error}`);
+    }
+    return report.valid;
+  }
+  if (!['set', 'unset'].includes(operation)) throw new Error('Usage: claude-autorouter config show|set|unset');
+  const [key, value, ...extra] = rest;
+  // Never echo an unknown key: it may itself be a pasted credential.
+  if (!CONFIG_KEYS.includes(key)) throw new Error('Unsupported configuration key. Run claude-autorouter config show for supported settings.');
+  if (extra.length || (operation === 'unset' && value !== undefined)) throw new Error(`Usage: claude-autorouter config ${operation} KEY${operation === 'set' ? ' VALUE' : ''}`);
+  if (operation === 'set' && secretKey(key) && value !== undefined && value !== '--stdin') {
+    throw new Error('Secret values are not accepted as command arguments. Use --stdin or the hidden prompt.');
+  }
+  if (operation === 'set' && !secretKey(key) && (value === undefined || value === '--stdin')) throw new Error('Nonsecret settings require a value argument.');
+  const loaded = loadUserConfig(env, { allowMissing: true, ...store });
+  const next = { ...loaded.values };
+  if (operation === 'unset') delete next[key];
+  else next[key] = normalizedValue(key, secretKey(key)
+    ? value === '--stdin' ? await stdinSecret(input) : await promptSecret(key)
+    : value);
+  // Validate the persisted setting itself, not an environment value that could
+  // mask it. An explicitly edited inactive provider is checked too.
+  const provider = operation === 'set' ? providerFor(key) : undefined;
+  readConfig({ ...next, ...(provider ? { AUTOROUTER_EVALUATOR: provider } : {}) });
+  const nextStore = next.AUTOROUTER_SECRET_STORE ?? 'file';
+  // Changing the store moves saved secrets; unsetting a secret deletes its item.
+  const removeSecrets = key === 'AUTOROUTER_SECRET_STORE' ? keychainRemovals(loaded, nextStore)
+    : operation === 'unset' && secretKey(key) && loaded.secretStore === 'keychain' ? [key] : [];
+  saveUserConfig(next, { env, overwrite: loaded.exists, expectedRevision: loaded.revision, removeSecrets, ...store });
+  if (key === 'AUTOROUTER_SECRET_STORE') {
+    const moved = SECRET_CONFIG_KEYS.filter(name => Object.hasOwn(next, name)).length;
+    const where = nextStore === 'keychain' ? 'macOS Keychain' : 'configuration file';
+    write(nextStore === loaded.secretStore || !moved ? `Saved ${key}. Saved secrets are stored in the ${where}.`
+      : `Saved ${key}. Moved ${moved} saved secret${moved === 1 ? '' : 's'} to the ${where}.`);
+    return true;
+  }
+  write(`${operation === 'unset' ? 'Removed saved' : 'Saved'} ${key}${secretKey(key) && nextStore === 'keychain' ? ' in the macOS Keychain' : ''}. Other saved settings are unchanged.`);
+  if (env[key] !== undefined) write(`The current environment still overrides ${key}; unset that environment variable to use the saved/default value.`);
+  return true;
+}