gitlab-ai-provider 5.0.0

package/dist/index.d.mts

@@ -0,0 +1,1521 @@
+import { LanguageModelV2, LanguageModelV2CallOptions, LanguageModelV2Content, LanguageModelV2FinishReason, LanguageModelV2Usage, LanguageModelV2CallWarning, LanguageModelV2StreamPart } from '@ai-sdk/provider';
+import { z } from 'zod';
+
+interface GitLabAnthropicConfig {
+    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>;
+    /**
+     * AI Gateway URL for the Anthropic proxy.
+     * Can also be set via GITLAB_AI_GATEWAY_URL environment variable.
+     * @default 'https://cloud.gitlab.com'
+     */
+    aiGatewayUrl?: string;
+    /**
+     * Custom headers for AI Gateway Anthropic proxy requests.
+     * Merged with headers from direct_access token response.
+     */
+    aiGatewayHeaders?: Record<string, string>;
+}
+/**
+ * GitLab Anthropic 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 GitLabAnthropicLanguageModel 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: GitLabAnthropicConfig);
+    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;
+    /**
+     * Check if an error is a context overflow error (prompt too long)
+     * These should NOT trigger token refresh and should be reported to the user.
+     */
+    private isContextOverflowError;
+    /**
+     * 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;
+}
+
+/**
+ * Dynamic model discovery via GitLab GraphQL API.
+ *
+ * Queries `aiChatAvailableModels` to discover which models are available
+ * for a given GitLab namespace. Used to dynamically populate `duo-workflow-*`
+ * model IDs at runtime.
+ *
+ * Requires GitLab 18.4+ (18.5+ for pinned model support).
+ */
+interface AiModel {
+    /** Display name (e.g., 'Claude Sonnet 4.6') */
+    name: string;
+    /** Model reference for API use (e.g., 'claude_sonnet_4_6' or 'anthropic/claude-sonnet-4-5-20250929') */
+    ref: string;
+}
+interface AiChatAvailableModels {
+    defaultModel: AiModel | null;
+    selectableModels: AiModel[];
+    pinnedModel: AiModel | null;
+}
+interface DiscoveredModels {
+    /** The effective model (pinned > user-selected > default) */
+    defaultModel: AiModel | null;
+    /** All models the user can select from */
+    selectableModels: AiModel[];
+    /** Admin-pinned model (overrides everything) */
+    pinnedModel: AiModel | null;
+    /** Whether the ai_user_model_switching feature flag is enabled */
+    modelSwitchingEnabled: boolean;
+    /** GitLab instance version */
+    instanceVersion: string | null;
+}
+interface ModelDiscoveryConfig {
+    /** GitLab instance URL */
+    instanceUrl: string;
+    /** Function returning auth headers */
+    getHeaders: () => Record<string, string>;
+    /** Custom fetch */
+    fetch?: typeof fetch;
+}
+declare class GitLabModelDiscovery {
+    private readonly config;
+    private readonly fetchFn;
+    private cache;
+    constructor(config: ModelDiscoveryConfig);
+    /**
+     * Discover available models for a given root namespace.
+     *
+     * Results are cached per `rootNamespaceId` with a 10-minute TTL.
+     * Use `invalidateCache()` to force an immediate refresh.
+     *
+     * @param rootNamespaceId - GitLab group ID (e.g., 'gid://gitlab/Group/12345')
+     */
+    discover(rootNamespaceId: string): Promise<DiscoveredModels>;
+    /**
+     * Get the effective model ref to use for a workflow.
+     *
+     * Priority: pinned > user-selected > default.
+     *
+     * @param rootNamespaceId - GitLab group ID
+     * @param userSelectedRef - Optional user preference
+     */
+    getEffectiveModelRef(rootNamespaceId: string, userSelectedRef?: string): Promise<string | null>;
+    /**
+     * Invalidate the cached discovery results.
+     */
+    invalidateCache(): void;
+}
+
+/**
+ * File-based cache for workflow model discovery results and user selection.
+ *
+ * A single cache file is stored at
+ * `~/.cache/opencode/gitlab-workflow-model-cache.json`
+ * (or `$XDG_CACHE_HOME/opencode/...` when set).
+ *
+ * The file contains a JSON object keyed by a truncated SHA-256 hash of the
+ * workspace directory path combined with the GitLab instance URL. This ensures
+ * that switching instances for the same workspace invalidates the cache.
+ * Each value holds:
+ *   - `discovery`: The full DiscoveredModels JSON from the last successful discovery
+ *   - `selectedModelRef`: The model ref the user last selected
+ *   - `selectedModelName`: Human-readable name of the selected model
+ *   - `updatedAt`: ISO timestamp of the last write
+ */
+
+interface ModelCacheEntry {
+    discovery: DiscoveredModels | null;
+    selectedModelRef: string | null;
+    selectedModelName: string | null;
+    updatedAt: string;
+}
+declare class GitLabModelCache {
+    private readonly filePath;
+    private readonly key;
+    constructor(workDir: string, instanceUrl?: string);
+    private readAll;
+    private writeAll;
+    /**
+     * Load the cached entry for this workspace.
+     * Returns null if no cache exists or is unreadable.
+     */
+    load(): ModelCacheEntry | null;
+    /**
+     * Persist the full cache entry to disk.
+     */
+    save(entry: ModelCacheEntry): void;
+    /**
+     * Update only the discovery portion of the cache, preserving selection.
+     */
+    saveDiscovery(discovery: DiscoveredModels): void;
+    /**
+     * Update only the selected model, preserving the discovery data.
+     */
+    saveSelection(ref: string | null, name: string | null): void;
+    /**
+     * Remove the entry for this workspace from the cache file.
+     */
+    clear(): void;
+    /**
+     * Convenience: get the cached selected model ref (or null).
+     */
+    getSelectedModelRef(): string | null;
+    /**
+     * Convenience: get the cached selected model name (or null).
+     */
+    getSelectedModelName(): string | null;
+    /**
+     * Convenience: get the cached discovery result (or null).
+     */
+    getDiscovery(): DiscoveredModels | null;
+}
+
+/**
+ * Types for the GitLab Duo Agent Platform (DWS) protocol.
+ *
+ * DWS uses a WebSocket-based bidirectional protocol where:
+ * - Client sends `ClientEvent` messages (startRequest, actionResponse, stopWorkflow, heartbeat)
+ * - Server sends `WorkflowAction` messages (newCheckpoint, runMcpTool, built-in tools)
+ *
+ * Message format is JSON-serialized protobuf with camelCase field names.
+ */
+interface GenerateTokenResponse {
+    gitlab_rails: {
+        base_url: string;
+        token: string;
+        token_expires_at: string;
+    };
+    duo_workflow_service: {
+        base_url: string;
+        token: string;
+        secure: boolean;
+        token_expires_at: number;
+        headers: Record<string, string>;
+    };
+    duo_workflow_executor: {
+        executor_binary_url: string;
+        version: string;
+    };
+}
+interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: string;
+}
+interface AdditionalContext {
+    category: string;
+    id?: string;
+    content?: string;
+    metadata?: string;
+}
+interface StartRequest {
+    workflowID: string;
+    clientVersion: string;
+    workflowDefinition: string;
+    goal: string;
+    workflowMetadata?: string;
+    additional_context?: AdditionalContext[];
+    clientCapabilities?: string[];
+    mcpTools?: McpToolDefinition[];
+    preapproved_tools?: string[];
+    flowConfig?: unknown;
+    flowConfigSchemaVersion?: string;
+}
+interface ActionResponsePayload {
+    requestID: string;
+    plainTextResponse: {
+        response: string;
+        error: string | null;
+    };
+}
+interface StopWorkflow {
+    reason: string;
+}
+interface Heartbeat {
+    timestamp: number;
+}
+/**
+ * Client → Server event union.
+ * Exactly one of the fields should be set per message.
+ */
+type ClientEvent = {
+    startRequest: StartRequest;
+} | {
+    actionResponse: ActionResponsePayload;
+} | {
+    stopWorkflow: StopWorkflow;
+} | {
+    heartbeat: Heartbeat;
+};
+type WorkflowStatus = 'CREATED' | 'RUNNING' | 'FINISHED' | 'COMPLETED' | 'FAILED' | 'STOPPED' | 'CANCELLED' | 'PAUSED' | 'INPUT_REQUIRED' | 'PLAN_APPROVAL_REQUIRED' | 'TOOL_CALL_APPROVAL_REQUIRED' | 'UNKNOWN';
+interface NewCheckpoint {
+    status: WorkflowStatus;
+    goal?: string;
+    /** Raw checkpoint JSON string from DWS (contains channel_values.ui_chat_log) */
+    checkpoint?: string;
+    /** Legacy content field (may be empty — text is in checkpoint.ui_chat_log) */
+    content?: string;
+}
+interface RunMcpTool {
+    name: string;
+    args: string;
+}
+interface ReadFileAction {
+    filepath: string;
+}
+interface ReadFilesAction {
+    filepaths: string[];
+}
+interface WriteFileAction {
+    filepath: string;
+    contents: string;
+}
+interface ShellCommandAction {
+    command: string;
+}
+interface EditFileAction {
+    filepath: string;
+    oldString: string;
+    newString: string;
+}
+interface ListDirectoryAction {
+    directory: string;
+}
+interface FindFilesAction {
+    name_pattern: string;
+}
+interface GrepAction {
+    pattern: string;
+    search_directory?: string;
+    case_insensitive?: boolean;
+}
+interface MkdirAction {
+    directory_path: string;
+}
+interface RunCommandAction {
+    program: string;
+    flags?: string[];
+    arguments?: string[];
+}
+interface RunGitCommandAction {
+    command: string;
+    arguments?: string[];
+    repository_url?: string;
+}
+interface GitLabApiRequestAction {
+    method: string;
+    path: string;
+    body?: string;
+}
+/**
+ * Server → Client action union.
+ * Field names match the DWS protobuf camelCase wire format exactly.
+ * Each message has an optional `requestID` (required for tool invocations
+ * that need an `actionResponse` back).
+ */
+interface WorkflowAction {
+    requestID?: string;
+    newCheckpoint?: NewCheckpoint;
+    runMCPTool?: RunMcpTool;
+    runReadFile?: ReadFileAction;
+    runReadFiles?: ReadFilesAction;
+    runWriteFile?: WriteFileAction;
+    runShellCommand?: ShellCommandAction;
+    runEditFile?: EditFileAction;
+    listDirectory?: ListDirectoryAction;
+    findFiles?: FindFilesAction;
+    grep?: GrepAction;
+    mkdir?: MkdirAction;
+    runCommand?: RunCommandAction;
+    runGitCommand?: RunGitCommandAction;
+    runHTTPRequest?: GitLabApiRequestAction;
+}
+/**
+ * Options for creating a workflow chat model via `provider.workflowChat()`.
+ */
+interface GitLabWorkflowOptions {
+    /**
+     * Workflow definition type.
+     * @default 'chat'
+     */
+    workflowDefinition?: string;
+    /**
+     * Root namespace ID for the GitLab group/project.
+     * Used for token scoping and model discovery.
+     */
+    rootNamespaceId?: string;
+    /**
+     * GitLab project ID (numeric or path).
+     * Sent as `x-gitlab-project-id` header on WebSocket.
+     */
+    projectId?: string;
+    /**
+     * GitLab namespace ID.
+     * Sent as `x-gitlab-namespace-id` header on WebSocket.
+     */
+    namespaceId?: string;
+    /**
+     * MCP tool definitions to expose to the workflow.
+     * These are sent in `startRequest.mcpTools`.
+     */
+    mcpTools?: McpToolDefinition[];
+    /**
+     * Client capabilities to advertise.
+     * @default ['shell_command']
+     */
+    clientCapabilities?: string[];
+    /**
+     * Tool names that are pre-approved for execution without user confirmation.
+     * Sent in `startRequest.preapproved_tools`.
+     */
+    preapprovedTools?: string[];
+    /**
+     * Additional context items to send with the first request.
+     * Used for conversation history continuity.
+     */
+    additionalContext?: AdditionalContext[];
+    /**
+     * Feature flags to pass to the GitLab API.
+     */
+    featureFlags?: Record<string, boolean>;
+    /**
+     * Working directory for auto-detecting GitLab project from git remote.
+     * Used to resolve `projectId` when not explicitly set.
+     * Defaults to `process.cwd()`.
+     */
+    workingDirectory?: string;
+    /**
+     * Flow configuration (parsed YAML object) to send to DWS.
+     * Controls agent behavior, intermediate text generation, etc.
+     * Sent as `startRequest.flowConfig`.
+     */
+    flowConfig?: unknown;
+    /**
+     * Schema version for the flow configuration.
+     * Sent as `startRequest.flowConfigSchemaVersion`.
+     */
+    flowConfigSchemaVersion?: string;
+    /**
+     * Callback invoked when multiple workflow models are available for the
+     * workspace and model switching is enabled by the instance admin.
+     *
+     * The provider calls this before starting the workflow so the host can
+     * present a model picker to the user. Return the `ref` of the chosen
+     * model, or `null`/`undefined` to fall back to the workspace default.
+     *
+     * If the returned ref is not in the list of selectable models it is
+     * ignored and the workspace default is used instead.
+     *
+     * Not called when the admin has pinned a model — in that case the
+     * pinned model is always used regardless of user preference.
+     *
+     * @param models - List of models the user can select from
+     * @returns The selected model ref, or null/undefined for default
+     */
+    onSelectModel?: (models: AiModel[]) => Promise<string | null | undefined>;
+}
+interface GitLabWorkflowClientConfig {
+    /** GitLab instance URL (e.g., 'https://gitlab.com') */
+    instanceUrl: string;
+    /** Function to get current auth headers */
+    getHeaders: () => Record<string, string>;
+    /**
+     * Optional callback to refresh the API key when a 401 error occurs.
+     */
+    refreshApiKey?: () => Promise<void>;
+    /** Custom fetch implementation */
+    fetch?: typeof fetch;
+    /** Feature flags for the token request */
+    featureFlags?: Record<string, boolean>;
+    /**
+     * AI Gateway URL.
+     * Can also be set via GITLAB_AI_GATEWAY_URL environment variable.
+     * @default 'https://cloud.gitlab.com'
+     */
+    aiGatewayUrl?: string;
+}
+type WorkflowClientEvent = {
+    type: 'checkpoint';
+    data: NewCheckpoint;
+} | {
+    type: 'tool-request';
+    requestID: string;
+    data: RunMcpTool;
+} | {
+    type: 'builtin-tool-request';
+    requestID: string;
+    toolName: string;
+    data: Record<string, unknown>;
+} | {
+    type: 'completed';
+} | {
+    type: 'failed';
+    error: Error;
+} | {
+    type: 'closed';
+    code: number;
+    reason: string;
+};
+/**
+ * Workflow type enum — matches gitlab-lsp WorkflowType.
+ *
+ * - CHAT: Shared token across sessions, tokens NOT revoked on completion
+ * - SOFTWARE_DEVELOPMENT: Per-workflow token, tokens revoked on completion
+ */
+declare enum WorkflowType {
+    CHAT = "chat",
+    SOFTWARE_DEVELOPMENT = "software_development"
+}
+/** WebSocket ping interval (TCP keepalive) — 45s matching gitlab-lsp */
+declare const WS_KEEPALIVE_PING_INTERVAL_MS = 45000;
+/** Application heartbeat interval — 60s matching gitlab-lsp */
+declare const WS_HEARTBEAT_INTERVAL_MS = 60000;
+/** Default workflow definition — uses CHAT for agentic chat (matches gitlab-lsp) */
+declare const DEFAULT_WORKFLOW_DEFINITION = WorkflowType.CHAT;
+/** Default client capabilities */
+declare const DEFAULT_CLIENT_CAPABILITIES: string[];
+/** Client version sent in startRequest */
+declare const CLIENT_VERSION = "1.0";
+/**
+ * Agent privileges for workflow creation.
+ * Matches gitlab-lsp AGENT_PRIVILEGES enum.
+ */
+declare const AGENT_PRIVILEGES: {
+    readonly READ_WRITE_FILES: 1;
+    readonly READ_ONLY_GITLAB: 2;
+    readonly READ_WRITE_GITLAB: 3;
+    readonly RUN_COMMANDS: 4;
+    readonly USE_GIT: 5;
+    readonly RUN_MCP_TOOLS: 6;
+};
+/** Default agent privileges — matches gitlab-lsp defaults */
+declare const DEFAULT_AGENT_PRIVILEGES: (1 | 2 | 4 | 3 | 5 | 6)[];
+/** Workflow execution environment */
+declare const WORKFLOW_ENVIRONMENT: "ide";
+
+interface GitLabWorkflowLanguageModelConfig extends GitLabWorkflowClientConfig {
+    /** Provider name (e.g., 'gitlab.workflow') */
+    provider: string;
+}
+/**
+ * Callback for executing a tool requested by DWS.
+ * Provided by the consumer (e.g., OpenCode) to bridge DWS tool requests
+ * to the host's tool execution system.
+ *
+ * @param toolName - Name of the tool DWS wants to execute
+ * @param args - JSON-encoded arguments
+ * @returns Tool execution result as a string, or throws on error
+ */
+type WorkflowToolExecutor = (toolName: string, args: string, requestID: string) => Promise<{
+    result: string;
+    error?: string | null;
+}>;
+/**
+ * GitLab Duo Agent Platform Language Model.
+ *
+ * Implements LanguageModelV2 by bridging the DWS WebSocket protocol
+ * to the Vercel AI SDK stream part format.
+ */
+declare class GitLabWorkflowLanguageModel implements LanguageModelV2 {
+    readonly specificationVersion: "v2";
+    readonly modelId: string;
+    readonly supportedUrls: Record<string, RegExp[]>;
+    private readonly config;
+    private readonly workflowOptions;
+    private readonly tokenClient;
+    private readonly projectDetector;
+    private readonly modelDiscovery;
+    private readonly modelCache;
+    private detectedProjectPath;
+    private currentWorkflowId;
+    private persistedAgentEmitted;
+    private readonly activeClients;
+    private _selectedModelRef?;
+    private _selectedModelName?;
+    private _rootNamespaceId?;
+    private _discoveryPromise?;
+    /**
+     * Get the cached selected model ref.
+     */
+    get selectedModelRef(): string | null;
+    /**
+     * Set the selected model ref (e.g., from an eager discover call).
+     * This will be used by resolveModelRef() to skip the picker.
+     * Also persists to the file-based workspace cache.
+     */
+    set selectedModelRef(ref: string | null);
+    /**
+     * Get the cached selected model display name.
+     */
+    get selectedModelName(): string | null;
+    /**
+     * Set the selected model display name.
+     * Also persists to the file-based workspace cache.
+     */
+    set selectedModelName(name: string | null);
+    /**
+     * Optional external tool executor. When set, this is called for tool
+     * requests instead of looking up tools from `options.tools`.
+     * This allows the consumer (OpenCode) to wire in its permission system.
+     *
+     * The executor is automatically bound to the async context at the time
+     * it is set, so that AsyncLocalStorage-based contexts (like Instance)
+     * remain available when the executor is invoked from WebSocket callbacks.
+     */
+    private _toolExecutor;
+    /**
+     * Optional callback invoked with intermediate token usage estimates
+     * after each tool execution completes. This allows the consumer to
+     * display live token counts during long-running DWS workflows, since
+     * the AI SDK only surfaces usage via finish-step at stream end.
+     */
+    onUsageUpdate: ((usage: {
+        inputTokens: number;
+        outputTokens: number;
+    }) => void) | null;
+    /**
+     * Optional callback invoked when multiple workflow models are available
+     * and the user should pick one. Set per-stream by the host (e.g., OpenCode)
+     * alongside `toolExecutor`. Takes precedence over `workflowOptions.onSelectModel`.
+     */
+    onSelectModel: ((models: AiModel[]) => Promise<string | null | undefined>) | null;
+    get toolExecutor(): WorkflowToolExecutor | null;
+    set toolExecutor(executor: WorkflowToolExecutor | null);
+    constructor(modelId: string, config: GitLabWorkflowLanguageModelConfig, workflowOptions?: GitLabWorkflowOptions);
+    get provider(): string;
+    /**
+     * Resolve the project ID (path) to use for workflow creation.
+     * Priority: explicit option > auto-detected from git remote > undefined.
+     */
+    private resolveProjectId;
+    /**
+     * Resolve the root namespace GID to use for model discovery.
+     *
+     * Priority:
+     *   1. Explicit `rootNamespaceId` in workflowOptions (caller-provided GID)
+     *   2. Auto-detected from git remote via project detector (namespace.id → GID)
+     *   3. Cached from previous call
+     */
+    private resolveRootNamespaceId;
+    /**
+     * Resolve the effective DWS model ref to use for this stream.
+     * Deduplicates concurrent calls via a shared promise.
+     *
+     * Priority for the canonical `duo-workflow` model ID:
+     *   1. Admin-pinned model (from GitLabModelDiscovery) — always wins
+     *   2. User selection via onSelectModel callback (if model switching enabled)
+     *   3. Workspace default model
+     *   4. File-cached discovery/selection — used when live discovery fails
+     *   5. Hard-coded 'default' (DWS decides) — fallback when discovery fails
+     *
+     * For all other `duo-workflow-*` model IDs the static mapping is used as-is.
+     */
+    private resolveModelRef;
+    private doResolveModelRef;
+    /**
+     * Pre-fetch available models for the workspace.
+     * Call this early (e.g., on IDE startup) to avoid blocking the first stream.
+     * Results are persisted to the workspace model cache.
+     *
+     * @param rootNamespaceId - GitLab group ID (e.g., 'gid://gitlab/Group/12345')
+     * @returns Discovered models with default, selectable, and pinned models
+     */
+    discoverModels(rootNamespaceId: string): Promise<DiscoveredModels>;
+    /**
+     * Get the file-based model cache instance for this workspace.
+     * Useful for consumers that need direct cache access (e.g., the discover route).
+     */
+    getModelCache(): GitLabModelCache;
+    /**
+     * Stop the active workflow.
+     */
+    stopWorkflow(): void;
+    /**
+     * Reset the workflow state, forcing a new workflow to be created on the
+     * next doStream() call. Call this when starting a new conversation.
+     */
+    resetWorkflow(): void;
+    /**
+     * Get the current workflow ID (if any).
+     * Useful for consumers that need to track workflow state.
+     */
+    get workflowId(): string | null;
+    doGenerate(options: LanguageModelV2CallOptions): Promise<{
+        content: LanguageModelV2Content[];
+        finishReason: LanguageModelV2FinishReason;
+        usage: LanguageModelV2Usage;
+        warnings: LanguageModelV2CallWarning[];
+    }>;
+    doStream(options: LanguageModelV2CallOptions): Promise<{
+        stream: ReadableStream<LanguageModelV2StreamPart>;
+        request?: {
+            body?: unknown;
+        };
+    }>;
+    private handleWorkflowEvent;
+    private processCheckpoint;
+    private executeToolAndRespond;
+    private cleanupClient;
+    private buildWorkflowMetadata;
+    private getGitInfo;
+    /**
+     * Extract the user's goal (last user message) from the AI SDK prompt.
+     */
+    private extractGoalFromPrompt;
+    /**
+     * Convert AI SDK tools to DWS McpToolDefinition format.
+     */
+    private extractMcpTools;
+    private static readonly MAX_START_REQUEST_BYTES;
+    /**
+     * Trim mcpTools and additionalContext to fit within the DWS 4MB gRPC
+     * message size limit (`MAX_MESSAGE_SIZE` in duo_workflow_service/server.py).
+     *
+     * DWS has no per-field limits on tool descriptions, schemas, or context items.
+     * The only hard constraint is the total serialized message size.
+     *
+     * Strategy (progressive, only if over budget):
+     * 1. Send everything as-is
+     * 2. Simplify tool input schemas (strip descriptions from properties)
+     * 3. Strip schemas to minimal form (type + property names only)
+     * 4. Drop tools from the end until it fits
+     */
+    private trimPayload;
+    private buildAdditionalContext;
+}
+
+interface GitLabProvider {
+    (modelId: string): LanguageModelV2;
+    readonly specificationVersion: 'v2';
+    languageModel(modelId: string): LanguageModelV2;
+    chat(modelId: string): LanguageModelV2;
+    /**
+     * Create an agentic chat model with tool calling support
+     *
+     * @param modelId - GitLab model identifier. Some IDs automatically map to specific Anthropic models.
+     * @param options - Configuration options for the agentic model
+     * @returns A language model with native tool calling support via Anthropic
+     *
+     * @example
+     * // Automatic model mapping
+     * const model = gitlab.agenticChat('duo-chat-opus-4-5');
+     * // Uses claude-opus-4-5-20251101
+     *
+     * @example
+     * // Explicit model override
+     * const model = gitlab.agenticChat('duo-chat', {
+     *   anthropicModel: 'claude-sonnet-4-5-20250929'
+     * });
+     */
+    agenticChat(modelId: string, options?: GitLabAgenticOptions): GitLabAnthropicLanguageModel;
+    /**
+     * Create a workflow chat model using GitLab Duo Agent Platform.
+     *
+     * Workflow models use a server-side agentic loop where GitLab's DWS drives
+     * the LLM, requests tool executions from the client via WebSocket, and
+     * streams text/status back.
+     *
+     * Requires GitLab Ultimate with Duo Enterprise add-on.
+     *
+     * @param modelId - Workflow model identifier (e.g., 'duo-workflow-sonnet-4-6')
+     * @param options - Workflow-specific configuration
+     * @returns A language model backed by the DWS WebSocket protocol
+     *
+     * @example
+     * const model = gitlab.workflowChat('duo-workflow-sonnet-4-6', {
+     *   mcpTools: [...],
+     *   preapprovedTools: ['read_file', 'write_file'],
+     * });
+     */
+    workflowChat(modelId: string, options?: GitLabWorkflowOptions): GitLabWorkflowLanguageModel;
+    textEmbeddingModel(modelId: string): never;
+    imageModel(modelId: string): never;
+}
+interface GitLabAgenticOptions {
+    /**
+     * Override the provider-specific model (optional).
+     * Must be a valid model for the detected provider.
+     *
+     * For Anthropic models:
+     * - 'claude-opus-4-6'
+     * - 'claude-sonnet-4-6'
+     * - 'claude-opus-4-5-20251101'
+     * - 'claude-sonnet-4-5-20250929'
+     * - 'claude-haiku-4-5-20251001'
+     *
+     * For OpenAI models:
+     * - 'gpt-5.1-2025-11-13'
+     * - 'gpt-5-mini-2025-08-07'
+     * - 'gpt-5-codex'
+     * - 'gpt-5.2-codex'
+     *
+     * @example
+     * // Override with explicit model
+     * const model = gitlab.agenticChat('duo-chat-opus-4-5', {
+     *   providerModel: 'claude-sonnet-4-5-20250929'
+     * });
+     */
+    providerModel?: string;
+    /**
+     * Maximum tokens to generate
+     * @default 8192
+     */
+    maxTokens?: number;
+    /**
+     * Feature flags to pass to the GitLab API
+     */
+    featureFlags?: Record<string, boolean>;
+    /**
+     * Custom headers for AI Gateway requests (per-model override).
+     * These headers are sent to the Anthropic/OpenAI proxy endpoints.
+     * Merged with provider-level aiGatewayHeaders (model-level takes precedence).
+     */
+    aiGatewayHeaders?: Record<string, string>;
+}
+interface GitLabProviderSettings {
+    /**
+     * GitLab instance URL (e.g., 'https://gitlab.com')
+     * Can also be set via GITLAB_INSTANCE_URL environment variable.
+     * @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>;
+    /**
+     * AI Gateway URL for the Anthropic proxy.
+     * Can also be set via GITLAB_AI_GATEWAY_URL environment variable.
+     * @default 'https://cloud.gitlab.com'
+     */
+    aiGatewayUrl?: string;
+    /**
+     * Custom headers to include in AI Gateway requests (Anthropic/OpenAI proxy).
+     * These headers are merged with the default headers from direct_access response.
+     * Default User-Agent: gitlab-ai-provider/{version}
+     */
+    aiGatewayHeaders?: Record<string, string>;
+}
+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;
+
+declare const VERSION: string;
+
+interface GitLabOpenAIConfig {
+    provider: string;
+    instanceUrl: string;
+    getHeaders: () => Record<string, string>;
+    fetch?: typeof fetch;
+    refreshApiKey?: () => Promise<void>;
+    openaiModel?: string;
+    maxTokens?: number;
+    featureFlags?: {
+        DuoAgentPlatformNext: true;
+    } & Record<string, boolean>;
+    aiGatewayUrl?: string;
+    /** Whether to use the Responses API instead of Chat Completions API */
+    useResponsesApi?: boolean;
+    /**
+     * Custom headers for AI Gateway OpenAI proxy requests.
+     * Merged with headers from direct_access token response.
+     */
+    aiGatewayHeaders?: Record<string, string>;
+}
+declare class GitLabOpenAILanguageModel implements LanguageModelV2 {
+    readonly specificationVersion: "v2";
+    readonly modelId: string;
+    readonly supportedUrls: Record<string, RegExp[]>;
+    private readonly config;
+    private readonly directAccessClient;
+    private readonly useResponsesApi;
+    private openaiClient;
+    constructor(modelId: string, config: GitLabOpenAIConfig);
+    get provider(): string;
+    private getOpenAIClient;
+    private isTokenError;
+    /**
+     * Check if an error is a context overflow error (prompt too long)
+     * These should NOT trigger token refresh and should be reported to the user.
+     */
+    private isContextOverflowError;
+    private convertTools;
+    private convertToolChoice;
+    private convertPrompt;
+    private convertFinishReason;
+    /**
+     * Convert tools to Responses API format
+     */
+    private convertToolsForResponses;
+    /**
+     * Convert prompt to Responses API input format
+     */
+    private convertPromptForResponses;
+    /**
+     * Extract system instructions from prompt
+     */
+    private extractSystemInstructions;
+    /**
+     * Convert Responses API status to finish reason
+     * Note: Responses API returns 'completed' even when making tool calls,
+     * so we need to check the content for tool calls separately.
+     */
+    private convertResponsesStatus;
+    doGenerate(options: LanguageModelV2CallOptions): Promise<{
+        content: LanguageModelV2Content[];
+        finishReason: LanguageModelV2FinishReason;
+        usage: LanguageModelV2Usage;
+        warnings: LanguageModelV2CallWarning[];
+    }>;
+    private doGenerateWithChatApi;
+    private doGenerateWithResponsesApi;
+    doStream(options: LanguageModelV2CallOptions): Promise<{
+        stream: ReadableStream<LanguageModelV2StreamPart>;
+        request?: {
+            body?: unknown;
+        };
+        response?: {
+            headers?: Record<string, string>;
+        };
+    }>;
+    private doStreamWithChatApi;
+    private doStreamWithResponsesApi;
+}
+
+type ModelProvider = 'anthropic' | 'openai' | 'workflow';
+type OpenAIApiType = 'chat' | 'responses';
+interface ModelMapping {
+    provider: ModelProvider;
+    model: string;
+    /** For OpenAI models, which API to use: 'chat' for /v1/chat/completions, 'responses' for /v1/responses */
+    openaiApiType?: OpenAIApiType;
+}
+declare const MODEL_MAPPINGS: Record<string, ModelMapping>;
+declare function getModelMapping(modelId: string): ModelMapping | undefined;
+declare function getProviderForModelId(modelId: string): ModelProvider | undefined;
+declare function getValidModelsForProvider(provider: ModelProvider): string[];
+declare function getAnthropicModelForModelId(modelId: string): string | undefined;
+declare function getOpenAIModelForModelId(modelId: string): string | undefined;
+declare function getOpenAIApiType(modelId: string): OpenAIApiType;
+declare function isResponsesApiModel(modelId: string): boolean;
+declare function isWorkflowModel(modelId: string): boolean;
+declare function getWorkflowModelRef(modelId: string): string | undefined;
+declare const MODEL_ID_TO_ANTHROPIC_MODEL: Record<string, string>;
+
+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;
+    /**
+     * Check if this error is a context overflow error (prompt too long).
+     * These errors occur when the conversation exceeds the model's token limit.
+     */
+    isContextOverflowError(): 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, {
+    created_at?: number;
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+}, {
+    created_at?: number;
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: 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;
+    /** @deprecated Use enterpriseUrl instead. Kept for backwards compatibility with older auth.json files. */
+    instanceUrl?: string;
+    /** Instance URL as written by opencode-gitlab-auth plugin (e.g. 'https://gitlab.com') */
+    enterpriseUrl?: string;
+}
+interface OpenCodeAuthApi {
+    type: 'api';
+    key: string;
+}
+type OpenCodeAuth = OpenCodeAuthOAuth | OpenCodeAuthApi;
+/**
+ * Default OAuth client ID for GitLab.com
+ * This is the same client ID used by opencode-gitlab-auth plugin.
+ * The GITLAB_OAUTH_CLIENT_ID env var takes precedence if set.
+ * Note: VS Code extension uses a different client ID ('36f2a70c...') but we use the opencode plugin's ID
+ * to ensure token refresh works correctly with tokens created by the auth plugin.
+ */
+declare const OPENCODE_GITLAB_AUTH_CLIENT_ID = "1d89f9fdb23ee96d4e603201f6861dab6e143c5c3c00469a018a2d94bdc03d4e";
+/**
+ * @deprecated Use OPENCODE_GITLAB_AUTH_CLIENT_ID instead. This is the VS Code extension's client ID
+ * and will cause refresh failures if used with tokens created by opencode-gitlab-auth.
+ */
+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.
+     * Priority: env var > opencode-gitlab-auth default (for GitLab.com).
+     * Note: callers (e.g. exchangeRefreshToken) may pass an explicit clientId
+     * that bypasses this method entirely.
+     */
+    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;
+}
+
+/**
+ * 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 not a git repo / no matching remote
+     * @throws GitLabError if the API call or an unexpected error occurs
+     */
+    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;
+}
+
+/**
+ * Response from /api/v4/ai/third_party_agents/direct_access
+ */
+declare const directAccessTokenSchema: z.ZodObject<{
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    token: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    headers?: Record<string, string>;
+    token?: string;
+}, {
+    headers?: Record<string, string>;
+    token?: string;
+}>;
+type DirectAccessToken = z.infer<typeof directAccessTokenSchema>;
+declare const DEFAULT_AI_GATEWAY_URL = "https://cloud.gitlab.com";
+interface GitLabDirectAccessConfig {
+    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>;
+    /**
+     * Feature flags to pass to the GitLab API
+     */
+    featureFlags?: Record<string, boolean>;
+    /**
+     * AI Gateway URL for the Anthropic proxy.
+     * Can also be set via GITLAB_AI_GATEWAY_URL environment variable.
+     * @default 'https://cloud.gitlab.com'
+     */
+    aiGatewayUrl?: string;
+}
+/**
+ * Client for GitLab's third-party agents direct access API.
+ * This allows routing requests through GitLab's proxy to Anthropic.
+ */
+declare class GitLabDirectAccessClient {
+    private readonly config;
+    private readonly fetchFn;
+    private readonly aiGatewayUrl;
+    private cachedToken;
+    private tokenExpiresAt;
+    constructor(config: GitLabDirectAccessConfig);
+    /**
+     * Get a direct access token for the Anthropic proxy.
+     * Tokens are cached for 25 minutes (they expire after 30 minutes).
+     * @param forceRefresh - If true, ignores the cache and fetches a new token
+     */
+    getDirectAccessToken(forceRefresh?: boolean): Promise<DirectAccessToken>;
+    /**
+     * Get the Anthropic proxy base URL
+     */
+    getAnthropicProxyUrl(): string;
+    /**
+     * Get the OpenAI proxy base URL
+     * Note: The OpenAI SDK expects a base URL like https://api.openai.com/v1
+     * and appends paths like /chat/completions. So we need /v1 at the end.
+     */
+    getOpenAIProxyUrl(): string;
+    /**
+     * Invalidate the cached token
+     */
+    invalidateToken(): void;
+}
+
+/**
+ * WebSocket client for the GitLab Duo Agent Platform (DWS).
+ *
+ * Handles:
+ * - WebSocket connection to `wss://{instance}/api/v4/ai/duo_workflows/ws`
+ * - Sending ClientEvent messages (startRequest, actionResponse, stopWorkflow)
+ * - Receiving WorkflowAction messages (newCheckpoint, runMcpTool, built-in tools)
+ * - Dual heartbeat: ws.ping(45s) + JSON heartbeat(60s) — matching gitlab-lsp
+ * - No reconnection on drop (matches gitlab-lsp behavior)
+ */
+
+interface WorkflowWebSocketOptions {
+    /** GitLab instance URL */
+    instanceUrl: string;
+    /** Model reference for DWS (e.g. 'anthropic/claude-sonnet-4-5-20250929' or 'default') */
+    modelRef: string;
+    /** Auth headers — must include Authorization */
+    headers: Record<string, string>;
+    /** Optional correlation ID */
+    requestId?: string;
+    /** Optional project context */
+    projectId?: string;
+    namespaceId?: string;
+    rootNamespaceId?: string;
+}
+type EventCallback = (event: WorkflowClientEvent) => void;
+declare class GitLabWorkflowClient {
+    private socket;
+    private keepaliveInterval;
+    private heartbeatInterval;
+    private eventCallback;
+    private closed;
+    private lastSendTime;
+    /**
+     * Connect to the DWS WebSocket and start listening for events.
+     *
+     * @param options - Connection parameters
+     * @param onEvent - Callback invoked for each WorkflowClientEvent
+     * @returns Promise that resolves when the connection is open
+     */
+    connect(options: WorkflowWebSocketOptions, onEvent: EventCallback): Promise<void>;
+    /**
+     * Send a startRequest to begin the workflow.
+     */
+    sendStartRequest(request: StartRequest): void;
+    /**
+     * Send an actionResponse (tool result) back to DWS.
+     */
+    sendActionResponse(requestID: string, response: string, error?: string | null): void;
+    /**
+     * Stop the workflow gracefully.
+     */
+    stop(): void;
+    /**
+     * Close the WebSocket connection.
+     */
+    close(): void;
+    /**
+     * Check if the WebSocket is currently connected.
+     */
+    get isConnected(): boolean;
+    private validateOptions;
+    private buildWebSocketUrl;
+    private buildWebSocketHeaders;
+    private handleAction;
+    private send;
+    private sendHeartbeatIfNeeded;
+    private emit;
+    /**
+     * Start ws.ping() keepalive (45s interval).
+     * Keeps TCP connection alive through proxies/load balancers.
+     */
+    private startKeepalive;
+    /**
+     * Start application-level heartbeat (60s interval).
+     * Prevents DWS from timing out the workflow.
+     */
+    private startHeartbeat;
+    private cleanedUp;
+    /**
+     * Clean up intervals. Idempotent — safe to call multiple times.
+     */
+    private cleanup;
+}
+
+/**
+ * Token management for the GitLab Duo Agent Platform (DWS).
+ *
+ * Handles two API calls:
+ * 1. POST /api/v4/ai/duo_workflows/direct_access  → GenerateTokenResponse (workflow token)
+ * 2. POST /api/v4/ai/duo_workflows/workflows       → CreateWorkflowResponse (workflow ID)
+ *
+ * Tokens are cached for 25 minutes (they expire after ~30 minutes).
+ * On 401, optionally triggers an API key refresh callback and retries once.
+ * On 403, throws a clear error explaining GitLab Duo Enterprise requirements.
+ */
+
+declare class GitLabWorkflowTokenClient {
+    private readonly config;
+    private readonly fetchFn;
+    /**
+     * Token cache keyed by workflow definition type.
+     *
+     * - CHAT workflows use a shared key (CHAT_SHARED_TOKEN_KEY) so tokens
+     *   are reused across ALL chat sessions (matching gitlab-lsp behavior).
+     * - SOFTWARE_DEVELOPMENT workflows would use per-workflow-id keys,
+     *   but since we fetch tokens before creating workflows, we key by type.
+     */
+    private tokenCache;
+    constructor(config: GitLabWorkflowClientConfig);
+    /**
+     * Resolve the cache key for a given workflow definition.
+     * CHAT workflows share a single token per namespace; other types get per-type keys.
+     */
+    private getCacheKey;
+    /**
+     * Get a DWS token, using cached value if still valid.
+     *
+     * Token caching strategy (matches gitlab-lsp):
+     * - CHAT workflows: shared token across all sessions
+     * - Other workflows: per-type token
+     *
+     * @param workflowDefinition - Workflow type (default: 'chat')
+     * @param rootNamespaceId - Optional root namespace for scoping
+     * @param forceRefresh - Bypass cache
+     */
+    getToken(workflowDefinition?: string, rootNamespaceId?: string, forceRefresh?: boolean): Promise<GenerateTokenResponse>;
+    /**
+     * Create a new workflow on the GitLab instance.
+     *
+     * @param goal - The user's message / goal for this workflow
+     * @param options - Additional workflow creation options
+     * @returns The created workflow's ID
+     */
+    createWorkflow(goal: string, options?: {
+        projectId?: string;
+        namespaceId?: string;
+        workflowDefinition?: string;
+        agentPrivileges?: number[];
+        environment?: string;
+        allowAgentToRequestUser?: boolean;
+    }): Promise<string>;
+    /**
+     * Invalidate cached tokens.
+     *
+     * @param workflowDefinition - If provided, only invalidate for this type.
+     *                             If omitted, clears ALL cached tokens.
+     */
+    invalidateToken(workflowDefinition?: string, rootNamespaceId?: string): void;
+}
+
+export { AGENT_PRIVILEGES, type ActionResponsePayload, type AdditionalContext, type AiChatAvailableModels, type AiModel, BUNDLED_CLIENT_ID, CLIENT_VERSION, type ClientEvent, DEFAULT_AGENT_PRIVILEGES, DEFAULT_AI_GATEWAY_URL, DEFAULT_CLIENT_CAPABILITIES, DEFAULT_WORKFLOW_DEFINITION, type DirectAccessToken, type DiscoveredModels, GITLAB_COM_URL, type GenerateTokenResponse, type GitLabAgenticOptions, type GitLabAnthropicConfig, GitLabAnthropicLanguageModel, GitLabDirectAccessClient, type GitLabDirectAccessConfig, GitLabError, type GitLabErrorOptions, GitLabModelCache, GitLabModelDiscovery, GitLabOAuthManager, type GitLabOAuthTokenResponse, type GitLabOAuthTokens, type GitLabOpenAIConfig, GitLabOpenAILanguageModel, type GitLabProject, GitLabProjectCache, GitLabProjectDetector, type GitLabProjectDetectorConfig, type GitLabProvider, type GitLabProviderSettings, GitLabWorkflowClient, type GitLabWorkflowClientConfig, GitLabWorkflowLanguageModel, type GitLabWorkflowLanguageModelConfig, type GitLabWorkflowOptions, GitLabWorkflowTokenClient, MODEL_ID_TO_ANTHROPIC_MODEL, MODEL_MAPPINGS, type McpToolDefinition, type ModelCacheEntry, type ModelDiscoveryConfig, type ModelMapping, type ModelProvider, type NewCheckpoint, OAUTH_SCOPES, OPENCODE_GITLAB_AUTH_CLIENT_ID, type OpenAIApiType, type OpenCodeAuth, type OpenCodeAuthApi, type OpenCodeAuthOAuth, type RunMcpTool, type StartRequest, TOKEN_EXPIRY_SKEW_MS, VERSION, WORKFLOW_ENVIRONMENT, WS_HEARTBEAT_INTERVAL_MS, WS_KEEPALIVE_PING_INTERVAL_MS, type WorkflowAction, type WorkflowClientEvent, type WorkflowStatus, type WorkflowToolExecutor, WorkflowType, type WorkflowWebSocketOptions, createGitLab, getAnthropicModelForModelId, getModelMapping, getOpenAIApiType, getOpenAIModelForModelId, getProviderForModelId, getValidModelsForProvider, getWorkflowModelRef, gitlab, isResponsesApiModel, isWorkflowModel };