@genesislcap/ai-assistant 14.469.0 → 14.470.0

package/dist/esm/utils/condense-history.js

@@ -34,6 +34,8 @@ function triggerReason(trigger) {
             return 'turn ended';
         case 'agentEnd':
             return 'agent finished';
+        case 'phaseEnd':
+            return 'phase ended';
         default:
             return 'superseded';
     }
@@ -52,7 +54,7 @@ function triggerLabel(trigger) {
         case 'superseded':
             return `superseded:${trigger.by}`;
         default:
-            return trigger.kind; // 'turnEnd' | 'agentEnd'
+            return trigger.kind; // 'turnEnd' | 'agentEnd' | 'phaseEnd'
     }
 }
 function estimateTokensSaved(origLen, stubLen) {
@@ -82,6 +84,9 @@ function estimateTokensSaved(origLen, stubLen) {
  * - `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.
@@ -128,6 +133,11 @@ export function applyCondensation(history, policies, ctx, onCondensed) {
                 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/dist/esm/utils/condense-history.test.js

@@ -10,21 +10,23 @@ const toolMsg = (toolCallId, content) => ({
     toolResult: { toolCallId, content },
 });
 const reg = (policy, clocks = {}) => {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
     return ({
         policy,
         iteration: (_a = clocks.iteration) !== null && _a !== void 0 ? _a : 1,
         turn: (_b = clocks.turn) !== null && _b !== void 0 ? _b : 1,
         activation: (_c = clocks.activation) !== null && _c !== void 0 ? _c : 1,
+        phaseEpoch: (_d = clocks.phaseEpoch) !== null && _d !== void 0 ? _d : 1,
     });
 };
 /** A CondenseContext for the pure transform. Defaults fire nothing; override per test. */
 const ctx = (o = {}) => {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
     return ({
         modelCall: (_a = o.modelCall) !== null && _a !== void 0 ? _a : 0,
         turn: (_b = o.turn) !== null && _b !== void 0 ? _b : 0,
         activationEnded: (_c = o.activationEnded) !== null && _c !== void 0 ? _c : (() => false),
+        phaseEnded: (_d = o.phaseEnded) !== null && _d !== void 0 ? _d : (() => false),
     });
 };
 const sink = () => {
@@ -254,6 +256,45 @@ 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 = [asstCall('p1', 'load_entity'), toolMsg('p1', big())];
+    const policies = new Map([
+        ['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 = [asstCall('p1', 'load_entity'), toolMsg('p1', big())];
+    const policies = new Map([
+        [
+            '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)
 // ---------------------------------------------------------------------------
 suite('multi-trigger: collapses when ANY listed trigger fires', () => {

package/dist/esm/utils/strip-agent-handlers.js

@@ -5,7 +5,8 @@
  * 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "14.469.0",
+  "version": "14.470.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -64,24 +64,24 @@
     }
   },
   "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",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "14.469.0",
-    "@genesislcap/foundation-logger": "14.469.0",
-    "@genesislcap/foundation-redux": "14.469.0",
-    "@genesislcap/foundation-ui": "14.469.0",
-    "@genesislcap/foundation-utils": "14.469.0",
-    "@genesislcap/rapid-design-system": "14.469.0",
-    "@genesislcap/web-core": "14.469.0",
+    "@genesislcap/foundation-ai": "14.470.0",
+    "@genesislcap/foundation-logger": "14.470.0",
+    "@genesislcap/foundation-redux": "14.470.0",
+    "@genesislcap/foundation-ui": "14.470.0",
+    "@genesislcap/foundation-utils": "14.470.0",
+    "@genesislcap/rapid-design-system": "14.470.0",
+    "@genesislcap/web-core": "14.470.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -93,5 +93,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "2b4460d5b9f20c36baddc55084e658bbcbd18c89"
+  "gitHead": "c222968b05dd3bb5db608222696b1f59a1c65913"
 }

package/src/components/chat-driver/chat-driver.test.ts

@@ -1,6 +1,7 @@
 import type {
   AIProvider,
   AIProviderRegistry,
+  CachePolicy,
   ChatMessage,
   ChatRequestOptions,
   ChatToolCall,
@@ -38,6 +39,12 @@ interface ScriptedProvider extends AIProvider {
   toolChoicePerCall: Array<ChatToolChoice | undefined>;
   /** `temperature` seen on each `chat()` call, in order. */
   temperaturePerCall: Array<number | undefined>;
+  /** `cachePolicy` seen on each `chat()` call, in order. */
+  cachePolicyPerCall: Array<CachePolicy | undefined>;
+  /** `tailContext` seen on each `chat()` call, in order (already framed by the driver). */
+  tailContextPerCall: Array<string | undefined>;
+  /** `systemPrompt` seen on each `chat()` call, in order. */
+  systemPromptPerCall: Array<string | undefined>;
   /** The model-bound history slice seen on each `chat()` call (post-transform). */
   historyPerCall: ChatMessage[][];
 }
@@ -47,11 +54,17 @@ const scriptedProvider = (responses: ChatMessage[]): ScriptedProvider => {
   const advertisedPerCall: string[][] = [];
   const toolChoicePerCall: Array<ChatToolChoice | undefined> = [];
   const temperaturePerCall: Array<number | undefined> = [];
+  const cachePolicyPerCall: Array<CachePolicy | undefined> = [];
+  const tailContextPerCall: Array<string | undefined> = [];
+  const systemPromptPerCall: Array<string | undefined> = [];
   const historyPerCall: ChatMessage[][] = [];
   return {
     advertisedPerCall,
     toolChoicePerCall,
     temperaturePerCall,
+    cachePolicyPerCall,
+    tailContextPerCall,
+    systemPromptPerCall,
     historyPerCall,
     chat: async (
       history: ChatMessage[],
@@ -61,6 +74,9 @@ const scriptedProvider = (responses: ChatMessage[]): ScriptedProvider => {
       advertisedPerCall.push((options?.tools ?? []).map((t) => t.name));
       toolChoicePerCall.push(options?.toolChoice);
       temperaturePerCall.push(options?.temperature);
+      cachePolicyPerCall.push(options?.cachePolicy);
+      tailContextPerCall.push(options?.tailContext);
+      systemPromptPerCall.push(options?.systemPrompt);
       // Snapshot the slice (condensation produces fresh objects per call and never
       // mutates stored history, so a shallow array copy is a stable per-call view).
       historyPerCall.push([...history]);
@@ -1077,16 +1093,31 @@ const settings = createLogicSuite('ChatDriver temperature & toolChoice');
 
 settings('passes a static agent temperature and tool-call mode to the provider', async () => {
   const provider = scriptedProvider([]);
-  const driver = makeDriver(agent({ name: 'a', temperature: 0.3, toolChoice: 'none' }), provider);
+  const driver = makeDriver(
+    agent({
+      name: 'a',
+      temperature: 0.3,
+      toolChoice: 'none',
+      cachePolicy: { scope: 'prompt' },
+      tailContext: 'STATE',
+    }),
+    provider,
+  );
 
   await driver.sendMessage('hi');
 
   assert.is(provider.temperaturePerCall[0], 0.3);
   assert.equal(provider.toolChoicePerCall[0], 'none');
+  assert.equal(provider.cachePolicyPerCall[0], { scope: 'prompt' });
+  // The driver frames the raw tail content in a <system-reminder> marker.
+  assert.is(provider.tailContextPerCall[0], '<system-reminder>\nSTATE\n</system-reminder>');
   // ...and surfaced in the per-turn debug snapshot (the effective values sent).
   const snap = driver.getTurnSnapshots()[0];
   assert.is(snap.temperature, 0.3);
   assert.equal(snap.toolChoice, 'none');
+  // The framed tail is captured on the snapshot too — it is never stored in
+  // history, so the snapshot is the only record of what the model actually saw.
+  assert.is(snap.tailContext, '<system-reminder>\nSTATE\n</system-reminder>');
 });
 
 settings('re-resolves the function form per turn (carrying turn context)', async () => {
@@ -1098,6 +1129,7 @@ settings('re-resolves the function form per turn (carrying turn context)', async
     // turnIndex: 0 on the first LLM call, > 0 on subsequent tool-loop iterations.
     temperature: (ctx) => (ctx.turnIndex === 0 ? 0.1 : 0.9),
     toolChoice: (ctx) => (ctx.turnIndex === 0 ? { tool: 'tool_a' } : 'auto'),
+    cachePolicy: (ctx) => (ctx.turnIndex === 0 ? { scope: 'history' } : { scope: 'tools' }),
   });
 
   await makeDriver(config, provider).sendMessage('go');
@@ -1105,9 +1137,11 @@ settings('re-resolves the function form per turn (carrying turn context)', async
   // First call forces the named tool at a low temperature...
   assert.is(provider.temperaturePerCall[0], 0.1);
   assert.equal(provider.toolChoicePerCall[0], { tool: 'tool_a' });
+  assert.equal(provider.cachePolicyPerCall[0], { scope: 'history' });
   // ...the follow-up call (after the tool result) sees the other branch.
   assert.is(provider.temperaturePerCall[1], 0.9);
   assert.equal(provider.toolChoicePerCall[1], 'auto');
+  assert.equal(provider.cachePolicyPerCall[1], { scope: 'tools' });
 });
 
 settings(
@@ -1119,6 +1153,42 @@ settings(
 
     assert.is(provider.temperaturePerCall[0], undefined);
     assert.is(provider.toolChoicePerCall[0], undefined);
+    assert.is(provider.cachePolicyPerCall[0], undefined);
+    assert.is(provider.tailContextPerCall[0], undefined);
+  },
+);
+
+// GENC-1380 A3b: the framework's malformed/empty retry nudge is routed to the framed tail (so the
+// system prompt stays byte-stable for caching), not appended to the system string.
+settings(
+  'routes the empty-response retry nudge into the framed tail, not the system prompt',
+  async () => {
+    // First call returns empty → the driver retries; the second exhausts the queue and ends the turn.
+    const provider = scriptedProvider([{ role: 'assistant', content: '' }]);
+
+    const driver = makeDriver(agent({ name: 'r', systemPrompt: 'BASE' }), provider);
+    await driver.sendMessage('go');
+
+    // The retry call (index 1) carries the nudge in the framed tail...
+    assert.ok(provider.tailContextPerCall[1]?.startsWith('<system-reminder>'), 'tail is framed');
+    assert.ok(
+      provider.tailContextPerCall[1]?.includes('You must respond'),
+      'retry nudge is in the tail',
+    );
+    // ...and the system prompt stays the bare agent prompt on both calls (nudge moved, not copied).
+    assert.is(provider.systemPromptPerCall[0], 'BASE');
+    assert.is(provider.systemPromptPerCall[1], 'BASE');
+
+    // Regression guard (debug-log reconstruction): the tail is never stored in
+    // history, so the per-turn snapshot must capture it — otherwise the retry
+    // nudge the model actually received would be invisible in the export. The
+    // snapshot's (systemPrompt + tailContext) must equal what the provider saw.
+    const retrySnap = driver.getTurnSnapshots()[1];
+    assert.is(retrySnap.systemPrompt, provider.systemPromptPerCall[1]);
+    assert.is(retrySnap.tailContext, provider.tailContextPerCall[1]);
+    assert.ok(retrySnap.tailContext?.includes('You must respond'), 'nudge reconstructable');
+    // The first (non-retry) call had no framework suffix and no agent tail → empty.
+    assert.is(driver.getTurnSnapshots()[0].tailContext, undefined);
   },
 );
 
@@ -1879,4 +1949,48 @@ condense('agentEnd: collapses once the agent releases (flow complete)', async ()
   assert.is(events[0].detail?.trigger, 'agentEnd');
 });
 
+condense('phaseEnd: collapses at endPhase() while the agent keeps running', async () => {
+  const sessionKey = 'condense-phase-end';
+  clearMetaEventRegistry();
+  const provider = scriptedProvider([
+    { role: 'assistant', content: '', toolCalls: [{ id: 's1', name: 'load', args: {} }] }, // call 1
+    { role: 'assistant', content: '', toolCalls: [{ id: 'a1', name: 'advance', args: {} }] }, // call 2 — ends the phase
+    { role: 'assistant', content: 'continuing' }, // call 3 — agent still active, just answers
+  ]);
+  const config = agent({
+    name: 'journey',
+    systemPrompt: 'a multi-phase flow',
+    toolDefinitions: [def('load'), def('advance')],
+    toolHandlers: {
+      load: async (_args, ctx) => {
+        ctx.condenseWhen({ on: { kind: 'phaseEnd' }, response: 'pointer' });
+        return bigBody;
+      },
+      advance: async (_args, ctx) => {
+        // Declares a phase boundary WITHOUT ending the agent (no releaseAgent).
+        ctx.endPhase?.();
+        return 'next phase';
+      },
+    },
+  });
+  const driver = makeDriver(config, provider, sessionKey);
+  const result = await driver.sendMessage('run the flow');
+  // The agent never released — the turn ends normally on the text response.
+  assert.is(result.reason, 'done');
+
+  // call #2 (index 1) ran before `advance` ended the phase — result still full.
+  const beforePhaseEnd = provider.historyPerCall[1].find((m) => m.toolResult?.toolCallId === 's1');
+  assert.is(beforePhaseEnd!.toolResult!.content, bigBody, 'full while the phase is current');
+  // call #3 (index 2) ran after endPhase() — collapsed. The activation never ended
+  // (no release/swap), so this collapse can ONLY be the phase boundary, not the
+  // agentEnd backstop.
+  const afterPhaseEnd = provider.historyPerCall[2].find((m) => m.toolResult?.toolCallId === 's1');
+  assert.match(afterPhaseEnd!.toolResult!.content, /re-call to restore/, 'collapsed at phase end');
+  assert.match(afterPhaseEnd!.toolResult!.content, /phase ended/);
+
+  const events = getMetaEvents(sessionKey).filter((e) => e.type === 'context.condensed');
+  assert.is(events.length, 1);
+  assert.is(events[0].detail?.trigger, 'phaseEnd');
+});
+
 condense.run();

package/src/components/chat-driver/chat-driver.ts

@@ -1,6 +1,7 @@
 import type {
   AIProvider,
   AIProviderRegistry,
+  CachePolicy,
   ChatAttachment,
   ChatDriverResult,
   ChatMessage,
@@ -19,13 +20,16 @@ import type {
 import {
   isObservableAIProviderRegistry,
   MalformedFunctionCallError,
+  ResponseTruncatedError,
 } from '@genesislcap/foundation-ai';
 import { agenticActivityBus } from '../../channel/ai-activity-bus';
 import type {
   AgentConfig,
+  CachePolicyInput,
   ProviderInput,
   SystemPromptContext,
   SystemPromptInput,
+  TailContextInput,
   TemperatureInput,
   ToolChoiceInput,
   ToolDefinitionsInput,
@@ -130,8 +134,22 @@ export interface TurnSnapshot {
   timestamp: string;
   /** Name of the agent active when this LLM call ran. */
   agentName?: string;
-  /** Final system prompt sent to the LLM (post-fold-suffix, post-retry hint). */
+  /**
+   * The agent's resolved system prompt sent to the LLM, verbatim. NOTE: this is
+   * now the *bare* prompt — the fold-surface suffix and the malformed/empty retry
+   * nudge no longer mutate it (they kept it byte-unstable and busted prompt
+   * caching), so they moved to {@link TurnSnapshot.tailContext}. To reconstruct
+   * exactly what the model saw, read both fields.
+   */
   systemPrompt?: string;
+  /**
+   * The framed `<system-reminder>` tail appended to the final user turn for this
+   * call, verbatim — never part of stored history, so this snapshot is the only
+   * record of it. Carries the framework's volatile additions (fold suffix, retry
+   * nudge) and the agent's per-turn `tailContext` (e.g. current file spec, live
+   * diagnostics). Undefined when the tail was empty (the normal case).
+   */
+  tailContext?: string;
   /** Tool names sent to the LLM, in order — definitions are static per name so names alone suffice. */
   toolNames: string[];
   /**
@@ -282,6 +300,15 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * collapsed until IT ends.
    */
   private currentActivation = 0;
+  /**
+   * Monotonic phase-epoch counter — the `phaseEnd` clock. Advanced by the
+   * handler-context `endPhase()` (an app-declared phase boundary within one
+   * activation), never reset. Unlike `currentActivation` it is NOT tied to agent
+   * swaps or releases — it ticks only when the agent itself declares a phase
+   * done. `phaseEnd` fires for a payload once a LATER epoch is current
+   * (`callPhaseEpoch < currentPhaseEpoch`), with an `agentEnd` backstop.
+   */
+  private currentPhaseEpoch = 0;
 
   /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
   private foldStack: FoldStackFrame[] = [];
@@ -395,6 +422,16 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * call; top-level turns are `'auto'`).
    */
   private activeToolChoiceInput?: ToolChoiceInput;
+  /**
+   * Active agent's prompt-cache policy selector (static value or per-turn resolver).
+   * `undefined` requests no caching (equivalent to `{ scope: 'default' }`).
+   */
+  private activeCachePolicyInput?: CachePolicyInput;
+  /**
+   * Active agent's tail-context selector (static value or per-turn resolver). The driver frames
+   * the resolved string in a `<system-reminder>` marker and injects it at the message tail.
+   */
+  private activeTailContextInput?: TailContextInput;
   /**
    * Active agent's unresolved-tool hook, captured from `applyAgent`. Consulted
    * only when a tool call cannot be dispatched (a stale or hallucinated name);
@@ -602,6 +639,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.activeProviderInput = config.provider;
     this.activeTemperatureInput = config.temperature;
     this.activeToolChoiceInput = config.toolChoice;
+    this.activeCachePolicyInput = config.cachePolicy;
+    this.activeTailContextInput = config.tailContext;
     this.activeOnUnresolvedTool = config.onUnresolvedTool;
     this.resolvedProviderCache.clear();
     this.lastResolvedProviderName = undefined;
@@ -851,6 +890,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
     resolvedSystemPrompt: string | undefined,
     temperature: number | undefined,
     toolChoice: ChatToolChoice | undefined,
+    tailContext: string | undefined,
   ): void {
     let agentSnapshot: unknown;
     if (this.debugSnapshotter) {
@@ -871,6 +911,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       agentName: this.activeAgentName,
       agentLabel: this.activeAgentLabel,
       systemPrompt: resolvedSystemPrompt,
+      tailContext,
       toolNames: this.toolDefinitions.map((t) => t.name),
       temperature,
       toolChoice,
@@ -1316,6 +1357,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
         // payloads collapse and a re-run starts a fresh activation.
         this.currentActivation += 1;
       },
+      endPhase: (): void => {
+        // Advance the phase epoch so payloads registered with `{ on: phaseEnd }`
+        // during the phase that just ended collapse on the next provider call.
+        // Repeatable (no once-only guard, unlike releaseAgent/completeSubAgent):
+        // each call opens a fresh phase for subsequent reads to accumulate in.
+        this.currentPhaseEpoch += 1;
+      },
       condenseWhen: (policy: CondensePolicy): void => {
         // No addressable tool call (e.g. fold-close handler) — nothing to attach to.
         if (!activeToolCallId) return;
@@ -1331,7 +1379,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
             ? typeof t.by === 'string' && t.by.length > 0
             : t?.kind === 'age'
               ? typeof t.turns === 'number' && t.turns >= 1
-              : t?.kind === 'turnEnd' || t?.kind === 'agentEnd';
+              : t?.kind === 'turnEnd' || t?.kind === 'agentEnd' || t?.kind === 'phaseEnd';
         if (triggers.length === 0 || !triggers.every(validTrigger)) {
           logger.warn(
             `ChatDriver(${this.activeAgentName ?? 'unknown'}): condenseWhen called with an invalid trigger — ignoring`,
@@ -1353,6 +1401,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
           iteration: this.modelCallSeq,
           turn: this.turnSeq,
           activation: this.currentActivation,
+          phaseEpoch: this.currentPhaseEpoch,
         });
       },
     };
@@ -1895,10 +1944,18 @@ export class ChatDriver extends EventTarget implements AiDriver {
         this.activeAgentLabel = await this.displayName(promptCtx);
       }
 
+      // Volatile framework additions — the fold-surface suffix and the per-attempt malformed/empty
+      // retry nudge — that would otherwise destabilize a cached system prompt. They are routed to
+      // the framed tail (below), never appended to the system string, so the system prompt stays
+      // byte-stable for every agent.
       const foldSuffix = this.buildFoldSystemPromptSuffix();
-      const baseSystemPrompt = resolvedSystemPrompt
-        ? `${resolvedSystemPrompt}${foldSuffix}`
-        : foldSuffix || undefined;
+      const retryNudge =
+        malformedAttempts > 0
+          ? '\n\nIMPORTANT: Use only the structured function-call API to invoke tools. Do not write Python code or use Python-style syntax to call tools.'
+          : emptyResponseAttempts > 0
+            ? "\n\nIMPORTANT: You must respond to the user's message. Call the appropriate tool or provide a text response — do not return an empty response."
+            : '';
+      const frameworkSystemSuffix = `${foldSuffix}${retryNudge}`;
 
       const primer = [...(this.primerHistory ?? []), ...(transientPrimer ?? [])];
       const baseHistory = firstLlmCall ? this.history.slice(0, -1) : this.history;
@@ -1915,6 +1972,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
           // A call's activation has ended once a later activation is current — a
           // swap or release/complete both advance the counter.
           activationEnded: (activation) => activation < this.currentActivation,
+          // A call's phase has ended once the app declared a later phase epoch
+          // current via `endPhase()`.
+          phaseEnded: (phaseEpoch) => phaseEpoch < this.currentPhaseEpoch,
         },
         (detail) => recordMetaEvent(this.sessionKey, 'context.condensed', detail),
       );
@@ -1923,29 +1983,38 @@ export class ChatDriver extends EventTarget implements AiDriver {
         : condensedHistory;
       const historyForCall = [...primer, ...historyForProvider];
 
-      const systemPrompt =
-        malformedAttempts > 0
-          ? `${baseSystemPrompt ?? ''}\n\nIMPORTANT: Use only the structured function-call API to invoke tools. Do not write Python code or use Python-style syntax to call tools.`
-          : emptyResponseAttempts > 0
-            ? `${baseSystemPrompt ?? ''}\n\nIMPORTANT: You must respond to the user's message. Call the appropriate tool or provide a text response — do not return an empty response.`
-            : baseSystemPrompt;
-
       // Resolve the per-turn temperature and tool-call mode the same way the
       // provider is resolved — static value or a function of the turn context
       // (which carries the live state for stateful agents). Resolved before the
       // snapshot so the debug log records the exact request config the model saw.
-      // oxlint-disable-next-line no-await-in-loop
-      const [resolvedTemperature, resolvedToolChoice] = await Promise.all([
-        this.resolveTurnInput<number>(this.activeTemperatureInput, promptCtx),
-        this.resolveTurnInput<ChatToolChoice>(this.activeToolChoiceInput, promptCtx),
-      ]);
+      const [resolvedTemperature, resolvedToolChoice, resolvedCachePolicy, resolvedTailContext] =
+        // oxlint-disable-next-line no-await-in-loop
+        await Promise.all([
+          this.resolveTurnInput<number>(this.activeTemperatureInput, promptCtx),
+          this.resolveTurnInput<ChatToolChoice>(this.activeToolChoiceInput, promptCtx),
+          this.resolveTurnInput<CachePolicy>(this.activeCachePolicyInput, promptCtx),
+          this.resolveTurnInput<string>(this.activeTailContextInput, promptCtx),
+        ]);
+      // The system prompt is always just the agent's resolved prompt — byte-stable, so it can be
+      // cached. The framework's volatile additions (fold suffix, retry nudge) and the agent's tail
+      // context all go to the framed tail: one uniform channel, no cache-scope branch. On a normal
+      // turn `frameworkSystemSuffix` is empty, so the tail is empty too — a no-op. The framework
+      // owns the framing; the corrective retry nudge lands last (recency).
+      const systemPrompt = resolvedSystemPrompt || undefined;
+      const tailBody = [resolvedTailContext, frameworkSystemSuffix]
+        .map((part) => (part ?? '').trim())
+        .filter((part) => part.length > 0)
+        .join('\n\n');
+      const tailContext = tailBody
+        ? `<system-reminder>\n${tailBody}\n</system-reminder>`
+        : undefined;
       // An agent/state-configured tool-call mode wins. Otherwise sub-agents must
       // finish by calling a tool (their completion tool) so the turn can't end
       // on a free-text answer; top-level agents stay 'auto'. (Transports no-op a
       // force when no tools are advertised.)
       const effectiveToolChoice = resolvedToolChoice ?? (this.isSubAgent ? 'required' : undefined);
 
-      this.recordTurnSnapshot(systemPrompt, resolvedTemperature, effectiveToolChoice);
+      this.recordTurnSnapshot(systemPrompt, resolvedTemperature, effectiveToolChoice, tailContext);
 
       // Capture the pending user input, then clear the slots BEFORE the chat
       // call. `sendMessage` already appended the user message to `this.history`,
@@ -1970,6 +2039,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
         // Agent/state-configured sampling temperature (normalized 0–1); each
         // transport translates it to its native range. Undefined → provider default.
         temperature: resolvedTemperature,
+        // Prompt-cache policy for this turn (Anthropic places breakpoints per scope; Gemini
+        // caches implicitly regardless). Undefined → no caching requested.
+        cachePolicy: resolvedCachePolicy,
+        // Framed volatile context injected at the message tail (never stored). Undefined → none.
+        tailContext,
       };
 
       // Resolve the active provider for this turn. Static names were validated
@@ -2019,6 +2093,35 @@ export class ChatDriver extends EventTarget implements AiDriver {
           }
           return { reason: 'done' };
         }
+        // The response was truncated at the provider's output-token cap while it
+        // still carried a tool call — its arguments are incomplete and unusable.
+        // Unlike a malformed call this is DETERMINISTIC: re-issuing the same
+        // request hits the same cap, so a silent retry just loops. Bail with a
+        // clear, actionable signal instead. The remedy is config (raise the
+        // provider maxTokens) or a smaller step — neither is fixed by retrying.
+        if (e instanceof ResponseTruncatedError) {
+          logger.error('ChatDriver: response truncated at the output-token cap', e);
+          recordTurnError(this.sessionKey, 'response-truncated', {
+            agent: this.activeAgentName,
+            provider: this.lastResolvedProviderName,
+            model: e.model,
+            maxTokens: e.maxTokens,
+            outputTokens: e.outputTokens,
+            tools: e.toolNames,
+            isSubAgent: this.isSubAgent,
+          });
+          if (this.isSubAgent) {
+            // Bubble a typed failure to the parent instead of speaking to the user.
+            this.failSubAgent('response_truncated');
+          } else {
+            this.appendToHistory({
+              role: 'assistant',
+              content:
+                'My response was cut off because a single step reached the model output limit. This usually means one step tried to produce too much at once — try breaking your request into smaller steps.',
+            });
+          }
+          return { reason: 'done' };
+        }
         // A request timeout from the transport (tagged `TimeoutError`) is not a
         // bug on our end — surface it distinctly instead of letting it fall
         // through to the generic "something went wrong" catch. No auto-retry: