gitlab-ai-provider 5.0.0

package/dist/index.d.ts

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