@gitlab/gitlab-ai-provider 1.0.5

package/dist/index.d.mts

@@ -0,0 +1,525 @@
+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 };