@linxiraos/pi-ai 1.0.0

package/dist/types/providers/gitlab-duo-workflow.d.ts

@@ -0,0 +1,254 @@
+import { type GitLabDuoWorkflowNamespaceSelection } from "@linxiraos/pi-catalog/discovery/gitlab-duo-workflow";
+import type { AssistantMessage, Context, FetchImpl, Model, ProviderSessionState, StreamFunction, StreamOptions, Tool, ToolChoice, ToolResultMessage } from "../types.js";
+import { AssistantMessageEventStream } from "../utils/event-stream.js";
+export declare const GITLAB_DUO_WORKFLOW_PROVIDER_ID = "gitlab-duo-agent";
+export declare const GITLAB_DUO_WORKFLOW_API = "gitlab-duo-agent";
+export declare const GITLAB_DUO_WORKFLOW_DEFINITION = "ambient";
+export type GitLabDuoWorkflowDefinition = "ambient" | (string & {});
+export declare const GITLAB_DUO_WORKFLOW_CLIENT_CAPABILITIES: readonly ["incremental_streaming", "read_file_chunked", "shell_command", "command_timeout", "tool_call_approval"];
+export interface GitLabMcpToolArgs {
+    name?: string;
+    tool_name?: string;
+    toolName?: string;
+    providerIdentifier?: string;
+    provider_identifier?: string;
+    toolCallId?: string;
+    tool_call_id?: string;
+    args?: Record<string, unknown> | string;
+    arguments?: Record<string, unknown> | string;
+}
+export interface GitLabPlainTextResponse {
+    response?: string;
+    error?: string;
+}
+export type PlainTextResponse = GitLabPlainTextResponse;
+export interface GitLabDuoWorkflowOptions extends StreamOptions {
+    rootNamespaceId?: string;
+    namespaceId?: string;
+    projectId?: string;
+    projectPath?: string;
+    workflowDefinition?: GitLabDuoWorkflowDefinition;
+    workflowId?: string;
+    workflowToken?: string;
+    cwd?: string;
+    webSocketFactory?: GitLabDuoWorkflowWebSocketFactory;
+    /** Idle WebSocket deadline (ms) before aborting and resuming; defaults to {@link GITLAB_DUO_WORKFLOW_IDLE_TIMEOUT_MS}. */
+    idleTimeoutMs?: number;
+    /**
+     * Tool-choice override forwarded from the stream layer. Only `"none"` is
+     * acted on: a side-request (e.g. handoff) keeps tool definitions in the cache
+     * prefix but disables tool use, so the provider must not advertise them to Duo.
+     */
+    toolChoice?: ToolChoice;
+}
+export interface GitLabDuoWorkflowWebSocketLike {
+    readyState?: number;
+    binaryType?: string;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+export interface GitLabDuoWorkflowWebSocketFactoryOptions {
+    headers: Record<string, string>;
+    protocols?: string[];
+}
+export type GitLabDuoWorkflowWebSocketFactory = (url: string, options: GitLabDuoWorkflowWebSocketFactoryOptions) => GitLabDuoWorkflowWebSocketLike;
+export interface GitLabDirectAccessResponse {
+    token?: string;
+    access_token?: string;
+    jwt?: string;
+    workflow_token?: string;
+    duo_workflow_access_token?: string;
+    duo_workflow_service?: {
+        token?: string;
+        base_url?: string;
+        headers?: Record<string, string>;
+    };
+    gitlab_rails?: {
+        token?: string;
+    };
+    [key: string]: unknown;
+}
+interface GitLabDuoWorkflowCreateBodyOptions {
+    projectId?: string;
+    goal?: string;
+    workflowDefinition?: GitLabDuoWorkflowDefinition;
+}
+interface GitLabDuoWorkflowStartMetadataOptions {
+    projectId?: string;
+    projectPath?: string;
+    namespaceId?: string;
+    rootNamespaceId?: string;
+    workflowDefinition?: GitLabDuoWorkflowDefinition;
+    inlineFlow?: boolean;
+}
+export interface GitLabMcpToolDefinition {
+    name: string;
+    originalToolName: string;
+    serverName: string;
+    description: string;
+    inputSchema: string;
+    isApproved: boolean;
+}
+export interface GitLabDuoWorkflowAdditionalContextItem {
+    id: string;
+    category: "agent_user_environment" | "user_rule";
+    content: string;
+    metadata: {
+        title: string;
+        enabled: boolean;
+        subType: "snippet";
+        icon: string;
+        secondaryText: string;
+        subTypeLabel: string;
+    };
+}
+export interface GitLabDuoWorkflowStartRequest {
+    workflowID: string;
+    clientVersion: "1.0";
+    workflowDefinition: GitLabDuoWorkflowDefinition;
+    goal: string;
+    workflowMetadata: string;
+    additional_context: readonly GitLabDuoWorkflowAdditionalContextItem[];
+    approval?: {
+        approval?: Record<string, never>;
+        rejection?: {
+            message?: string;
+        };
+    };
+    clientCapabilities: readonly (typeof GITLAB_DUO_WORKFLOW_CLIENT_CAPABILITIES)[number][];
+    mcpTools: GitLabMcpToolDefinition[];
+    preapproved_tools: string[];
+    flowConfigSchemaVersion?: "v1";
+    flowConfigId?: string;
+    flowVersion?: string;
+    flowConfig?: GitLabDuoWorkflowInlineFlowConfig;
+}
+export interface GitLabDuoWorkflowInlineFlowComponent {
+    name: string;
+    type: "AgentComponent";
+    prompt_id: string;
+    toolset: string[];
+    inputs: {
+        from: string;
+        as: string;
+    }[];
+    ui_log_events: string[];
+}
+export interface GitLabDuoWorkflowInlineFlowPrompt {
+    name: string;
+    prompt_id: string;
+    unit_primitives: string[];
+    prompt_template: {
+        system: string;
+        user: string;
+        placeholder: string;
+    };
+}
+export interface GitLabDuoWorkflowInlineFlowConfig {
+    version: "v1";
+    environment: "ambient";
+    flow: {
+        entry_point: string;
+    };
+    components: GitLabDuoWorkflowInlineFlowComponent[];
+    routers: {
+        from: string;
+        to: string;
+    }[];
+    prompts: GitLabDuoWorkflowInlineFlowPrompt[];
+}
+export interface GitLabDuoWorkflowActionResponse {
+    actionResponse: {
+        requestID: string;
+        plainTextResponse?: GitLabPlainTextResponse;
+    };
+}
+interface GitLabDuoWorkflowActionDescriptor {
+    requestID: string;
+    name: string;
+    args: unknown;
+}
+export interface GitLabDuoWorkflowActiveSession {
+    workflowId: string;
+    startPayload: GitLabDuoWorkflowStartRequest;
+    ws: GitLabDuoWorkflowWebSocketLike;
+    stop?: () => void;
+    pendingActions?: GitLabDuoWorkflowActionDescriptor[];
+    checkpointAgentContentByKey?: Record<string, string>;
+    checkpointAgentContentSignatures?: Record<string, true>;
+    paused?: boolean;
+    pauseBuffer?: unknown[];
+    lastToolBoundaryContentLength?: number;
+}
+export interface GitLabDuoWorkflowProviderSessionState extends ProviderSessionState {
+    active?: GitLabDuoWorkflowActiveSession;
+}
+export interface GitLabDuoWorkflowStreamState {
+    stream: AssistantMessageEventStream;
+    output: AssistantMessage;
+    activeTextIndex?: number;
+    activeThinkingIndex?: number;
+    activeCheckpointMessageKey?: string;
+    started: boolean;
+    checkpointAgentContentByKey?: Record<string, string>;
+    checkpointAgentContentSignatures?: Record<string, true>;
+    pauseRequested?: boolean;
+    stepLimitRequested?: boolean;
+    retryableErrorRequested?: boolean;
+    lastCheckpointContentLength?: number;
+    stalledRequested?: boolean;
+    providerSessionState?: GitLabDuoWorkflowProviderSessionState;
+    lastApprovalStatus?: string;
+    goalOverflowMessage?: string;
+}
+type GitLabDuoWorkflowSocketResult = "closed" | "terminal" | "approval" | "action" | "pause" | "timeout" | "step_limit" | "retryable_error" | "stalled";
+export interface GitLabAvailableModel {
+    name?: string | null;
+    ref?: string | null;
+}
+export interface GitLabAvailableModelsPayload {
+    pinnedModel?: GitLabAvailableModel | null;
+    selectedModel?: GitLabAvailableModel | null;
+    defaultModel?: GitLabAvailableModel | null;
+    selectableModels?: GitLabAvailableModel[] | null;
+}
+export declare const streamGitLabDuoWorkflow: StreamFunction<"gitlab-duo-agent">;
+export declare function buildGitLabDuoWorkflowDirectAccessBody(rootNamespaceId: string, projectId?: string, workflowDefinition?: GitLabDuoWorkflowDefinition): Record<string, string>;
+export declare function buildGitLabDuoWorkflowCreateBody(namespaceId?: string, options?: GitLabDuoWorkflowCreateBodyOptions): Record<string, string | boolean | string[] | number[]>;
+export declare function buildGitLabDuoWorkflowStopBody(): Record<string, string>;
+export declare function buildGitLabDuoWorkflowWebSocketUrl(baseUrl: string, options?: {
+    projectId?: string;
+    namespaceId?: string;
+    rootNamespaceId?: string;
+    selectedModelIdentifier?: string;
+    workflowDefinition?: GitLabDuoWorkflowDefinition;
+    serviceEndpoint?: boolean;
+}): string;
+export declare function buildGitLabDuoWorkflowWebSocketHeaders(options: {
+    token: string;
+    baseUrl?: string;
+    projectId?: string;
+    namespaceId?: string;
+    rootNamespaceId?: string;
+    extraHeaders?: Record<string, string>;
+}): Record<string, string>;
+export declare function buildGitLabDuoWorkflowStartRequest(workflowId: string, model: Model<"gitlab-duo-agent">, context: Context, tools?: Tool[] | undefined, availableModels?: GitLabAvailableModelsPayload | null, metadataOptions?: GitLabDuoWorkflowStartMetadataOptions): GitLabDuoWorkflowStartRequest;
+export declare function buildGitLabDuoWorkflowInlineFlowConfig(systemPrompt: string): GitLabDuoWorkflowInlineFlowConfig;
+export declare function buildGitLabDuoWorkflowClientAdditionalContext(): GitLabDuoWorkflowAdditionalContextItem[];
+export declare function buildGitLabDuoWorkflowMcpTools(tools: Tool[] | undefined): GitLabMcpToolDefinition[];
+export declare function selectGitLabDuoWorkflowModelRef(selectedModel: string, availableModels?: GitLabAvailableModelsPayload | null): string;
+export declare function buildGitLabPlainTextFromToolResult(toolResult: ToolResultMessage): GitLabPlainTextResponse;
+export declare function gitLabDuoWorkflowErrorText(error: unknown): string;
+export declare function buildGitLabDuoWorkflowSettingsBody(): Record<string, unknown>;
+export declare function runGitLabDuoWorkflowSocket(ws: GitLabDuoWorkflowWebSocketLike, startPayload: GitLabDuoWorkflowStartRequest, state: GitLabDuoWorkflowStreamState, options: GitLabDuoWorkflowOptions, resumeResponse?: GitLabDuoWorkflowActionResponse | readonly GitLabDuoWorkflowActionResponse[], replayMessages?: readonly unknown[]): Promise<GitLabDuoWorkflowSocketResult>;
+export declare function buildGitLabDuoWorkflowApprovalStartRequest(startPayload: GitLabDuoWorkflowStartRequest): GitLabDuoWorkflowStartRequest;
+export declare function describeGitLabDuoWorkflowSocketEvent(event: unknown): string;
+export declare function traceGitLabDuoWorkflow(event: string, data?: Record<string, unknown>): void;
+export declare function extractGitLabWorkflowToken(payload: GitLabDirectAccessResponse): string | undefined;
+export declare function resolveGitLabDuoWorkflowNamespaceSelection(model: Model<"gitlab-duo-agent">, options: GitLabDuoWorkflowOptions, apiKey: string, baseUrl: string, fetchImpl: FetchImpl): Promise<GitLabDuoWorkflowNamespaceSelection>;
+export declare function resolveGitLabDuoWorkflowRootNamespaceId(model: Model<"gitlab-duo-agent">, options: GitLabDuoWorkflowOptions, apiKey: string, baseUrl: string, fetchImpl: FetchImpl): Promise<string>;
+export {};

package/dist/types/providers/gitlab-duo.d.ts

@@ -0,0 +1,27 @@
+import type { Api, Context, Model, SimpleStreamOptions } from "../types.js";
+import { AssistantMessageEventStream } from "../utils/event-stream.js";
+type GitLabProvider = "anthropic" | "openai";
+type GitLabOpenAIApiType = "chat" | "responses";
+export type GitLabModelMapping = {
+    provider: GitLabProvider;
+    model: string;
+    openaiApiType?: GitLabOpenAIApiType;
+    name: string;
+    reasoning: boolean;
+    input: ("text" | "image")[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+};
+export declare const MODEL_MAPPINGS: Record<string, GitLabModelMapping>;
+export declare function getModelMapping(modelId: string): GitLabModelMapping | undefined;
+export declare function getGitLabDuoModels(): Model<Api>[];
+export declare function clearGitLabDuoDirectAccessCache(): void;
+export declare function isGitLabDuoModel(model: Model<Api>): boolean;
+export declare function streamGitLabDuo(model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+export {};

package/dist/types/providers/google-auth.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Application Default Credentials (ADC) resolution for Vertex AI.
+ *
+ * Replaces `google-auth-library` with a direct WebCrypto + REST implementation.
+ * Sources, in priority order:
+ *   1. `GOOGLE_APPLICATION_CREDENTIALS` env → file with `type: "service_account"` (RS256 JWT exchange)
+ *     or `type: "authorized_user"` (refresh-token exchange).
+ *   2. `~/.config/gcloud/application_default_credentials.json` (user ADC, same authorized_user flow).
+ *   3. GCE / Cloud Run metadata server (`metadata.google.internal`).
+ *
+ * Tokens are cached per source key and refreshed `GOOGLE_VERTEX_REFRESH_SKEW_MS` before expiry
+ * (default 60s). Concurrent callers waiting on a refresh share the same in-flight promise.
+ */
+import type { FetchImpl } from "../types.js";
+/**
+ * Returns a Bearer access token suitable for the `Authorization` header on Vertex AI calls.
+ * The token is cached in module scope and refreshed `GOOGLE_VERTEX_REFRESH_SKEW_MS` ms before it expires.
+ */
+export declare function getVertexAccessToken(options?: {
+    signal?: AbortSignal;
+    fetch?: FetchImpl;
+}): Promise<string>;
+/** Test seam: clears every cached token. */
+export declare function __resetVertexTokenCache(): void;

package/dist/types/providers/google-gemini-cli.d.ts

@@ -0,0 +1,120 @@
+import type { Context, Model, ProviderSessionState, StreamFunction, StreamOptions } from "../types.js";
+import type { Content, FunctionCallingConfigMode, ThinkingConfig } from "./google-shared.js";
+import { type GoogleThinkingLevel } from "./google-shared.js";
+/**
+ * Thinking level for Gemini 3 models. Re-exported from `google-shared` so existing
+ * `import { GoogleThinkingLevel } from "./google-gemini-cli.js"` callers keep working.
+ */
+export type { GoogleThinkingLevel };
+export interface GoogleGeminiCliOptions extends StreamOptions {
+    /**
+     * Tool selection mode. String forms map directly to Gemini
+     * `FunctionCallingConfigMode`. The object form forces a single named tool —
+     * `mode: "ANY"` is wire-required when `allowedFunctionNames` is set.
+     */
+    toolChoice?: "auto" | "none" | "any" | {
+        mode: "ANY";
+        allowedFunctionNames: [string, ...string[]];
+    };
+    /**
+     * Thinking/reasoning configuration.
+     * - Gemini 2.x models: use `budgetTokens` to set the thinking budget
+     * - Gemini 3 models (gemini-3-pro-*, gemini-3-flash-*): use `level` instead
+     *
+     * When using `streamSimple`, this is handled automatically based on the model.
+     */
+    thinking?: {
+        enabled: boolean;
+        /** Thinking budget in tokens. Use for Gemini 2.x models. */
+        budgetTokens?: number;
+        /** Thinking level. Use for Gemini 3 models (LOW/HIGH for Pro, MINIMAL/LOW/MEDIUM/HIGH for Flash). */
+        level?: GoogleThinkingLevel;
+        /**
+         * Explicit wire suppression when `enabled` is false. Cloud Code Assist
+         * re-applies the per-id baked server default when thinkingConfig is
+         * omitted, so models with `thinking.suppressWhenOff` must send
+         * `includeThoughts: false` plus a MINIMAL level (or zero budget).
+         */
+        suppress?: {
+            level: GoogleThinkingLevel;
+        } | {
+            budget: number;
+        };
+    };
+    /** Request that Cloud Code Assist omit human-readable thought summaries while still allowing internal reasoning. */
+    hideThinkingSummary?: boolean;
+    /**
+     * Upstream wire model id override for collapsed effort-tier variants.
+     * Serialized as `requestModelId ?? model.requestModelId ?? model.id`.
+     */
+    requestModelId?: string;
+    projectId?: string;
+    /** Antigravity endpoint routing mode: "auto" (default with failover), "production", "sandbox". */
+    antigravityEndpointMode?: "auto" | "production" | "sandbox";
+    providerSessionState?: Map<string, ProviderSessionState>;
+}
+export interface AntigravityProviderSessionState extends ProviderSessionState {
+    lastGoodEndpoint?: string;
+    /**
+     * Per-conversation request-envelope identity that mirrors the real
+     * Antigravity client. `sessionId` is the signed-decimal session id;
+     * `agentId`/`trajectoryId` are UUIDs; `stepIndex` is the monotonic step
+     * counter; `lastExecutionId` is the prior response id echoed as
+     * `labels.last_execution_id`.
+     */
+    agentId?: string;
+    trajectoryId?: string;
+    sessionId?: string;
+    stepIndex?: number;
+    lastExecutionId?: string;
+}
+export declare function getAntigravityProviderSessionState(providerSessionState: Map<string, ProviderSessionState> | undefined): AntigravityProviderSessionState | undefined;
+export { ANTIGRAVITY_SYSTEM_INSTRUCTION, getAntigravityUserAgent, getGeminiCliHeaders, getGeminiCliUserAgent, } from "@linxiraos/pi-catalog/wire/gemini-headers";
+interface ParsedGeminiCliCredentials {
+    accessToken: string;
+    projectId: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    email?: string;
+}
+export declare function parseGeminiCliCredentials(apiKeyRaw: string): ParsedGeminiCliCredentials;
+export declare function shouldRefreshGeminiCliCredentials(expiresAt: number | undefined, isAntigravity: boolean, nowMs?: number): boolean;
+interface CloudCodeAssistRequest {
+    project: string;
+    model: string;
+    request: {
+        contents: Content[];
+        sessionId?: string;
+        systemInstruction?: {
+            role?: string;
+            parts: {
+                text: string;
+            }[];
+        };
+        generationConfig?: {
+            maxOutputTokens?: number;
+            temperature?: number;
+            topP?: number;
+            topK?: number;
+            minP?: number;
+            presencePenalty?: number;
+            repetitionPenalty?: number;
+            thinkingConfig?: ThinkingConfig;
+        };
+        tools?: {
+            functionDeclarations: Record<string, unknown>[];
+        }[] | undefined;
+        toolConfig?: {
+            functionCallingConfig: {
+                mode: FunctionCallingConfigMode;
+                allowedFunctionNames?: string[];
+            };
+        };
+        labels?: Record<string, string>;
+    };
+    requestType?: string;
+    userAgent?: string;
+    requestId?: string;
+}
+export declare const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli">;
+export declare function buildRequest(model: Model<"google-gemini-cli">, context: Context, projectId: string, options?: GoogleGeminiCliOptions, isAntigravity?: boolean): CloudCodeAssistRequest;

package/dist/types/providers/google-shared.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Shared utilities for Google Generative AI and Google Cloud Code Assist providers.
+ */
+import type { AssistantMessage, Context, FetchImpl, Model, ServiceTier, StopReason, StreamOptions, TextContent, ThinkingContent, Tool, ToolCall } from "../types.js";
+import { AssistantMessageEventStream } from "../utils/event-stream.js";
+import { normalizeSchemaForGoogle } from "../utils/schema/index.js";
+import type { Content, FinishReason, FunctionCallingConfigMode, GenerateContentParameters, GenerateContentResponse, Part } from "./google-types.js";
+export type { Content, FunctionCallingConfigMode, GenerateContentParameters, GenerateContentResponse, ThinkingConfig, } from "./google-types.js";
+export { normalizeSchemaForGoogle };
+type GoogleApiType = "google-generative-ai" | "google-gemini-cli" | "google-vertex";
+/**
+ * Thinking level for Gemini 3 models. Mirrors Google's `ThinkingLevel` enum values.
+ * Defined here (not in any specific provider) so all Google providers can reference it
+ * without inducing a circular dependency.
+ */
+export type GoogleThinkingLevel = "THINKING_LEVEL_UNSPECIFIED" | "MINIMAL" | "LOW" | "MEDIUM" | "HIGH";
+/**
+ * Sampling/thinking options shared by `streamGoogle` and `streamGoogleVertex`.
+ * `google-gemini-cli` uses a different transport and request shape — do not extend this for it.
+ */
+export interface GoogleSharedStreamOptions extends StreamOptions {
+    /**
+     * Tool selection mode. String forms map directly to Gemini
+     * `FunctionCallingConfigMode`. The object form forces a single named tool
+     * — `mode: "ANY"` is wire-required when `allowedFunctionNames` is set.
+     */
+    toolChoice?: "auto" | "none" | "any" | {
+        mode: "ANY";
+        allowedFunctionNames: [string, ...string[]];
+    };
+    thinking?: {
+        enabled: boolean;
+        budgetTokens?: number;
+        level?: GoogleThinkingLevel;
+    };
+    /** Request that Google omit human-readable thought summaries while still allowing internal reasoning. */
+    hideThinkingSummary?: boolean;
+    /** Gemini/Vertex serving tier (`flex`/`priority`); other values are omitted. */
+    serviceTier?: ServiceTier;
+    /**
+     * Caller-owned Google context-cache resource name for GenerateContent.
+     * Passed through opaquely as the wire `cachedContent` field on
+     * `google-generative-ai` and `google-vertex` only. OMP does not create,
+     * refresh, validate model/project/location compatibility, or delete the
+     * resource — callers own that lifecycle.
+     *
+     * @see https://ai.google.dev/api/generate-content
+     * @see `@google/genai` `GenerateContentConfig.cachedContent`
+     */
+    cachedContent?: string;
+}
+/**
+ * Determines whether a streamed Gemini `Part` should be treated as "thinking".
+ *
+ * Protocol note (Gemini / Vertex AI thought signatures):
+ * - `thought: true` is the definitive marker for thinking content (thought summaries).
+ * - `thoughtSignature` is an encrypted representation of the model's internal thought process
+ *   used to preserve reasoning context across multi-turn interactions.
+ * - `thoughtSignature` can appear on ANY part type (text, functionCall, etc.) - it does NOT
+ *   indicate the part itself is thinking content.
+ * - For non-functionCall responses, the signature appears on the last part for context replay.
+ * - When persisting/replaying model outputs, signature-bearing parts must be preserved as-is;
+ *   do not merge/move signatures across parts.
+ *
+ * See: https://ai.google.dev/gemini-api/docs/thought-signatures
+ */
+export declare function isThinkingPart(part: Pick<Part, "thought" | "thoughtSignature">): boolean;
+/**
+ * Retain thought signatures during streaming.
+ *
+ * Some backends only send `thoughtSignature` on the first delta for a given part/block; later deltas may omit it.
+ * This helper preserves the last non-empty signature for the current block.
+ *
+ * Note: this does NOT merge or move signatures across distinct response parts. It only prevents
+ * a signature from being overwritten with `undefined` within the same streamed block.
+ */
+export declare function retainThoughtSignature(existing: string | undefined, incoming: string | undefined): string | undefined;
+/**
+ * Convert internal messages to Gemini Content[] format.
+ */
+export declare function convertMessages<T extends GoogleApiType>(model: Model<T>, context: Context): Content[];
+/**
+ * Convert tools to Gemini function declarations format.
+ *
+ * We prefer `parametersJsonSchema` (full JSON Schema: anyOf/oneOf/const/etc.).
+ *
+ * Claude models via Cloud Code Assist require the legacy `parameters` field; the API
+ * translates it into Anthropic's `input_schema`. When using that path, we sanitize the
+ * schema to remove Google-unsupported JSON Schema keywords.
+ */
+export declare function convertTools(tools: Tool[], model: Model<"google-generative-ai" | "google-gemini-cli" | "google-vertex">): {
+    functionDeclarations: Record<string, unknown>[];
+}[] | undefined;
+/**
+ * Map tool choice string to Gemini FunctionCallingConfigMode.
+ */
+export declare function mapToolChoice(choice: string): FunctionCallingConfigMode;
+/**
+ * Map Gemini FinishReason to our StopReason.
+ */
+export declare function mapStopReason(reason: FinishReason): StopReason;
+/**
+ * Map string finish reason to our StopReason (for raw API responses).
+ */
+export declare function mapStopReasonString(reason: string): StopReason;
+/**
+ * Bounded retries for the well-known Gemini "empty response" failure: a benign
+ * `finishReason: STOP` carrying only an empty/whitespace text part and no tool call.
+ * Shared by the public/Vertex `streamGoogleGenAI` path and the Cloud Code Assist
+ * (`google-gemini-cli`/`google-antigravity`) provider so both apply the same policy.
+ */
+export declare const MAX_EMPTY_STREAM_RETRIES = 2;
+export declare const EMPTY_STREAM_BASE_DELAY_MS = 500;
+/**
+ * Whether a completed Google assistant message carries content worth delivering.
+ *
+ * A tool call or any non-whitespace text counts as meaningful. An empty/whitespace-only
+ * text part — or thinking that never produced an answer — is the "empty response" failure:
+ * delivered as-is the agent loop has nothing to act on and silently halts, so the request
+ * must be retried instead of surfaced.
+ */
+export declare function hasMeaningfulGoogleContent(output: AssistantMessage): boolean;
+export declare function nextToolCallId(name: string): string;
+/**
+ * Push the appropriate `text_end` / `thinking_end` event for the given block.
+ * Shared between the SDK-backed stream consumer and the gemini-cli SSE consumer so
+ * the end-of-block event shape stays in lockstep.
+ */
+export declare function pushBlockEndEvent(block: TextContent | ThinkingContent, contentIndex: number, output: AssistantMessage, stream: AssistantMessageEventStream): void;
+/**
+ * Push the three lifecycle events (`toolcall_start` / `toolcall_delta` / `toolcall_end`) for a
+ * fully-assembled `ToolCall`. Caller is responsible for appending the toolCall to `output.content`
+ * before invoking — this helper does not mutate `output.content`.
+ */
+export declare function pushToolCallEvents(toolCall: ToolCall, contentIndex: number, output: AssistantMessage, stream: AssistantMessageEventStream): void;
+/**
+ * Append a new text- or thinking-block to `output.content` and push the matching
+ * `text_start` / `thinking_start` event. `onBeforeStartEvent` lets the SSE consumer
+ * inject its `ensureStarted()` first-token side effect into the canonical event order.
+ */
+export declare function startTextOrThinkingBlock(isThinking: true, output: AssistantMessage, stream: AssistantMessageEventStream, onBeforeStartEvent?: () => void): ThinkingContent;
+export declare function startTextOrThinkingBlock(isThinking: false, output: AssistantMessage, stream: AssistantMessageEventStream, onBeforeStartEvent?: () => void): TextContent;
+export declare function startTextOrThinkingBlock(isThinking: boolean, output: AssistantMessage, stream: AssistantMessageEventStream, onBeforeStartEvent?: () => void): TextContent | ThinkingContent;
+/**
+ * Drives the chunked `generateContentStream` iterator into an `AssistantMessage` and
+ * the corresponding `AssistantMessageEventStream`. Shared between `streamGoogle` and
+ * `streamGoogleVertex` — every observable event order and stop-reason rule is preserved.
+ *
+ * The caller still owns: `output` construction, timing fields (`duration`/`ttft`),
+ * `rawRequestDump`, the `client.models.generateContentStream(params)` call itself,
+ * pushing `start`/`done`/`error` events, and the surrounding try/catch that translates
+ * thrown errors into `output.stopReason`/`errorMessage`.
+ *
+ * This helper handles: the chunk loop, currentBlock flush transitions, usage metadata
+ * decoding (`calculateCost` included), tool-call id collision avoidance, finish-reason
+ * mapping, and the abort/stop-reason post-checks that re-throw to bubble into the
+ * caller's catch.
+ */
+export declare function consumeGoogleStream<T extends GoogleApiType>(args: {
+    googleStream: AsyncIterable<GenerateContentResponse>;
+    output: AssistantMessage;
+    stream: AssistantMessageEventStream;
+    model: Model<T>;
+    options: {
+        signal?: AbortSignal;
+    } | undefined;
+    /** Vertex preserves `textSignature` on streamed text deltas; google-generative-ai does not. */
+    retainTextSignature?: boolean;
+    onFirstToken?: () => void;
+}): Promise<void>;
+/**
+ * Build the `GenerateContentParameters` payload for the public Gemini API and Vertex AI.
+ * Both surfaces accept the same `GenerateContentConfig` shape — every numeric/string knob,
+ * tool-config, thinking-config, and system-instruction conversion is identical.
+ *
+ * `google-gemini-cli` is NOT routed through here: its `CloudCodeAssistRequest` body has a
+ * distinct top-level shape (project/request/requestType) and a different thinking-config
+ * placement on `generationConfig`.
+ */
+export declare function buildGoogleGenerateContentParams<T extends "google-generative-ai" | "google-vertex">(model: Model<T>, context: Context, options: GoogleSharedStreamOptions): GenerateContentParameters;
+/**
+ * Drive the `streamGoogle` / `streamGoogleVertex` event flow: build the assistant message,
+ * push start/done/error events, run `consumeGoogleStream`, and translate thrown errors into
+ * the canonical `error` event shape.
+ *
+ * Caller-supplied `prepare()` runs inside the try-block so any failure (missing project,
+ * bad auth, etc.) is funneled through the same error path as a streaming failure.
+ */
+export interface GoogleGenAIRequestPlan {
+    params: GenerateContentParameters;
+    url: string;
+    headers: Record<string, string>;
+    fetch?: FetchImpl;
+    /** Optional URL retried once when {@link url} returns 404 (regional Vertex endpoint missing a global-only model). */
+    fallbackUrl?: string;
+}
+export declare function streamGoogleGenAI<T extends "google-generative-ai" | "google-vertex">(args: {
+    model: Model<T>;
+    options: GoogleSharedStreamOptions | undefined;
+    api: T;
+    retainTextSignature?: boolean;
+    prepare: () => GoogleGenAIRequestPlan | Promise<GoogleGenAIRequestPlan>;
+}): AssistantMessageEventStream;