@genesislcap/foundation-ai 15.40.0 → 15.42.0

package/dist/foundation-ai.api.json

@@ -378,6 +378,62 @@
             "endIndex": 0
           }
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-ai!AI_SERVICE_ACCESS_REFUSALS:var",
+          "docComment": "/**\n * 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}.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "AI_SERVICE_ACCESS_REFUSALS: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Readonly",
+              "canonicalReference": "!Readonly:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<{\n    readonly SIGNED_OUT: \"SIGNED_OUT\";\n    readonly ACCESS_DENIED: \"ACCESS_DENIED\";\n}>"
+            }
+          ],
+          "fileUrlPath": "src/transports/ai-service-error.ts",
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "AI_SERVICE_ACCESS_REFUSALS",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 3
+          }
+        },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-ai!AI_SERVICE_ERROR_CODES:var",
+          "docComment": "/**\n * 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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "AI_SERVICE_ERROR_CODES: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Readonly",
+              "canonicalReference": "!Readonly:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<{\n    readonly NO_API_KEY: \"NO_API_KEY\";\n    readonly BAD_API_KEY: \"BAD_API_KEY\";\n    readonly KEY_UNREADABLE: \"KEY_UNREADABLE\";\n    readonly MODEL_NOT_ALLOWED: \"MODEL_NOT_ALLOWED\";\n    readonly BAD_REQUEST: \"BAD_REQUEST\";\n    readonly FALLBACKS_NOT_SUPPORTED: \"FALLBACKS_NOT_SUPPORTED\";\n    readonly REQUEST_TOO_LARGE: \"REQUEST_TOO_LARGE\";\n    readonly VENDOR_UNREACHABLE: \"VENDOR_UNREACHABLE\";\n}>"
+            }
+          ],
+          "fileUrlPath": "src/transports/ai-service-error.ts",
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "AI_SERVICE_ERROR_CODES",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 3
+          }
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/foundation-ai!AI_TIER_IDS:var",
@@ -1246,91 +1302,611 @@
               }
             },
             {
-              "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/foundation-ai!AIProviderRegistryStatusEntry#name:member",
-              "docComment": "/**\n * The name the provider was registered under.\n */\n",
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!AIProviderRegistryStatusEntry#name:member",
+              "docComment": "/**\n * The name the provider was registered under.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "name: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "name",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!AIProviderRegistryStatusEntry#status:member",
+              "docComment": "/**\n * The provider's `getStatus()` result, or `null` if unavailable.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "status: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AIStatus",
+                  "canonicalReference": "@genesislcap/foundation-ai!AIStatus:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "status",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-ai!AIProviderType:type",
+          "docComment": "/**\n * All AI provider identifiers (server, client, unconfigured).\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type AIProviderType = "
+            },
+            {
+              "kind": "Content",
+              "text": "'openai' | 'chrome' | 'gemini' | 'anthropic' | 'none'"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/types/config.types.ts",
+          "releaseTag": "Beta",
+          "name": "AIProviderType",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-ai!AIServiceAccessRefusal:type",
+          "docComment": "/**\n * One of {@link AI_SERVICE_ACCESS_REFUSALS}.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type AIServiceAccessRefusal = "
+            },
+            {
+              "kind": "Content",
+              "text": "(typeof "
+            },
+            {
+              "kind": "Reference",
+              "text": "AI_SERVICE_ACCESS_REFUSALS",
+              "canonicalReference": "@genesislcap/foundation-ai!AI_SERVICE_ACCESS_REFUSALS:var"
+            },
+            {
+              "kind": "Content",
+              "text": ")[keyof typeof "
+            },
+            {
+              "kind": "Reference",
+              "text": "AI_SERVICE_ACCESS_REFUSALS",
+              "canonicalReference": "@genesislcap/foundation-ai!AI_SERVICE_ACCESS_REFUSALS:var"
+            },
+            {
+              "kind": "Content",
+              "text": "]"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/transports/ai-service-error.ts",
+          "releaseTag": "Beta",
+          "name": "AIServiceAccessRefusal",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 6
+          }
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-ai!aiServiceAccessRefusalOf:function(1)",
+          "docComment": "/**\n * The access refusal behind a 401 or 403 from the app's router, which carries no `code`.\n *\n * 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.\n *\n * @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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function aiServiceAccessRefusalOf(status: "
+            },
+            {
+              "kind": "Content",
+              "text": "number"
+            },
+            {
+              "kind": "Content",
+              "text": ", payload: "
+            },
+            {
+              "kind": "Content",
+              "text": "unknown"
+            },
+            {
+              "kind": "Content",
+              "text": ", bodyText?: "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "AIServiceAccessRefusal",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceAccessRefusal:type"
+            },
+            {
+              "kind": "Content",
+              "text": " | undefined"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/transports/ai-service-error.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 7,
+            "endIndex": 9
+          },
+          "releaseTag": "Beta",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "status",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "payload",
+              "parameterTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "bodyText",
+              "parameterTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "isOptional": true
+            }
+          ],
+          "name": "aiServiceAccessRefusalOf"
+        },
+        {
+          "kind": "Class",
+          "canonicalReference": "@genesislcap/foundation-ai!AIServiceError:class",
+          "docComment": "/**\n * 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}.\n *\n * 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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare class AIServiceError extends "
+            },
+            {
+              "kind": "Reference",
+              "text": "Error",
+              "canonicalReference": "!Error:interface"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "fileUrlPath": "src/transports/ai-service-error.ts",
+          "releaseTag": "Beta",
+          "isAbstract": false,
+          "name": "AIServiceError",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "Constructor",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceError:constructor(1)",
+              "docComment": "/**\n * Constructs a new instance of the `AIServiceError` class\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "constructor(\n    vendorLabel: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", code: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AIServiceRefusal",
+                  "canonicalReference": "@genesislcap/foundation-ai!AIServiceRefusal:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    status: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    detail?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ");"
+                }
+              ],
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "vendorLabel",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "code",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "status",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 5,
+                    "endIndex": 6
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "detail",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 7,
+                    "endIndex": 8
+                  },
+                  "isOptional": true
+                }
+              ]
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceError#code:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly code: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AIServiceRefusal",
+                  "canonicalReference": "@genesislcap/foundation-ai!AIServiceRefusal:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "code",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceError#detail:member",
+              "docComment": "/**\n * The service's own message, for the console. Never shown to the user.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly detail?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "detail",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceError#status:member",
+              "docComment": "/**\n * HTTP status, or the err frame's status on the framed path.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly status: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "status",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceError#terminal:member",
+              "docComment": "/**\n * Whether sending the request again cannot help.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "name: "
+                  "text": "get terminal(): "
                 },
                 {
                   "kind": "Content",
-                  "text": "string"
+                  "text": "boolean"
                 },
                 {
                   "kind": "Content",
                   "text": ";"
                 }
               ],
-              "isReadonly": false,
+              "isReadonly": true,
               "isOptional": false,
               "releaseTag": "Beta",
-              "name": "name",
+              "name": "terminal",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
                 "endIndex": 2
-              }
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
             },
             {
-              "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/foundation-ai!AIProviderRegistryStatusEntry#status:member",
-              "docComment": "/**\n * The provider's `getStatus()` result, or `null` if unavailable.\n */\n",
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceError#vendorLabel:member",
+              "docComment": "/**\n * Vendor label of the transport that was refused (e.g. `'Gemini'`).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "status: "
-                },
-                {
-                  "kind": "Reference",
-                  "text": "AIStatus",
-                  "canonicalReference": "@genesislcap/foundation-ai!AIStatus:interface"
+                  "text": "readonly vendorLabel: "
                 },
                 {
                   "kind": "Content",
-                  "text": " | null"
+                  "text": "string"
                 },
                 {
                   "kind": "Content",
                   "text": ";"
                 }
               ],
-              "isReadonly": false,
+              "isReadonly": true,
               "isOptional": false,
               "releaseTag": "Beta",
-              "name": "status",
+              "name": "vendorLabel",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 3
-              }
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
             }
           ],
-          "extendsTokenRanges": []
+          "extendsTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "implementsTokenRanges": []
         },
         {
           "kind": "TypeAlias",
-          "canonicalReference": "@genesislcap/foundation-ai!AIProviderType:type",
-          "docComment": "/**\n * All AI provider identifiers (server, client, unconfigured).\n *\n * @beta\n */\n",
+          "canonicalReference": "@genesislcap/foundation-ai!AIServiceErrorCode:type",
+          "docComment": "/**\n * One of {@link AI_SERVICE_ERROR_CODES}.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
-              "text": "export type AIProviderType = "
+              "text": "export type AIServiceErrorCode = "
             },
             {
               "kind": "Content",
-              "text": "'openai' | 'chrome' | 'gemini' | 'anthropic' | 'none'"
+              "text": "(typeof "
+            },
+            {
+              "kind": "Reference",
+              "text": "AI_SERVICE_ERROR_CODES",
+              "canonicalReference": "@genesislcap/foundation-ai!AI_SERVICE_ERROR_CODES:var"
+            },
+            {
+              "kind": "Content",
+              "text": ")[keyof typeof "
+            },
+            {
+              "kind": "Reference",
+              "text": "AI_SERVICE_ERROR_CODES",
+              "canonicalReference": "@genesislcap/foundation-ai!AI_SERVICE_ERROR_CODES:var"
+            },
+            {
+              "kind": "Content",
+              "text": "]"
             },
             {
               "kind": "Content",
               "text": ";"
             }
           ],
-          "fileUrlPath": "src/types/config.types.ts",
+          "fileUrlPath": "src/transports/ai-service-error.ts",
           "releaseTag": "Beta",
-          "name": "AIProviderType",
+          "name": "AIServiceErrorCode",
           "typeTokenRange": {
             "startIndex": 1,
-            "endIndex": 2
+            "endIndex": 6
+          }
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-ai!aiServiceErrorCodeOf:function(1)",
+          "docComment": "/**\n * The code, when it is one of {@link AI_SERVICE_ERROR_CODES}; otherwise `undefined`.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function aiServiceErrorCodeOf(code: "
+            },
+            {
+              "kind": "Content",
+              "text": "unknown"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "AIServiceErrorCode",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceErrorCode:type"
+            },
+            {
+              "kind": "Content",
+              "text": " | undefined"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/transports/ai-service-error.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 5
+          },
+          "releaseTag": "Beta",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "code",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "aiServiceErrorCodeOf"
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-ai!AIServiceRefusal:type",
+          "docComment": "/**\n * 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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type AIServiceRefusal = "
+            },
+            {
+              "kind": "Reference",
+              "text": "AIServiceErrorCode",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceErrorCode:type"
+            },
+            {
+              "kind": "Content",
+              "text": " | "
+            },
+            {
+              "kind": "Reference",
+              "text": "AIServiceAccessRefusal",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceAccessRefusal:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/transports/ai-service-error.ts",
+          "releaseTag": "Beta",
+          "name": "AIServiceRefusal",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 4
           }
         },
         {
@@ -7527,7 +8103,16 @@
             },
             {
               "kind": "Content",
-              "text": "<{\n        ok: true;\n        result: T;\n        reason?: never;\n    } | {\n        ok: false;\n        result?: never;\n        reason: "
+              "text": "<{\n        ok: true;\n        result: T;\n        reason?: never;\n        code?: never;\n        terminal?: never;\n    } | {\n        ok: false;\n        result?: never;\n        reason: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Exclude",
+              "canonicalReference": "!Exclude:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
             },
             {
               "kind": "Reference",
@@ -7536,7 +8121,16 @@
             },
             {
               "kind": "Content",
-              "text": ";\n    }>;\n    completeSubAgent?: (result: unknown) => void;\n    releaseAgent?: () => void;\n    endPhase?: () => void;\n    condenseWhen: (policy: "
+              "text": ", 'ai_service_error'>;\n        code?: never;\n        terminal?: never;\n    } | {\n        ok: false;\n        result?: never;\n        reason: 'ai_service_error';\n        code: "
+            },
+            {
+              "kind": "Reference",
+              "text": "AIServiceRefusal",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceRefusal:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n        terminal: boolean;\n    }>;\n    completeSubAgent?: (result: unknown) => void;\n    releaseAgent?: () => void;\n    endPhase?: () => void;\n    condenseWhen: (policy: "
             },
             {
               "kind": "Reference",
@@ -7545,7 +8139,16 @@
             },
             {
               "kind": "Content",
-              "text": ") => void;\n}) => "
+              "text": ") => void;\n    turnSignal?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "AbortSignal",
+              "canonicalReference": "!AbortSignal:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n}) => "
             },
             {
               "kind": "Reference",
@@ -7579,7 +8182,7 @@
           ],
           "typeTokenRange": {
             "startIndex": 5,
-            "endIndex": 23
+            "endIndex": 29
           }
         },
         {
@@ -9481,6 +10084,52 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-ai!DEFAULT_AI_SERVICE_ERROR_MESSAGES:var",
+          "docComment": "/**\n * 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).\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "DEFAULT_AI_SERVICE_ERROR_MESSAGES: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Readonly",
+              "canonicalReference": "!Readonly:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "Record",
+              "canonicalReference": "!Record:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "AIServiceRefusal",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceRefusal:type"
+            },
+            {
+              "kind": "Content",
+              "text": ", string>>"
+            }
+          ],
+          "fileUrlPath": "src/transports/ai-service-error.ts",
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "DEFAULT_AI_SERVICE_ERROR_MESSAGES",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 7
+          }
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/foundation-ai!DEFAULT_AI_TIERS:var",
@@ -11131,6 +11780,34 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/foundation-ai!InteractionRequestOptions#signal:member",
+              "docComment": "/**\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "signal?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AbortSignal",
+                  "canonicalReference": "!AbortSignal:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "signal",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/foundation-ai!InteractionRequestOptions#timeoutMs:member",
@@ -11418,6 +12095,48 @@
           "parameters": [],
           "name": "isSpeechRecognitionAvailable"
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-ai!isTerminalAIServiceRefusal:function(1)",
+          "docComment": "/**\n * 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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "isTerminalAIServiceRefusal: (code: "
+            },
+            {
+              "kind": "Reference",
+              "text": "AIServiceRefusal",
+              "canonicalReference": "@genesislcap/foundation-ai!AIServiceRefusal:type"
+            },
+            {
+              "kind": "Content",
+              "text": ") => "
+            },
+            {
+              "kind": "Content",
+              "text": "boolean"
+            }
+          ],
+          "fileUrlPath": "src/transports/ai-service-error.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Beta",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "code",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "name": "isTerminalAIServiceRefusal"
+        },
         {
           "kind": "Class",
           "canonicalReference": "@genesislcap/foundation-ai!MalformedFunctionCallError:class",
@@ -13501,7 +14220,7 @@
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/foundation-ai!SubAgentFailureReason:type",
-          "docComment": "/**\n * Why a sub-agent run ended without producing a structured result via `completeSubAgent`. Surfaced on the `{ ok: false }` branch of `requestSubAgent` so the parent tool handler can decide how to recover.\n *\n * - `max_iterations` — the sub-agent's tool loop ended without calling its completion tool (hit the iteration cap, or — defensively — a provider ignored forced tool use and returned a free-text turn). - `malformed_tool_call` — the provider repeatedly returned an unparseable tool call (e.g. Gemini `MALFORMED_FUNCTION_CALL`) after retries. - `empty_response` — the model repeatedly returned an empty response after retries. - `unknown_tool_limit` — the model repeatedly called tools that aren't available to it. - `timeout` — the sub-agent did not finish within {@link SubAgentRequestOptions.timeoutMs} (its run was aborted), or a transport request timed out inside the child's own run. - `response_truncated` — a turn stopped at the provider's output-token cap with an incomplete tool call; deterministic, so it is not retried. - `refusal` — a safety-classifier decline (e.g. Fable 5 `stop_reason: 'refusal'`), which returns empty content; deterministic, so it is not retried. - `budget_exhausted` — the AI-spend budget is used up and the proxy refused the request (HTTP 402). **Terminal for the parent too, and enforced**: the parent driver ends its own turn as soon as this outcome comes back, instead of appending it as a tool result and calling the model again into the same wall. 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.\n *\n * 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.\n *\n * @beta\n */\n",
+          "docComment": "/**\n * Why a sub-agent run ended without producing a structured result via `completeSubAgent`. Surfaced on the `{ ok: false }` branch of `requestSubAgent` so the parent tool handler can decide how to recover.\n *\n * - `max_iterations` — the sub-agent's tool loop ended without calling its completion tool (hit the iteration cap, or — defensively — a provider ignored forced tool use and returned a free-text turn). - `malformed_tool_call` — the provider repeatedly returned an unparseable tool call (e.g. Gemini `MALFORMED_FUNCTION_CALL`) after retries. - `empty_response` — the model repeatedly returned an empty response after retries. - `unknown_tool_limit` — the model repeatedly called tools that aren't available to it. - `timeout` — the sub-agent did not finish within {@link SubAgentRequestOptions.timeoutMs} (its run was aborted), or a transport request timed out inside the child's own run. - `response_truncated` — a turn stopped at the provider's output-token cap with an incomplete tool call; deterministic, so it is not retried. - `refusal` — a safety-classifier decline (e.g. Fable 5 `stop_reason: 'refusal'`), which returns empty content; deterministic, so it is not retried. - `budget_exhausted` — the AI-spend budget is used up and the proxy refused the request (HTTP 402). **Terminal for the parent too, and enforced**: the parent driver ends its own turn as soon as this outcome comes back, instead of appending it as a tool result and calling the model again into the same wall. 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.\n *\n * 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.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -13509,7 +14228,7 @@
             },
             {
               "kind": "Content",
-              "text": "'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated' | 'refusal' | 'budget_exhausted'\n/**\n * The upstream vendor refused the account (GENC-1506). **Terminal for the PARENT turn too**, on the\n * same reasoning as `budget_exhausted`: the parent cannot recover by calling the model again,\n * because the very next call hits the same wall. N batched sub-agent calls would otherwise cost N\n * doomed children AND a doomed parent call.\n */\n | 'provider_refused'\n/**\n * The sub-agent was stopped because continuing would have overrun the context\n * window (GENC-1567). **Terminal for the PARENT turn too**, on the same\n * reasoning as `budget_exhausted` and `provider_refused`: the parent shares the\n * conversation whose size caused it, so calling the model again hits the same\n * wall.\n */\n | 'context_exhausted'"
+              "text": "'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated' | 'refusal' | 'budget_exhausted'\n/**\n * The upstream vendor refused the account (GENC-1506). **Terminal for the PARENT turn too**, on the\n * same reasoning as `budget_exhausted`: the parent cannot recover by calling the model again,\n * because the very next call hits the same wall. N batched sub-agent calls would otherwise cost N\n * doomed children AND a doomed parent call.\n */\n | 'provider_refused'\n/**\n * The sub-agent was stopped because continuing would have overrun the context window\n * (GENC-1567). Re-invoking it with the same conversation stops it the same way. The parent's turn\n * goes on, but it shares the conversation whose size caused this, so its own next model call is\n * likely to stop on the same guard.\n */\n | 'context_exhausted'\n/**\n * The app's AI service refused the sub-agent's request (GENC-1611). The outcome carries the\n * refusal's `code` and whether it is `terminal`: re-invoking the sub-agent with the same request\n * gets the same refusal, so recover without calling it again. Only a `VENDOR_UNREACHABLE` refusal\n * is not terminal. Even so, a refusal from your own vendor that is about the service (for example\n * `VENDOR_UNREACHABLE`) still ends this turn; retry on the user's next message, not in the\n * handler.\n *\n * **Terminal for the PARENT turn too only when** the refusal is about the service rather than the\n * child's own request (a missing or unusable key, no session or no right, the vendor unreachable)\n * and the child called the parent's own vendor, unless a completion or a handoff from the same\n * batch goes on past it. Otherwise the parent is told and its turn goes on. The user is shown a\n * key, access, model (`MODEL_NOT_ALLOWED`) or reachability refusal's sentence once per user\n * message; `REQUEST_TOO_LARGE`, `BAD_REQUEST` and `FALLBACKS_NOT_SUPPORTED` are left to the parent\n * and the console.\n */\n | 'ai_service_error'"
             },
             {
               "kind": "Content",
@@ -14082,7 +14801,7 @@
             },
             {
               "kind": "Content",
-              "text": "'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted' | 'provider-refused'\n/**\n * The turn was stopped because continuing it would have overrun the model's\n * context window (GENC-1567). Pre-emptive: the driver ends the tool loop at\n * the edge rather than issuing a request the provider would reject, so the\n * transcript stays intact and compaction is still possible.\n */\n | 'context-exhausted'"
+              "text": "'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted' | 'provider-refused'\n/**\n * The turn was stopped because continuing it would have overrun the model's\n * context window (GENC-1567). Pre-emptive: the driver ends the tool loop at\n * the edge rather than issuing a request the provider would reject, so the\n * transcript stays intact and compaction is still possible.\n */\n | 'context-exhausted'\n/**\n * The app's AI service refused the request with one of `AI_SERVICE_ERROR_CODES` (GENC-1611): a\n * configuration error such as a missing API key, or the vendor still unreachable after the\n * retries. The transcript says what is wrong in words for the user.\n */\n | 'ai-service-error'"
             },
             {
               "kind": "Content",