converse-mcp-server 3.7.1 → 4.1.0

package/src/decisionProviders/systemOne.js

@@ -0,0 +1,199 @@
+/**
+ * System One HTTP client
+ *
+ * One client for every host of the System One decision API. TypeSafe serves it
+ * natively at `/v1/systemone`; OpenRouter serves the same request/response
+ * schema at the same path under its own base URL, so providers differ only in
+ * base URL, key, and headers.
+ *
+ * Plain fetch rather than @typesafe-ai/sdk: the schema is small, the tool
+ * needs its own abort signal and error mapping, and the SDK's model listing
+ * breaks against OpenRouter.
+ */
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_RETRIES = 2;
+const BACKOFF_INITIAL_MS = 500;
+const BACKOFF_MAX_MS = 5_000;
+// A longer server-requested wait is better spent failing over to another host.
+const MAX_RETRY_AFTER_MS = 30_000;
+
+/**
+ * Error from a System One call. `retryable` marks failures worth repeating or
+ * failing over (network, timeout, 408/429/5xx, auth); `terminal` marks request
+ * faults that every host would reject the same way.
+ */
+export class DecisionError extends Error {
+  constructor(message, { status = null, retryable = false, terminal = false, requestId = null, retryAfterMs = null } = {}) {
+    super(message);
+    this.name = 'DecisionError';
+    this.status = status;
+    this.retryable = retryable;
+    this.terminal = terminal;
+    this.requestId = requestId;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/**
+ * Render a validation issue list (zod-style `[{path, message}]`) as one line
+ * per issue; anything else is returned as-is.
+ */
+function formatIssues(text) {
+  let issues;
+  try {
+    issues = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  if (!Array.isArray(issues) || !issues.every((i) => i && typeof i.message === 'string')) {
+    return text;
+  }
+  return issues
+    .map((i) => (Array.isArray(i.path) && i.path.length ? `${i.path.join('.')}: ${i.message}` : i.message))
+    .join('; ');
+}
+
+/**
+ * Extract a readable message from an error body. OpenRouter wraps errors as
+ * `{ error: { message } }`; TypeSafe answers `{ detail: { error_type, message } }`,
+ * or `{ detail }` as a string or a list of validation issues.
+ */
+export function extractErrorMessage(body, rawText) {
+  if (typeof body?.detail?.message === 'string') {
+    const type = body.detail.error_type ? `${body.detail.error_type}: ` : '';
+    return `${type}${body.detail.message}`;
+  }
+  const nested = body?.error?.message ?? body?.error ?? body?.detail ?? body?.message;
+  if (typeof nested === 'string') {
+    const inner = nested.match(/^HTTP \d+: (\{.*\})$/s);
+    if (inner) {
+      try {
+        return extractErrorMessage(JSON.parse(inner[1]), inner[1]);
+      } catch {
+        return nested;
+      }
+    }
+    return formatIssues(nested);
+  }
+  if (Array.isArray(nested)) {
+    return nested
+      .map((d) => (d?.loc ? `${d.loc.join('.')}: ${d.msg}` : d?.msg || JSON.stringify(d)))
+      .join('; ');
+  }
+  return rawText?.trim() || 'No error details returned';
+}
+
+function parseRetryAfter(headers) {
+  const ms = Number(headers.get('retry-after-ms'));
+  if (Number.isFinite(ms) && ms > 0) return ms;
+  const value = headers.get('retry-after');
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return seconds * 1000;
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(signal.reason);
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+async function sendOnce({ url, headers, body, signal, timeoutMs }) {
+  const attemptSignal = signal
+    ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])
+    : AbortSignal.timeout(timeoutMs);
+
+  let response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify(body),
+      signal: attemptSignal,
+    });
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    const timedOut = error?.name === 'TimeoutError';
+    throw new DecisionError(
+      timedOut ? `Request timed out after ${timeoutMs / 1000}s` : `Connection failed: ${error.message}`,
+      { retryable: true },
+    );
+  }
+
+  const rawText = await response.text();
+  let parsed = null;
+  try {
+    parsed = rawText ? JSON.parse(rawText) : null;
+  } catch {
+    parsed = null;
+  }
+
+  if (!response.ok) {
+    const status = response.status;
+    throw new DecisionError(`HTTP ${status}: ${extractErrorMessage(parsed, rawText)}`, {
+      status,
+      retryable: status === 408 || status === 429 || status >= 500 || status === 401 || status === 403,
+      terminal: status === 400 || status === 422,
+      requestId: response.headers.get('x-typesafe-request-id') || response.headers.get('x-generation-id'),
+      retryAfterMs: parseRetryAfter(response.headers),
+    });
+  }
+
+  if (!parsed || typeof parsed.answers !== 'object' || parsed.answers === null) {
+    throw new DecisionError('Malformed response: missing "answers" object', { status: response.status });
+  }
+  return parsed;
+}
+
+/**
+ * POST a decision request, retrying transient failures (except auth, which
+ * retrying cannot fix) with exponential backoff that honors Retry-After.
+ * @param {object} params
+ * @param {string} params.baseURL - Host base, e.g. https://api.typesafe.ai
+ * @param {object} params.headers - Auth and attribution headers
+ * @param {object} params.body - `{ model, state, questions }`
+ * @param {AbortSignal} [params.signal] - Caller cancellation
+ * @param {number} [params.timeoutMs] - Per-attempt timeout
+ * @param {number} [params.maxRetries] - Retries after the first attempt
+ * @returns {Promise<object>} Parsed response body
+ */
+export async function callSystemOne({
+  baseURL,
+  headers,
+  body,
+  signal,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  maxRetries = DEFAULT_MAX_RETRIES,
+}) {
+  const url = `${baseURL.replace(/\/+$/, '')}/v1/systemone`;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await sendOnce({ url, headers, body, signal, timeoutMs });
+    } catch (error) {
+      const authFailure = error.status === 401 || error.status === 403;
+      if (!(error instanceof DecisionError) || !error.retryable || authFailure || attempt >= maxRetries) {
+        throw error;
+      }
+      if (error.retryAfterMs !== null && error.retryAfterMs > MAX_RETRY_AFTER_MS) {
+        throw error;
+      }
+      const backoff = Math.min(BACKOFF_INITIAL_MS * 2 ** attempt, BACKOFF_MAX_MS);
+      await sleep(error.retryAfterMs ?? backoff, signal);
+    }
+  }
+}

package/src/prompts/helpPrompt.js

@@ -8,6 +8,11 @@
 import { getProviders } from '../providers/index.js';
 import { getTools } from '../tools/index.js';
 import { CONFIG_SCHEMA } from '../config.js';
+import {
+  BARE_NAME_PRIORITY,
+  PROVIDER_NAMESPACES,
+  PROVIDER_PRIORITY,
+} from '../utils/modelRouting.js';
 
 /**
  * Sample values for generating realistic tool examples.
@@ -147,6 +152,27 @@ function generateToolExamplesFromSchema(toolName, inputSchema) {
     ].join('\n');
   }
 
+  if (toolName === 'decide') {
+    const decideExample = {
+      state: { message: 'I was charged twice for order A-104. Please fix this ASAP.' },
+      questions: {
+        urgent: { type: 'noul', instructions: 'Does the message convey urgency?' },
+        team: {
+          type: 'choice',
+          instructions: 'Which team should handle this?',
+          criteria: { billing: 'Payments, invoicing, refunds', technical: 'Bugs, outages', sales: null },
+        },
+        frustration: {
+          type: 'score',
+          instructions: 'How frustrated is the customer?',
+          criteria: ['Calm', 'Frustrated', 'Very angry'],
+        },
+      },
+      model: 'auto',
+    };
+    return `\`\`\`json\n${JSON.stringify(decideExample, null, 2)}\n\`\`\``;
+  }
+
   if (toolName === 'check_status' || toolName === 'cancel_job') {
     if (properties.continuation_id)
       example.continuation_id = SAMPLE_VALUES.continuation_id;
@@ -352,6 +378,7 @@ export function generateHelpContent(config = null) {
     codex: safeGetModels(providers.codex, 'codex'),
     claude: safeGetModels(providers.claude, 'claude'),
     'gemini-cli': safeGetModels(providers['gemini-cli'], 'gemini-cli'),
+    copilot: safeGetModels(providers.copilot, 'copilot'),
   };
 
   // Limit OpenRouter models if dynamic models enabled (could have hundreds)
@@ -406,8 +433,9 @@ export function generateHelpContent(config = null) {
         prop.default !== undefined
           ? ` (default: ${JSON.stringify(prop.default)})`
           : '';
+      const type = prop.type ?? prop.anyOf?.map((s) => s.type).join(' | ');
       params.push(
-        `- **${name}** (${isRequired ? 'required' : 'optional'}, ${prop.type}): ${prop.description}${defaultValue}`,
+        `- **${name}** (${isRequired ? 'required' : 'optional'}, ${type}): ${prop.description}${defaultValue}`,
       );
     }
 
@@ -436,6 +464,21 @@ Welcome to the Converse MCP Server! This guide provides detailed information abo
 
 ${toolsSection}
 
+## Model Names
+
+Every entry in \`models\` takes one of these forms:
+
+- **\`provider\`** — that provider's default model (e.g. \`codex\`, \`claude\`, \`gemini\`, \`openai\`). Override a default with \`<PROVIDER>_DEFAULT_MODEL\` (see Environment Variables).
+- **\`provider:model\`** — that model on that provider only (e.g. \`codex:astra\`, \`openai:gpt-6-astra\`, \`gemini:pro\`, \`copilot:sonnet\`). \`model\` is a model ID or alias from the provider's list below.
+- **\`model\`** — a bare model ID or alias (e.g. \`gpt-6-astra\`, \`opus\`). It goes to the first configured provider that offers it, in this order: ${BARE_NAME_PRIORITY.join(', ')}. When that provider fails with an auth or availability error, the next provider offering the same model takes over. Copilot is reachable only as \`copilot:model\`.
+- **\`auto\`** — the default model of the first available provider (${PROVIDER_PRIORITY.join(', ')}).
+
+Provider namespaces: ${Object.entries(PROVIDER_NAMESPACES)
+    .map(([name, tokens]) => (tokens.length > 1 ? `${tokens[0]} (${name}; also ${tokens.slice(1).join(', ')})` : tokens[0]))
+    .join(', ')}. OpenRouter also accepts any \`vendor/model\` slug, bare or as \`openrouter:vendor/model\`, checked against OpenRouter's live catalog.
+
+Names that match nothing are rejected with "did you mean" suggestions rather than guessed.
+
 ## Provider Models
 ${formatProviderModels('OpenAI', allModels.openai)}
 ${formatProviderModels('Google Gemini', allModels.google)}
@@ -447,6 +490,7 @@ ${formatProviderModels('OpenRouter', allModels.openrouter)}
 ${formatProviderModels('Codex', allModels.codex)}
 ${formatProviderModels('Claude CLI', allModels.claude)}
 ${formatProviderModels('Gemini (Antigravity CLI)', allModels['gemini-cli'])}
+${formatProviderModels('GitHub Copilot', allModels.copilot)}
 
 ${generateModelCategories(allModels)}
 
@@ -482,9 +526,12 @@ ${generateEnvironmentVariablesSection()}
 
 These providers use local CLI tools and don't require API keys:
 
-- **codex**: Requires ChatGPT login or CODEX_API_KEY environment variable
-- **claude**: Requires \`claude login\` command (Claude Code CLI authentication)
+- **codex**: Requires ChatGPT login (\`codex login\`) or CODEX_API_KEY environment variable
+- **claude**: Requires \`claude login\` command (Claude Code CLI authentication) or CLAUDE_CODE_OAUTH_TOKEN
 - **gemini-cli**: Requires the Antigravity CLI (\`agy\`) installed and authenticated via Google OAuth (run \`agy\` once interactively to log in)
+- **copilot**: Requires @github/copilot-sdk and a GitHub Copilot subscription
+
+Codex and Claude count as available only when their login file or token is present; an expired login is detected at call time and routing fails over to the next provider.
 
 ## Need More Help?
 

package/src/providers/anthropic.js

@@ -587,7 +587,11 @@ async function getAnthropicSDK() {
 /**
  * Main Anthropic provider implementation
  */
+const DEFAULT_MODEL = 'claude-opus-5-5';
+
 export const anthropicProvider = {
+  defaultModel: DEFAULT_MODEL,
+
   /**
    * Unified provider interface: invoke messages with options
    * @param {Array} messages - Array of message objects with role and content
@@ -596,7 +600,7 @@ export const anthropicProvider = {
    */
   async invoke(messages, options = {}) {
     const {
-      model = 'claude-opus-5-5',
+      model = DEFAULT_MODEL,
       maxTokens = null,
       stream = false,
       reasoning_effort = 'medium',

package/src/providers/claude.js

@@ -16,14 +16,20 @@
 import { debugLog, debugError } from '../utils/console.js';
 import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
 import { clampReasoningEffort } from '../utils/reasoningEffort.js';
+import { findCatalogEntry, findCatalogId } from '../utils/modelCatalog.js';
+import {
+  hasClaudeCredentials,
+  isPackageResolvable,
+} from '../utils/localProviderAuth.js';
 
-// Default underlying model when the request is just "claude" (or "claude:opus")
-const DEFAULT_SDK_MODEL = 'claude-opus-5-5';
+const DEFAULT_MODEL = 'claude-opus-5-5';
 const SDK_EFFORT_TIERS = ['low', 'medium', 'high', 'xhigh', 'max'];
+const CLAUDE_SDK_PACKAGE = '@anthropic-ai/claude-agent-sdk';
 
-// Supported Claude SDK models with their configurations
+// Keyed by the model ID the Agent SDK accepts, which is also the canonical ID
+// the router resolves to.
 const SUPPORTED_MODELS = {
-  opus: {
+  'claude-opus-5-5': {
     modelName: 'claude-opus-5-5',
     friendlyName: 'Claude Opus 5.5 (via Agent SDK)',
     contextWindow: 1000000,
@@ -35,18 +41,14 @@ const SUPPORTED_MODELS = {
     description:
       'Claude Opus 5.5 via Agent SDK (default) - requires claude login authentication',
     aliases: [
-      'claude',
-      'claude-sdk',
-      'claude-code',
-      'claude:opus',
+      'opus',
       'claude-opus',
-      'claude-opus-5-5',
       'claude-opus-5.5',
       'opus-5-5',
       'opus-5.5',
     ],
   },
-  'opus-5': {
+  'claude-opus-5': {
     modelName: 'claude-opus-5',
     friendlyName: 'Claude Opus 5 (via Agent SDK)',
     contextWindow: 1000000,
@@ -57,9 +59,9 @@ const SUPPORTED_MODELS = {
     timeout: 1800000,
     description:
       'Claude Opus 5 via Agent SDK - requires claude login authentication',
-    aliases: ['claude-opus-5'],
+    aliases: ['opus-5', 'opus5'],
   },
-  fable: {
+  'claude-fable-5-1': {
     modelName: 'claude-fable-5-1',
     friendlyName: 'Claude Fable 5.1 (via Agent SDK)',
     contextWindow: 1000000,
@@ -71,15 +73,14 @@ const SUPPORTED_MODELS = {
     description:
       'Claude Fable 5.1 via Agent SDK - requires claude login authentication',
     aliases: [
-      'claude:fable',
+      'fable',
       'claude-fable',
-      'claude-fable-5-1',
       'claude-fable-5.1',
       'fable-5-1',
       'fable-5.1',
     ],
   },
-  'fable-5': {
+  'claude-fable-5': {
     modelName: 'claude-fable-5',
     friendlyName: 'Claude Fable 5 (via Agent SDK)',
     contextWindow: 1000000,
@@ -90,7 +91,7 @@ const SUPPORTED_MODELS = {
     timeout: 1800000,
     description:
       'Claude Fable 5 via Agent SDK - requires claude login authentication',
-    aliases: ['claude-fable-5'],
+    aliases: ['fable-5', 'fable5'],
   },
 };
 
@@ -104,25 +105,12 @@ class ClaudeProviderError extends ProviderError {
   }
 }
 
-/**
- * Check if Claude SDK is available (optional dependency)
- */
-function isClaudeSDKAvailable() {
-  try {
-    // Simple presence check that works in ES modules
-    // If SDK not available, the actual import() will fail later with clear error
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Dynamically import Claude SDK (lazy loading)
  * This keeps the SDK as an optional dependency
  */
 async function getClaudeSDK() {
-  if (!isClaudeSDKAvailable()) {
+  if (!isPackageResolvable(CLAUDE_SDK_PACKAGE)) {
     throw new ClaudeProviderError(
       'Claude SDK not installed. Install with: npm install @anthropic-ai/claude-agent-sdk',
       'CLAUDE_SDK_NOT_INSTALLED',
@@ -143,58 +131,24 @@ async function getClaudeSDK() {
 }
 
 /**
- * Look up model config from SUPPORTED_MODELS by name or alias.
- * Strips the claude: prefix first (e.g. "claude:opus" -> "opus").
- */
-function findModelConfig(modelName) {
-  if (typeof modelName !== 'string') return null;
-
-  let name = modelName.trim();
-  if (name.toLowerCase().startsWith('claude:')) {
-    name = name.slice('claude:'.length).trim();
-  }
-  if (!name) return SUPPORTED_MODELS.opus;
-
-  const nameLower = name.toLowerCase();
-
-  if (SUPPORTED_MODELS[nameLower]) {
-    return SUPPORTED_MODELS[nameLower];
-  }
-
-  for (const config of Object.values(SUPPORTED_MODELS)) {
-    if (
-      config.aliases &&
-      config.aliases.some((alias) => alias.toLowerCase() === nameLower)
-    ) {
-      return config;
-    }
-  }
-
-  return null;
-}
-
-/**
- * Resolve the requested model to the underlying SDK model ID.
- * - "claude" (and bare "claude:") defaults to Claude Opus 5.5
- * - "claude:opus" / "claude:opus-5" / "claude:fable" / "claude:fable-5" select the specific model
- * - Unknown names are passed through (after prefix stripping) so users can
- *   target any model ID the Agent SDK accepts (e.g. "claude:claude-sonnet-4-6")
+ * Resolve a model name to the Agent SDK model ID. The router hands over
+ * canonical catalog IDs; aliases are accepted for direct callers.
+ * @param {string} [modelName] - Catalog ID or alias; defaults to DEFAULT_MODEL
+ * @returns {string}
+ * @throws {ClaudeProviderError} When the name is not in the catalog
  */
 function resolveSdkModel(modelName) {
   if (typeof modelName !== 'string' || !modelName.trim()) {
-    return DEFAULT_SDK_MODEL;
+    return DEFAULT_MODEL;
   }
-
-  const config = findModelConfig(modelName);
-  if (config) {
-    return config.modelName;
-  }
-
-  let name = modelName.trim();
-  if (name.toLowerCase().startsWith('claude:')) {
-    name = name.slice('claude:'.length).trim();
+  const id = findCatalogId(SUPPORTED_MODELS, modelName);
+  if (!id) {
+    throw new ClaudeProviderError(
+      `Unknown Claude model "${modelName}"`,
+      ErrorCodes.MODEL_NOT_FOUND,
+    );
   }
-  return name || DEFAULT_SDK_MODEL;
+  return SUPPORTED_MODELS[id].modelName;
 }
 
 /**
@@ -338,7 +292,7 @@ async function* createStreamingGenerator(
   try {
     const queryOptions = {
       ...options,
-      model: options.model || DEFAULT_SDK_MODEL,
+      model: options.model || DEFAULT_MODEL,
       maxTurns: 100,
       permissionMode: 'bypassPermissions', // Don't prompt for permissions
     };
@@ -475,7 +429,7 @@ export const claudeProvider = {
    */
   async invoke(messages, options = {}) {
     const {
-      model = 'claude',
+      model = DEFAULT_MODEL,
       config,
       stream = false,
       signal,
@@ -616,16 +570,14 @@ export const claudeProvider = {
     }
   },
 
+  defaultModel: DEFAULT_MODEL,
+
   /**
-   * Validate Claude SDK configuration
-   * Claude SDK uses CLI authentication (NOT API keys)
-   * Returns true optimistically - authentication errors handled at runtime
+   * Validate Claude SDK configuration: the SDK is installed and a Claude Code
+   * credential is present. Expired logins surface at invoke time.
    */
   validateConfig(_config) {
-    // Claude SDK uses CLI authentication, not API keys
-    // We can't reliably check auth status, so return true optimistically
-    // and let the SDK handle authentication errors during execution
-    return isClaudeSDKAvailable();
+    return isPackageResolvable(CLAUDE_SDK_PACKAGE) && hasClaudeCredentials();
   },
 
   /**
@@ -644,9 +596,8 @@ export const claudeProvider = {
 
   /**
    * Get model configuration for specific model
-   * Handles claude: prefixed names (e.g. "claude:opus", "claude:fable", "claude:opus-5")
    */
   getModelConfig(modelName) {
-    return findModelConfig(modelName);
+    return findCatalogEntry(SUPPORTED_MODELS, modelName);
   },
 };