@genesislcap/ai-assistant 14.469.0 → 14.470.0

package/src/config/config.ts

@@ -1,4 +1,5 @@
 import type {
+  CachePolicy,
   ChatInputDuringExecutionMode,
   ChatMessage,
   ChatToolChoice,
@@ -6,7 +7,7 @@ import type {
   ChatToolHandlers,
 } from '@genesislcap/foundation-ai';
 
-export type { ChatInputDuringExecutionMode, ChatToolChoice };
+export type { CachePolicy, ChatInputDuringExecutionMode, ChatToolChoice };
 
 /**
  * Context passed to `onActivate` / `onDeactivate` lifecycle hooks on an agent.
@@ -116,6 +117,29 @@ export type ToolChoiceInput =
   | ChatToolChoice
   | ((ctx: SystemPromptContext) => ChatToolChoice | Promise<ChatToolChoice>);
 
+/**
+ * Prompt-cache policy for an agent. Either a static `CachePolicy` (resolved once) or a
+ * function resolved each tool-loop iteration — pick the function form to vary it by current state
+ * (e.g. cache `'history'` in a long generating phase, `'default'` in short low-touch ones). Omit
+ * to request no caching. Resolved and applied the same way as {@link TemperatureInput}.
+ *
+ * @beta
+ */
+export type CachePolicyInput =
+  | CachePolicy
+  | ((ctx: SystemPromptContext) => CachePolicy | Promise<CachePolicy>);
+
+/**
+ * Per-turn tail context for an agent — volatile content (current file/spec, diagnostics, live
+ * state) injected at the tail of every model-call so the model sees it without invalidating the
+ * cached prefix. Either a static string or a function resolved each tool-loop iteration. **Provide
+ * raw content** — the framework frames it (wraps it in a `<system-reminder>` marker) so the model
+ * reads it as ambient context, not user input. Omit, or return an empty string, for none.
+ *
+ * @beta
+ */
+export type TailContextInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
+
 /**
  * Context passed to an agent's `onUnresolvedTool` hook when the model calls a
  * tool the driver cannot dispatch.
@@ -258,6 +282,27 @@ interface BaseAgentConfig {
    * @beta
    */
   toolChoice?: ToolChoiceInput;
+  /**
+   * Prompt-cache policy for this agent — whether to emit cache breakpoints and how far up the
+   * prefix. Either a static value or a function resolved each tool-loop iteration (vary by state).
+   * Resolved and applied the same way as {@link BaseAgentConfig.temperature}. Omit to request no
+   * caching. Provider-neutral — see {@link CachePolicyInput} / `CachePolicy` for the
+   * Anthropic-vs-Gemini behaviour. See {@link CachePolicyInput}.
+   *
+   * @beta
+   */
+  cachePolicy?: CachePolicyInput;
+  /**
+   * Volatile per-turn context injected at the tail of every model-call (after the history and any
+   * cache breakpoint), so it is seen each turn without busting the cached prefix — the place to put
+   * the changing parts (current file/spec, diagnostics, live state) that would otherwise
+   * destabilize a cached system prompt. Provide *raw* content; the framework frames it (wraps it in
+   * a `<system-reminder>` marker). Resolved per turn like {@link BaseAgentConfig.temperature}. See
+   * {@link TailContextInput}.
+   *
+   * @beta
+   */
+  tailContext?: TailContextInput;
   /**
    * Optional hook consulted when the model calls a tool the driver cannot
    * dispatch — either a *stale* tool (advertised earlier this activation but

package/src/config/define-stateful-agent.ts

@@ -1,4 +1,5 @@
 import type {
+  CachePolicy,
   ChatMessage,
   ChatToolChoice,
   ChatToolDefinition,
@@ -8,11 +9,13 @@ import { TOOL_FOLD_SYMBOL } from '../utils/tool-fold';
 import type {
   AgentConfig,
   AgentLifecycleContext,
+  CachePolicyInput,
   ChatInputDuringExecutionMode,
   ManualSelectionConfig,
   ProviderInput,
   SystemPromptContext,
   SystemPromptInput,
+  TailContextInput,
   TemperatureInput,
   ToolChoiceInput,
   ToolDefinitionsInput,
@@ -155,6 +158,23 @@ export interface StatefulAgentInit<S> {
     | ChatToolChoice
     | ((ctx: StatefulAgentContext<S>) => ChatToolChoice | Promise<ChatToolChoice>);
 
+  /**
+   * Prompt-cache policy. Either a static `CachePolicy` or a function resolved each tool-loop
+   * iteration with the current `state` — pick the function form to vary it per machine state
+   * (e.g. `'history'` in a long generating phase, `'default'` in short low-touch ones). Omit to
+   * request no caching.
+   */
+  cachePolicy?:
+    | CachePolicy
+    | ((ctx: StatefulAgentContext<S>) => CachePolicy | Promise<CachePolicy>);
+
+  /**
+   * Volatile per-turn tail context (current file/spec, diagnostics, live state). Either a static
+   * string or a function resolved each tool-loop iteration with the current `state`. Provide raw
+   * content; the framework frames it. Omit, or return an empty string, for none.
+   */
+  tailContext?: string | ((ctx: StatefulAgentContext<S>) => string | Promise<string>);
+
   /**
    * Hook consulted when the model calls a tool that isn't dispatchable in the
    * current state — a *stale* tool (valid in an earlier state of this agent) or
@@ -344,6 +364,31 @@ export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig
         }
       : opts.toolChoice;
 
+  const wrappedCachePolicy: CachePolicyInput | undefined =
+    typeof opts.cachePolicy === 'function'
+      ? async (ctx: SystemPromptContext) => {
+          if (!state) {
+            throw new Error(`Stateful agent "${opts.name}" cachePolicy called before init`);
+          }
+          return (
+            opts.cachePolicy as (ctx: StatefulAgentContext<S>) => CachePolicy | Promise<CachePolicy>
+          )({ ...ctx, state });
+        }
+      : opts.cachePolicy;
+
+  const wrappedTailContext: TailContextInput | undefined =
+    typeof opts.tailContext === 'function'
+      ? async (ctx: SystemPromptContext) => {
+          if (!state) {
+            throw new Error(`Stateful agent "${opts.name}" tailContext called before init`);
+          }
+          return (opts.tailContext as (ctx: StatefulAgentContext<S>) => string | Promise<string>)({
+            ...ctx,
+            state,
+          });
+        }
+      : opts.tailContext;
+
   // `onUnresolvedTool` threads `state` in like the resolvers above, but unlike
   // them returns `undefined` before init rather than throwing: it fires on the
   // tool-dispatch path, so a pre-init call must degrade to the framework
@@ -370,6 +415,8 @@ export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig
     provider: wrappedProvider,
     temperature: wrappedTemperature,
     toolChoice: wrappedToolChoice,
+    cachePolicy: wrappedCachePolicy,
+    tailContext: wrappedTailContext,
     onUnresolvedTool: wrappedOnUnresolvedTool,
 
     onActivate: async (ctx: AgentLifecycleContext) => {

package/src/state/debug-event-log.ts

@@ -199,13 +199,16 @@ export function recordMetaEvent(
  * - `unknown-tool-limit`     — the model repeatedly called tools it couldn't dispatch,
  *                              whether hallucinated or stale (real earlier, retired now).
  * - `max-iterations`         — the tool loop hit its iteration cap.
+ * - `response-truncated`     — a turn stopped at the provider's output-token cap with an
+ *                              incomplete tool call; deterministic, so it bails without retry.
  */
 export type TurnFailureReason =
   | 'exception'
   | 'malformed-function-call'
   | 'empty-response'
   | 'unknown-tool-limit'
-  | 'max-iterations';
+  | 'max-iterations'
+  | 'response-truncated';
 
 /**
  * Record a turn-ending failure (`turn.error`, importance `high`). The `reason`
@@ -301,7 +304,7 @@ export const DEBUG_LOG_README: readonly string[] = [
   "kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.",
   "kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.",
   "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.",
-  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
+  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
   'Sub-agent meta events: a sub-agent\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `"<parent> › <sub-agent>"` breadcrumb that composes when nested (e.g. `"UI Builder › Planner › Grounding"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\'s span.',
   "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, token usage, session cost), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.",
   'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it.',

package/src/utils/condense-history.test.ts

@@ -28,21 +28,28 @@ const toolMsg = (toolCallId: string, content: string): ChatMessage => ({
 
 const reg = (
   policy: CondensePolicy,
-  clocks: { iteration?: number; turn?: number; activation?: number } = {},
+  clocks: { iteration?: number; turn?: number; activation?: number; phaseEpoch?: number } = {},
 ): RegisteredCondensePolicy => ({
   policy,
   iteration: clocks.iteration ?? 1,
   turn: clocks.turn ?? 1,
   activation: clocks.activation ?? 1,
+  phaseEpoch: clocks.phaseEpoch ?? 1,
 });
 
 /** A CondenseContext for the pure transform. Defaults fire nothing; override per test. */
 const ctx = (
-  o: { modelCall?: number; turn?: number; activationEnded?: (a: number) => boolean } = {},
+  o: {
+    modelCall?: number;
+    turn?: number;
+    activationEnded?: (a: number) => boolean;
+    phaseEnded?: (e: number) => boolean;
+  } = {},
 ): CondenseContext => ({
   modelCall: o.modelCall ?? 0,
   turn: o.turn ?? 0,
   activationEnded: o.activationEnded ?? (() => false),
+  phaseEnded: o.phaseEnded ?? (() => false),
 });
 
 const sink = () => {
@@ -310,6 +317,62 @@ suite('agentEnd: kept while the agent is active, collapsed once its activation e
   assert.is(events[0].trigger, 'agentEnd');
 });
 
+// ---------------------------------------------------------------------------
+// phaseEnd
+// ---------------------------------------------------------------------------
+
+suite('phaseEnd: kept within the phase, collapsed once the app advances the epoch', () => {
+  // Registered in phase epoch 1.
+  const history: ChatMessage[] = [asstCall('p1', 'load_entity'), toolMsg('p1', big())];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['p1', reg({ on: { kind: 'phaseEnd' }, response: 'pointer' }, { phaseEpoch: 1 })],
+  ]);
+  const { events, on } = sink();
+
+  // Still in phase 1 (no endPhase yet) — full.
+  const sameP = applyCondensation(history, policies, ctx({ phaseEnded: (e) => e < 1 }), on);
+  assert.is(sameP[1].toolResult!.content, big(), 'full while the phase is current');
+  assert.is(events.length, 0);
+
+  // endPhase() advanced the current epoch to 2 → the phase-1 payload collapses.
+  const ended = applyCondensation(history, policies, ctx({ phaseEnded: (e) => e < 2 }), on);
+  assert.match(ended[1].toolResult!.content, /phase ended/);
+  assert.match(ended[1].toolResult!.content, /re-call to restore/);
+  assert.is(events.length, 1);
+  assert.is(events[0].trigger, 'phaseEnd');
+});
+
+suite('phaseEnd: falls back to agentEnd when no phase boundary is ever declared', () => {
+  // Phase epoch never advances (phaseEnded always false), but the activation ends.
+  const history: ChatMessage[] = [asstCall('p1', 'load_entity'), toolMsg('p1', big())];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    [
+      'p1',
+      reg({ on: { kind: 'phaseEnd' }, response: 'pointer' }, { activation: 1, phaseEpoch: 1 }),
+    ],
+  ]);
+  const { events, on } = sink();
+
+  const active = applyCondensation(
+    history,
+    policies,
+    ctx({ phaseEnded: () => false, activationEnded: () => false }),
+    on,
+  );
+  assert.is(active[1].toolResult!.content, big(), 'full while both phase and agent are live');
+  assert.is(events.length, 0);
+
+  const disposed = applyCondensation(
+    history,
+    policies,
+    ctx({ phaseEnded: () => false, activationEnded: (a) => a === 1 }),
+    on,
+  );
+  assert.match(disposed[1].toolResult!.content, /phase ended/, 'agentEnd backstop collapses it');
+  assert.is(events.length, 1);
+  assert.is(events[0].trigger, 'phaseEnd');
+});
+
 // ---------------------------------------------------------------------------
 // multi-trigger (OR / first-wins)
 // ---------------------------------------------------------------------------

package/src/utils/condense-history.ts

@@ -50,6 +50,8 @@ export interface RegisteredCondensePolicy {
   turn: number;
   /** Agent-activation sequence when the call was made — the `agentEnd` clock. */
   activation: number;
+  /** App-controlled phase epoch when the call was made — the `phaseEnd` clock. */
+  phaseEpoch: number;
   /** `context.condensed` already emitted for the args payload (fire-once). */
   reportedArgs?: boolean;
   /** `context.condensed` already emitted for the response payload (fire-once). */
@@ -68,6 +70,11 @@ export interface CondenseContext {
   turn: number;
   /** Whether the agent activation that made a call has since ended — the `agentEnd` clock. */
   activationEnded: (activation: number) => boolean;
+  /**
+   * Whether a later phase epoch is current than the one a call was made in — the
+   * `phaseEnd` clock. True once `endPhase()` has been called since the call.
+   */
+  phaseEnded: (phaseEpoch: number) => boolean;
 }
 
 /**
@@ -99,6 +106,8 @@ function triggerReason(trigger: CondenseTrigger): string {
       return 'turn ended';
     case 'agentEnd':
       return 'agent finished';
+    case 'phaseEnd':
+      return 'phase ended';
     default:
       return 'superseded';
   }
@@ -124,7 +133,7 @@ function triggerLabel(trigger: CondenseTrigger): string {
     case 'superseded':
       return `superseded:${trigger.by}`;
     default:
-      return trigger.kind; // 'turnEnd' | 'agentEnd'
+      return trigger.kind; // 'turnEnd' | 'agentEnd' | 'phaseEnd'
   }
 }
 
@@ -156,6 +165,9 @@ function estimateTokensSaved(origLen: number, stubLen: number): number {
  * - `agentEnd` — collapses once the agent activation that made the call has ended
  *   (a swap to another agent, or `releaseAgent`/`completeSubAgent`): kept across
  *   all of the agent's turns, dropped when its flow finishes.
+ * - `phaseEnd` — collapses once the app advances its phase epoch via `endPhase()`
+ *   after the call (a sub-`agentEnd` boundary the author declares), OR at
+ *   `agentEnd` as a backstop if no boundary is ever declared.
  *
  * The tool-call/result envelope is never removed (providers reject orphaned
  * calls/results) — only the args object or the result content is replaced.
@@ -210,6 +222,11 @@ export function applyCondensation(
         return ctx.turn > entry.turn;
       case 'agentEnd':
         return ctx.activationEnded(entry.activation);
+      // Fires when the app advanced the phase epoch since the call — OR, as a
+      // backstop, when the whole activation has ended, so a phase boundary that
+      // is never declared still collapses at `agentEnd` rather than never.
+      case 'phaseEnd':
+        return ctx.phaseEnded(entry.phaseEpoch) || ctx.activationEnded(entry.activation);
       default:
         return latestByKey.get(trig.by) !== toolCallId; // superseded by a newer call
     }

package/src/utils/strip-agent-handlers.ts

@@ -7,7 +7,8 @@ import type { AgentConfig } from '../config/config';
  * 1. **Directly function-valued** — the lifecycle/dispatch hooks (`onActivate`,
  *    `onDeactivate`, `getDebugSnapshot`, `onUnresolvedTool`) and the function
  *    form of the per-turn resolvers (`systemPrompt`, `toolDefinitions`,
- *    `displayName`, `provider`, `temperature`, `toolChoice`, `toolHandlers`).
+ *    `displayName`, `provider`, `temperature`, `toolChoice`, `cachePolicy`,
+ *    `toolHandlers`).
  * 2. **Object "handler bags" whose *values* are functions** — `toolHandlers` in
  *    its object form is `{ name: handler }`, so `typeof` is `'object'`, not
  *    `'function'`. A by-value check on the field alone misses it, leaking a live