@genesislcap/foundation-ai 14.438.0 → 14.439.0

package/dist/foundation-ai.d.ts

@@ -27,7 +27,7 @@ export declare const AI_FEATURE_FLAG = "ai";
  *
  * @beta
  */
-export declare type AIConfig = ServerAIConfig | ChromeAIConfig | GeminiAIConfig;
+export declare type AIConfig = ServerAIConfig | ChromeAIConfig | GeminiAIConfig | AnthropicAIConfig;
 
 /**
  * AI Provider interface for foundation-ai.
@@ -103,7 +103,7 @@ declare interface AIProviderConfig {
  *
  * @beta
  */
-export declare type AIProviderType = 'openai' | 'chrome' | 'gemini' | 'none';
+export declare type AIProviderType = 'openai' | 'chrome' | 'gemini' | 'anthropic' | 'none';
 
 /**
  * AI status for display in the header indicator.
@@ -114,6 +114,13 @@ export declare interface AIStatus {
     provider: AIProviderType;
     model: string;
     chromeAvailability?: ChromeAvailability;
+    /**
+     * Maximum input context window for the active model, in tokens. Used by the
+     * chat UI to render context utilisation. Optional — providers without a
+     * well-defined limit (e.g. Chrome on-device) leave it undefined and the UI
+     * hides the indicator.
+     */
+    contextLimit?: number;
 }
 
 /**
@@ -127,6 +134,149 @@ declare interface AITransport {
     isAvailable?(): Promise<boolean>;
 }
 
+/**
+ * Anthropic server-proxy AI configuration (client calls your server; server calls Anthropic).
+ *
+ * @remarks
+ * API key stays on the server. URL defaults to `/gwf/ai-service/anthropic/chat`.
+ * When `apiKey` is provided, the transport calls `api.anthropic.com/v1/messages` directly
+ * (browser direct calls require `anthropic-dangerous-direct-browser-access: true`, which the
+ * transport sends automatically — only use this in trusted contexts).
+ *
+ * @beta
+ */
+export declare interface AnthropicAIConfig extends AIProviderConfig {
+    providerType: 'anthropic';
+    /** Defaults to `claude-haiku-4-5-20251001`. Only {@link SUPPORTED_ANTHROPIC_MODEL_IDS} are accepted at runtime. */
+    model?: AnthropicModelId;
+    serverEndpoint?: string;
+    apiKey?: string;
+    /**
+     * Hard cap on tokens generated per response. Anthropic's `max_tokens` is a required
+     * field on every request. Defaults to 4096.
+     */
+    maxTokens?: number;
+}
+
+/**
+ * Anthropic Messages API model ids supported by {@link AnthropicTransport}.
+ *
+ * @beta
+ */
+export declare type AnthropicModelId = 'claude-opus-4-7' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001';
+
+/**
+ * Anthropic Claude AI provider. Uses {@link AnthropicTransport} to handle requests.
+ * Implements criteria interpretation and multi-turn chat.
+ *
+ * @beta
+ */
+export declare class AnthropicProvider implements AIProvider {
+    private readonly transport;
+    private readonly criteriaInstructions?;
+    constructor(config: AnthropicProviderConfig, transport: AnthropicTransport);
+    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>;
+}
+
+declare interface AnthropicProviderConfig {
+    criteriaInstructions?: string;
+}
+
+/**
+ * Transport for Anthropic Claude. Calls the Messages API directly when `apiKey`
+ * is provided, otherwise falls back to a server-proxy endpoint (if `serverEndpoint`
+ * is configured).
+ *
+ * Implements `AITransport` (structured prompt via tool-forcing) and `ChatTransport`
+ * (multi-turn chat).
+ *
+ * @beta
+ */
+export declare class AnthropicTransport implements AITransport, ChatTransport, CostReportingTransport {
+    private readonly model;
+    private readonly timeout;
+    private readonly apiKey;
+    private readonly serverEndpoint;
+    private readonly maxTokens;
+    /**
+     * Estimated USD cost accumulated across every successful request on this
+     * transport instance. Convenience accessor for non-chat consumers
+     * (telemetry, debug overlays). The main chat UI sums per-message `cost`
+     * fields instead so its session total stays attributed to chat turns only.
+     */
+    private lifetimeCostUsd;
+    constructor(config?: AnthropicTransportConfig);
+    getConfig(): {
+        provider: 'anthropic';
+        model: AnthropicModelId;
+        contextLimit: number;
+    };
+    /** Estimated USD cost accumulated across every successful request on this transport instance. */
+    getLifetimeCost(): number;
+    /** Reset the lifetime cost counter. Intended for chat-clear / new-session flows. */
+    resetLifetimeCost(): void;
+    sendStructuredPrompt(options: StructuredPromptOptions): Promise<string>;
+    sendChatMessage(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): Promise<ChatMessage>;
+    private static readonly TOKENS_PER_MILLION;
+    private static readonly COST_DECIMAL_PLACES;
+    /**
+     * Logs the per-call cost breakdown, accumulates the lifetime running total,
+     * and returns the per-call total so the caller can attach it to the response
+     * message.
+     */
+    private logTokenUsage;
+    /**
+     * Convert the internal `ChatMessage[]` history into Anthropic's message format.
+     *
+     * Anthropic alternates strictly `user` / `assistant`. Tool calls are emitted by
+     * the assistant as `tool_use` blocks; the corresponding `tool_result` blocks
+     * must appear in the *next* user message and reference the tool by `tool_use_id`.
+     * Consecutive same-role turns are merged by the API but we merge here to keep
+     * the payload tidy.
+     */
+    private toAnthropicMessages;
+    private fromAnthropicResponse;
+    private buildEndpoint;
+    private static readonly MAX_RETRIES;
+    private static readonly RATE_LIMIT_STATUS;
+    private static readonly SERVICE_UNAVAILABLE_STATUS;
+    private static readonly OVERLOADED_STATUS;
+    private static readonly RETRYABLE_STATUSES;
+    private static readonly BACKOFF_BASE_MS;
+    private post;
+}
+
+declare interface AnthropicTransportConfig {
+    /**
+     * Defaults to `claude-haiku-4-5-20251001`. Only {@link SUPPORTED_ANTHROPIC_MODEL_IDS}
+     * are accepted.
+     */
+    model?: AnthropicModelId;
+    timeout?: number;
+    /**
+     * API key for direct calls to the Anthropic API.
+     * Must be provided explicitly; callers are responsible for reading it from
+     * their environment (e.g. a build-time injected global). When set, requests
+     * include `anthropic-dangerous-direct-browser-access: true` so the API
+     * accepts the call from a browser origin.
+     */
+    apiKey?: string;
+    /**
+     * Server-proxy endpoint (e.g. `/gwf/ai-service/anthropic/chat`).
+     * Only used when no API key is available. When omitted and no API key
+     * is found, requests will fail.
+     */
+    serverEndpoint?: string;
+    /**
+     * Hard cap on tokens generated per response. Defaults to 4096.
+     */
+    maxTokens?: number;
+}
+
 /**
  * Agent engine configuration for the chat assistant.
  *
@@ -287,6 +437,18 @@ export declare interface ChatMessage {
      * context window utilisation in the UI.
      */
     inputTokens?: number;
+    /**
+     * Total output (generated) tokens for the request that produced this message.
+     * Set by transports that return usage metadata. Used alongside `cost`.
+     */
+    outputTokens?: number;
+    /**
+     * Estimated USD cost for the single request that produced this message,
+     * derived from the active model's input/output rates. Set by transports.
+     * Hosts can sum this across the message list to display a running session
+     * cost without re-deriving rates.
+     */
+    cost?: number;
 }
 
 /**
@@ -528,6 +690,19 @@ export declare interface ChatUiConfig {
      * - `false` — hidden
      */
     showContextUsage?: boolean;
+    /**
+     * Show the running session cost (aggregated USD across all chat turns) in
+     * the settings panel.
+     * - `true` or `undefined` (default) — shown when cost data is available
+     * - `false` — hidden
+     */
+    showSessionCost?: boolean;
+    /**
+     * Show the active model id in the settings panel.
+     * - `true` or `undefined` (default) — shown when the provider exposes a model
+     * - `false` — hidden
+     */
+    showActiveModel?: boolean;
 }
 
 /**
@@ -551,6 +726,29 @@ export declare interface ChromeAIConfig extends AIProviderConfig {
  */
 export declare type ChromeAvailability = 'available' | 'downloading' | 'downloadable' | 'unavailable';
 
+/**
+ * Optional capability implemented by transports that can report the estimated
+ * USD cost they have incurred over their lifetime.
+ *
+ * @remarks
+ * Surfaces a transport-lifetime running total for non-chat consumers such as
+ * telemetry, debug overlays, or admin dashboards. The chat UI deliberately
+ * does not depend on this — it sums per-message `cost` fields instead so the
+ * session total stays scoped to chat turns and excludes other call sites
+ * (suggestions, criteria interpretation, etc.) that share the same transport.
+ *
+ * Consumers can either accept a `CostReportingTransport` directly or duck-type
+ * with `'getLifetimeCost' in transport`.
+ *
+ * @beta
+ */
+export declare interface CostReportingTransport {
+    /** Estimated USD cost accumulated across every successful request on this transport instance. */
+    getLifetimeCost(): number;
+    /** Reset the lifetime cost counter. Intended for chat-clear / new-session flows. */
+    resetLifetimeCost(): void;
+}
+
 /**
  * Creates an AIProvider from config.
  * Uses ChromeProvider when providerType is 'chrome'.
@@ -669,20 +867,37 @@ declare interface GeminiProviderConfig {
  *
  * @beta
  */
-export declare class GeminiTransport implements AITransport, ChatTransport {
+export declare class GeminiTransport implements AITransport, ChatTransport, CostReportingTransport {
     private readonly model;
     private readonly timeout;
     private readonly apiKey;
     private readonly serverEndpoint;
+    /**
+     * Estimated USD cost accumulated across every successful request on this
+     * transport instance. Convenience accessor for non-chat consumers
+     * (telemetry, debug overlays). The main chat UI sums per-message `cost`
+     * fields instead so its session total stays attributed to chat turns only.
+     */
+    private lifetimeCostUsd;
     constructor(config?: GeminiTransportConfig);
     getConfig(): {
         provider: 'gemini';
         model: GeminiModelId;
+        contextLimit: number;
     };
+    /** Estimated USD cost accumulated across every successful request on this transport instance. */
+    getLifetimeCost(): number;
+    /** Reset the lifetime cost counter. Intended for chat-clear / new-session flows. */
+    resetLifetimeCost(): void;
     sendStructuredPrompt(options: StructuredPromptOptions): Promise<string>;
     sendChatMessage(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): Promise<ChatMessage>;
     private static readonly TOKENS_PER_MILLION;
     private static readonly COST_DECIMAL_PLACES;
+    /**
+     * Logs the per-call cost breakdown, accumulates the lifetime running total,
+     * and returns the per-call total so the caller can attach it to the response
+     * message.
+     */
     private logTokenUsage;
     private toGeminiContents;
     private fromGeminiResponse;
@@ -814,9 +1029,15 @@ export declare function resolveAIConfig(options?: ResolveAIConfigOptions): Promi
  * @beta
  */
 export declare interface ResolveAIConfigOptions {
-    /** Cloud provider (openai, gemini). Default: openai */
-    provider?: 'openai' | 'gemini';
-    /** Model name. OpenAI default: gpt-4o-mini. Gemini: only {@link SUPPORTED_GEMINI_MODEL_IDS} (default flash-lite). */
+    /** Cloud provider (openai, gemini, anthropic). Default: openai */
+    provider?: 'openai' | 'gemini' | 'anthropic';
+    /**
+     * Model name.
+     *
+     * - OpenAI default: `gpt-4o-mini`.
+     * - Gemini: only {@link SUPPORTED_GEMINI_MODEL_IDS} (default `gemini-2.5-flash-lite`).
+     * - Anthropic: only {@link SUPPORTED_ANTHROPIC_MODEL_IDS} (default `claude-haiku-4-5-20251001`).
+     */
     model?: string;
     /** Prefer Chrome built-in AI when available */
     preferChrome?: boolean;
@@ -884,6 +1105,9 @@ export declare interface SubAgentRequestOptions {
     chatInputDuringExecution?: ChatInputDuringExecutionMode;
 }
 
+/** @beta */
+export declare const SUPPORTED_ANTHROPIC_MODEL_IDS: readonly AnthropicModelId[];
+
 /** @beta */
 export declare const SUPPORTED_GEMINI_MODEL_IDS: readonly GeminiModelId[];
 

package/package.json

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