@pellux/goodvibes-tui 0.18.4

package/src/providers/openai.ts

@@ -0,0 +1,231 @@
+import OpenAI from 'openai';
+import type {
+  LLMProvider,
+  ChatRequest,
+  ChatResponse,
+  ProviderEmbeddingRequest,
+  ProviderEmbeddingResult,
+  ProviderRuntimeMetadata,
+  ProviderRuntimeMetadataDeps,
+} from './interface.ts';
+import { ProviderError } from '@pellux/goodvibes-sdk/platform/types/errors';
+import { withRetry } from '@pellux/goodvibes-sdk/platform/utils/retry';
+import {
+  toOpenAITools,
+  toOpenAIMessages,
+  fromOpenAIToolCalls,
+  extractTextToolCalls,
+} from './tool-formats.ts';
+import type { OpenAIToolCall } from './tool-formats.ts';
+import type { CacheHitTracker } from '@pellux/goodvibes-sdk/platform/providers/cache-strategy';
+import { extractOpenAIStreamTextDelta } from '@pellux/goodvibes-sdk/platform/providers/openai-stream-delta';
+import { summarizeError, toProviderError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+const NOOP_CACHE_HIT_TRACKER: Pick<CacheHitTracker, 'recordTurn'> = {
+  recordTurn: () => {},
+};
+
+/**
+ * OpenAIProvider — wraps the official `openai` npm package.
+ * Supports GPT-5 family models with full function/tool calling.
+ */
+export class OpenAIProvider implements LLMProvider {
+  readonly name = 'openai';
+  readonly models: string[] = [];
+
+  private client: OpenAI;
+  private readonly embeddingModel = 'text-embedding-3-small';
+  private readonly cacheHitTracker: Pick<CacheHitTracker, 'recordTurn'>;
+
+  constructor(apiKey: string, cacheHitTracker: Pick<CacheHitTracker, 'recordTurn'> = NOOP_CACHE_HIT_TRACKER) {
+    this.client = new OpenAI({ apiKey });
+    this.cacheHitTracker = cacheHitTracker;
+  }
+
+  async chat(params: ChatRequest): Promise<ChatResponse> {
+    const { messages, tools, model, maxTokens, signal, systemPrompt, onDelta, reasoningEffort: _reasoningEffort } = params;
+    // Note: OpenAI GPT-5 does not expose reasoning effort as a configurable API parameter
+
+    return withRetry(async () => {
+      let responseText = '';
+      let inputTokens = 0;
+      let outputTokens = 0;
+      let cacheReadTokens = 0;
+      let stopReason: ChatResponse['stopReason'] = 'end';
+      let rawToolCalls: OpenAIToolCall[] = [];
+
+      const openaiMessages = toOpenAIMessages(messages, systemPrompt);
+      const openaiTools = tools && tools.length > 0 ? toOpenAITools(tools) : undefined;
+
+      try {
+        const stream = await this.client.chat.completions.create(
+          {
+            model,
+            messages: openaiMessages as Parameters<typeof this.client.chat.completions.create>[0]['messages'],
+            ...(openaiTools ? { tools: openaiTools as Parameters<typeof this.client.chat.completions.create>[0]['tools'] } : {}),
+            ...(maxTokens ? { max_tokens: maxTokens } : {}),
+            stream: true,
+            stream_options: { include_usage: true },
+          },
+          { signal },
+        );
+
+        const accToolCalls: Map<number, { id: string; name: string; args: string }> = new Map();
+
+        for await (const chunk of stream) {
+          const delta = chunk.choices[0]?.delta;
+          const textDelta = extractOpenAIStreamTextDelta(chunk);
+          for (const contentDelta of textDelta.content) {
+            responseText += contentDelta;
+            if (onDelta) onDelta({ content: contentDelta });
+          }
+          for (const reasoningDelta of textDelta.reasoning) {
+            if (onDelta) onDelta({ reasoning: reasoningDelta });
+          }
+
+          // Accumulate streaming tool_calls deltas
+          if (delta?.tool_calls) {
+            for (const tc of delta.tool_calls) {
+              const idx = tc.index;
+              if (!accToolCalls.has(idx)) {
+                accToolCalls.set(idx, { id: tc.id ?? '', name: tc.function?.name ?? '', args: '' });
+              }
+              const entry = accToolCalls.get(idx)!;
+              if (tc.id) entry.id = tc.id;
+              if (tc.function?.name) entry.name = tc.function.name;
+              if (tc.function?.arguments) entry.args += tc.function.arguments;
+              if (onDelta) {
+                onDelta({ toolCalls: [{ index: idx, id: tc.id, name: tc.function?.name, arguments: tc.function?.arguments }] });
+              }
+            }
+          }
+
+          const finishReason = chunk.choices[0]?.finish_reason;
+          if (finishReason === 'tool_calls') stopReason = 'tool_use';
+          else if (finishReason === 'length') stopReason = 'max_tokens';
+
+          const usage = (chunk as { usage?: { prompt_tokens?: number; completion_tokens?: number; prompt_tokens_details?: { cached_tokens?: number } } }).usage;
+          if (usage) {
+            inputTokens = usage.prompt_tokens ?? 0;
+            outputTokens = usage.completion_tokens ?? 0;
+            cacheReadTokens = usage.prompt_tokens_details?.cached_tokens ?? cacheReadTokens;
+          }
+        }
+
+        // Finalise accumulated tool calls
+        for (const [, tc] of [...accToolCalls.entries()].sort(([a], [b]) => a - b)) {
+          rawToolCalls.push({
+            id: tc.id,
+            type: 'function',
+            function: { name: tc.name, arguments: tc.args },
+          });
+        }
+      } catch (err: unknown) {
+        const { hasStatus } = await import('@pellux/goodvibes-sdk/platform/utils/retry');
+        const status = hasStatus(err) ? err.status : undefined;
+        throw toProviderError(err, {
+          ...(status !== undefined ? { statusCode: status } : {}),
+          provider: this.name,
+          operation: 'chat',
+          phase: 'stream',
+        });
+      }
+
+      // Some models may emit tool calls as raw text tokens instead of the
+      // OpenAI function-calling wire format. Fall back to text extraction.
+      let toolCalls = rawToolCalls.length > 0 ? fromOpenAIToolCalls(rawToolCalls) : [];
+      if (toolCalls.length === 0 && (responseText.includes('<|toolcallbegin|>') || responseText.includes('<|tool_call_begin|>'))) {
+        const extracted = extractTextToolCalls(responseText);
+        if (extracted.toolCalls.length > 0) {
+          toolCalls = extracted.toolCalls;
+          responseText = extracted.cleanedContent;
+          stopReason = 'tool_use';
+        }
+      }
+
+      this.cacheHitTracker.recordTurn({
+        inputTokens,
+        cacheReadTokens,
+      });
+
+      return {
+        content: responseText,
+        toolCalls,
+        usage: {
+          inputTokens,
+          outputTokens,
+          ...(cacheReadTokens > 0 ? { cacheReadTokens } : {}),
+        },
+        stopReason,
+      };
+    });
+  }
+
+  async embed(request: ProviderEmbeddingRequest): Promise<ProviderEmbeddingResult> {
+    let response;
+    try {
+      response = await this.client.embeddings.create(
+        {
+          model: request.model ?? this.embeddingModel,
+          input: request.text,
+          ...(request.dimensions ? { dimensions: request.dimensions } : {}),
+        },
+        request.signal ? { signal: request.signal } : undefined,
+      );
+    } catch (error: unknown) {
+      throw toProviderError(error, {
+        provider: this.name,
+        operation: 'embed',
+        phase: 'request',
+      });
+    }
+    const embedding = response.data[0]?.embedding ?? [];
+    return {
+      vector: Float32Array.from(embedding),
+      dimensions: embedding.length,
+      modelId: response.model,
+      metadata: {
+        usage: request.usage,
+        provider: this.name,
+      },
+    };
+  }
+
+  async describeRuntime(deps: ProviderRuntimeMetadataDeps): Promise<ProviderRuntimeMetadata> {
+    const configured = Boolean(process.env.OPENAI_API_KEY || process.env.OPENAI_KEY);
+    const { buildStandardProviderAuthRoutes } = await import('./runtime-metadata.ts');
+    const authRoutes = await buildStandardProviderAuthRoutes({
+      providerId: 'openai',
+      apiKeyEnvVars: ['OPENAI_API_KEY', 'OPENAI_KEY'],
+      serviceNames: ['openai'],
+      subscriptionProviderId: 'openai',
+    }, deps);
+    return {
+      auth: {
+        mode: 'api-key',
+        configured,
+        detail: configured ? 'OpenAI API key available' : 'OPENAI_API_KEY or OPENAI_KEY not set',
+        envVars: ['OPENAI_API_KEY', 'OPENAI_KEY'],
+        routes: authRoutes,
+      },
+      models: {
+        models: this.models,
+        embeddingModel: this.embeddingModel,
+        embeddingDimensions: 384,
+      },
+      usage: {
+        streaming: true,
+        toolCalling: true,
+        parallelTools: true,
+        notes: ['Embeddings use the OpenAI embeddings API.'],
+      },
+      policy: {
+        local: false,
+        streamProtocol: 'openai-chat-completions',
+        reasoningMode: 'provider-default',
+        cacheStrategy: 'implicit-openai-cache-observation',
+        notes: ['OpenAI embedding usage is subject to OpenAI API terms.'],
+      },
+    };
+  }
+}

package/src/providers/optimizer.ts

@@ -0,0 +1,381 @@
+/**
+ * Provider Optimizer
+ *
+ * Lives above provider implementations. Routes requests based on capability
+ * contracts from ProviderCapabilityRegistry. Supports auto/manual/pinned
+ * routing modes with deterministic, fully-explainable decisions.
+ *
+ * Optimizer off → zero behavior change (selectRoute returns null).
+ * Optimizer on  → deterministic route explanation for every request profile.
+ */
+
+import {
+  ProviderCapabilityRegistry,
+  type RequestProfile,
+  type RouteExplanation,
+} from './capabilities.ts';
+import type { ModelDefinition, ProviderRegistry } from './registry.ts';
+import type { ProviderHealthRecord } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/provider-health';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Optimizer routing mode. */
+export type OptimizerMode = 'auto' | 'manual' | 'pinned';
+
+/** A single fallback transition log entry. */
+export interface FallbackTransition {
+  /** Epoch ms when the transition occurred. */
+  readonly ts: number;
+  /** Provider/model that failed or was skipped. */
+  readonly from: string;
+  /** Provider/model selected as fallback. */
+  readonly to: string;
+  /** Human-readable reason for the transition. */
+  readonly reason: string;
+}
+
+/** Result of a route selection decision. */
+export interface RouteDecision {
+  /** Provider ID selected. */
+  readonly providerId: string;
+  /** Model ID selected. */
+  readonly modelId: string;
+  /** Full route explanation from the capability registry. */
+  readonly explanation: RouteExplanation;
+  /** All candidates considered (accepted and rejected). */
+  readonly allCandidates: readonly RouteExplanation[];
+  /** Epoch ms when this decision was made. */
+  readonly decidedAt: number;
+  /** Whether this decision was constrained by a pin. */
+  readonly pinned: boolean;
+}
+
+/** Result of a fallback chain test. */
+export interface FallbackTestResult {
+  /** Ordered nodes in the simulated fallback chain. */
+  readonly chain: ReadonlyArray<{
+    readonly position: number;
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly capable: boolean;
+    readonly explanation: RouteExplanation;
+  }>;
+  /** Number of nodes that satisfy the empty request profile. */
+  readonly viableCount: number;
+  /** Total nodes tested. */
+  readonly totalCount: number;
+  /** Epoch ms when the test was run. */
+  readonly testedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// ProviderOptimizer
+// ---------------------------------------------------------------------------
+
+/**
+ * Optimizer that selects the best provider/model for a given request profile.
+ *
+ * When disabled (`enabled = false`) every method returns null/empty — the
+ * optimizer has zero effect on normal request flow.
+ *
+ * When enabled, routing decisions are driven entirely by `ProviderCapabilityRegistry`
+ * capability contracts. The selection algorithm is deterministic: candidates are
+ * evaluated in registry order (custom → synthetic → catalog → discovered), and
+ * the first capable model wins. Ties are never broken by opaque scoring.
+ */
+export class ProviderOptimizer {
+  private _mode: OptimizerMode = 'manual';
+  private _enabled: boolean;
+  private _pinnedProvider: string | null = null;
+  private _pinnedModel: string | null = null;
+  private readonly _fallbackLog: FallbackTransition[] = [];
+  private static readonly MAX_LOG_ENTRIES = 200;
+  private readonly _clock: () => number;
+  private readonly registry: Pick<ProviderRegistry, 'getCurrentModel' | 'getSelectableModels' | 'explainRoute'>;
+  private readonly capabilityRegistry: ProviderCapabilityRegistry;
+
+  constructor(
+    registry: Pick<ProviderRegistry, 'getCurrentModel' | 'getSelectableModels' | 'explainRoute'>,
+    capabilityRegistry: ProviderCapabilityRegistry,
+    enabled = false,
+    clock: () => number = Date.now,
+  ) {
+    this.registry = registry;
+    this.capabilityRegistry = capabilityRegistry;
+    this._enabled = enabled;
+    this._clock = clock;
+  }
+
+  // -------------------------------------------------------------------------
+  // Mode control
+  // -------------------------------------------------------------------------
+
+  /** Current routing mode. */
+  get mode(): OptimizerMode {
+    return this._mode;
+  }
+
+  /** Whether the optimizer is active. When false, selectRoute always returns null. */
+  get enabled(): boolean {
+    return this._enabled;
+  }
+
+  /** Enable or disable the optimizer. */
+  setEnabled(enabled: boolean): void {
+    this._enabled = enabled;
+  }
+
+  /**
+   * Set the routing mode.
+   * - `auto`   — optimizer selects the best capable provider for each request profile.
+   * - `manual` — optimizer is advisory only; caller drives provider selection.
+   * - `pinned` — optimizer always returns the pinned provider/model (if capable).
+   */
+  setMode(mode: OptimizerMode): void {
+    this._mode = mode;
+    if (mode !== 'pinned') {
+      this._pinnedProvider = null;
+      this._pinnedModel = null;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Pinning
+  // -------------------------------------------------------------------------
+
+  /**
+   * Pin routing to a specific provider and model.
+   * Automatically switches mode to `pinned`.
+   *
+   * @param providerId - Provider name (e.g. `'anthropic'`).
+   * @param modelId    - Model ID (e.g. `'claude-opus-4-5'`).
+   */
+  pin(providerId: string, modelId: string): void {
+    this._pinnedProvider = providerId;
+    this._pinnedModel = modelId;
+    this._mode = 'pinned';
+  }
+
+  /** Remove the current pin and return to `manual` mode. */
+  unpin(): void {
+    this._pinnedProvider = null;
+    this._pinnedModel = null;
+    this._mode = 'manual';
+  }
+
+  /** Current pin target, or null if not pinned. */
+  get pinnedTarget(): { providerId: string; modelId: string } | null {
+    if (this._pinnedProvider && this._pinnedModel) {
+      return { providerId: this._pinnedProvider, modelId: this._pinnedModel };
+    }
+    return null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Route selection
+  // -------------------------------------------------------------------------
+
+  /**
+   * Select the best route for the given request profile.
+   *
+   * Returns `null` when the optimizer is disabled — callers must handle null
+   * and fall through to their own provider selection logic.
+   *
+   * @param profile        - Capability requirements for the request.
+   * @param healthSnapshot - Optional map of provider health records for filtering
+   *                         unhealthy providers in `auto` mode.
+   * @returns A `RouteDecision` or `null` when optimizer is off.
+   *
+   * @remarks
+   * `selectRoute` is wired by the orchestrator when the `provider-optimizer`
+   * feature flag is enabled. This follows the same deferred-integration pattern
+   * as session emitters — the method is fully functional but called externally
+   * only when the feature is active. Until then it is a no-op (returns `null`).
+   */
+  selectRoute(
+    profile: RequestProfile,
+    healthSnapshot?: ReadonlyMap<string, ProviderHealthRecord>,
+  ): RouteDecision | null {
+    if (!this._enabled) return null;
+
+    const candidates = this.registry.getSelectableModels();
+    const allCandidates: RouteExplanation[] = [];
+
+    // Pinned mode — evaluate only the pinned target
+    if (this._mode === 'pinned' && this._pinnedProvider && this._pinnedModel) {
+      const explanation = this.capabilityRegistry.getRouteExplanation(
+        this._pinnedProvider,
+        this._pinnedModel,
+        profile,
+      );
+      allCandidates.push(explanation);
+      return {
+        providerId: this._pinnedProvider,
+        modelId: this._pinnedModel,
+        explanation,
+        allCandidates,
+        decidedAt: this._clock(),
+        pinned: true,
+      };
+    }
+
+    // Auto mode — evaluate all selectable models; pick first capable
+    // Manual mode — same evaluation but result is advisory (caller may ignore)
+    let selected: ModelDefinition | null = null;
+    let selectedExplanation: RouteExplanation | null = null;
+
+    for (const model of candidates) {
+      // Skip unhealthy providers in auto mode when health data is available
+      if (this._mode === 'auto' && healthSnapshot) {
+        const health = healthSnapshot.get(model.provider);
+        if (health && (health.status === 'unavailable' || health.status === 'auth_error')) {
+          continue;
+        }
+      }
+
+      const explanation = this.capabilityRegistry.getRouteExplanation(
+        model.provider,
+        model.id,
+        profile,
+      );
+      allCandidates.push(explanation);
+
+      if (explanation.accepted && !selected) {
+        selected = model;
+        selectedExplanation = explanation;
+      }
+    }
+
+    if (!selected || !selectedExplanation) {
+      // No capable provider found — return first candidate's explanation as the decision
+      // so callers get a fully-populated rejection explanation
+      const fallbackExpl = allCandidates[0] ?? this._emptyExplanation();
+      return {
+        providerId: fallbackExpl.providerId,
+        modelId: fallbackExpl.modelId,
+        explanation: fallbackExpl,
+        allCandidates,
+        decidedAt: this._clock(),
+        pinned: false,
+      };
+    }
+
+    return {
+      providerId: selected.provider,
+      modelId: selected.id,
+      explanation: selectedExplanation,
+      allCandidates,
+      decidedAt: this._clock(),
+      pinned: false,
+    };
+  }
+
+  /**
+   * Explain the current routing decision for the active model without changing it.
+   * Always returns a full explanation even when the optimizer is in manual mode.
+   *
+   * @param profile - Optional request profile; defaults to empty (no requirements).
+   */
+  explainCurrentRoute(profile: RequestProfile = {}): RouteExplanation {
+    const current = this.registry.getCurrentModel();
+    return this.registry.explainRoute(current.registryKey ?? `${current.provider}:${current.id}`, profile);
+  }
+
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+
+  /** Returns a fully-typed rejection explanation when no candidates are available. */
+  private _emptyExplanation() {
+    return {
+      accepted: false as const,
+      providerId: 'none',
+      modelId: 'none',
+      summary: 'No selectable models available in registry.',
+      rejections: [] as import('./capabilities.ts').RouteRejectionDetail[],
+      capability: this.capabilityRegistry.getCapability('unknown', 'unknown'),
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Fallback test
+  // -------------------------------------------------------------------------
+
+  /**
+   * Simulate the fallback chain by evaluating all selectable models against
+   * the given profile. Returns an ordered list of results (capable first,
+   * then incapable) so operators can visualize the full fallback topology.
+   *
+   * @param profile - Capability requirements to test against.
+   */
+  testFallback(profile: RequestProfile = {}): FallbackTestResult {
+    const candidates = this.registry.getSelectableModels();
+
+    const chain: Array<{
+      position: number;
+      providerId: string;
+      modelId: string;
+      capable: boolean;
+      explanation: RouteExplanation;
+    }> = [];
+
+    let position = 0;
+    for (const model of candidates) {
+      const explanation = this.capabilityRegistry.getRouteExplanation(model.provider, model.id, profile);
+      chain.push({
+        position,
+        providerId: model.provider,
+        modelId: model.id,
+        capable: explanation.accepted,
+        explanation,
+      });
+      position++;
+    }
+
+    const viableCount = chain.filter((n) => n.capable).length;
+
+    return {
+      chain,
+      viableCount,
+      totalCount: chain.length,
+      testedAt: this._clock(),
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Fallback transition log
+  // -------------------------------------------------------------------------
+
+  /**
+   * Record a fallback transition. Called by orchestration layers when a
+   * provider fails and routing switches to a fallback.
+   *
+   * Transitions are always recorded regardless of optimizer enabled state
+   * so that manual fallbacks are also visible in the log.
+   */
+  recordFallbackTransition(from: string, to: string, reason: string): void {
+    const entry: FallbackTransition = {
+      ts: this._clock(),
+      from,
+      to,
+      reason,
+    };
+    this._fallbackLog.push(entry);
+    // Trim to bounded size
+    if (this._fallbackLog.length > ProviderOptimizer.MAX_LOG_ENTRIES) {
+      this._fallbackLog.splice(0, this._fallbackLog.length - ProviderOptimizer.MAX_LOG_ENTRIES);
+    }
+  }
+
+  /** All recorded fallback transitions (oldest first). */
+  get fallbackLog(): readonly FallbackTransition[] {
+    return this._fallbackLog;
+  }
+
+  /** Clear the fallback transition log. */
+  clearFallbackLog(): void {
+    this._fallbackLog.splice(0);
+  }
+}