@genesislcap/foundation-ai 14.420.0 → 14.421.0

package/dist/foundation-ai.d.ts

@@ -1,6 +1,6 @@
 import { InterfaceSymbol } from '@microsoft/fast-foundation';
 
-/** Feature flag name for AI functionality (beta). Enable via ?feature.ai in URL. */
+/** Feature flag name for AI functionality (beta). Enable via ?feature.ai in URL or GENX_ENABLE_AI env var. */
 export declare const AI_FEATURE_FLAG = "ai";
 
 /**
@@ -31,6 +31,14 @@ export declare interface AIProvider {
      * Must be called from a user gesture (e.g. click).
      */
     triggerDownload?(): Promise<void>;
+    /**
+     * Stateless one-off prompt. No conversation history is maintained.
+     * Returns the plain text response.
+     * Use this for side-calls (suggestions, summarisation, classification) that
+     * should not interact with any ongoing conversation context.
+     * Providers that support chat implement this.
+     */
+    prompt?(message: string, options?: ChatRequestOptions): Promise<string>;
     /**
      * Multi-turn chat (non-streaming). Returns the assistant's response message.
      * Providers that support chat (Gemini, OpenAI) implement this.
@@ -101,6 +109,27 @@ declare interface AITransport {
     isAvailable?(): Promise<boolean>;
 }
 
+/**
+ * Agent engine configuration for the chat assistant.
+ *
+ * @beta
+ */
+export declare interface ChatAgentConfig {
+    /** Maximum number of tool call iterations within one agent's loop. Default: 50. */
+    maxToolIterations?: number;
+    /** Maximum number of agent-to-agent handoffs per user turn. Default: 3. */
+    maxHandoffs?: number;
+    /** Number of recent messages passed to the classifier for context. Default: 4. */
+    classifierHistoryLength?: number;
+    /** Number of retries on classifier failure before erroring. Default: 2. */
+    classifierRetries?: number;
+    /**
+     * Maximum number of consecutive fold open/close operations without a real tool call before
+     * the driver injects a guidance message. Default: 5.
+     */
+    maxFoldOperations?: number;
+}
+
 /**
  * Configuration for the animations feature.
  *
@@ -131,35 +160,32 @@ export declare interface ChatAttachment {
 }
 
 /**
- * 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
+ * Display and engine configuration for the chat assistant.
  *
  * @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;
+    /** UI display settings — toggles, file upload, animations, etc. */
+    ui?: ChatUiConfig;
+    /** Agent engine settings — iteration limits, handoff caps, classifier tuning. */
+    agent?: ChatAgentConfig;
+    /** Query suggestions feature configuration. */
+    suggestions?: ChatSuggestionsConfig;
 }
 
+/**
+ * The result returned by a driver after processing a user turn.
+ *
+ * @beta
+ */
+export declare type ChatDriverResult = {
+    reason: 'done';
+} | {
+    reason: 'agent-handoff';
+    summary: string;
+    remainingTask: string;
+};
+
 /**
  * A user interaction component request.
  *
@@ -169,8 +195,8 @@ 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;
+    /** The result when the interaction has been resolved. Truthy check indicates resolved state; value is available for widgets to display. */
+    resolved?: InteractionResult<unknown>;
 }
 
 /**
@@ -186,6 +212,14 @@ export declare interface ChatMessage {
     attachments?: ChatAttachment[];
     interaction?: ChatInteraction;
     thinking?: boolean;
+    /** Name of the agent that produced this message. Set by OrchestratingDriver. */
+    agentName?: string;
+    /**
+     * Total prompt tokens consumed for the request that produced this message.
+     * Set by transports that return usage metadata (e.g. Gemini). Used to display
+     * context window utilisation in the UI.
+     */
+    inputTokens?: number;
 }
 
 /**
@@ -205,7 +239,7 @@ export declare interface ChatRequestOptions {
  *
  * @beta
  */
-export declare type ChatRole = 'user' | 'assistant' | 'system' | 'tool';
+export declare type ChatRole = 'user' | 'assistant' | 'system' | 'tool' | 'system-event';
 
 /**
  * A streaming chunk from a chat response.
@@ -218,16 +252,77 @@ export declare interface ChatStreamChunk {
     toolCalls?: ChatToolCall[];
 }
 
+/**
+ * Configuration for the chat suggestions feature.
+ *
+ * @beta
+ */
+export declare type ChatSuggestionsConfig = {
+    /** Suggestions are disabled. */
+    behavior: 'never';
+    /** Not applicable when behavior is 'never'. */
+    count?: never;
+    /** Not applicable when behavior is 'never'. */
+    prompt?: never;
+} | {
+    /**
+     * 'initial': Show suggestions on first load before any messages are sent.
+     * 'always': Show suggestions after every assistant response.
+     */
+    behavior: 'initial' | 'always';
+    /**
+     * Number of suggestions to generate.
+     * @default 3
+     */
+    count?: number;
+    /**
+     * Custom prompt to steer the suggestion generation. If omitted, a
+     * default prompt is used.
+     */
+    prompt?: string;
+};
+
 /**
  * A tool call requested by the assistant.
  *
  * @beta
  */
-export declare interface ChatToolCall {
+export declare type ChatToolCall = ChatToolCallBase | ChatToolCallUnknown;
+
+/**
+ * A tool call requested by the assistant.
+ *
+ * @beta
+ */
+declare type ChatToolCallBase = {
     id: string;
     name: string;
     args: Record<string, unknown>;
-}
+    /**
+     * Set by the driver when this tool call is a fold lifecycle event.
+     * Used by the template to render fold opens/closes distinctly.
+     * Not sent to the AI provider.
+     */
+    foldEvent?: 'open' | 'close';
+    /**
+     * UI-only breadcrumb path of fold names the tool lives inside, e.g. ['trading_tools'].
+     * Set by the driver from the active fold stack when a tool call is appended.
+     * Not sent to the AI provider.
+     */
+    foldPath?: string[];
+};
+
+/**
+ * A tool call for a tool name the driver could not resolve to any handler.
+ * `availableTools` lists every tool name registered at the time of the call.
+ * Not sent to the AI provider.
+ *
+ * @beta
+ */
+export declare type ChatToolCallUnknown = ChatToolCallBase & {
+    unknown: true;
+    availableTools: string[];
+};
 
 /**
  * JSON Schema-based tool definition for function calling.
@@ -274,6 +369,55 @@ export declare interface ChatTransport {
     streamChatMessage?(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): AsyncIterable<ChatStreamChunk>;
 }
 
+/**
+ * UI display 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 ChatUiConfig {
+    /** 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;
+    /**
+     * When `true`, shows the `slot="splash"` content when there are no messages.
+     * The host element reflects a `showing-splash` boolean attribute that consumers
+     * can use as a CSS hook to animate the splash in and out. Default: `false`.
+     */
+    showSplash?: boolean;
+    /**
+     * Show an inline divider in the message list when the active specialist changes.
+     * Also shown automatically when showToolCalls is true.
+     * - `true` — default on, user can toggle off
+     * - `false` — default off, user can toggle on
+     * - `null` / `undefined` — completely disabled, no UI control shown
+     */
+    showAgentSwitchIndicator?: boolean | null;
+    /**
+     * Show a context window usage indicator in the settings panel.
+     * Visible when the settings panel is open and token usage data is available.
+     * - `true` or `undefined` (default) — shown when data is available
+     * - `false` — hidden
+     */
+    showContextUsage?: boolean;
+}
+
 /**
  * Chrome built-in AI (Prompt API / Gemini Nano) configuration.
  *
@@ -370,11 +514,19 @@ export declare type FieldLike = string | {
  */
 export declare interface GeminiAIConfig extends AIProviderConfig {
     providerType: 'gemini';
-    model?: string;
+    /** Defaults to `gemini-2.5-flash-lite`. Only {@link SUPPORTED_GEMINI_MODEL_IDS} are accepted at runtime. */
+    model?: GeminiModelId;
     serverEndpoint?: string;
     apiKey?: string;
 }
 
+/**
+ * Gemini REST model ids supported by {@link GeminiTransport}.
+ *
+ * @beta
+ */
+export declare type GeminiModelId = 'gemini-2.5-flash' | 'gemini-2.5-flash-lite';
+
 /**
  * Gemini AI provider. Uses {@link GeminiTransport} to handle requests.
  * Implements criteria interpretation and multi-turn chat.
@@ -387,6 +539,7 @@ export declare class GeminiProvider implements AIProvider {
     constructor(config: GeminiProviderConfig, transport: GeminiTransport);
     getStatus(): Promise<AIStatus>;
     interpretCriteria(input: string, context: CriteriaInterpretContext): Promise<CriteriaInterpretationResult | null>;
+    prompt(message: string, options?: ChatRequestOptions): Promise<string>;
     chat(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): Promise<ChatMessage>;
     streamChat(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): AsyncIterable<ChatStreamChunk>;
 }
@@ -412,13 +565,11 @@ export declare class GeminiTransport implements AITransport, ChatTransport {
     constructor(config?: GeminiTransportConfig);
     getConfig(): {
         provider: 'gemini';
-        model: string;
+        model: GeminiModelId;
     };
     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;
@@ -432,7 +583,10 @@ export declare class GeminiTransport implements AITransport, ChatTransport {
 }
 
 declare interface GeminiTransportConfig {
-    model?: string;
+    /**
+     * Defaults to `gemini-2.5-flash-lite`. Only {@link SUPPORTED_GEMINI_MODEL_IDS} are accepted.
+     */
+    model?: GeminiModelId;
     timeout?: number;
     /**
      * API key for direct calls to the Gemini API.
@@ -479,9 +633,16 @@ export declare type InteractionResult<T = unknown> = {
     message?: string;
 };
 
-/** Returns true when AI features (beta) are enabled. Requires ?feature.ai in URL. */
+/** Returns true when AI features (beta) are enabled via ?feature.ai URL param or GENX_ENABLE_AI=true env var. */
 export declare const isAIFeatureEnabled: () => boolean;
 
+/**
+ * Type guard that narrows a `ChatToolCall` to `ChatToolCallUnknown`.
+ *
+ * @beta
+ */
+export declare function isChatToolCallUnknown(tc: ChatToolCall): tc is ChatToolCallUnknown;
+
 /**
  * Speech-to-text using Web Speech API.
  * Gracefully degrades when SpeechRecognition is unavailable.
@@ -524,7 +685,7 @@ export declare function resolveAIConfig(options?: ResolveAIConfigOptions): Promi
 export declare interface ResolveAIConfigOptions {
     /** Cloud provider (openai, gemini). Default: openai */
     provider?: 'openai' | 'gemini';
-    /** Model name (e.g. gpt-4o-mini). Default: gpt-4o-mini */
+    /** Model name. OpenAI default: gpt-4o-mini. Gemini: only {@link SUPPORTED_GEMINI_MODEL_IDS} (default flash-lite). */
     model?: string;
     /** Prefer Chrome built-in AI when available */
     preferChrome?: boolean;
@@ -569,4 +730,7 @@ declare interface StructuredPromptOptions {
     responseSchema?: object;
 }
 
+/** @beta */
+export declare const SUPPORTED_GEMINI_MODEL_IDS: readonly GeminiModelId[];
+
 export { }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-ai",
   "description": "Genesis Foundation AI - Provider-agnostic AI configuration and shared utilities",
-  "version": "14.420.0",
+  "version": "14.421.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -51,17 +51,17 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.420.0",
-    "@genesislcap/genx": "14.420.0",
-    "@genesislcap/rollup-builder": "14.420.0",
-    "@genesislcap/ts-builder": "14.420.0",
-    "@genesislcap/uvu-playwright-builder": "14.420.0",
-    "@genesislcap/vite-builder": "14.420.0",
-    "@genesislcap/webpack-builder": "14.420.0"
+    "@genesislcap/foundation-testing": "14.421.0",
+    "@genesislcap/genx": "14.421.0",
+    "@genesislcap/rollup-builder": "14.421.0",
+    "@genesislcap/ts-builder": "14.421.0",
+    "@genesislcap/uvu-playwright-builder": "14.421.0",
+    "@genesislcap/vite-builder": "14.421.0",
+    "@genesislcap/webpack-builder": "14.421.0"
   },
   "dependencies": {
-    "@genesislcap/foundation-logger": "14.420.0",
-    "@genesislcap/foundation-utils": "14.420.0",
+    "@genesislcap/foundation-logger": "14.421.0",
+    "@genesislcap/foundation-utils": "14.421.0",
     "@microsoft/fast-foundation": "2.50.0"
   },
   "repository": {
@@ -72,5 +72,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "52c9259f8fb7a203979c832b08388579ae728a38"
+  "gitHead": "d109b70edbd07af351ed8bf393ace74b42bb5356"
 }