@pellux/goodvibes-tui 0.18.4

package/src/providers/github-copilot.ts

@@ -0,0 +1,254 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { ChatRequest, ChatResponse, LLMProvider, ProviderRuntimeMetadata, ProviderRuntimeMetadataDeps } from './interface.ts';
+import { OpenAICompatProvider } from './openai-compat.ts';
+import { AnthropicCompatProvider } from './anthropic-compat.ts';
+import { ProviderError } from '@pellux/goodvibes-sdk/platform/types/errors';
+import { buildStandardProviderAuthRoutes } from './runtime-metadata.ts';
+import { toProviderError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+const COPILOT_TOKEN_URL = 'https://api.github.com/copilot_internal/v2/token';
+const DEFAULT_COPILOT_API_BASE_URL = 'https://api.individual.githubcopilot.com';
+const COPILOT_EDITOR_VERSION = 'vscode/1.96.2';
+const COPILOT_USER_AGENT = 'GitHubCopilotChat/0.26.7';
+const COPILOT_GITHUB_API_VERSION = '2025-04-01';
+const COPILOT_TOKEN_ENV_VARS = ['COPILOT_GITHUB_TOKEN', 'GH_TOKEN', 'GITHUB_TOKEN'] as const;
+
+interface CachedCopilotToken {
+  readonly token: string;
+  readonly expiresAt: number;
+  readonly updatedAt: number;
+}
+
+export interface GitHubCopilotProviderOptions {
+  readonly tokenCachePath: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly fetchFn?: typeof fetch;
+}
+
+export function getGitHubCopilotTokenCachePath(cacheDir: string): string {
+  return join(cacheDir, 'credentials', 'github-copilot.token.json');
+}
+
+function readFirstEnv(envVars: readonly string[], env: NodeJS.ProcessEnv): string | null {
+  for (const envVar of envVars) {
+    const value = env[envVar];
+    if (typeof value === 'string' && value.trim().length > 0) return value.trim();
+  }
+  return null;
+}
+
+function buildCopilotIdeHeaders(includeApiVersion = false): Record<string, string> {
+  return {
+    'Editor-Version': COPILOT_EDITOR_VERSION,
+    'User-Agent': COPILOT_USER_AGENT,
+    ...(includeApiVersion ? { 'X-Github-Api-Version': COPILOT_GITHUB_API_VERSION } : {}),
+  };
+}
+
+function hasCopilotVisionInput(messages: ChatRequest['messages']): boolean {
+  return messages.some((message) =>
+    Array.isArray(message.content) && message.content.some((part) => part.type === 'image'));
+}
+
+function buildCopilotDynamicHeaders(messages: ChatRequest['messages']): Record<string, string> {
+  const last = messages[messages.length - 1];
+  const initiator = last && last.role !== 'user' ? 'agent' : 'user';
+  return {
+    ...buildCopilotIdeHeaders(false),
+    'X-Initiator': initiator,
+    'Openai-Intent': 'conversation-edits',
+    ...(hasCopilotVisionInput(messages) ? { 'Copilot-Vision-Request': 'true' } : {}),
+  };
+}
+
+function isTokenUsable(cache: CachedCopilotToken, now = Date.now()): boolean {
+  return cache.expiresAt - now > 5 * 60 * 1000;
+}
+
+function parseCopilotTokenResponse(value: unknown): { token: string; expiresAt: number } {
+  if (!value || typeof value !== 'object') {
+    throw new Error('Unexpected response from GitHub Copilot token endpoint');
+  }
+  const record = value as Record<string, unknown>;
+  const token = typeof record['token'] === 'string' ? record['token'].trim() : '';
+  const rawExpiresAt = record['expires_at'];
+  if (!token) throw new Error('Copilot token response missing token');
+  let expiresAt: number;
+  if (typeof rawExpiresAt === 'number' && Number.isFinite(rawExpiresAt)) {
+    expiresAt = rawExpiresAt < 100_000_000_000 ? rawExpiresAt * 1000 : rawExpiresAt;
+  } else if (typeof rawExpiresAt === 'string' && rawExpiresAt.trim()) {
+    const parsed = Number.parseInt(rawExpiresAt.trim(), 10);
+    if (!Number.isFinite(parsed)) throw new Error('Copilot token response has invalid expires_at');
+    expiresAt = parsed < 100_000_000_000 ? parsed * 1000 : parsed;
+  } else {
+    throw new Error('Copilot token response missing expires_at');
+  }
+  return { token, expiresAt };
+}
+
+function deriveCopilotApiBaseUrlFromToken(token: string): string | null {
+  const match = token.trim().match(/(?:^|;)\s*proxy-ep=([^;\s]+)/i);
+  const proxyEp = match?.[1]?.trim();
+  if (!proxyEp) return null;
+  const candidate = /^https?:\/\//i.test(proxyEp) ? proxyEp : `https://${proxyEp}`;
+  try {
+    const parsed = new URL(candidate);
+    const host = parsed.hostname.replace(/^proxy\./i, 'api.');
+    return `https://${host}`;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveCopilotToken(options: GitHubCopilotProviderOptions): Promise<{ token: string; baseUrl: string; expiresAt: number }> {
+  const env = options.env ?? process.env;
+  const fetchFn = options.fetchFn ?? fetch;
+  const githubToken = readFirstEnv(COPILOT_TOKEN_ENV_VARS, env);
+  if (!githubToken) {
+    throw new Error('GitHub Copilot requires COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN.');
+  }
+
+  const cachePath = options.tokenCachePath;
+  if (existsSync(cachePath)) {
+    try {
+      const cached = JSON.parse(readFileSync(cachePath, 'utf-8')) as CachedCopilotToken;
+      if (cached?.token && typeof cached.expiresAt === 'number' && isTokenUsable(cached)) {
+        return {
+          token: cached.token,
+          baseUrl: deriveCopilotApiBaseUrlFromToken(cached.token) ?? DEFAULT_COPILOT_API_BASE_URL,
+          expiresAt: cached.expiresAt,
+        };
+      }
+    } catch {
+      // Ignore stale or malformed cache files.
+    }
+  }
+
+  const response = await fetchFn(COPILOT_TOKEN_URL, {
+    method: 'GET',
+    headers: {
+      Accept: 'application/json',
+      Authorization: `Bearer ${githubToken}`,
+      ...buildCopilotIdeHeaders(true),
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`Copilot token exchange failed: HTTP ${response.status}`);
+  }
+  const parsed = parseCopilotTokenResponse(await response.json());
+  const cachePayload: CachedCopilotToken = {
+    token: parsed.token,
+    expiresAt: parsed.expiresAt,
+    updatedAt: Date.now(),
+  };
+  mkdirSync(dirname(cachePath), { recursive: true });
+  writeFileSync(cachePath, JSON.stringify(cachePayload, null, 2));
+  return {
+    token: parsed.token,
+    baseUrl: deriveCopilotApiBaseUrlFromToken(parsed.token) ?? DEFAULT_COPILOT_API_BASE_URL,
+    expiresAt: parsed.expiresAt,
+  };
+}
+
+function usesAnthropicTransport(model: string): boolean {
+  return model.trim().toLowerCase().includes('claude');
+}
+
+export class GitHubCopilotProvider implements LLMProvider {
+  readonly name = 'github-copilot';
+  readonly models = [
+    'claude-sonnet-4.6',
+    'claude-sonnet-4.5',
+    'gpt-4o',
+    'gpt-4.1',
+    'gpt-4.1-mini',
+    'gpt-4.1-nano',
+    'gpt-5.4',
+    'o1',
+    'o1-mini',
+    'o3-mini',
+  ];
+
+  constructor(private readonly options: GitHubCopilotProviderOptions) {}
+
+  async chat(params: ChatRequest): Promise<ChatResponse> {
+    try {
+      const model = params.model ?? this.models[0]!;
+      const session = await resolveCopilotToken(this.options);
+      const baseURL = `${session.baseUrl.replace(/\/+$/, '')}/v1`;
+      const defaultHeaders = buildCopilotDynamicHeaders(params.messages);
+      if (usesAnthropicTransport(model)) {
+        const provider = new AnthropicCompatProvider({
+          name: this.name,
+          baseURL,
+          apiKey: session.token,
+          defaultModel: model,
+          models: this.models,
+          defaultHeaders,
+          authEnvVars: COPILOT_TOKEN_ENV_VARS,
+          serviceNames: ['github-copilot'],
+          authHeaderMode: 'bearer',
+          streamProtocol: 'anthropic-sse',
+        });
+        return provider.chat({ ...params, model });
+      }
+
+      const provider = new OpenAICompatProvider({
+        name: this.name,
+        baseURL,
+        apiKey: session.token,
+        defaultModel: model,
+        models: this.models,
+        defaultHeaders,
+        authEnvVars: COPILOT_TOKEN_ENV_VARS,
+        serviceNames: ['github-copilot'],
+        aliases: ['copilot'],
+        streamProtocol: 'openai-sse',
+      });
+      return provider.chat({ ...params, model });
+    } catch (error) {
+      throw toProviderError(error, {
+        provider: this.name,
+        operation: 'chat',
+      });
+    }
+  }
+
+  async describeRuntime(deps: ProviderRuntimeMetadataDeps): Promise<ProviderRuntimeMetadata> {
+    const configured = readFirstEnv(COPILOT_TOKEN_ENV_VARS, this.options.env ?? process.env) !== null;
+    const authRoutes = await buildStandardProviderAuthRoutes({
+      providerId: this.name,
+      apiKeyEnvVars: COPILOT_TOKEN_ENV_VARS,
+      secretKeys: COPILOT_TOKEN_ENV_VARS,
+      serviceNames: ['github-copilot'],
+    }, deps);
+    return {
+      auth: {
+        mode: 'api-key',
+        configured,
+        detail: configured
+          ? 'GitHub token is available for Copilot token exchange.'
+          : 'Set COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN to use GitHub Copilot.',
+        envVars: COPILOT_TOKEN_ENV_VARS,
+        routes: authRoutes,
+      },
+      models: {
+        defaultModel: this.models[0],
+        models: this.models,
+        aliases: ['copilot'],
+      },
+      usage: {
+        streaming: true,
+        toolCalling: true,
+        parallelTools: true,
+        notes: ['Claude-family Copilot models use Anthropic transport. Other models use the OpenAI-compatible Copilot endpoint.'],
+      },
+      policy: {
+        local: false,
+        streamProtocol: 'mixed:anthropic+openai',
+        reasoningMode: 'provider-managed',
+      },
+    };
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,47 @@
+export type {
+  ChatRequest,
+  ChatResponse,
+  ContentPart,
+  LLMProvider,
+  PartialToolCall,
+  ProviderAuthRouteDescriptor,
+  ProviderDeclaredAuthRoute,
+  ProviderEmbeddingRequest,
+  ProviderEmbeddingResult,
+  ProviderMessage,
+  ProviderRuntimeMetadata,
+  ProviderRuntimeMetadataDeps,
+  ProviderUsageCostMetadata,
+  StreamDelta,
+} from './interface.ts';
+export { createProviderApi } from './provider-api.ts';
+export type {
+  ProviderApi,
+  ProviderApiBenchmarkStore,
+  ProviderApiBenchmarkQuery,
+  ProviderApiBenchmarkRecord,
+  ProviderApiCatalogBenchmarkRecord,
+  ProviderApiDependencies,
+  ProviderApiFavoriteRecord,
+  ProviderApiFavoritesStore,
+  ProviderApiFavoriteState,
+  ProviderApiFavoritesSnapshot,
+  ProviderApiModelQuery,
+  ProviderApiModelRecord,
+  ProviderApiModelReference,
+  ProviderApiModelRouting,
+  ProviderApiRegistry,
+  ProviderApiRuntimeQuery,
+  ProviderApiRuntimeQueryResult,
+  ProviderApiSyntheticBenchmarkRecord,
+  ProviderApiSyntheticRouting,
+} from './provider-api.ts';
+export type {
+  ContextWindowProvenance,
+  ModelDefinition,
+  ModelTier,
+  ProviderRegistryOptions,
+  RuntimeProviderRegistration,
+  TokenLimits,
+} from './registry-types.ts';
+export type { ProviderRuntimeSnapshot, ProviderUsageSnapshot } from './runtime-snapshot.ts';

package/src/providers/interface.ts

@@ -0,0 +1,185 @@
+import type { ToolDefinition, ToolCall } from '@pellux/goodvibes-sdk/platform/types/tools';
+import type { ProviderCapability } from './capabilities.ts';
+import type { SecretsManager } from '../config/secrets.ts';
+import type { ServiceRegistry } from '../config/service-registry.ts';
+import type { SubscriptionManager } from '@pellux/goodvibes-sdk/platform/config/subscriptions';
+
+/** Shared budget token map for reasoning effort levels. */
+export const REASONING_BUDGET_MAP: Record<string, number> = {
+  instant: 0,
+  low: 2048,
+  medium: 8192,
+  high: 32768,
+};
+
+/** Runtime metadata emitted by providers for diagnostics and policy surfaces. */
+export type ProviderDeclaredAuthRoute =
+  | 'api-key'
+  | 'secret-ref'
+  | 'service-oauth'
+  | 'subscription-oauth'
+  | 'anonymous'
+  | 'none';
+
+export interface ProviderAuthRouteDescriptor {
+  readonly route: ProviderDeclaredAuthRoute;
+  readonly label: string;
+  readonly configured: boolean;
+  readonly usable?: boolean;
+  readonly freshness?: 'healthy' | 'expiring' | 'expired' | 'pending' | 'unconfigured';
+  readonly detail?: string;
+  readonly envVars?: readonly string[];
+  readonly secretKeys?: readonly string[];
+  readonly serviceNames?: readonly string[];
+  readonly providerId?: string;
+  readonly repairHints?: readonly string[];
+}
+
+export interface ProviderUsageCostMetadata {
+  readonly source: 'catalog' | 'provider' | 'none';
+  readonly currency?: string;
+  readonly inputPerMillionTokens?: number;
+  readonly outputPerMillionTokens?: number;
+  readonly detail?: string;
+}
+
+export interface ProviderRuntimeMetadata {
+  readonly auth?: {
+    readonly mode: 'api-key' | 'oauth' | 'anonymous' | 'none';
+    readonly configured: boolean;
+    readonly detail?: string;
+    readonly envVars?: readonly string[];
+    readonly routes?: readonly ProviderAuthRouteDescriptor[];
+  };
+  readonly models?: {
+    readonly defaultModel?: string;
+    readonly models: readonly string[];
+    readonly embeddingModel?: string;
+    readonly embeddingDimensions?: number;
+    readonly aliases?: readonly string[];
+    readonly suppressedModels?: readonly string[];
+  };
+  readonly usage?: {
+    readonly streaming: boolean;
+    readonly toolCalling: boolean;
+    readonly parallelTools: boolean;
+    readonly promptCaching?: boolean;
+    readonly cost?: ProviderUsageCostMetadata;
+    readonly notes?: readonly string[];
+  };
+  readonly policy?: {
+    readonly local?: boolean;
+    readonly dataRetention?: string;
+    readonly streamProtocol?: string;
+    readonly reasoningMode?: string;
+    readonly supportedReasoningEfforts?: readonly string[];
+    readonly cacheStrategy?: string;
+    readonly notes?: readonly string[];
+  };
+  readonly notes?: readonly string[];
+}
+
+export interface ProviderRuntimeMetadataDeps {
+  readonly secretsManager: Pick<SecretsManager, 'listDetailed'>;
+  readonly serviceRegistry: Pick<ServiceRegistry, 'getAll' | 'inspect'>;
+  readonly subscriptionManager: Pick<SubscriptionManager, 'get' | 'getPending'>;
+}
+
+/** Shared embedding request shape used by providers and provider-backed adapters. */
+export interface ProviderEmbeddingRequest {
+  readonly text: string;
+  readonly dimensions: number;
+  readonly usage: 'record' | 'query' | 'doctor';
+  readonly model?: string;
+  readonly signal?: AbortSignal;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/** Shared embedding response shape used by providers and provider-backed adapters. */
+export interface ProviderEmbeddingResult {
+  readonly vector: Float32Array | readonly number[];
+  readonly dimensions: number;
+  readonly modelId?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/** Contract all LLM providers must implement. */
+export interface LLMProvider {
+  readonly name: string;
+  readonly models: string[];
+  /**
+   * Optional self-declared capability overrides for this provider instance.
+   * When present, these take precedence over the built-in `PROVIDER_DEFAULTS`
+   * table in `capabilities.ts` but are overridden by per-model `MODEL_OVERRIDES`.
+   *
+   * @remarks Useful for custom / dynamically-discovered providers that know
+   * their own capabilities and want to participate in explainable routing.
+   */
+  readonly capabilities?: Partial<ProviderCapability>;
+  chat(params: ChatRequest): Promise<ChatResponse>;
+  embed?(request: ProviderEmbeddingRequest): Promise<ProviderEmbeddingResult>;
+  describeRuntime?(deps: ProviderRuntimeMetadataDeps): ProviderRuntimeMetadata | Promise<ProviderRuntimeMetadata>;
+}
+
+/** Incremental tool call data received during streaming. */
+export interface PartialToolCall {
+  index: number;
+  id?: string;
+  name?: string;
+  arguments?: string;  // Partial JSON string
+}
+
+/** A single streaming delta from the provider. */
+export interface StreamDelta {
+  content?: string;           // Text content delta
+  toolCalls?: PartialToolCall[];  // Incremental tool call data
+  reasoning?: string;         // Reasoning/thinking delta
+}
+
+/** Content part for multimodal messages. */
+export type ContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data: string; mediaType: string };
+
+export interface ChatRequest {
+  messages: ProviderMessage[];
+  tools?: ToolDefinition[];
+  model: string;
+  maxTokens?: number;
+  signal?: AbortSignal;
+  systemPrompt?: string;
+  /** Controls reasoning depth for models that support it. Format varies by provider. */
+  reasoningEffort?: 'instant' | 'low' | 'medium' | 'high';
+  /** Mercury-2 specific: whether to include a reasoning summary in the response. */
+  reasoningSummary?: boolean;
+  /** Called per-chunk during streaming when streaming is enabled. */
+  onDelta?: (delta: StreamDelta) => void;
+}
+
+export interface ChatResponse {
+  content: string;
+  toolCalls: ToolCall[];
+  usage: {
+    inputTokens: number;       // Billed input tokens (excludes cache tokens on Anthropic)
+    outputTokens: number;
+    cacheReadTokens?: number;  // Anthropic: tokens read from prompt cache
+    cacheWriteTokens?: number; // Anthropic: tokens written to prompt cache
+  };
+  stopReason: 'end' | 'tool_use' | 'max_tokens' | 'error';
+  /** Mercury-2 specific: condensed chain-of-thought, if requested. */
+  reasoningSummary?: string;
+  /**
+   * Cache metrics for this response.
+   * @remarks Currently only populated by the Anthropic provider. Other providers return `undefined`.
+   */
+  cacheMetrics?: {
+    strategy: string;           // e.g. 'explicit-4bp', 'automatic', 'implicit', 'none'
+    breakpointsPlaced: number;
+    hitRate?: number;           // Computed from this response's usage
+  };
+}
+
+export type ProviderMessage =
+  | { role: 'user'; content: string | ContentPart[] }
+  | { role: 'assistant'; content: string; toolCalls?: ToolCall[] }
+  | { role: 'tool'; callId: string; content: string; name?: string };