@gitlab/gitlab-ai-provider 1.0.5

package/dist/index.d.ts

@@ -0,0 +1,572 @@
+import {
+  LanguageModelV2,
+  LanguageModelV2CallOptions,
+  LanguageModelV2Content,
+  LanguageModelV2FinishReason,
+  LanguageModelV2Usage,
+  LanguageModelV2CallWarning,
+  LanguageModelV2StreamPart,
+} from '@ai-sdk/provider';
+import { z } from 'zod';
+import { Tool } from '@anthropic-ai/sdk/resources/messages';
+
+interface GitLabAgenticConfig {
+  provider: string;
+  instanceUrl: string;
+  getHeaders: () => Record<string, string>;
+  fetch?: typeof fetch;
+  /**
+   * Optional callback to refresh the API key when a 401 error occurs.
+   * Should clear cached credentials and re-fetch from auth provider.
+   */
+  refreshApiKey?: () => Promise<void>;
+  /**
+   * The Anthropic model to use (e.g., 'claude-sonnet-4-5-20250929')
+   * @default 'claude-sonnet-4-5-20250929'
+   */
+  anthropicModel?: string;
+  /**
+   * Maximum tokens to generate
+   * @default 8192
+   */
+  maxTokens?: number;
+  /**
+   * Feature flags to pass to the GitLab API
+   * @default { DuoAgentPlatformNext: true }
+   */
+  featureFlags?: {
+    DuoAgentPlatformNext: true;
+  } & Record<string, boolean>;
+}
+/**
+ * GitLab Agentic Language Model
+ *
+ * This model uses GitLab's Anthropic proxy to provide native tool calling support
+ * for the duo-chat model. It connects to Claude through GitLab's cloud proxy
+ * at https://cloud.gitlab.com/ai/v1/proxy/anthropic/
+ */
+declare class GitLabAgenticLanguageModel implements LanguageModelV2 {
+  readonly specificationVersion: 'v2';
+  readonly modelId: string;
+  readonly supportedUrls: Record<string, RegExp[]>;
+  private readonly config;
+  private readonly directAccessClient;
+  private anthropicClient;
+  constructor(modelId: string, config: GitLabAgenticConfig);
+  get provider(): string;
+  /**
+   * Get or create an Anthropic client with valid credentials
+   * @param forceRefresh - If true, forces a token refresh before creating the client
+   */
+  private getAnthropicClient;
+  /**
+   * Check if an error is a token-related authentication error that can be retried
+   */
+  private isTokenError;
+  /**
+   * Convert AI SDK tools to Anthropic tool format
+   */
+  private convertTools;
+  /**
+   * Convert AI SDK tool choice to Anthropic format
+   */
+  private convertToolChoice;
+  /**
+   * Convert AI SDK prompt to Anthropic messages format
+   */
+  private convertPrompt;
+  /**
+   * Convert Anthropic finish reason to AI SDK format
+   */
+  private convertFinishReason;
+  doGenerate(options: LanguageModelV2CallOptions): Promise<{
+    content: LanguageModelV2Content[];
+    finishReason: LanguageModelV2FinishReason;
+    usage: LanguageModelV2Usage;
+    warnings: LanguageModelV2CallWarning[];
+  }>;
+  private doGenerateWithRetry;
+  doStream(options: LanguageModelV2CallOptions): Promise<{
+    stream: ReadableStream<LanguageModelV2StreamPart>;
+    request?: {
+      body?: unknown;
+    };
+    response?: {
+      headers?: Record<string, string>;
+    };
+  }>;
+  private doStreamWithRetry;
+}
+
+interface GitLabProvider {
+  (modelId: string): LanguageModelV2;
+  readonly specificationVersion: 'v2';
+  languageModel(modelId: string): LanguageModelV2;
+  chat(modelId: string): LanguageModelV2;
+  agenticChat(modelId: string, options?: GitLabAgenticOptions): GitLabAgenticLanguageModel;
+  textEmbeddingModel(modelId: string): never;
+  imageModel(modelId: string): never;
+}
+interface GitLabAgenticOptions {
+  /**
+   * The Anthropic model to use
+   * @default 'claude-sonnet-4-20250514'
+   */
+  anthropicModel?: string;
+  /**
+   * Maximum tokens to generate
+   * @default 8192
+   */
+  maxTokens?: number;
+  /**
+   * Feature flags to pass to the GitLab API
+   */
+  featureFlags?: Record<string, boolean>;
+}
+interface GitLabProviderSettings {
+  /**
+   * GitLab instance URL (e.g., 'https://gitlab.com')
+   * @default 'https://gitlab.com'
+   */
+  instanceUrl?: string;
+  /**
+   * API token (Personal Access Token or OAuth access token)
+   * Can also be set via GITLAB_TOKEN environment variable
+   */
+  apiKey?: string;
+  /**
+   * OAuth refresh token (optional, for OAuth flow)
+   */
+  refreshToken?: string;
+  /**
+   * OAuth client ID (required for OAuth flow)
+   */
+  clientId?: string;
+  /**
+   * OAuth redirect URI (required for OAuth flow)
+   */
+  redirectUri?: string;
+  /**
+   * Custom headers to include in requests
+   */
+  headers?: Record<string, string>;
+  /**
+   * Custom fetch implementation
+   */
+  fetch?: typeof fetch;
+  /**
+   * Provider name override
+   */
+  name?: string;
+  /**
+   * Default feature flags to pass to the GitLab API for all agentic chat models
+   */
+  featureFlags?: Record<string, boolean>;
+}
+declare function createGitLab(options?: GitLabProviderSettings): GitLabProvider;
+/**
+ * Default GitLab Duo provider instance
+ *
+ * @example
+ * ```typescript
+ * import { gitlab } from '@ai-sdk/gitlab';
+ *
+ * const model = gitlab('duo-chat');
+ * ```
+ */
+declare const gitlab: GitLabProvider;
+
+interface GitLabErrorOptions {
+  message: string;
+  statusCode?: number;
+  responseBody?: string;
+  cause?: unknown;
+}
+declare class GitLabError extends Error {
+  readonly statusCode?: number;
+  readonly responseBody?: string;
+  readonly cause?: unknown;
+  constructor(options: GitLabErrorOptions);
+  static fromResponse(response: Response, body: string): GitLabError;
+  isAuthError(): boolean;
+  isRateLimitError(): boolean;
+  isForbiddenError(): boolean;
+  isServerError(): boolean;
+}
+
+declare const gitlabOAuthTokenResponseSchema: z.ZodObject<
+  {
+    access_token: z.ZodString;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    expires_in: z.ZodNumber;
+    created_at: z.ZodNumber;
+  },
+  'strip',
+  z.ZodTypeAny,
+  {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    created_at?: number;
+  },
+  {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    created_at?: number;
+  }
+>;
+type GitLabOAuthTokenResponse = z.infer<typeof gitlabOAuthTokenResponseSchema>;
+
+/**
+ * OAuth types and constants for GitLab authentication
+ * Based on gitlab-vscode-extension and gitlab-lsp patterns
+ */
+interface GitLabOAuthTokens {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+  instanceUrl: string;
+}
+interface OpenCodeAuthOAuth {
+  type: 'oauth';
+  refresh: string;
+  access: string;
+  expires: number;
+  instanceUrl?: string;
+}
+interface OpenCodeAuthApi {
+  type: 'api';
+  key: string;
+}
+type OpenCodeAuth = OpenCodeAuthOAuth | OpenCodeAuthApi;
+/**
+ * Bundled OAuth client ID for GitLab.com
+ * Same as used in gitlab-vscode-extension
+ */
+declare const BUNDLED_CLIENT_ID =
+  '36f2a70cddeb5a0889d4fd8295c241b7e9848e89cf9e599d0eed2d8e5350fbf5';
+/**
+ * GitLab.com URL constant
+ */
+declare const GITLAB_COM_URL = 'https://gitlab.com';
+/**
+ * Token expiry skew in milliseconds (5 minutes)
+ * Refresh tokens this many milliseconds before they expire
+ */
+declare const TOKEN_EXPIRY_SKEW_MS: number;
+/**
+ * OAuth scopes to request
+ */
+declare const OAUTH_SCOPES: string[];
+
+/**
+ * GitLab OAuth Manager
+ * Handles OAuth token management, refresh, and exchange
+ * Based on gitlab-vscode-extension TokenExchangeService and gitlab-lsp OAuthClientProvider
+ */
+
+interface TokenExchangeParams {
+  instanceUrl: string;
+  clientId?: string;
+  redirectUri?: string;
+}
+interface AuthorizationCodeParams extends TokenExchangeParams {
+  code: string;
+  codeVerifier: string;
+}
+interface RefreshTokenParams extends TokenExchangeParams {
+  refreshToken: string;
+}
+declare class GitLabOAuthManager {
+  private fetch;
+  constructor(fetchImpl?: typeof fetch);
+  /**
+   * Check if a token is expired
+   */
+  isTokenExpired(expiresAt: number): boolean;
+  /**
+   * Check if a token needs refresh (within skew window)
+   */
+  needsRefresh(expiresAt: number): boolean;
+  /**
+   * Refresh tokens if needed
+   * Returns the same tokens if refresh is not needed, or new tokens if refreshed
+   */
+  refreshIfNeeded(tokens: GitLabOAuthTokens, clientId?: string): Promise<GitLabOAuthTokens>;
+  /**
+   * Exchange authorization code for tokens
+   * Based on gitlab-vscode-extension createOAuthAccountFromCode
+   */
+  exchangeAuthorizationCode(params: AuthorizationCodeParams): Promise<GitLabOAuthTokens>;
+  /**
+   * Exchange refresh token for new tokens
+   * Based on gitlab-vscode-extension TokenExchangeService
+   */
+  exchangeRefreshToken(params: RefreshTokenParams): Promise<GitLabOAuthTokens>;
+  /**
+   * Get the OAuth client ID for an instance
+   */
+  private getClientId;
+  /**
+   * Exchange token with GitLab OAuth endpoint
+   * Based on gitlab-vscode-extension GitLabService.exchangeToken
+   */
+  private exchangeToken;
+  /**
+   * Create GitLabOAuthTokens from token response
+   */
+  private createTokensFromResponse;
+  /**
+   * Create expiry timestamp from token response
+   * Based on gitlab-vscode-extension createExpiresTimestamp
+   */
+  private createExpiresTimestamp;
+}
+
+/**
+ * Tool definitions for Anthropic Claude
+ */
+declare const ANTHROPIC_TOOLS: Tool[];
+interface ToolResult {
+  result: string;
+  error?: string;
+}
+interface ToolInput {
+  [key: string]: unknown;
+}
+/**
+ * Tool executor for local file and command operations
+ */
+declare class AnthropicToolExecutor {
+  private readonly workingDirectory;
+  constructor(workingDirectory: string);
+  /**
+   * Execute a tool by name with given input
+   */
+  execute(toolName: string, input: ToolInput): Promise<ToolResult>;
+  private resolvePath;
+  private listDir;
+  private readFile;
+  private writeFile;
+  private editFile;
+  private findFiles;
+  private mkdir;
+  private grep;
+  private runCommand;
+  private runGitCommand;
+  private executeCommand;
+}
+
+/**
+ * GitLab API tools for interacting with GitLab resources
+ * These tools allow the AI to access merge requests, issues, pipelines, etc.
+ */
+declare const GITLAB_API_TOOLS: Tool[];
+interface GitLabApiToolsConfig {
+  instanceUrl: string;
+  token: string;
+  fetch?: typeof fetch;
+}
+/**
+ * Executor for GitLab API tools
+ */
+declare class GitLabApiToolExecutor {
+  private readonly config;
+  constructor(config: GitLabApiToolsConfig);
+  private get headers();
+  private fetchApi;
+  private encodeProjectId;
+  /**
+   * Execute a GitLab API tool by name
+   */
+  execute(toolName: string, input: ToolInput): Promise<ToolResult>;
+  private getMergeRequest;
+  private listMergeRequests;
+  private getMrChanges;
+  private listMrDiscussions;
+  private createMrNote;
+  private getIssue;
+  private listIssues;
+  private createIssueNote;
+  private listPipelines;
+  private getPipeline;
+  private listPipelineJobs;
+  private getJobLog;
+  private retryJob;
+  private getFile;
+  private listCommits;
+  private getCommitDiff;
+  private listBranches;
+  private search;
+  private getProject;
+  private listProjectMembers;
+}
+/**
+ * Check if a tool name is a GitLab API tool
+ */
+declare function isGitLabApiTool(toolName: string): boolean;
+
+/**
+ * Simple in-memory cache for GitLab project information
+ * Used to avoid repeated API calls when detecting projects from git remotes
+ */
+interface GitLabProject {
+  id: number;
+  path: string;
+  pathWithNamespace: string;
+  name: string;
+  namespaceId?: number;
+}
+/**
+ * In-memory cache for GitLab project information with TTL support
+ */
+declare class GitLabProjectCache {
+  private cache;
+  private defaultTTL;
+  /**
+   * Create a new project cache
+   * @param defaultTTL - Default time-to-live in milliseconds (default: 5 minutes)
+   */
+  constructor(defaultTTL?: number);
+  /**
+   * Get a cached project by key
+   * @param key - Cache key (typically the working directory path)
+   * @returns The cached project or null if not found or expired
+   */
+  get(key: string): GitLabProject | null;
+  /**
+   * Store a project in the cache
+   * @param key - Cache key (typically the working directory path)
+   * @param project - The project to cache
+   * @param ttl - Optional custom TTL in milliseconds
+   */
+  set(key: string, project: GitLabProject, ttl?: number): void;
+  /**
+   * Check if a key exists in the cache (and is not expired)
+   * @param key - Cache key to check
+   * @returns true if the key exists and is not expired
+   */
+  has(key: string): boolean;
+  /**
+   * Remove a specific entry from the cache
+   * @param key - Cache key to remove
+   */
+  delete(key: string): void;
+  /**
+   * Clear all entries from the cache
+   */
+  clear(): void;
+  /**
+   * Get the number of entries in the cache (including expired ones)
+   */
+  get size(): number;
+  /**
+   * Clean up expired entries from the cache
+   * This is useful for long-running processes to prevent memory leaks
+   */
+  cleanup(): void;
+}
+
+interface GitLabProjectDetectorConfig {
+  instanceUrl: string;
+  getHeaders: () => Record<string, string>;
+  fetch?: typeof fetch;
+  cache?: GitLabProjectCache;
+  gitTimeout?: number;
+}
+/**
+ * Detects GitLab project information from git remote URLs
+ *
+ * This class provides functionality to:
+ * - Parse git remote URLs (SSH, HTTPS, custom domains)
+ * - Execute git commands to get remote URLs
+ * - Fetch project details from GitLab API
+ * - Cache project information to avoid repeated API calls
+ */
+declare class GitLabProjectDetector {
+  private readonly config;
+  private readonly fetchFn;
+  private readonly cache;
+  constructor(config: GitLabProjectDetectorConfig);
+  /**
+   * Auto-detect GitLab project from git remote in the working directory
+   *
+   * @param workingDirectory - The directory to check for git remote
+   * @param remoteName - The git remote name to use (default: 'origin')
+   * @returns The detected project or null if detection fails
+   */
+  detectProject(workingDirectory: string, remoteName?: string): Promise<GitLabProject | null>;
+  /**
+   * Parse a git remote URL to extract the project path
+   *
+   * Supports:
+   * - SSH: git@gitlab.com:namespace/project.git
+   * - HTTPS: https://gitlab.com/namespace/project.git
+   * - HTTP: http://gitlab.local/namespace/project.git
+   * - Custom domains and ports
+   *
+   * @param remoteUrl - The git remote URL
+   * @param instanceUrl - The GitLab instance URL to match against
+   * @returns The project path (e.g., "namespace/project") or null if parsing fails
+   */
+  parseGitRemoteUrl(remoteUrl: string, instanceUrl: string): string | null;
+  /**
+   * Get the git remote URL from a working directory
+   *
+   * @param workingDirectory - The directory to check
+   * @param remoteName - The git remote name (default: 'origin')
+   * @returns The remote URL or null if not found
+   */
+  getGitRemoteUrl(workingDirectory: string, remoteName?: string): Promise<string | null>;
+  /**
+   * Fetch project details from GitLab API by project path
+   *
+   * @param projectPath - The project path (e.g., "namespace/project")
+   * @returns The project details
+   * @throws GitLabError if the API call fails
+   */
+  getProjectByPath(projectPath: string): Promise<GitLabProject>;
+  /**
+   * Clear the project cache
+   */
+  clearCache(): void;
+  /**
+   * Get the cache instance (useful for testing)
+   */
+  getCache(): GitLabProjectCache;
+}
+
+export {
+  ANTHROPIC_TOOLS,
+  AnthropicToolExecutor,
+  BUNDLED_CLIENT_ID,
+  GITLAB_API_TOOLS,
+  GITLAB_COM_URL,
+  type GitLabAgenticConfig,
+  GitLabAgenticLanguageModel,
+  type GitLabAgenticOptions,
+  GitLabApiToolExecutor,
+  type GitLabApiToolsConfig,
+  GitLabError,
+  type GitLabErrorOptions,
+  GitLabOAuthManager,
+  type GitLabOAuthTokenResponse,
+  type GitLabOAuthTokens,
+  type GitLabProject,
+  GitLabProjectCache,
+  GitLabProjectDetector,
+  type GitLabProjectDetectorConfig,
+  type GitLabProvider,
+  type GitLabProviderSettings,
+  OAUTH_SCOPES,
+  type OpenCodeAuth,
+  type OpenCodeAuthApi,
+  type OpenCodeAuthOAuth,
+  TOKEN_EXPIRY_SKEW_MS,
+  type ToolInput,
+  type ToolResult,
+  createGitLab,
+  gitlab,
+  isGitLabApiTool,
+};