@genesislcap/foundation-ai 14.407.0-workspaces.4 → 14.408.0

package/dist/foundation-ai.d.ts

@@ -9,7 +9,7 @@ export declare const AI_FEATURE_FLAG = "ai";
  *
  * @beta
  */
-export declare type AIConfig = ServerAIConfig | ChromeAIConfig;
+export declare type AIConfig = ServerAIConfig | ChromeAIConfig | GeminiAIConfig;
 
 /**
  * AI Provider interface for foundation-ai.
@@ -31,6 +31,16 @@ export declare interface AIProvider {
      * Must be called from a user gesture (e.g. click).
      */
     triggerDownload?(): Promise<void>;
+    /**
+     * Multi-turn chat (non-streaming). Returns the assistant's response message.
+     * Providers that support chat (Gemini, OpenAI) implement this.
+     */
+    chat?(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): Promise<ChatMessage>;
+    /**
+     * Multi-turn chat (streaming). Yields chunks as they arrive.
+     * Providers that support streaming implement this.
+     */
+    streamChat?(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): AsyncIterable<ChatStreamChunk>;
 }
 
 /**
@@ -67,7 +77,7 @@ declare interface AIProviderConfig {
  *
  * @beta
  */
-export declare type AIProviderType = 'openai' | 'chrome' | 'none';
+export declare type AIProviderType = 'openai' | 'chrome' | 'gemini' | 'none';
 
 /**
  * AI status for display in the header indicator.
@@ -80,6 +90,190 @@ export declare interface AIStatus {
     chromeAvailability?: ChromeAvailability;
 }
 
+/**
+ * Transport interface for AI providers.
+ * Each provider (OpenAI, Chrome, Anthropic) implements this to handle API-specific details.
+ *
+ * @beta
+ */
+declare interface AITransport {
+    sendStructuredPrompt(options: StructuredPromptOptions): Promise<string>;
+    isAvailable?(): Promise<boolean>;
+}
+
+/**
+ * Configuration for the animations feature.
+ *
+ * @beta
+ */
+export declare interface ChatAnimationsConfig {
+    /**
+     * When true, a multiselect control is shown in the settings panel so the
+     * user can toggle individual animations on or off.
+     */
+    userConfigurable: boolean;
+    /**
+     * Initially enabled animations. When omitted all animations are enabled by
+     * default.
+     */
+    enabled?: string[];
+}
+
+/**
+ * A file attachment included with a user message.
+ *
+ * @beta
+ */
+export declare interface ChatAttachment {
+    name: string;
+    content: string;
+    mimeType: string;
+}
+
+/**
+ * Display and behaviour configuration for the chat assistant.
+ *
+ * For toggle flags (`showToolCalls`, `showThinkingSteps`):
+ * - `true` — default on, user can toggle off
+ * - `false` — default off, user can toggle on
+ * - `null` / `undefined` — completely disabled, no UI control shown
+ *
+ * @beta
+ */
+export declare interface ChatConfig {
+    /** Show tool call details in the chat UI. */
+    showToolCalls?: boolean | null;
+    /** Show model thinking/reasoning steps. */
+    showThinkingSteps?: boolean | null;
+    /** Show a button to download the full chat history as JSON. */
+    allowDebugDownload?: boolean;
+    /** Comma-separated list of accepted file extensions for upload, e.g., ".txt,.md,.csv". If undefined or empty, file uploads are disabled. */
+    acceptedFiles?: string;
+    /**
+     * Seconds to wait before showing the loading spinner. Default: 5.
+     * Set to 0 to show the spinner immediately when a request is in flight.
+     */
+    loadingDelay?: number;
+    /** Animations feature configuration. */
+    animations?: ChatAnimationsConfig;
+    /** Maximum number of tool call iterations per turn. Default: 50. */
+    maxToolIterations?: number;
+}
+
+/**
+ * A user interaction component request.
+ *
+ * @beta
+ */
+export declare interface ChatInteraction {
+    interactionId: string;
+    componentName: string;
+    data: any;
+    /** Set to true once the interaction has been resolved. Used to render a read-only state on re-render. */
+    resolved?: boolean;
+}
+
+/**
+ * A single message in a chat conversation.
+ *
+ * @beta
+ */
+export declare interface ChatMessage {
+    role: ChatRole;
+    content: string;
+    toolCalls?: ChatToolCall[];
+    toolResult?: ChatToolResult;
+    attachments?: ChatAttachment[];
+    interaction?: ChatInteraction;
+    thinking?: boolean;
+}
+
+/**
+ * Options for a chat request.
+ *
+ * @beta
+ */
+export declare interface ChatRequestOptions {
+    systemPrompt?: string;
+    tools?: ChatToolDefinition[];
+    attachments?: ChatAttachment[];
+    signal?: AbortSignal;
+}
+
+/**
+ * Role of a message in a chat conversation.
+ *
+ * @beta
+ */
+export declare type ChatRole = 'user' | 'assistant' | 'system' | 'tool';
+
+/**
+ * A streaming chunk from a chat response.
+ *
+ * @beta
+ */
+export declare interface ChatStreamChunk {
+    delta: string;
+    done: boolean;
+    toolCalls?: ChatToolCall[];
+}
+
+/**
+ * A tool call requested by the assistant.
+ *
+ * @beta
+ */
+export declare interface ChatToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+
+/**
+ * JSON Schema-based tool definition for function calling.
+ *
+ * @beta
+ */
+export declare interface ChatToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+
+/**
+ * Map of tool name to async handler function.
+ *
+ * @beta
+ */
+export declare type ChatToolHandlers = Record<string, (args: Record<string, unknown>, context: {
+    requestInteraction: <T = unknown>(componentName: string, data: any) => Promise<T>;
+}) => Promise<unknown>>;
+
+/**
+ * The result of executing a tool call.
+ *
+ * @beta
+ */
+export declare interface ChatToolResult {
+    toolCallId: string;
+    content: string;
+}
+
+/**
+ * Transport interface for chat-capable AI providers.
+ *
+ * @remarks
+ * Implement alongside `AITransport` for providers that support multi-turn chat
+ * conversations (e.g. Gemini, OpenAI). The `streamChatMessage` method is optional —
+ * providers that don't support streaming may omit it.
+ *
+ * @beta
+ */
+export declare interface ChatTransport {
+    sendChatMessage(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): Promise<ChatMessage>;
+    streamChatMessage?(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): AsyncIterable<ChatStreamChunk>;
+}
+
 /**
  * Chrome built-in AI (Prompt API / Gemini Nano) configuration.
  *
@@ -124,20 +318,41 @@ export declare interface CriteriaClauseResult {
     value: string | number | boolean | null;
 }
 
+/**
+ * A group of criteria clauses combined by a logical operator.
+ *
+ * @beta
+ */
 export declare interface CriteriaGroupResult {
     logic: 'and' | 'or';
     negated?: boolean;
     clauses: CriteriaClauseResult[];
 }
 
+/**
+ * Top-level result returned by criteria interpretation.
+ *
+ * @beta
+ */
 export declare interface CriteriaInterpretationResult {
     groups: CriteriaGroupResult[];
 }
 
+/**
+ * Context passed to criteria interpretation, providing available field metadata.
+ *
+ * @beta
+ */
 export declare interface CriteriaInterpretContext {
     fields?: FieldLike[];
 }
 
+/**
+ * A field descriptor accepted by criteria interpretation utilities.
+ * Can be a plain string name or an object with common field metadata properties.
+ *
+ * @beta
+ */
 export declare type FieldLike = string | {
     name?: string;
     field?: string;
@@ -145,6 +360,94 @@ export declare type FieldLike = string | {
     NAME?: string;
 };
 
+/**
+ * Gemini server-proxy AI configuration (client calls your server; server calls Gemini).
+ *
+ * @remarks
+ * API key stays on the server. URL defaults to /gwf/ai-service/gemini/chat.
+ *
+ * @beta
+ */
+export declare interface GeminiAIConfig extends AIProviderConfig {
+    providerType: 'gemini';
+    model?: string;
+    serverEndpoint?: string;
+    apiKey?: string;
+}
+
+/**
+ * Gemini AI provider. Uses {@link GeminiTransport} to handle requests.
+ * Implements criteria interpretation and multi-turn chat.
+ *
+ * @beta
+ */
+export declare class GeminiProvider implements AIProvider {
+    private readonly transport;
+    private readonly criteriaInstructions?;
+    constructor(config: GeminiProviderConfig, transport: GeminiTransport);
+    getStatus(): Promise<AIStatus>;
+    interpretCriteria(input: string, context: CriteriaInterpretContext): Promise<CriteriaInterpretationResult | null>;
+    chat(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): Promise<ChatMessage>;
+    streamChat(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): AsyncIterable<ChatStreamChunk>;
+}
+
+declare interface GeminiProviderConfig {
+    criteriaInstructions?: string;
+}
+
+/**
+ * Transport for Gemini. Calls the Gemini REST API directly when `apiKey` is
+ * provided, otherwise falls back to a server-proxy endpoint (if `serverEndpoint`
+ * is configured).
+ *
+ * Implements `AITransport` (structured prompt) and `ChatTransport` (multi-turn chat).
+ *
+ * @beta
+ */
+export declare class GeminiTransport implements AITransport, ChatTransport {
+    private readonly model;
+    private readonly timeout;
+    private readonly apiKey;
+    private readonly serverEndpoint;
+    constructor(config?: GeminiTransportConfig);
+    getConfig(): {
+        provider: 'gemini';
+        model: string;
+    };
+    sendStructuredPrompt(options: StructuredPromptOptions): Promise<string>;
+    sendChatMessage(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): Promise<ChatMessage>;
+    private static readonly TOKENS_PER_MILLION;
+    private static readonly PROMPT_COST_PER_MILLION;
+    private static readonly CANDIDATE_COST_PER_MILLION;
+    private static readonly COST_DECIMAL_PLACES;
+    private logTokenUsage;
+    private toGeminiContents;
+    private fromGeminiResponse;
+    private buildEndpoint;
+    private static readonly MAX_RETRIES;
+    private static readonly RATE_LIMIT_STATUS;
+    private static readonly BACKOFF_BASE_MS;
+    private post;
+    private toDirectPayload;
+}
+
+declare interface GeminiTransportConfig {
+    model?: string;
+    timeout?: number;
+    /**
+     * API key for direct calls to the Gemini API.
+     * Must be provided explicitly; callers are responsible for reading it from
+     * their environment (e.g. a build-time injected global).
+     */
+    apiKey?: string;
+    /**
+     * Server-proxy endpoint (e.g. `/gwf/ai-service/gemini/chat`).
+     * Only used when no API key is available. When omitted and no API key
+     * is found, requests will fail.
+     */
+    serverEndpoint?: string;
+}
+
 /**
  * Gets AIProvider from the DI container.
  * When the AI feature flag is disabled (?feature.ai), returns DefaultAIProvider (no-op).
@@ -165,6 +468,17 @@ export declare type FieldLike = string | {
  */
 export declare function getAIProvider(): AIProvider;
 
+/**
+ * The result of a user interaction component.
+ *
+ * @beta
+ */
+export declare type InteractionResult<T = unknown> = {
+    status: 'approved' | 'rejected';
+    payload?: T;
+    message?: string;
+};
+
 /** Returns true when AI features (beta) are enabled. Requires ?feature.ai in URL. */
 export declare const isAIFeatureEnabled: () => boolean;
 
@@ -174,8 +488,25 @@ export declare const isAIFeatureEnabled: () => boolean;
  *
  * @beta
  */
+/**
+ * Returns true if the Web Speech API is available in the current environment.
+ *
+ * @beta
+ */
 export declare function isSpeechRecognitionAvailable(): boolean;
 
+/**
+ * Thrown when Gemini returns a `MALFORMED_FUNCTION_CALL` finish reason,
+ * typically because the model tried to batch multiple tool calls using
+ * Python-style syntax instead of the proper API format.
+ *
+ * @beta
+ */
+export declare class MalformedFunctionCallError extends Error {
+    readonly finishMessage?: string;
+    constructor(finishMessage?: string);
+}
+
 /**
  * Resolves AI config, optionally preferring Chrome when available.
  * Use before registering AIProvider. Server URL is derived from API_HOST.
@@ -185,9 +516,14 @@ export declare function isSpeechRecognitionAvailable(): boolean;
  */
 export declare function resolveAIConfig(options?: ResolveAIConfigOptions): Promise<AIConfig | null>;
 
+/**
+ * Options for {@link resolveAIConfig}.
+ *
+ * @beta
+ */
 export declare interface ResolveAIConfigOptions {
-    /** Cloud provider (openai). Default: openai */
-    provider?: 'openai';
+    /** Cloud provider (openai, gemini). Default: openai */
+    provider?: 'openai' | 'gemini';
     /** Model name (e.g. gpt-4o-mini). Default: gpt-4o-mini */
     model?: string;
     /** Prefer Chrome built-in AI when available */
@@ -214,6 +550,23 @@ declare type SpeechRecognitionErrorHandler = (error: string) => void;
 
 declare type SpeechRecognitionResultHandler = (transcript: string, isFinal: boolean) => void;
 
+/**
+ * Starts continuous speech recognition, calling `onResult` with each transcript update.
+ * Returns a stop function, or null if speech recognition is unavailable.
+ *
+ * @beta
+ */
 export declare function startSpeechRecognition(onResult: SpeechRecognitionResultHandler, onError?: SpeechRecognitionErrorHandler): (() => void) | null;
 
+/**
+ * Options for sending a structured prompt to an AI provider.
+ *
+ * @beta
+ */
+declare interface StructuredPromptOptions {
+    systemPrompt: string;
+    userPrompt: string;
+    responseSchema?: object;
+}
+
 export { }

package/docs/api/foundation-ai.aiconfig.md

@@ -12,7 +12,7 @@ Union type for provider-specific configs. Extend when adding new providers.
 **Signature:**
 
 ```typescript
-export type AIConfig = ServerAIConfig | ChromeAIConfig;
+export type AIConfig = ServerAIConfig | ChromeAIConfig | GeminiAIConfig;
 ```
-**References:** [ServerAIConfig](./foundation-ai.serveraiconfig.md)<!-- -->, [ChromeAIConfig](./foundation-ai.chromeaiconfig.md)
+**References:** [ServerAIConfig](./foundation-ai.serveraiconfig.md)<!-- -->, [ChromeAIConfig](./foundation-ai.chromeaiconfig.md)<!-- -->, [GeminiAIConfig](./foundation-ai.geminiaiconfig.md)
 

package/docs/api/foundation-ai.aiprovider.chat.md

@@ -0,0 +1,85 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-ai](./foundation-ai.md) &gt; [AIProvider](./foundation-ai.aiprovider.md) &gt; [chat](./foundation-ai.aiprovider.chat.md)
+
+## AIProvider.chat() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Multi-turn chat (non-streaming). Returns the assistant's response message. Providers that support chat (Gemini, OpenAI) implement this.
+
+**Signature:**
+
+```typescript
+chat?(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): Promise<ChatMessage>;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+history
+
+
+</td><td>
+
+[ChatMessage](./foundation-ai.chatmessage.md)<!-- -->\[\]
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+userMessage
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+options
+
+
+</td><td>
+
+[ChatRequestOptions](./foundation-ai.chatrequestoptions.md)
+
+
+</td><td>
+
+_(Optional)_
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;[ChatMessage](./foundation-ai.chatmessage.md)<!-- -->&gt;
+

package/docs/api/foundation-ai.aiprovider.md

@@ -34,6 +34,17 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
+[chat(history, userMessage, options)?](./foundation-ai.aiprovider.chat.md)
+
+
+</td><td>
+
+**_(BETA)_** _(Optional)_ Multi-turn chat (non-streaming). Returns the assistant's response message. Providers that support chat (Gemini, OpenAI) implement this.
+
+
+</td></tr>
+<tr><td>
+
 [getStatus()?](./foundation-ai.aiprovider.getstatus.md)
 
 
@@ -53,6 +64,17 @@ Description
 **_(BETA)_** _(Optional)_
 
 
+</td></tr>
+<tr><td>
+
+[streamChat(history, userMessage, options)?](./foundation-ai.aiprovider.streamchat.md)
+
+
+</td><td>
+
+**_(BETA)_** _(Optional)_ Multi-turn chat (streaming). Yields chunks as they arrive. Providers that support streaming implement this.
+
+
 </td></tr>
 <tr><td>
 

package/docs/api/foundation-ai.aiprovider.streamchat.md

@@ -0,0 +1,85 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-ai](./foundation-ai.md) &gt; [AIProvider](./foundation-ai.aiprovider.md) &gt; [streamChat](./foundation-ai.aiprovider.streamchat.md)
+
+## AIProvider.streamChat() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Multi-turn chat (streaming). Yields chunks as they arrive. Providers that support streaming implement this.
+
+**Signature:**
+
+```typescript
+streamChat?(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): AsyncIterable<ChatStreamChunk>;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+history
+
+
+</td><td>
+
+[ChatMessage](./foundation-ai.chatmessage.md)<!-- -->\[\]
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+userMessage
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+options
+
+
+</td><td>
+
+[ChatRequestOptions](./foundation-ai.chatrequestoptions.md)
+
+
+</td><td>
+
+_(Optional)_
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+AsyncIterable&lt;[ChatStreamChunk](./foundation-ai.chatstreamchunk.md)<!-- -->&gt;
+

package/docs/api/foundation-ai.aiprovidertype.md

@@ -12,5 +12,5 @@ All AI provider identifiers (server, client, unconfigured).
 **Signature:**
 
 ```typescript
-export type AIProviderType = 'openai' | 'chrome' | 'none';
+export type AIProviderType = 'openai' | 'chrome' | 'gemini' | 'none';
 ```

package/docs/api/foundation-ai.chatanimationsconfig.enabled.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@genesislcap/foundation-ai](./foundation-ai.md) &gt; [ChatAnimationsConfig](./foundation-ai.chatanimationsconfig.md) &gt; [enabled](./foundation-ai.chatanimationsconfig.enabled.md)
+
+## ChatAnimationsConfig.enabled property
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Initially enabled animations. When omitted all animations are enabled by default.
+
+**Signature:**
+
+```typescript
+enabled?: string[];
+```