@genesislcap/ai-assistant 15.14.2 → 15.15.0-GENC-1508.2

package/dist/ai-assistant.api.json

@@ -3205,6 +3205,67 @@
               ],
               "name": "primeRestoredAgentState"
             },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AiDriver#recordExternalCost:member(1)",
+              "docComment": "/**\n * Record external spend against an interaction that has ALREADY resolved.\n *\n * For widgets that resolve early — so the assistant stops waiting — and then keep doing paid work on the user's behalf. Reports a positive DELTA; repeated calls sum. Returns false when the message is no longer in history.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "recordExternalCost?(interactionId: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", costUsd: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": true,
+              "returnTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "releaseTag": "Beta",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "interactionId",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "costUsd",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "recordExternalCost"
+            },
             {
               "kind": "MethodSignature",
               "canonicalReference": "@genesislcap/ai-assistant!AiDriver#resolveInteraction:member(1)",
@@ -3286,7 +3347,7 @@
                 {
                   "kind": "Reference",
                   "text": "ChatAttachment",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:interface"
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:type"
                 },
                 {
                   "kind": "Content",
@@ -5265,6 +5326,70 @@
               "isAbstract": false,
               "name": "markAsSubAgent"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#recordExternalCost:member(1)",
+              "docComment": "/**\n * Add external (non-LLM) spend to an interaction's message AFTER it has resolved.\n *\n * **Why this exists separately from `resolveInteraction`.** A widget's spend reaches the session total only through `InteractionResult.costUsd`, which is read exactly once — `resolveInteraction` does its whole job inside `if (interaction)` and then deletes the entry from `pendingInteractions`. That is correct for the resolution itself, but it assumes a widget stops costing money when it resolves, and several deliberately do not: a widget that resolves EARLY so the assistant stops waiting (options shown, a preview rendered) may stay interactive for minutes afterwards and do more paid work on the user's behalf. Re-emitting `interaction-completed` does not help — with the interaction gone from the map the call is a silent no-op — so that spend had nowhere to go and was simply missing from the figure shown to the user.\n *\n * Additive by design: the caller reports a DELTA, not a running total, so repeated calls sum. It touches only `externalCostUsd`; the recorded `interaction.resolved` payload is left exactly as the resolution wrote it, because this is not a second resolution and must not read like one.\n *\n * Deliberately does NOT require the interaction to be pending, does not resurrect it, and has no loading/turn side effects — this is bookkeeping about a turn that already happened.\n *\n * @param interactionId - the interaction whose message owns the spend.\n *\n * @param costUsd - a positive delta in USD. Non-finite, zero and negative values are ignored.\n *\n * @returns `true` when the spend was recorded; `false` when the message is no longer in history (trimmed or condensed away), which is a real outcome the caller may want to log rather than a failure to throw on.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "recordExternalCost(interactionId: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", costUsd: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "interactionId",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "costUsd",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "recordExternalCost"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#reportBudgetExhausted:member(1)",
@@ -5515,7 +5640,7 @@
                 {
                   "kind": "Reference",
                   "text": "ChatAttachment",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:interface"
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:type"
                 },
                 {
                   "kind": "Content",
@@ -7723,7 +7848,7 @@
                 {
                   "kind": "Reference",
                   "text": "ChatAttachment",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:interface"
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:type"
                 },
                 {
                   "kind": "Content",
@@ -9077,6 +9202,55 @@
               "isAbstract": false,
               "name": "handleInteractionCompleted"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#handleInteractionCost:member(1)",
+              "docComment": "/**\n * A widget reporting spend it incurred AFTER resolving.\n *\n * Note what this deliberately does NOT do: no `startLoadingTimer()`. This is bookkeeping about a turn that already finished, so it must be invisible — showing a spinner would tell the user the assistant is working when nothing is pending.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "handleInteractionCost(e: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Event",
+                  "canonicalReference": "!Event:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "e",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "handleInteractionCost"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#handlePopout:member(1)",
@@ -10474,7 +10648,7 @@
                 {
                   "kind": "Reference",
                   "text": "ChatAttachment",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:interface"
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:type"
                 },
                 {
                   "kind": "Content",
@@ -14889,6 +15063,70 @@
               "isAbstract": false,
               "name": "primeRestoredAgentState"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#recordExternalCost:member(1)",
+              "docComment": "/**\n * Delegated for the same reason as `resolveInteraction`: the history that owns the interaction — and therefore the cost — lives on the wrapped driver, not here.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "recordExternalCost(interactionId: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", costUsd: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "interactionId",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "costUsd",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "recordExternalCost"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#resolveInteraction:member(1)",
@@ -14973,7 +15211,7 @@
                 {
                   "kind": "Reference",
                   "text": "ChatAttachment",
-                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:interface"
+                  "canonicalReference": "@genesislcap/foundation-ai!ChatAttachment:type"
                 },
                 {
                   "kind": "Content",

package/dist/ai-assistant.d.ts

@@ -597,6 +597,16 @@ export declare interface AiDriver extends EventTarget {
      * Resolve a pending blocking interaction with the given result.
      */
     resolveInteraction(interactionId: string, result: unknown): void;
+    /**
+     * Record external spend against an interaction that has ALREADY resolved.
+     *
+     * For widgets that resolve early — so the assistant stops waiting — and then keep doing paid work
+     * on the user's behalf. Reports a positive DELTA; repeated calls sum. Returns false when the
+     * message is no longer in history.
+     *
+     * @beta
+     */
+    recordExternalCost?(interactionId: string, costUsd: number): boolean;
     /**
      * The live {@link InteractionContext} for a pending interaction (GENC-1390), or
      * `undefined` if the interaction is resolved/evicted or the driver owns no
@@ -1858,6 +1868,34 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      *   bubble and/or shows the "Assistant" label.
      */
     requestInteraction<T>(componentName: string, data: any, options?: InteractionRequestOptions): Promise<T>;
+    /**
+     * Add external (non-LLM) spend to an interaction's message AFTER it has resolved.
+     *
+     * **Why this exists separately from `resolveInteraction`.** A widget's spend reaches the session
+     * total only through `InteractionResult.costUsd`, which is read exactly once — `resolveInteraction`
+     * does its whole job inside `if (interaction)` and then deletes the entry from
+     * `pendingInteractions`. That is correct for the resolution itself, but it assumes a widget stops
+     * costing money when it resolves, and several deliberately do not: a widget that resolves EARLY so
+     * the assistant stops waiting (options shown, a preview rendered) may stay interactive for minutes
+     * afterwards and do more paid work on the user's behalf. Re-emitting `interaction-completed` does
+     * not help — with the interaction gone from the map the call is a silent no-op — so that spend had
+     * nowhere to go and was simply missing from the figure shown to the user.
+     *
+     * Additive by design: the caller reports a DELTA, not a running total, so repeated calls sum. It
+     * touches only `externalCostUsd`; the recorded `interaction.resolved` payload is left exactly as
+     * the resolution wrote it, because this is not a second resolution and must not read like one.
+     *
+     * Deliberately does NOT require the interaction to be pending, does not resurrect it, and has no
+     * loading/turn side effects — this is bookkeeping about a turn that already happened.
+     *
+     * @param interactionId the interaction whose message owns the spend.
+     * @param costUsd a positive delta in USD. Non-finite, zero and negative values are ignored.
+     * @returns `true` when the spend was recorded; `false` when the message is no longer in history
+     *   (trimmed or condensed away), which is a real outcome the caller may want to log rather than a
+     *   failure to throw on.
+     * @beta
+     */
+    recordExternalCost(interactionId: string, costUsd: number): boolean;
     /**
      * Resolve a pending interaction. The wrapper component calls this on completion.
      * Marks the interaction message as resolved so it renders read-only on re-render.
@@ -2057,6 +2095,10 @@ declare type ChatInteractionEventsMap = {
     'interaction-completed': InteractionResult<unknown> & {
         interactionId: string;
     };
+    'interaction-cost': {
+        interactionId: string;
+        costUsd: number;
+    };
 };
 
 export { ChatThinkingPolicy }
@@ -3960,6 +4002,14 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private send;
     onChatHeaderMouseDown(e: MouseEvent): void;
     handleInteractionCompleted(e: Event): void;
+    /**
+     * A widget reporting spend it incurred AFTER resolving.
+     *
+     * Note what this deliberately does NOT do: no `startLoadingTimer()`. This is bookkeeping about a
+     * turn that already finished, so it must be invisible — showing a spinner would tell the user the
+     * assistant is working when nothing is pending.
+     */
+    handleInteractionCost(e: Event): void;
     /**
      * The live {@link InteractionContext} for a pending interaction (GENC-1390).
      * `AiChatInteractionWrapper` pierces this across the shadow boundary to build the
@@ -4294,6 +4344,9 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
         budgetExhaustedMessage?: string;
     });
     resolveInteraction(interactionId: string, result: unknown): void;
+    /** Delegated for the same reason as `resolveInteraction`: the history that owns the
+     *  interaction — and therefore the cost — lives on the wrapped driver, not here. */
+    recordExternalCost(interactionId: string, costUsd: number): boolean;
     getInteractionContext(interactionId: string): InteractionContext | undefined;
     isBusy(): boolean;
     /** Currently active provider name from the underlying ChatDriver. */