@pellux/goodvibes-tui 0.18.4

package/src/providers/custom-loader.ts

@@ -0,0 +1,425 @@
+import * as fs from 'fs';
+import * as fsPromises from 'fs/promises';
+import * as path from 'path';
+import type { RuntimeEventBus } from '../runtime/events/index.ts';
+import { emitProviderWarning } from '../runtime/emitters/index.ts';
+import { OpenAICompatProvider } from './openai-compat.ts';
+import { AnthropicCompatProvider } from './anthropic-compat.ts';
+import type { LLMProvider } from './interface.ts';
+import type { ModelDefinition } from './registry.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+import {
+  LocalContextIngestionService,
+  resolveContextWindow,
+} from '@pellux/goodvibes-sdk/platform/providers/local-context-ingestion';
+
+/** Debounce delay for file watcher (ms). */
+const WATCH_DEBOUNCE_MS = 300;
+
+/**
+ * JSON schema for a custom provider configuration file.
+ * Place a *.json file in ~/.goodvibes/tui/providers/ to define a custom provider.
+ */
+export interface CustomProviderConfig {
+  /** Unique provider identifier, e.g. 'ollama' */
+  name: string;
+  /** Human-friendly display name, e.g. 'Ollama' */
+  displayName: string;
+  /**
+   * API compatibility type.
+   * - 'openai-compat': provider speaks the OpenAI Chat Completions API
+   * - 'anthropic-compat': provider speaks the Anthropic Messages API (SSE streaming)
+   */
+  type: 'openai-compat' | 'anthropic-compat';
+  /** Base URL for the API, e.g. 'http://localhost:11434/v1' */
+  baseURL: string;
+  /** Optional env var name whose value is used as the API key */
+  apiKeyEnv?: string;
+  /** Optional explicit API key (takes precedence over apiKeyEnv) */
+  apiKey?: string;
+  /** Optional extra HTTP headers sent with every request */
+  defaultHeaders?: Record<string, string>;
+  /** How to send reasoning params. Default: 'none' (don't send). */
+  reasoningFormat?: 'mercury' | 'openrouter' | 'llamacpp' | 'none';
+  /** List of models exposed by this provider */
+  models: Array<{
+    id: string;
+    displayName: string;
+    description?: string;
+    contextWindow: number;
+    selectable?: boolean;
+    capabilities: {
+      toolCalling: boolean;
+      codeEditing: boolean;
+      reasoning: boolean;
+      multimodal: boolean;
+    };
+    reasoningEffort?: string[];
+    /** Model capability tier — controls system prompt verbosity. */
+    tier?: 'free' | 'standard' | 'premium';
+  }>;
+}
+
+/** Result of loading all custom providers from disk. */
+export interface LoadCustomProvidersResult {
+  providers: Array<{ config: CustomProviderConfig; provider: LLMProvider }>;
+  models: ModelDefinition[];
+  warnings: string[];
+}
+
+/** Options for loadCustomProviders. */
+export interface LoadCustomProvidersOptions {
+  /** Directory that owns custom provider JSON files. */
+  providersDir: string;
+  /**
+   * When true, attempts to fetch max_context_length from each provider's
+   * /v1/models endpoint and uses the reported value with 'provider_api'
+   * provenance. Falls back to the configured contextWindow or DEFAULT_CONTEXT_WINDOW.
+   * Defaults to false.
+   */
+  ingestContextWindows?: boolean;
+  contextIngestion?: Pick<LocalContextIngestionService, 'ingestProviderContextWindows'>;
+}
+
+/**
+ * Resolve API key from config.
+ * Priority: explicit apiKey > env var (apiKeyEnv) > empty string.
+ */
+function resolveApiKey(config: CustomProviderConfig): string {
+  if (config.apiKey) return config.apiKey;
+  if (config.apiKeyEnv) {
+    const val = process.env[config.apiKeyEnv];
+    if (val) return val;
+  }
+  return '';
+}
+
+/**
+ * Validate a single parsed JSON object against the CustomProviderConfig schema.
+ * Returns { valid, errors } — errors is empty when valid.
+ */
+function validateCustomProvider(data: unknown): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+    return { valid: false, errors: ['Root value must be a JSON object'] };
+  }
+
+  const obj = data as Record<string, unknown>;
+
+  if (typeof obj['name'] !== 'string' || obj['name'].trim() === '') {
+    errors.push('"name" must be a non-empty string');
+  }
+
+  if (typeof obj['displayName'] !== 'string' || obj['displayName'].trim() === '') {
+    errors.push('"displayName" must be a non-empty string');
+  }
+
+  if (obj['type'] !== 'openai-compat' && obj['type'] !== 'anthropic-compat') {
+    errors.push('"type" must be "openai-compat" or "anthropic-compat"');
+  }
+
+  if (typeof obj['baseURL'] !== 'string' || obj['baseURL'].trim() === '') {
+    errors.push('"baseURL" must be a non-empty string');
+  }
+
+  if (obj['reasoningFormat'] !== undefined) {
+    if (!['mercury', 'openrouter', 'llamacpp', 'none'].includes(obj['reasoningFormat'] as string)) {
+      errors.push('"reasoningFormat" must be "mercury", "openrouter", "llamacpp", or "none"');
+    }
+  }
+
+  if (!Array.isArray(obj['models']) || (obj['models'] as unknown[]).length === 0) {
+    errors.push('"models" must be a non-empty array');
+  } else {
+    const models = obj['models'] as unknown[];
+    models.forEach((m, i) => {
+      if (typeof m !== 'object' || m === null || Array.isArray(m)) {
+        errors.push(`models[${i}]: must be an object`);
+        return;
+      }
+      const model = m as Record<string, unknown>;
+      if (typeof model['id'] !== 'string' || model['id'].trim() === '') {
+        errors.push(`models[${i}]: "id" must be a non-empty string`);
+      }
+      if (typeof model['displayName'] !== 'string' || model['displayName'].trim() === '') {
+        errors.push(`models[${i}]: "displayName" must be a non-empty string`);
+      }
+      if (typeof model['contextWindow'] !== 'number' || model['contextWindow'] <= 0) {
+        errors.push(`models[${i}]: "contextWindow" must be a positive number`);
+      }
+      if (typeof model['capabilities'] !== 'object' || model['capabilities'] === null) {
+        errors.push(`models[${i}]: "capabilities" must be an object`);
+      } else {
+        const caps = model['capabilities'] as Record<string, unknown>;
+        for (const cap of ['toolCalling', 'codeEditing', 'reasoning', 'multimodal']) {
+          if (typeof caps[cap] !== 'boolean') {
+            errors.push(`models[${i}]: capabilities.${cap} must be a boolean`);
+          }
+        }
+      }
+    });
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Ensure the providers directory exists, creating it if necessary.
+ */
+async function ensureProvidersDir(providersDir: string): Promise<void> {
+  try {
+    await fsPromises.mkdir(providersDir, { recursive: true });
+  } catch (err) {
+    throw new Error(
+      `[custom-loader] Failed to create providers directory '${providersDir}': ${
+        summarizeError(err)
+      }`,
+    );
+  }
+}
+
+/**
+ * Load all custom providers from an owned providers directory.
+ * Auto-creates the directory if it does not exist.
+ * Invalid files are skipped with a warning rather than failing the whole load.
+ *
+ * When `options.ingestContextWindows` is true, each provider's /v1/models
+ * endpoint is queried concurrently (via Promise.allSettled) to resolve
+ * `max_context_length` with `provider_api` provenance.
+ */
+export async function loadCustomProviders(
+  options: LoadCustomProvidersOptions,
+): Promise<LoadCustomProvidersResult> {
+  const warnings: string[] = [];
+  const providers: Array<{ config: CustomProviderConfig; provider: LLMProvider }> = [];
+  const models: ModelDefinition[] = [];
+  const { providersDir } = options;
+
+  await ensureProvidersDir(providersDir);
+
+  let entries: string[];
+  try {
+    const dirents = await fsPromises.readdir(providersDir, { withFileTypes: true });
+    entries = dirents
+      .filter((d) => d.isFile() && d.name.endsWith('.json'))
+      .map((d) => d.name);
+  } catch (err) {
+    warnings.push(
+      `[custom-loader] Could not read providers directory: ${
+        summarizeError(err)
+      }`,
+    );
+    return { providers, models, warnings };
+  }
+
+  // Phase 1: Parse and validate all provider files, instantiate provider objects.
+  // Collect valid entries; skip invalid ones with warnings.
+  const validConfigs: Array<{ cfg: CustomProviderConfig; provider: LLMProvider; apiKey: string }> = [];
+
+  for (const filename of entries) {
+    const filepath = path.join(providersDir, filename);
+    let raw: string;
+    try {
+      raw = await fsPromises.readFile(filepath, 'utf-8');
+    } catch (err) {
+      warnings.push(
+        `[custom-loader] Could not read '${filename}': ${
+          summarizeError(err)
+        }`,
+      );
+      continue;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      warnings.push(
+        `[custom-loader] Invalid JSON in '${filename}': ${
+          summarizeError(err)
+        }`,
+      );
+      continue;
+    }
+
+    const { valid, errors } = validateCustomProvider(parsed);
+    if (!valid) {
+      warnings.push(
+        `[custom-loader] Skipping '${filename}' — validation errors:\n  ${errors.join('\n  ')}`,
+      );
+      continue;
+    }
+
+    const cfg = parsed as CustomProviderConfig;
+
+    const apiKey = resolveApiKey(cfg);
+    const modelIds = cfg.models.map((m) => m.id);
+
+    let provider: LLMProvider;
+    try {
+      if (cfg.type === 'anthropic-compat') {
+        provider = new AnthropicCompatProvider({
+          name: cfg.name,
+          baseURL: cfg.baseURL,
+          apiKey,
+          defaultModel: modelIds[0]!,
+          models: modelIds,
+          ...(cfg.defaultHeaders ? { defaultHeaders: cfg.defaultHeaders } : {}),
+        });
+      } else {
+        provider = new OpenAICompatProvider({
+          name: cfg.name,
+          baseURL: cfg.baseURL,
+          apiKey,
+          defaultModel: modelIds[0]!,
+          models: modelIds,
+          ...(cfg.defaultHeaders ? { defaultHeaders: cfg.defaultHeaders } : {}),
+          reasoningFormat: cfg.reasoningFormat ?? 'none',
+        });
+      }
+    } catch (err) {
+      warnings.push(
+        `[custom-loader] Failed to instantiate provider from '${filename}': ${
+          summarizeError(err)
+        }`,
+      );
+      continue;
+    }
+
+    validConfigs.push({ cfg, provider, apiKey });
+  }
+
+  // Phase 2: Ingest context windows concurrently for all valid providers.
+  // Runs only when options.ingestContextWindows is true.
+  const ingestionResults: Array<Map<string, number> | null> = validConfigs.map(() => null);
+  if (options.ingestContextWindows && options.contextIngestion && validConfigs.length > 0) {
+    const ingestionPromises = validConfigs.map(({ cfg, apiKey }) =>
+      options.contextIngestion?.ingestProviderContextWindows(
+        cfg.name,
+        cfg.baseURL,
+        apiKey || undefined,
+      ),
+    );
+    const settled = await Promise.allSettled(ingestionPromises);
+    for (let i = 0; i < settled.length; i++) {
+      const result = settled[i];
+      if (result) {
+        ingestionResults[i] = result.status === 'fulfilled' ? (result.value ?? null) : null;
+      }
+    }
+  }
+
+  // Phase 3: Build model definitions and populate output arrays.
+  for (let i = 0; i < validConfigs.length; i++) {
+    const { cfg, provider } = validConfigs[i]!;
+    const apiContextMap = ingestionResults[i] ?? null;
+
+    const modelDefs: ModelDefinition[] = cfg.models.map((m) => {
+      const apiContextLength = apiContextMap?.get(m.id) ?? null;
+      const resolved = resolveContextWindow(m.id, apiContextLength, m.contextWindow);
+      return {
+        id: m.id,
+        provider: cfg.name,
+        registryKey: `${cfg.name}:${m.id}`,
+        displayName: m.displayName,
+        description: m.description ?? '',
+        contextWindow: resolved.tokens,
+        contextWindowProvenance: resolved.provenance,
+        selectable: m.selectable ?? true,
+        capabilities: {
+          toolCalling: m.capabilities.toolCalling,
+          codeEditing: m.capabilities.codeEditing,
+          reasoning: m.capabilities.reasoning,
+          multimodal: m.capabilities.multimodal,
+        },
+        ...(m.reasoningEffort ? { reasoningEffort: m.reasoningEffort } : {}),
+        ...(m.tier ? { tier: m.tier } : {}),
+      };
+    });
+
+    providers.push({ config: cfg, provider });
+    models.push(...modelDefs);
+  }
+
+  return { providers, models, warnings };
+}
+
+/**
+ * Start watching an owned providers directory for file changes.
+ * Debounces rapid events by 300ms before invoking the onChange callback.
+ * Emits typed provider warnings if the watcher cannot be started.
+ * Returns a handle with a `close()` method to stop watching.
+ */
+export function watchCustomProviders(
+  runtimeBus: RuntimeEventBus | null,
+  onChange: () => void,
+  providersDir: string,
+): { close: () => void } {
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let watcher: fs.FSWatcher | null = null;
+  let closed = false;
+
+  const emitWarning = (message: string): void => {
+    if (runtimeBus) {
+      emitProviderWarning(runtimeBus, {
+        sessionId: 'system',
+        traceId: `providers:warning:${Date.now()}`,
+        source: 'custom-provider-loader',
+      }, { message });
+    }
+  };
+
+  const startWatch = () => {
+    if (closed) return;
+    try {
+      // Note: fs.watch() may miss atomic renames (e.g. editor save-via-rename) on
+      // some Linux filesystems. If that becomes a problem, consider replacing this
+      // with the 'chokidar' library which uses inotify directly.
+      watcher = fs.watch(
+        providersDir,
+        { persistent: false }, // Don't keep the Node process alive just for this watcher
+        (_eventType, _filename) => {
+        if (debounceTimer) clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+          debounceTimer = null;
+          onChange();
+        }, WATCH_DEBOUNCE_MS);
+      });
+
+      watcher.on('error', (err) => {
+        if (closed) return;
+        emitWarning(`[custom-loader] Watcher error: ${err.message}`);
+      });
+    } catch (err) {
+      if (closed) return;
+      emitWarning(`[custom-loader] Could not watch providers directory: ${summarizeError(err)}`);
+    }
+  };
+
+  // Ensure the directory exists before starting the watcher
+  fsPromises
+    .mkdir(providersDir, { recursive: true })
+    .then(() => {
+      if (closed) return;
+      startWatch();
+    })
+    .catch((err) => {
+      if (closed) return;
+      emitWarning(`[custom-loader] Could not create/watch providers directory: ${summarizeError(err)}`);
+    });
+
+  return {
+    close() {
+      closed = true;
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      if (watcher) {
+        watcher.close();
+        watcher = null;
+      }
+    },
+  };
+}

package/src/providers/discovered-compat.ts

@@ -0,0 +1,18 @@
+import type { OpenAICompatOptions } from './openai-compat.ts';
+import { OpenAICompatProvider } from './openai-compat.ts';
+
+export interface DiscoveredCompatOptions extends OpenAICompatOptions {}
+
+class DiscoveredCompatProvider extends OpenAICompatProvider {
+  constructor(opts: DiscoveredCompatOptions) {
+    super(opts);
+  }
+}
+
+export class VLLMProvider extends DiscoveredCompatProvider {}
+
+export class LlamaCppProvider extends DiscoveredCompatProvider {}
+
+export class TGIProvider extends DiscoveredCompatProvider {}
+
+export class LocalAIProvider extends DiscoveredCompatProvider {}

package/src/providers/discovered-factory.ts

@@ -0,0 +1,61 @@
+import type { DiscoveredServer } from '@pellux/goodvibes-sdk/platform/discovery/scanner';
+import type { LLMProvider } from './interface.ts';
+import { getDiscoveredTraits } from './discovered-traits.ts';
+import { LocalAIProvider, TGIProvider, VLLMProvider } from './discovered-compat.ts';
+import { LlamaCppProvider } from './llama-cpp.ts';
+import { LMStudioProvider } from './lm-studio.ts';
+import { OpenAICompatProvider } from './openai-compat.ts';
+import { OllamaProvider } from './ollama.ts';
+
+export function createDiscoveredProvider(server: DiscoveredServer): LLMProvider {
+  const traits = getDiscoveredTraits(server.serverType);
+  const common = {
+    name: server.name,
+    baseURL: server.baseURL,
+    apiKey: '',
+    defaultModel: server.models[0]!,
+    models: server.models,
+    capabilities: traits.providerCapabilities,
+  };
+
+  switch (traits.adapter) {
+    case 'lm-studio':
+      return new LMStudioProvider(common);
+    case 'ollama':
+      return new OllamaProvider({
+        ...common,
+        reasoningFormat: traits.reasoningFormat,
+      });
+    case 'vllm':
+      return new VLLMProvider({
+        ...common,
+        reasoningFormat: traits.reasoningFormat,
+      });
+    case 'llamacpp':
+      return new LlamaCppProvider({
+        ...common,
+        reasoningFormat: traits.reasoningFormat,
+      });
+    case 'tgi':
+      return new TGIProvider({
+        ...common,
+        reasoningFormat: traits.reasoningFormat,
+      });
+    case 'localai':
+      return new LocalAIProvider({
+        ...common,
+        reasoningFormat: traits.reasoningFormat,
+      });
+    default:
+      return new OpenAICompatProvider({
+        ...common,
+        reasoningFormat: traits.reasoningFormat,
+      });
+  }
+}
+
+export function getDiscoveredReasoningFormat(
+  serverType: DiscoveredServer['serverType'],
+): 'llamacpp' | 'none' {
+  return getDiscoveredTraits(serverType).reasoningFormat;
+}

package/src/providers/discovered-traits.ts

@@ -0,0 +1,138 @@
+import type { ServerType } from '@pellux/goodvibes-sdk/platform/discovery/scanner';
+import type { ProviderCapability } from './capabilities.ts';
+
+export interface DiscoveredServerTraits {
+  readonly adapter:
+    | 'lm-studio'
+    | 'ollama'
+    | 'vllm'
+    | 'llamacpp'
+    | 'tgi'
+    | 'localai'
+    | 'compat';
+  readonly reasoningFormat: 'llamacpp' | 'none';
+  readonly providerCapabilities?: Partial<ProviderCapability>;
+  readonly modelCapabilities: {
+    toolCalling: boolean;
+    codeEditing: boolean;
+    reasoning: boolean;
+    multimodal: boolean;
+  };
+  readonly reasoningEffort?: string[];
+}
+
+const DEFAULT_MODEL_CAPABILITIES = {
+  toolCalling: true,
+  codeEditing: true,
+  reasoning: false,
+  multimodal: false,
+} as const;
+
+const HIGH_TIMEOUT_MS = 300_000;
+
+export function getDiscoveredTraits(serverType: ServerType): DiscoveredServerTraits {
+  switch (serverType) {
+    case 'lm-studio':
+      return {
+        adapter: 'lm-studio',
+        reasoningFormat: 'none',
+        providerCapabilities: {
+          streaming: true,
+          toolCalling: true,
+          parallelTools: true,
+          jsonMode: false,
+          reasoningControls: true,
+          timeoutMs: HIGH_TIMEOUT_MS,
+        },
+        modelCapabilities: {
+          ...DEFAULT_MODEL_CAPABILITIES,
+          reasoning: true,
+        },
+        reasoningEffort: ['instant', 'low', 'medium', 'high'],
+      };
+    case 'ollama':
+      return {
+        adapter: 'ollama',
+        reasoningFormat: 'llamacpp',
+        providerCapabilities: {
+          streaming: true,
+          toolCalling: true,
+          parallelTools: false,
+          jsonMode: true,
+          reasoningControls: true,
+          timeoutMs: HIGH_TIMEOUT_MS,
+        },
+        modelCapabilities: {
+          ...DEFAULT_MODEL_CAPABILITIES,
+          reasoning: true,
+        },
+        reasoningEffort: ['instant', 'low', 'medium', 'high'],
+      };
+    case 'vllm':
+      return {
+        adapter: 'vllm',
+        reasoningFormat: 'none',
+        providerCapabilities: {
+          streaming: true,
+          toolCalling: true,
+          parallelTools: false,
+          jsonMode: true,
+          reasoningControls: false,
+          timeoutMs: HIGH_TIMEOUT_MS,
+        },
+        modelCapabilities: DEFAULT_MODEL_CAPABILITIES,
+      };
+    case 'llamacpp':
+      return {
+        adapter: 'llamacpp',
+        reasoningFormat: 'llamacpp',
+        providerCapabilities: {
+          streaming: true,
+          toolCalling: true,
+          parallelTools: false,
+          jsonMode: true,
+          reasoningControls: true,
+          timeoutMs: HIGH_TIMEOUT_MS,
+        },
+        modelCapabilities: {
+          ...DEFAULT_MODEL_CAPABILITIES,
+          reasoning: true,
+        },
+        reasoningEffort: ['instant', 'low', 'medium', 'high'],
+      };
+    case 'tgi':
+      return {
+        adapter: 'tgi',
+        reasoningFormat: 'none',
+        providerCapabilities: {
+          streaming: true,
+          toolCalling: true,
+          parallelTools: false,
+          jsonMode: true,
+          reasoningControls: false,
+          timeoutMs: HIGH_TIMEOUT_MS,
+        },
+        modelCapabilities: DEFAULT_MODEL_CAPABILITIES,
+      };
+    case 'localai':
+      return {
+        adapter: 'localai',
+        reasoningFormat: 'none',
+        providerCapabilities: {
+          streaming: true,
+          toolCalling: true,
+          parallelTools: false,
+          jsonMode: true,
+          reasoningControls: false,
+          timeoutMs: HIGH_TIMEOUT_MS,
+        },
+        modelCapabilities: DEFAULT_MODEL_CAPABILITIES,
+      };
+    default:
+      return {
+        adapter: 'compat',
+        reasoningFormat: 'none',
+        modelCapabilities: DEFAULT_MODEL_CAPABILITIES,
+      };
+  }
+}