@genesislcap/foundation-ai 14.469.0 → 14.470.0

package/dist/foundation-ai.d.ts

@@ -266,6 +266,12 @@ export declare class AnthropicTransport implements AITransport, ChatTransport, C
      * fields instead so its session total stays attributed to chat turns only.
      */
     private lifetimeCostUsd;
+    /**
+     * Estimated USD saved by prompt caching vs paying full input price, accumulated across
+     * every request. Net of cache-write premiums, so it can be briefly negative before reads
+     * accrue. Surfaced alongside `getLifetimeCost`.
+     */
+    private lifetimeSavingsUsd;
     constructor(config?: AnthropicTransportConfig);
     getConfig(): {
         provider: 'anthropic';
@@ -274,10 +280,35 @@ export declare class AnthropicTransport implements AITransport, ChatTransport, C
     };
     /** 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. */
+    /** Estimated USD saved by prompt caching (net of write premiums) across this instance. */
+    getLifetimeSavings(): number;
+    /** Reset the lifetime cost + savings counters. Intended for chat-clear / new-session flows. */
     resetLifetimeCost(): void;
     sendStructuredPrompt(options: StructuredPromptOptions): Promise<string>;
     sendChatMessage(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): Promise<ChatMessage>;
+    /**
+     * Place prompt-cache breakpoints on the outgoing request per the resolved {@link CachePolicy}.
+     * A breakpoint is `cache_control: {type:'ephemeral'}` on a content block / tool / system block;
+     * the API caches the byte-exact prefix up to it. Below a model's minimum cacheable prefix the
+     * marker is silently ignored (no error), so placing one is always safe.
+     *
+     * Render order is tools → system → messages, so a breakpoint's cached prefix covers everything
+     * before it:
+     * - `'tools'`   — last tool (caches the tool block; survives a later system-prompt change).
+     * - `'prompt'`  — system block (caches tools + system); falls back to the last tool when there
+     *   is no system prompt.
+     * - `'history'` — last stored message block (caches tools + system + the whole stored history),
+     *   keeping the system-tier breakpoint as a cheaper fallback. The injected, never-stored tail
+     *   context (if any) sits after this and is intentionally left uncached.
+     */
+    private applyCacheControl;
+    /**
+     * Append never-stored tail context (already framed by the caller) as the final block of the
+     * outbound messages. Called AFTER `applyCacheControl`, so any `'history'` breakpoint sits
+     * on the last *stored* block and this per-turn volatile block stays outside the cached prefix.
+     * At a model-call the last message is user-role; if not (defensive), start a fresh user turn.
+     */
+    private appendTailContext;
     private static readonly TOKENS_PER_MILLION;
     private static readonly COST_DECIMAL_PLACES;
     /**
@@ -334,6 +365,50 @@ declare interface AnthropicTransportConfig {
     maxTokens?: number;
 }
 
+/**
+ * Prompt-cache policy for a chat request, resolved per turn. **Provider-neutral intent,
+ * provider-specific effect** — read this carefully, the two providers differ sharply:
+ *
+ * - **Anthropic** — `scope` controls where explicit `cache_control` breakpoints are placed
+ *   (see each variant). This is the *only* way Anthropic caches; no scope → no caching.
+ * - **Gemini** — `scope` is effectively a **no-op**. Gemini 2.5+ does *implicit* caching
+ *   automatically and always-on, caching as much of the stable prefix as it can (everything up
+ *   to the volatile tail) on every request — regardless of `scope`, **including under
+ *   `'default'`**. We issue no explicit `cachedContent`, so nothing here changes the Gemini
+ *   request. Do NOT expect `'tools'`/`'prompt'` to *limit* Gemini caching, nor `'default'` to
+ *   *disable* it; the most you control on Gemini is keeping the prefix byte-stable so implicit
+ *   caching can engage.
+ *
+ * Omit, or use `{ scope: 'default' }`, to add no breakpoints of our own.
+ *
+ * @beta
+ */
+export declare type CachePolicy = {
+    /**
+     * No breakpoints from us — you get the provider's own default behaviour (Anthropic: no
+     * caching; Gemini: automatic implicit caching). Equivalent to omitting `cachePolicy`.
+     */
+    scope: 'default';
+} | {
+    /**
+     * How far up the request the (Anthropic) cache prefix extends — slide it to the last
+     * point that is byte-stable turn-to-turn:
+     * - `'tools'` — cache the tool definitions only. Use when the system prompt is *volatile*
+     *   but tools are stable; tools render first, so this cache survives a system change.
+     * - `'prompt'` — cache tools + system prompt. For agents whose system prompt is stable.
+     * - `'history'` — cache tools + system + the full *stored* conversation. The breakpoint
+     *   sits on the last stored message block, so it caches as much as possible without
+     *   busting on the volatile tail; only the injected, never-stored tail context is left
+     *   uncached. Needs an append-only, byte-stable history to actually hit.
+     */
+    scope: 'tools' | 'prompt' | 'history';
+    /**
+     * Cache time-to-live (Anthropic only). `'5m'` (default) suits back-to-back turns; `'1h'`
+     * keeps the entry warm across longer gaps at a higher write cost. Ignored on Gemini.
+     */
+    ttl?: '5m' | '1h';
+};
+
 /**
  * Agent engine configuration for the chat assistant.
  *
@@ -591,6 +666,25 @@ export declare interface ChatRequestOptions {
      * @beta
      */
     temperature?: number;
+    /**
+     * Prompt-cache policy for this turn. See {@link CachePolicy} — Anthropic places explicit
+     * `cache_control` breakpoints per `scope`; Gemini caches implicitly regardless. Omit to add
+     * no breakpoints of our own.
+     *
+     * @beta
+     */
+    cachePolicy?: CachePolicy;
+    /**
+     * Operator/volatile context to inject at the **very tail** of the outbound messages — after the
+     * stored history *and* after any cache breakpoint — so the model sees it every turn without
+     * invalidating the cached prefix. **Never persisted to stored history**; it is re-supplied per
+     * request. Anthropic appends it as a text block on the final user turn; Gemini as a trailing
+     * `user` content. The caller is responsible for any framing (e.g. a `<system-reminder>` /
+     * `<current_context>` marker) so the model reads it as ambient context, not user input.
+     *
+     * @beta
+     */
+    tailContext?: string;
 }
 
 /**
@@ -874,6 +968,20 @@ export declare type ChatToolHandlers<TSubAgent extends {
      * guards the flow can release.
      */
     releaseAgent?: () => void;
+    /**
+     * Mark the agent's current *phase* as finished, collapsing every payload
+     * registered with `condenseWhen({ on: { kind: 'phaseEnd' } })` during that
+     * phase out of the to-model history (stored history is untouched). Advances
+     * an app-controlled phase epoch — repeatable, with no terminal effect
+     * (unlike `releaseAgent` / `completeSubAgent`): call it at each phase
+     * boundary and the next phase's reads accumulate against a fresh epoch.
+     *
+     * Intended for long multi-phase stateful flows that want to trim a phase's
+     * grounding reads (entity dumps, validations) as they advance, without
+     * ending the agent. Deliberately decoupled from any state-machine library:
+     * call it from whichever tool handlers advance the agent's own state.
+     */
+    endPhase?: () => void;
     /**
      * Declare how THIS tool call's payload(s) should be condensed out of the
      * history sent to the model once they go stale (see {@link CondensePolicy}).
@@ -1100,6 +1208,17 @@ export declare type CondenseResult = 'pointer' | 'drop' | {
  *   re-selects the same agent on the next turn it is treated as the same
  *   activation, so use `turnEnd` (not `agentEnd`) when you want per-request
  *   collapse on a non-stateful agent.
+ * - `phaseEnd` — collapse once the agent declares the current *phase* finished by
+ *   calling `endPhase()` from a tool handler. A phase is an app-defined span
+ *   *within* one activation — narrower than `agentEnd` (which only fires at whole-
+ *   agent disposal) and phase-aware in a way `age:N` is not. The intended use is a
+ *   long, multi-phase stateful flow (e.g. a bootstrap journey) that wants to trim
+ *   each phase's grounding reads as it moves on, without waiting for the whole
+ *   agent to end. It is NOT tied to any state-machine library: the author fires
+ *   `endPhase()` from whichever tool handlers advance their own notion of state,
+ *   exactly as `condenseWhen` is itself called from tool handlers. If `endPhase()`
+ *   is never called, the payload still collapses at `agentEnd` — so `phaseEnd`
+ *   degrades to `agentEnd` rather than never firing.
  *
  * @beta
  */
@@ -1113,6 +1232,8 @@ export declare type CondenseTrigger = {
     kind: 'turnEnd';
 } | {
     kind: 'agentEnd';
+} | {
+    kind: 'phaseEnd';
 };
 
 /**
@@ -1134,7 +1255,12 @@ export declare type CondenseTrigger = {
 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. */
+    /**
+     * Estimated USD saved by prompt caching vs paying full input price, accumulated across this
+     * instance. Net of cache-write premiums, so it can be briefly negative before reads accrue.
+     */
+    getLifetimeSavings(): number;
+    /** Reset the lifetime cost + savings counters. Intended for chat-clear / new-session flows. */
     resetLifetimeCost(): void;
 }
 
@@ -1268,6 +1394,12 @@ export declare class GeminiTransport implements AITransport, ChatTransport, Cost
      * fields instead so its session total stays attributed to chat turns only.
      */
     private lifetimeCostUsd;
+    /**
+     * Estimated USD saved by context caching vs paying full input price, accumulated across
+     * every request. Gemini implicit caching has no write premium, so this is always ≥ 0.
+     * Surfaced alongside `getLifetimeCost`.
+     */
+    private lifetimeSavingsUsd;
     constructor(config?: GeminiTransportConfig);
     getConfig(): {
         provider: 'gemini';
@@ -1276,7 +1408,9 @@ export declare class GeminiTransport implements AITransport, ChatTransport, Cost
     };
     /** 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. */
+    /** Estimated USD saved by context caching across this instance (implicit caching → always ≥ 0). */
+    getLifetimeSavings(): number;
+    /** Reset the lifetime cost + savings counters. Intended for chat-clear / new-session flows. */
     resetLifetimeCost(): void;
     sendStructuredPrompt(options: StructuredPromptOptions): Promise<string>;
     sendChatMessage(history: ChatMessage[], userMessage: string, options?: ChatRequestOptions): Promise<ChatMessage>;
@@ -1643,6 +1777,42 @@ export declare interface ResolveAIConfigOptions {
     preferChrome?: boolean;
 }
 
+/**
+ * Thrown when a response stops at `stop_reason: 'max_tokens'` while it still
+ * carries tool calls. The model ran out of its output-token budget mid-stream,
+ * so the truncated tool call's argument JSON was cut off before it closed — the
+ * arguments are incomplete and the call is unusable (e.g. a `vfs_write` whose
+ * `content` never finished serializing). Rather than hand a corrupt tool call to
+ * the caller — which silently runs with missing args and tends to be retried into
+ * an identical wall — the transport raises this so the failure is loud and
+ * diagnosable.
+ *
+ * It is deterministic: re-issuing the same request hits the same cap. The remedy
+ * is to raise the provider's `maxTokens` (see {@link AnthropicAIConfig.maxTokens})
+ * or to split the work into smaller outputs — not to retry verbatim.
+ *
+ * @beta
+ */
+export declare class ResponseTruncatedError extends Error {
+    /** The model that produced the truncated response. */
+    readonly model: string;
+    /** The `max_tokens` cap the request was sent with. */
+    readonly maxTokens: number;
+    /** Output tokens generated before truncation, when the usage block is present. */
+    readonly outputTokens: number | undefined;
+    /** Names of the tool call(s) on the truncated turn (the last is the cut-off one). */
+    readonly toolNames: string[];
+    constructor(
+    /** The model that produced the truncated response. */
+    model: string, 
+    /** The `max_tokens` cap the request was sent with. */
+    maxTokens: number, 
+    /** Output tokens generated before truncation, when the usage block is present. */
+    outputTokens: number | undefined, 
+    /** Names of the tool call(s) on the truncated turn (the last is the cut-off one). */
+    toolNames: string[]);
+}
+
 /**
  * Server-proxy AI configuration (client calls your server; server calls the provider).
  *
@@ -1698,10 +1868,12 @@ declare interface StructuredPromptOptions {
  *   available to it.
  * - `timeout` — the sub-agent did not finish within
  *   {@link SubAgentRequestOptions.timeoutMs}; its run was aborted.
+ * - `response_truncated` — a turn stopped at the provider's output-token cap with
+ *   an incomplete tool call; deterministic, so it is not retried.
  *
  * @beta
  */
-export declare type SubAgentFailureReason = 'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout';
+export declare type SubAgentFailureReason = 'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated';
 
 /**
  * Options passed to `requestSubAgent` at call time.

package/package.json

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