@genesislcap/foundation-ai 15.19.6 → 15.20.0

package/dist/foundation-ai.d.ts

@@ -813,6 +813,8 @@ export declare type ChatAttachment = ChatTextAttachment | ChatImageAttachment;
 export declare interface ChatConfig {
     /** UI display settings — toggles, file upload, animations, etc. */
     ui?: ChatUiConfig;
+    /** Context-window headroom and the compaction gate. */
+    context?: ChatContextConfig;
     /** Cost tab display and opt-in build-history persistence. */
     costHistory?: ChatCostHistoryConfig;
     /** Agent engine settings — iteration limits, handoff caps, classifier tuning. */
@@ -823,6 +825,74 @@ export declare interface ChatConfig {
     picker?: ChatAgentPickerConfig;
 }
 
+/**
+ * Context-window management for the chat assistant (GENC-1567).
+ *
+ * The assistant reserves headroom rather than letting the conversation run to
+ * the edge of the model's window and compacting automatically at the last
+ * moment. The reason is that a turn is not atomic in cost: a send allowed just
+ * under a threshold can run a long tool loop and add a large amount on its own,
+ * so a threshold set as a fraction of the window bounds only the size at the
+ * START of a turn. What has to be bounded is the growth of one whole turn — and
+ * that is a number of tokens, not a percentage.
+ *
+ * It is also why compaction here is user-initiated rather than automatic:
+ * machine state for a stateful flow lives outside the transcript, so rewriting
+ * the transcript underneath a mid-flow agent is a judgement the user should
+ * make, at a moment of their choosing, rather than something that happens to
+ * them mid-journey.
+ *
+ * @beta
+ */
+export declare interface ChatContextConfig {
+    /**
+     * Whether the context gate is active at all.
+     * - `true` or `undefined` (default) — warn, then block, as the window fills
+     * - `false` — no warning and no block; the context indicator still shows
+     *
+     * An escape hatch for a host that would rather take the provider error than
+     * ever have its composer disabled.
+     */
+    enabled?: boolean;
+    /**
+     * Tokens kept free for a single turn to complete in. The assistant blocks new
+     * sends once the conversation would leave less than this much headroom.
+     *
+     * Deliberately a token count and not a percentage of the window: the reserve
+     * needs to cover the worst-case growth of one agentic turn, which does not
+     * scale with the model's context size. A percentage gives a 1M-token model a
+     * reserve far larger than any turn needs while potentially starving a
+     * 200k-token one. Default: `25000`.
+     */
+    reserveTokens?: number;
+    /**
+     * How many reserves ahead of the block the warning appears, as a multiple of
+     * {@link ChatContextConfig.reserveTokens}. At the default `2` the warning
+     * arrives one full reserve before the block, leaving room to compact at a
+     * convenient moment rather than at the wall. Default: `2`.
+     */
+    warnMultiplier?: number;
+    /**
+     * Context window to assume when the active provider reports none.
+     *
+     * Without a limit there is no percentage and so no gate, which is the right
+     * default — guessing a window and blocking against the guess would be worse
+     * than not blocking. Set this when you know the window but your provider
+     * does not report it.
+     */
+    fallbackContextLimit?: number;
+    /**
+     * Smallest reclaim, in tokens, for compaction to be worth running and to be
+     * offered as the way past a block.
+     *
+     * A compaction spends a summarizer call on most of the conversation, so a
+     * plan that frees less than this costs more than it buys — and, when the
+     * composer is blocked, would be an escape that does not actually clear the
+     * block. Default: `5000`.
+     */
+    minReclaimTokens?: number;
+}
+
 /**
  * Cost tab and build-history settings.
  *
@@ -2065,6 +2135,54 @@ export declare type CondenseTrigger = {
     kind: 'phaseEnd';
 };
 
+/**
+ * Thrown when the provider rejects a request because the prompt exceeds the
+ * model's context window.
+ *
+ * Terminal for the attempt in the same sense as its siblings — retrying the same
+ * request cannot clear it — but unlike them it is terminal only until the user
+ * acts. Compaction genuinely resolves it, which is why the copy says so.
+ *
+ * @beta
+ */
+export declare class ContextOverflowError extends Error {
+    /** Vendor label of the transport that refused (e.g. `'Anthropic'`). */
+    readonly vendorLabel: string;
+    /** Prompt size the provider reported, when its message stated one. */
+    readonly promptTokens?: number;
+    /** Window size the provider reported, when its message stated one. */
+    readonly limitTokens?: number;
+    /** The provider's human-readable message, verbatim, for the log. Never shown to the user. */
+    readonly detail?: string;
+    constructor(
+    /** Vendor label of the transport that refused (e.g. `'Anthropic'`). */
+    vendorLabel: string, 
+    /** Prompt size the provider reported, when its message stated one. */
+    promptTokens?: number, 
+    /** Window size the provider reported, when its message stated one. */
+    limitTokens?: number, 
+    /** The provider's human-readable message, verbatim, for the log. Never shown to the user. */
+    detail?: string);
+}
+
+/**
+ * Classify a rejection as a context overflow, returning the reported figures
+ * when the provider stated them, or `undefined` when it is something else.
+ *
+ * Vendor-agnostic, unlike `providerRefusalOf`: the failure is a property of
+ * the request rather than of a vendor's account model, both observed shapes are
+ * a `400` with a phrase, and — critically — a false positive here cannot break a
+ * retry ladder, so the caution that scopes the spend classifier to Anthropic does
+ * not apply.
+ *
+ * @beta
+ */
+export declare function contextOverflowOf(_vendor: AIProviderType | undefined, status: number | undefined, payload: unknown): {
+    promptTokens?: number;
+    limitTokens?: number;
+    message?: string;
+} | undefined;
+
 /**
  * Optional capability implemented by transports that can report the estimated
  * USD cost they have incurred over their lifetime.
@@ -2160,6 +2278,18 @@ export declare interface CriteriaInterpretContext {
  */
 export declare const DEFAULT_BUDGET_EXHAUSTED_MESSAGE = "You've reached your AI usage limit. Contact your administrator to raise it.";
 
+/**
+ * The single sentence shown to a user whose request overran the context window.
+ *
+ * Unlike {@link DEFAULT_PROVIDER_REFUSED_MESSAGE} this one deliberately DOES name
+ * a cause and an action, because both are true and both are the user's: they can
+ * see the conversation that caused it, and compacting fixes it. Telling them it
+ * "needs no action from you" would be the wrong advice as well as the wrong fact.
+ *
+ * @beta
+ */
+export declare const DEFAULT_CONTEXT_OVERFLOW_MESSAGE: string;
+
 /**
  * The single sentence shown to a user whose provider has refused — the transcript bubble the chat
  * driver appends, and the string ai-service reuses for its own generation surfaces.
@@ -3072,7 +3202,15 @@ export declare type SubAgentFailureReason = 'max_iterations' | 'malformed_tool_c
 * because the very next call hits the same wall. N batched sub-agent calls would otherwise cost N
 * doomed children AND a doomed parent call.
 */
-| 'provider_refused';
+| '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.
+*/
+| 'context_exhausted';
 
 /**
  * Options passed to `requestSubAgent` at call time.
@@ -3204,7 +3342,14 @@ export declare interface TokenRates {
  *
  * @beta
  */
-export declare type TurnFailureReason = 'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted' | 'provider-refused';
+export declare type TurnFailureReason = 'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted' | 'provider-refused'
+/**
+* The turn was stopped because continuing it would have overrun the model's
+* context window (GENC-1567). Pre-emptive: the driver ends the tool loop at
+* the edge rather than issuing a request the provider would reject, so the
+* transcript stays intact and compaction is still possible.
+*/
+| 'context-exhausted';
 
 /**
  * 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.19.6",
+  "version": "15.20.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -52,17 +52,17 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.19.6",
-    "@genesislcap/genx": "15.19.6",
-    "@genesislcap/rollup-builder": "15.19.6",
-    "@genesislcap/ts-builder": "15.19.6",
-    "@genesislcap/uvu-playwright-builder": "15.19.6",
-    "@genesislcap/vite-builder": "15.19.6",
-    "@genesislcap/webpack-builder": "15.19.6"
+    "@genesislcap/foundation-testing": "15.20.0",
+    "@genesislcap/genx": "15.20.0",
+    "@genesislcap/rollup-builder": "15.20.0",
+    "@genesislcap/ts-builder": "15.20.0",
+    "@genesislcap/uvu-playwright-builder": "15.20.0",
+    "@genesislcap/vite-builder": "15.20.0",
+    "@genesislcap/webpack-builder": "15.20.0"
   },
   "dependencies": {
-    "@genesislcap/foundation-logger": "15.19.6",
-    "@genesislcap/foundation-utils": "15.19.6",
+    "@genesislcap/foundation-logger": "15.20.0",
+    "@genesislcap/foundation-utils": "15.20.0",
     "@microsoft/fast-foundation": "2.50.0"
   },
   "repository": {