byterover-cli 0.4.0 → 1.0.0

package/dist/core/domain/cipher/llm/registry.js

@@ -0,0 +1,244 @@
+/**
+ * LLM Model Registry - Single Source of Truth for Model Metadata.
+ *
+ * This registry provides centralized model information including:
+ * - Context window sizes (maxInputTokens)
+ * - Character-per-token ratios for estimation
+ * - Supported file types for multimodal input
+ * - Model capabilities
+ *
+ * Following patterns from Dexto's LLM registry.
+ */
+import { LLM_PROVIDERS, } from './types.js';
+/** Default fallback for unknown models */
+export const DEFAULT_MAX_INPUT_TOKENS = 128_000;
+export const DEFAULT_CHARS_PER_TOKEN = 4;
+/**
+ * LLM Model Registry
+ *
+ * IMPORTANT: supportedFileTypes is the SINGLE SOURCE OF TRUTH for file upload capabilities:
+ * - Empty array [] = Model does NOT support file uploads
+ * - Specific types ['image', 'pdf'] = Model supports ONLY those file types
+ */
+export const LLM_REGISTRY = {
+    claude: {
+        defaultModel: '',
+        models: [],
+        supportedFileTypes: [],
+    },
+    gemini: {
+        defaultModel: 'gemini-2.5-flash',
+        models: [
+            // Gemini 2.5 series
+            {
+                capabilities: {
+                    supportsAudio: true,
+                    supportsImages: true,
+                    supportsPdf: true,
+                    supportsStreaming: true,
+                    supportsThinking: true,
+                },
+                charsPerToken: 4,
+                default: true,
+                displayName: 'Gemini 2.5 Flash',
+                maxInputTokens: 1_000_000,
+                maxOutputTokens: 8192,
+                name: 'gemini-2.5-flash',
+                pricing: { inputPerM: 0.075, outputPerM: 0.3 },
+                supportedFileTypes: ['image', 'pdf', 'audio'],
+            },
+            // Gemini 1.5 series
+            {
+                capabilities: {
+                    supportsAudio: true,
+                    supportsImages: true,
+                    supportsPdf: true,
+                    supportsStreaming: true,
+                    supportsThinking: false,
+                },
+                charsPerToken: 4,
+                displayName: 'Gemini 1.5 Pro',
+                maxInputTokens: 2_000_000,
+                maxOutputTokens: 8192,
+                name: 'gemini-1.5-pro',
+                pricing: { inputPerM: 1.25, outputPerM: 5 },
+                supportedFileTypes: ['image', 'pdf', 'audio'],
+            },
+        ],
+        supportedFileTypes: ['image', 'pdf', 'audio'],
+    },
+    openrouter: {
+        defaultModel: '',
+        models: [],
+        supportedFileTypes: [],
+    },
+};
+// ============================================================================
+// Registry Helper Functions
+// ============================================================================
+/**
+ * Get model information from the registry.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns ModelInfo or undefined if not found
+ */
+export function getModelInfo(provider, model) {
+    const providerInfo = LLM_REGISTRY[provider];
+    if (!providerInfo)
+        return undefined;
+    return providerInfo.models.find((m) => m.name === model);
+}
+/**
+ * Get model info with fallback for unknown models.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns ModelInfo (falls back to default values for unknown models)
+ */
+export function getModelInfoWithFallback(provider, model) {
+    const info = getModelInfo(provider, model);
+    if (info)
+        return info;
+    // Fallback for unknown models
+    const providerInfo = LLM_REGISTRY[provider];
+    return {
+        capabilities: {
+            supportsAudio: false,
+            supportsImages: provider !== 'openrouter', // Assume basic image support
+            supportsPdf: provider === 'claude' || provider === 'gemini',
+            supportsStreaming: true,
+        },
+        charsPerToken: DEFAULT_CHARS_PER_TOKEN,
+        displayName: model,
+        maxInputTokens: DEFAULT_MAX_INPUT_TOKENS,
+        name: model,
+        supportedFileTypes: providerInfo?.supportedFileTypes ?? [],
+    };
+}
+/**
+ * Get characters per token ratio for a model.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns Characters per token ratio
+ */
+export function getCharsPerToken(provider, model) {
+    const info = getModelInfo(provider, model);
+    return info?.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+}
+/**
+ * Get maximum input tokens for a model.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns Maximum input tokens
+ */
+export function getMaxInputTokensForModel(provider, model) {
+    const info = getModelInfo(provider, model);
+    return info?.maxInputTokens ?? DEFAULT_MAX_INPUT_TOKENS;
+}
+/**
+ * Check if a model is valid for a provider.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns true if the model is in the registry
+ */
+export function isValidProviderModel(provider, model) {
+    return getModelInfo(provider, model) !== undefined;
+}
+/**
+ * Get supported models for a provider.
+ * @param provider - LLM provider
+ * @returns Array of model names
+ */
+export function getSupportedModels(provider) {
+    const providerInfo = LLM_REGISTRY[provider];
+    if (!providerInfo)
+        return [];
+    return providerInfo.models.map((m) => m.name);
+}
+/**
+ * Get the default model for a provider.
+ * @param provider - LLM provider
+ * @returns Default model name
+ */
+export function getDefaultModelForProvider(provider) {
+    const providerInfo = LLM_REGISTRY[provider];
+    return providerInfo?.defaultModel ?? '';
+}
+/**
+ * Infer provider from model name.
+ * @param model - Model name
+ * @returns LLMProvider or undefined if not found
+ */
+export function getProviderFromModel(model) {
+    // Check each provider's models
+    for (const provider of LLM_PROVIDERS) {
+        if (getModelInfo(provider, model)) {
+            return provider;
+        }
+    }
+    // Fallback: infer from model name prefix
+    const lowerModel = model.toLowerCase();
+    if (lowerModel.startsWith('claude'))
+        return 'claude';
+    if (lowerModel.startsWith('gemini'))
+        return 'gemini';
+    if (lowerModel.includes('/'))
+        return 'openrouter'; // OpenRouter uses provider/model format
+    return undefined;
+}
+/**
+ * Get supported file types for a model.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns Array of supported file types
+ */
+export function getSupportedFileTypesForModel(provider, model) {
+    const info = getModelInfo(provider, model);
+    if (info)
+        return info.supportedFileTypes;
+    // Fallback to provider-level defaults
+    const providerInfo = LLM_REGISTRY[provider];
+    return providerInfo?.supportedFileTypes ?? [];
+}
+/**
+ * Check if a model supports a specific file type.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @param fileType - File type to check
+ * @returns true if the model supports the file type
+ */
+export function modelSupportsFileType(provider, model, fileType) {
+    const supportedTypes = getSupportedFileTypesForModel(provider, model);
+    return supportedTypes.includes(fileType);
+}
+/**
+ * Get model capabilities.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns ModelCapabilities
+ */
+export function getModelCapabilities(provider, model) {
+    const info = getModelInfoWithFallback(provider, model);
+    return info.capabilities;
+}
+/**
+ * Get effective max input tokens considering config override.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @param configuredMax - Optional configured max from user
+ * @returns Effective max input tokens (min of model limit and configured limit)
+ */
+export function getEffectiveMaxInputTokens(provider, model, configuredMax) {
+    const modelMax = getMaxInputTokensForModel(provider, model);
+    if (configuredMax === undefined)
+        return modelMax;
+    return Math.min(modelMax, configuredMax);
+}
+/**
+ * Check if OpenRouter accepts any model (custom models).
+ * OpenRouter can route to many models not in our registry.
+ * @param provider - LLM provider
+ * @returns true if provider accepts arbitrary models
+ */
+export function acceptsAnyModel(provider) {
+    return provider === 'openrouter';
+}

package/dist/core/domain/cipher/llm/schemas.d.ts

@@ -0,0 +1,155 @@
+/**
+ * LLM Configuration Schemas
+ *
+ * Zod schemas for validating LLM configuration with cross-field validation.
+ */
+import { z } from 'zod';
+/**
+ * Base LLM config object schema (before validation/branding).
+ */
+export declare const LLMConfigBaseSchema: z.ZodObject<{
+    maxInputTokens: z.ZodOptional<z.ZodNumber>;
+    maxIterations: z.ZodDefault<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    model: z.ZodString;
+    provider: z.ZodEnum<["claude", "gemini", "openrouter"]>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    maxIterations: number;
+    model: string;
+    provider: "claude" | "gemini" | "openrouter";
+    timeout?: number | undefined;
+    temperature?: number | undefined;
+    maxInputTokens?: number | undefined;
+    maxOutputTokens?: number | undefined;
+}, {
+    model: string;
+    provider: "claude" | "gemini" | "openrouter";
+    timeout?: number | undefined;
+    maxIterations?: number | undefined;
+    temperature?: number | undefined;
+    maxInputTokens?: number | undefined;
+    maxOutputTokens?: number | undefined;
+}>;
+/**
+ * Full LLM config schema with cross-field validation.
+ */
+export declare const LLMConfigSchema: z.ZodEffects<z.ZodObject<{
+    maxInputTokens: z.ZodOptional<z.ZodNumber>;
+    maxIterations: z.ZodDefault<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    model: z.ZodString;
+    provider: z.ZodEnum<["claude", "gemini", "openrouter"]>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    maxIterations: number;
+    model: string;
+    provider: "claude" | "gemini" | "openrouter";
+    timeout?: number | undefined;
+    temperature?: number | undefined;
+    maxInputTokens?: number | undefined;
+    maxOutputTokens?: number | undefined;
+}, {
+    model: string;
+    provider: "claude" | "gemini" | "openrouter";
+    timeout?: number | undefined;
+    maxIterations?: number | undefined;
+    temperature?: number | undefined;
+    maxInputTokens?: number | undefined;
+    maxOutputTokens?: number | undefined;
+}>, {
+    maxIterations: number;
+    model: string;
+    provider: "claude" | "gemini" | "openrouter";
+    timeout?: number | undefined;
+    temperature?: number | undefined;
+    maxInputTokens?: number | undefined;
+    maxOutputTokens?: number | undefined;
+}, {
+    model: string;
+    provider: "claude" | "gemini" | "openrouter";
+    timeout?: number | undefined;
+    maxIterations?: number | undefined;
+    temperature?: number | undefined;
+    maxInputTokens?: number | undefined;
+    maxOutputTokens?: number | undefined;
+}>;
+/**
+ * Input type for LLM config (what users provide).
+ */
+export type LLMConfig = z.input<typeof LLMConfigSchema>;
+/**
+ * Output type for validated LLM config (after defaults applied).
+ */
+export type ValidatedLLMConfig = z.output<typeof LLMConfigSchema>;
+/**
+ * PATCH-like schema for LLM config updates (e.g., model switching).
+ * All fields are optional, but at least model or provider must be specified.
+ */
+export declare const LLMUpdatesSchema: z.ZodEffects<z.ZodObject<{
+    maxInputTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    model: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodEnum<["claude", "gemini", "openrouter"]>>;
+    temperature: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    timeout: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    timeout?: number | undefined;
+    maxIterations?: number | undefined;
+    model?: string | undefined;
+    provider?: "claude" | "gemini" | "openrouter" | undefined;
+    temperature?: number | undefined;
+    maxInputTokens?: number | undefined;
+    maxOutputTokens?: number | undefined;
+}, {
+    timeout?: number | undefined;
+    maxIterations?: number | undefined;
+    model?: string | undefined;
+    provider?: "claude" | "gemini" | "openrouter" | undefined;
+    temperature?: number | undefined;
+    maxInputTokens?: number | undefined;
+    maxOutputTokens?: number | undefined;
+}>, {
+    timeout?: number | undefined;
+    maxIterations?: number | undefined;
+    model?: string | undefined;
+    provider?: "claude" | "gemini" | "openrouter" | undefined;
+    temperature?: number | undefined;
+    maxInputTokens?: number | undefined;
+    maxOutputTokens?: number | undefined;
+}, {
+    timeout?: number | undefined;
+    maxIterations?: number | undefined;
+    model?: string | undefined;
+    provider?: "claude" | "gemini" | "openrouter" | undefined;
+    temperature?: number | undefined;
+    maxInputTokens?: number | undefined;
+    maxOutputTokens?: number | undefined;
+}>;
+/**
+ * Input type for LLM updates.
+ */
+export type LLMUpdates = z.input<typeof LLMUpdatesSchema>;
+/**
+ * Validate LLM configuration and return validated result.
+ * @param config - Raw configuration input
+ * @returns Validated configuration with defaults applied
+ * @throws ZodError if validation fails
+ */
+export declare function validateLLMConfig(config: LLMConfig): ValidatedLLMConfig;
+/**
+ * Safely validate LLM configuration without throwing.
+ * @param config - Raw configuration input
+ * @returns SafeParseResult with success flag and data or error
+ */
+export declare function safeParseLLMConfig(config: unknown): z.SafeParseReturnType<LLMConfig, ValidatedLLMConfig>;
+/**
+ * Validate LLM updates (partial config for switching).
+ * @param updates - Partial configuration updates
+ * @returns Validated updates
+ * @throws ZodError if validation fails
+ */
+export declare function validateLLMUpdates(updates: LLMUpdates): LLMUpdates;

package/dist/core/domain/cipher/llm/schemas.js

@@ -0,0 +1,151 @@
+/**
+ * LLM Configuration Schemas
+ *
+ * Zod schemas for validating LLM configuration with cross-field validation.
+ */
+import { z } from 'zod';
+import { ErrorScope, ErrorType, LLMErrorCode } from './error-codes.js';
+import { acceptsAnyModel, getMaxInputTokensForModel, getSupportedModels, isValidProviderModel } from './registry.js';
+import { LLM_PROVIDERS } from './types.js';
+/**
+ * Default-free field definitions for LLM configuration.
+ * Used to build both the full config schema (with defaults) and the updates schema (no defaults).
+ */
+const LLMConfigFields = {
+    maxInputTokens: z.coerce
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Max input tokens for history; defaults to model limit'),
+    maxIterations: z.coerce
+        .number()
+        .int()
+        .positive()
+        .describe('Max iterations for agentic loops'),
+    maxOutputTokens: z.coerce
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Max tokens for model output'),
+    model: z
+        .string()
+        .min(1, 'Model name is required')
+        .describe('Specific model name for the selected provider'),
+    provider: z
+        .enum(LLM_PROVIDERS)
+        .describe("LLM provider (e.g., 'claude', 'gemini', 'openrouter')"),
+    temperature: z.coerce
+        .number()
+        .min(0)
+        .max(2)
+        .optional()
+        .describe('Randomness: 0 deterministic, 2 creative'),
+    timeout: z.coerce
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Request timeout in milliseconds'),
+};
+/**
+ * Base LLM config object schema (before validation/branding).
+ */
+export const LLMConfigBaseSchema = z
+    .object({
+    maxInputTokens: LLMConfigFields.maxInputTokens,
+    maxIterations: z.coerce.number().int().positive().default(50),
+    maxOutputTokens: LLMConfigFields.maxOutputTokens,
+    model: LLMConfigFields.model,
+    provider: LLMConfigFields.provider,
+    temperature: LLMConfigFields.temperature,
+    timeout: LLMConfigFields.timeout,
+})
+    .strict();
+/**
+ * Full LLM config schema with cross-field validation.
+ */
+export const LLMConfigSchema = LLMConfigBaseSchema.superRefine((data, ctx) => {
+    const maxInputTokensIsSet = data.maxInputTokens !== null && data.maxInputTokens !== undefined;
+    // Validate model exists for provider (unless provider accepts any model)
+    if (!acceptsAnyModel(data.provider) && !isValidProviderModel(data.provider, data.model)) {
+        const supportedModelsList = getSupportedModels(data.provider);
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Model '${data.model}' is not supported for provider '${data.provider}'. ` +
+                `Supported: ${supportedModelsList.slice(0, 5).join(', ')}${supportedModelsList.length > 5 ? '...' : ''}`,
+            params: {
+                code: LLMErrorCode.MODEL_INCOMPATIBLE,
+                scope: ErrorScope.LLM,
+                type: ErrorType.USER,
+            },
+            path: ['model'],
+        });
+    }
+    // Validate maxInputTokens doesn't exceed model limit
+    if (maxInputTokensIsSet && !acceptsAnyModel(data.provider)) {
+        try {
+            const modelMax = getMaxInputTokensForModel(data.provider, data.model);
+            if (data.maxInputTokens > modelMax) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `maxInputTokens (${data.maxInputTokens}) exceeds model limit (${modelMax}) ` +
+                        `for '${data.model}'`,
+                    params: {
+                        code: LLMErrorCode.TOKENS_EXCEEDED,
+                        scope: ErrorScope.LLM,
+                        type: ErrorType.USER,
+                    },
+                    path: ['maxInputTokens'],
+                });
+            }
+        }
+        catch {
+            // Model not found in registry - validation already handled above
+        }
+    }
+});
+/**
+ * PATCH-like schema for LLM config updates (e.g., model switching).
+ * All fields are optional, but at least model or provider must be specified.
+ */
+export const LLMUpdatesSchema = z
+    .object({ ...LLMConfigFields })
+    .partial()
+    .superRefine((data, ctx) => {
+    // Require at least one meaningful change field: model or provider
+    if (!data.model && !data.provider) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'At least model or provider must be specified for LLM update',
+            path: [],
+        });
+    }
+});
+/**
+ * Validate LLM configuration and return validated result.
+ * @param config - Raw configuration input
+ * @returns Validated configuration with defaults applied
+ * @throws ZodError if validation fails
+ */
+export function validateLLMConfig(config) {
+    return LLMConfigSchema.parse(config);
+}
+/**
+ * Safely validate LLM configuration without throwing.
+ * @param config - Raw configuration input
+ * @returns SafeParseResult with success flag and data or error
+ */
+export function safeParseLLMConfig(config) {
+    return LLMConfigSchema.safeParse(config);
+}
+/**
+ * Validate LLM updates (partial config for switching).
+ * @param updates - Partial configuration updates
+ * @returns Validated updates
+ * @throws ZodError if validation fails
+ */
+export function validateLLMUpdates(updates) {
+    return LLMUpdatesSchema.parse(updates);
+}

package/dist/core/domain/cipher/llm/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * LLM Provider types and constants.
+ *
+ * This module defines the core types for LLM provider abstraction,
+ */
+/**
+ * Supported LLM providers as a const array for runtime validation.
+ */
+export declare const LLM_PROVIDERS: readonly ["claude", "gemini", "openrouter"];
+/**
+ * Union type of all supported LLM providers.
+ */
+export type LLMProvider = (typeof LLM_PROVIDERS)[number];
+/**
+ * Supported file types for multimodal input.
+ */
+export declare const SUPPORTED_FILE_TYPES: readonly ["audio", "image", "pdf"];
+/**
+ * Union type of supported file types.
+ */
+export type SupportedFileType = (typeof SUPPORTED_FILE_TYPES)[number];
+/**
+ * Model capabilities configuration.
+ * Defines what features a specific model supports.
+ */
+export interface ModelCapabilities {
+    /** Whether the model supports audio input */
+    supportsAudio: boolean;
+    /** Whether the model supports image input */
+    supportsImages: boolean;
+    /** Whether the model supports PDF input */
+    supportsPdf: boolean;
+    /** Whether the model supports streaming responses */
+    supportsStreaming: boolean;
+    /** Whether the model supports extended thinking (Gemini) */
+    supportsThinking?: boolean;
+}
+/**
+ * Model metadata information.
+ * Contains all relevant details about a specific model.
+ */
+export interface ModelInfo {
+    /** Model capabilities */
+    capabilities: ModelCapabilities;
+    /** Characters per token ratio for estimation (e.g., 3.5 for Claude) */
+    charsPerToken: number;
+    /** Whether this is the default model for the provider */
+    default?: boolean;
+    /** Human-readable display name */
+    displayName: string;
+    /** Maximum input tokens (context window size) */
+    maxInputTokens: number;
+    /** Default max output tokens */
+    maxOutputTokens?: number;
+    /** Model identifier (e.g., 'claude-sonnet-4-20250514') */
+    name: string;
+    /** Optional pricing info (USD per million tokens) */
+    pricing?: {
+        inputPerM: number;
+        outputPerM: number;
+    };
+    /** File types this model supports */
+    supportedFileTypes: SupportedFileType[];
+}
+/**
+ * Provider configuration information.
+ * Contains metadata about a provider and its available models.
+ */
+export interface ProviderInfo {
+    /** Default model name for this provider */
+    defaultModel: string;
+    /** List of available models */
+    models: ModelInfo[];
+    /** Provider-level supported file types (fallback when model doesn't specify) */
+    supportedFileTypes: SupportedFileType[];
+}
+/**
+ * Runtime LLM context information.
+ * Represents the current LLM configuration in use.
+ */
+export interface LLMContext {
+    /** Current model name */
+    model: string;
+    /** Current provider */
+    provider: LLMProvider;
+}
+/**
+ * Token usage statistics.
+ */
+export interface LLMTokenUsage {
+    /** Number of input tokens */
+    inputTokens: number;
+    /** Number of output tokens */
+    outputTokens: number;
+    /** Number of reasoning tokens (if applicable) */
+    reasoningTokens?: number;
+    /** Total tokens (input + output + reasoning) */
+    totalTokens: number;
+}
+/**
+ * MIME type to file type mapping.
+ * Used to determine supported file types from MIME types.
+ */
+export declare const MIME_TYPE_TO_FILE_TYPE: Record<string, SupportedFileType>;
+/**
+ * Get all allowed MIME types.
+ * @returns Array of allowed MIME type strings
+ */
+export declare function getAllowedMimeTypes(): string[];
+/**
+ * Get file type from MIME type.
+ * @param mimeType - MIME type string
+ * @returns SupportedFileType or undefined if not supported
+ */
+export declare function getFileTypeFromMimeType(mimeType: string): SupportedFileType | undefined;
+/**
+ * Check if a MIME type is supported.
+ * @param mimeType - MIME type string
+ * @returns true if the MIME type is supported
+ */
+export declare function isSupportedMimeType(mimeType: string): boolean;