@genesislcap/foundation-ai 15.40.0 → 15.41.0

package/dist/foundation-ai.d.ts

@@ -64,6 +64,46 @@ export declare interface AggregateUsage {
 /** 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";
 
+/**
+ * Refusals that come from the app's gateway, not from its AI service. The Genesis router turns a
+ * request away before the service runs: with no session (401) or without the right the endpoint
+ * demands (403). Its body is the router's own NACK, with no `code` a proxy would send, so these are
+ * kept out of {@link AI_SERVICE_ERROR_CODES}.
+ *
+ * @beta
+ */
+export declare const AI_SERVICE_ACCESS_REFUSALS: Readonly<{
+    /** 401: the request had no session. */
+    readonly SIGNED_OUT: "SIGNED_OUT";
+    /** 403: the user lacks the right the endpoint demands. */
+    readonly ACCESS_DENIED: "ACCESS_DENIED";
+}>;
+
+/**
+ * Every code an AI service may put in an error body. A code not listed here keeps the old,
+ * status-based handling: an unknown code must not become a silent dead end, or a retry loop.
+ *
+ * @beta
+ */
+export declare const AI_SERVICE_ERROR_CODES: Readonly<{
+    /** No API key is configured for the vendor. */
+    readonly NO_API_KEY: "NO_API_KEY";
+    /** The configured key has characters an API key cannot have. */
+    readonly BAD_API_KEY: "BAD_API_KEY";
+    /** An encrypted key could not be decrypted. */
+    readonly KEY_UNREADABLE: "KEY_UNREADABLE";
+    /** The request asked for a model the service does not allow. */
+    readonly MODEL_NOT_ALLOWED: "MODEL_NOT_ALLOWED";
+    /** The service refused the shape of the request. */
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    /** The request named fallback models, which the service does not accept. */
+    readonly FALLBACKS_NOT_SUPPORTED: "FALLBACKS_NOT_SUPPORTED";
+    /** The request body is larger, or nested deeper, than the service accepts. */
+    readonly REQUEST_TOO_LARGE: "REQUEST_TOO_LARGE";
+    /** The service could not reach the vendor. The only code that is worth retrying. */
+    readonly VENDOR_UNREACHABLE: "VENDOR_UNREACHABLE";
+}>;
+
 /**
  * Every tier id, in ascending capability order.
  *
@@ -231,6 +271,76 @@ export declare interface AIProviderRegistryStatusEntry {
  */
 export declare type AIProviderType = 'openai' | 'chrome' | 'gemini' | 'anthropic' | 'none';
 
+/**
+ * One of {@link AI_SERVICE_ACCESS_REFUSALS}.
+ *
+ * @beta
+ */
+export declare type AIServiceAccessRefusal = (typeof AI_SERVICE_ACCESS_REFUSALS)[keyof typeof AI_SERVICE_ACCESS_REFUSALS];
+
+/**
+ * The access refusal behind a 401 or 403 from the app's router, which carries no `code`.
+ *
+ * Recognised by a positive signal only, like the rest of this module's family: the router's NACK,
+ * or an empty body. A vendor's own 401/403, a coded one, and anything else (an HTML page from a
+ * proxy in between, say) keep their own handling.
+ *
+ * @param bodyText - the raw response body, so an empty one can be told from one that isn't JSON.
+ * Left out, the body is unknown rather than empty, and only the router's NACK counts.
+ * @beta
+ */
+export declare function aiServiceAccessRefusalOf(status: number, payload: unknown, bodyText?: string): AIServiceAccessRefusal | undefined;
+
+/**
+ * Thrown when the AI service answers with one of {@link AI_SERVICE_ERROR_CODES}, or the app's router
+ * refuses the request with one of {@link AI_SERVICE_ACCESS_REFUSALS}.
+ *
+ * All but `VENDOR_UNREACHABLE` are terminal: sending the same request again gets the same answer
+ * until someone changes the configuration, or the user's session or rights.
+ *
+ * @beta
+ */
+export declare class AIServiceError extends Error {
+    /** Vendor label of the transport that was refused (e.g. `'Gemini'`). */
+    readonly vendorLabel: string;
+    readonly code: AIServiceRefusal;
+    /** HTTP status, or the err frame's status on the framed path. */
+    readonly status: number;
+    /** The service's own message, for the console. Never shown to the user. */
+    readonly detail?: string;
+    constructor(
+    /** Vendor label of the transport that was refused (e.g. `'Gemini'`). */
+    vendorLabel: string, code: AIServiceRefusal, 
+    /** HTTP status, or the err frame's status on the framed path. */
+    status: number, 
+    /** The service's own message, for the console. Never shown to the user. */
+    detail?: string);
+    /** Whether sending the request again cannot help. */
+    get terminal(): boolean;
+}
+
+/**
+ * One of {@link AI_SERVICE_ERROR_CODES}.
+ *
+ * @beta
+ */
+export declare type AIServiceErrorCode = (typeof AI_SERVICE_ERROR_CODES)[keyof typeof AI_SERVICE_ERROR_CODES];
+
+/**
+ * The code, when it is one of {@link AI_SERVICE_ERROR_CODES}; otherwise `undefined`.
+ *
+ * @beta
+ */
+export declare function aiServiceErrorCodeOf(code: unknown): AIServiceErrorCode | undefined;
+
+/**
+ * Everything the chat can tell the user about a refused request: a code the service sent, or an
+ * access refusal from in front of it.
+ *
+ * @beta
+ */
+export declare type AIServiceRefusal = AIServiceErrorCode | AIServiceAccessRefusal;
+
 /**
  * AI status for display in the header indicator.
  *
@@ -2055,6 +2165,8 @@ export declare type ChatToolHandlers<TSubAgent extends {
      * - `{ ok: false, reason }` — the run ended without completing (see
      *   {@link SubAgentFailureReason}). The parent handler decides how to
      *   recover — typically by returning the issue info to its own agent.
+     *   With `reason: 'ai_service_error'` it also carries the refusal's `code`
+     *   and whether it is `terminal`.
      *
      * Sub-agents run with tool use forced, so they can no longer end on a
      * free-text turn; the previous string fallback has been removed.
@@ -2063,10 +2175,22 @@ export declare type ChatToolHandlers<TSubAgent extends {
         ok: true;
         result: T;
         reason?: never;
+        code?: never;
+        terminal?: never;
     } | {
         ok: false;
         result?: never;
-        reason: SubAgentFailureReason;
+        reason: Exclude<SubAgentFailureReason, 'ai_service_error'>;
+        code?: never;
+        terminal?: never;
+    } | {
+        ok: false;
+        result?: never;
+        reason: 'ai_service_error';
+        /** The refusal's code. */
+        code: AIServiceRefusal;
+        /** Whether re-invoking it with the same request gets the same refusal. */
+        terminal: boolean;
     }>;
     /**
      * Signal explicit completion from within a sub-agent tool handler.
@@ -2113,6 +2237,22 @@ export declare type ChatToolHandlers<TSubAgent extends {
      * restores the content); non-idempotent tools must use `replaceWith`.
      */
     condenseWhen: (policy: CondensePolicy) => void;
+    /**
+     * The current TURN's abort signal: one object for every tool call made while answering
+     * one user message, a new one for the next, and aborted when the user stops the turn or
+     * the view is disposed. One message includes an orchestrated handoff's continuation and a
+     * sub-agent the message delegates to: both see the same object, and a stop reaches both.
+     * A continuation after the user stopped the message is not part of it, and gets a new one.
+     *
+     * Two uses. A long-running handler can listen for it to stop early. And a handler that
+     * must remember something for the rest of the turn — a write the user denied, say — can
+     * key that state on this object (a `WeakMap`), which cannot collide the way a turn number
+     * would when several chat views share one set of handlers.
+     *
+     * Optional: a host that builds its own context may not supply it, and a handler relying on
+     * it must decide what its absence means.
+     */
+    turnSignal?: AbortSignal;
 }) => Promise<unknown>>;
 
 /**
@@ -2543,6 +2683,15 @@ export declare interface CriteriaInterpretContext {
     fields?: FieldLike[];
 }
 
+/**
+ * What the user sees for each code and access refusal. Written for the app's user, with a hint for
+ * whoever runs it, and never quoting the server: its text goes to the console only. A host can
+ * replace any of them (`aiServiceErrorMessages` on the assistant).
+ *
+ * @beta
+ */
+export declare const DEFAULT_AI_SERVICE_ERROR_MESSAGES: Readonly<Record<AIServiceRefusal, string>>;
+
 /**
  * The platform's default tier table.
  *
@@ -2972,6 +3121,13 @@ export declare interface InteractionRequestOptions {
      * means no timeout — the interaction waits indefinitely.
      */
     timeoutMs?: number;
+    /**
+     * Closes the interaction when it aborts, exactly as an unanswered one closes at `timeoutMs`: the
+     * widget goes read-only and `requestInteraction` resolves with `status: 'timeout'`. A tool
+     * handler passes its `turnSignal`, so a user's Stop closes a widget left open instead of leaving
+     * the turn parked on it, and nothing the user clicks afterwards is taken as an answer.
+     */
+    signal?: AbortSignal;
     /**
      * How the host frames this widget in the transcript — see
      * {@link InteractionPresentation}. Defaults to `'label'` (the historical
@@ -3079,6 +3235,14 @@ export declare function isObservableAIProviderRegistry(r: AIProviderRegistry): r
  */
 export declare function isSpeechRecognitionAvailable(): boolean;
 
+/**
+ * Whether sending the same request again gets the same refusal. Every code but `VENDOR_UNREACHABLE`
+ * does, until someone changes the configuration or the user's session or rights.
+ *
+ * @beta
+ */
+export declare const isTerminalAIServiceRefusal: (code: AIServiceRefusal) => boolean;
+
 /**
  * Thrown when Gemini returns a `MALFORMED_FUNCTION_CALL` finish reason,
  * typically because the model tried to batch multiple tool calls using
@@ -3542,9 +3706,10 @@ declare interface StructuredPromptOptions {
  *   So a handler that receives it will not be called a second time this turn, and
  *   the parent turn reports `'budget-exhausted'` in its own right.
  *
- * Recovery guidance differs sharply by reason — see `docs/sub_agent.md`. Only
- * `budget_exhausted` and `refusal` are terminal; retrying either just reproduces
- * it. The rest are worth a retry or a question to the user.
+ * Recovery guidance differs sharply by reason — see `docs/sub_agent.md`.
+ * `budget_exhausted`, `refusal`, `provider_refused`, `context_exhausted` and a
+ * `terminal` `ai_service_error` are terminal: retrying any of them with the same
+ * request just reproduces it. The rest are worth a retry or a question to the user.
  *
  * @beta
  */
@@ -3557,13 +3722,29 @@ export declare type SubAgentFailureReason = 'max_iterations' | 'malformed_tool_c
 */
 | 'provider_refused'
 /**
-* The sub-agent was stopped because continuing would have overrun the context
-* window (GENC-1567). **Terminal for the PARENT turn too**, on the same
-* reasoning as `budget_exhausted` and `provider_refused`: the parent shares the
-* conversation whose size caused it, so calling the model again hits the same
-* wall.
+* The sub-agent was stopped because continuing would have overrun the context window
+* (GENC-1567). Re-invoking it with the same conversation stops it the same way. The parent's turn
+* goes on, but it shares the conversation whose size caused this, so its own next model call is
+* likely to stop on the same guard.
+*/
+| 'context_exhausted'
+/**
+* The app's AI service refused the sub-agent's request (GENC-1611). The outcome carries the
+* refusal's `code` and whether it is `terminal`: re-invoking the sub-agent with the same request
+* gets the same refusal, so recover without calling it again. Only a `VENDOR_UNREACHABLE` refusal
+* is not terminal. Even so, a refusal from your own vendor that is about the service (for example
+* `VENDOR_UNREACHABLE`) still ends this turn; retry on the user's next message, not in the
+* handler.
+*
+* **Terminal for the PARENT turn too only when** the refusal is about the service rather than the
+* child's own request (a missing or unusable key, no session or no right, the vendor unreachable)
+* and the child called the parent's own vendor, unless a completion or a handoff from the same
+* batch goes on past it. Otherwise the parent is told and its turn goes on. The user is shown a
+* key, access, model (`MODEL_NOT_ALLOWED`) or reachability refusal's sentence once per user
+* message; `REQUEST_TOO_LARGE`, `BAD_REQUEST` and `FALLBACKS_NOT_SUPPORTED` are left to the parent
+* and the console.
 */
-| 'context_exhausted';
+| 'ai_service_error';
 
 /**
  * Options passed to `requestSubAgent` at call time.
@@ -3723,7 +3904,13 @@ export declare type TurnFailureReason = 'exception' | 'malformed-function-call'
 * the edge rather than issuing a request the provider would reject, so the
 * transcript stays intact and compaction is still possible.
 */
-| 'context-exhausted';
+| 'context-exhausted'
+/**
+* The app's AI service refused the request with one of `AI_SERVICE_ERROR_CODES` (GENC-1611): a
+* configuration error such as a missing API key, or the vendor still unreachable after the
+* retries. The transcript says what is wrong in words for the user.
+*/
+| 'ai-service-error';
 
 /**
  * Display name for each concrete AI vendor: the **single source** every

package/package.json

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