@genesislcap/ai-assistant 14.469.0 → 14.470.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/dist/ai-assistant.api.json +272 -3
  2. package/dist/ai-assistant.d.ts +95 -1
  3. package/dist/dts/components/chat-driver/chat-driver.d.ts +34 -1
  4. package/dist/dts/components/chat-driver/chat-driver.d.ts.map +1 -1
  5. package/dist/dts/components/chat-driver/chat-driver.test.d.ts.map +1 -1
  6. package/dist/dts/config/config.d.ts +42 -2
  7. package/dist/dts/config/config.d.ts.map +1 -1
  8. package/dist/dts/config/define-stateful-agent.d.ts +14 -1
  9. package/dist/dts/config/define-stateful-agent.d.ts.map +1 -1
  10. package/dist/dts/main/main.d.ts +3 -0
  11. package/dist/dts/main/main.d.ts.map +1 -1
  12. package/dist/dts/state/debug-event-log.d.ts +3 -1
  13. package/dist/dts/state/debug-event-log.d.ts.map +1 -1
  14. package/dist/dts/utils/condense-history.d.ts +10 -0
  15. package/dist/dts/utils/condense-history.d.ts.map +1 -1
  16. package/dist/dts/utils/strip-agent-handlers.d.ts +2 -1
  17. package/dist/dts/utils/strip-agent-handlers.d.ts.map +1 -1
  18. package/dist/esm/components/chat-driver/chat-driver.js +87 -13
  19. package/dist/esm/components/chat-driver/chat-driver.test.js +95 -1
  20. package/dist/esm/config/define-stateful-agent.js +18 -0
  21. package/dist/esm/state/debug-event-log.js +1 -1
  22. package/dist/esm/utils/condense-history.js +11 -1
  23. package/dist/esm/utils/condense-history.test.js +43 -2
  24. package/dist/esm/utils/strip-agent-handlers.js +2 -1
  25. package/package.json +16 -16
  26. package/src/components/chat-driver/chat-driver.test.ts +115 -1
  27. package/src/components/chat-driver/chat-driver.ts +121 -18
  28. package/src/config/config.ts +46 -1
  29. package/src/config/define-stateful-agent.ts +47 -0
  30. package/src/state/debug-event-log.ts +5 -2
  31. package/src/utils/condense-history.test.ts +65 -2
  32. package/src/utils/condense-history.ts +18 -1
  33. package/src/utils/strip-agent-handlers.ts +2 -1
@@ -2604,6 +2604,73 @@
2604
2604
  "endIndex": 2
2605
2605
  }
2606
2606
  },
2607
+ {
2608
+ "kind": "TypeAlias",
2609
+ "canonicalReference": "@genesislcap/ai-assistant!CachePolicyInput:type",
2610
+ "docComment": "/**\n * 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}.\n *\n * @beta\n */\n",
2611
+ "excerptTokens": [
2612
+ {
2613
+ "kind": "Content",
2614
+ "text": "export type CachePolicyInput = "
2615
+ },
2616
+ {
2617
+ "kind": "Reference",
2618
+ "text": "CachePolicy",
2619
+ "canonicalReference": "@genesislcap/foundation-ai!CachePolicy:type"
2620
+ },
2621
+ {
2622
+ "kind": "Content",
2623
+ "text": " | ((ctx: "
2624
+ },
2625
+ {
2626
+ "kind": "Reference",
2627
+ "text": "SystemPromptContext",
2628
+ "canonicalReference": "@genesislcap/ai-assistant!SystemPromptContext:interface"
2629
+ },
2630
+ {
2631
+ "kind": "Content",
2632
+ "text": ") => "
2633
+ },
2634
+ {
2635
+ "kind": "Reference",
2636
+ "text": "CachePolicy",
2637
+ "canonicalReference": "@genesislcap/foundation-ai!CachePolicy:type"
2638
+ },
2639
+ {
2640
+ "kind": "Content",
2641
+ "text": " | "
2642
+ },
2643
+ {
2644
+ "kind": "Reference",
2645
+ "text": "Promise",
2646
+ "canonicalReference": "!Promise:interface"
2647
+ },
2648
+ {
2649
+ "kind": "Content",
2650
+ "text": "<"
2651
+ },
2652
+ {
2653
+ "kind": "Reference",
2654
+ "text": "CachePolicy",
2655
+ "canonicalReference": "@genesislcap/foundation-ai!CachePolicy:type"
2656
+ },
2657
+ {
2658
+ "kind": "Content",
2659
+ "text": ">)"
2660
+ },
2661
+ {
2662
+ "kind": "Content",
2663
+ "text": ";"
2664
+ }
2665
+ ],
2666
+ "fileUrlPath": "src/config/config.ts",
2667
+ "releaseTag": "Beta",
2668
+ "name": "CachePolicyInput",
2669
+ "typeTokenRange": {
2670
+ "startIndex": 1,
2671
+ "endIndex": 11
2672
+ }
2673
+ },
2607
2674
  {
2608
2675
  "kind": "Class",
2609
2676
  "canonicalReference": "@genesislcap/ai-assistant!ChatDriver:class",
@@ -5394,7 +5461,7 @@
5394
5461
  },
5395
5462
  {
5396
5463
  "kind": "Content",
5397
- "text": " | {\n systemPrompt: string;\n turnIndex: string;\n timestamp: string;\n agentName?: string;\n toolNames: string[];\n temperature?: number;\n toolChoice?: import(\"@genesislcap/foundation-ai\")."
5464
+ "text": " | {\n systemPrompt: string;\n turnIndex: string;\n timestamp: string;\n agentName?: string;\n tailContext?: string;\n toolNames: string[];\n temperature?: number;\n toolChoice?: import(\"@genesislcap/foundation-ai\")."
5398
5465
  },
5399
5466
  {
5400
5467
  "kind": "Reference",
@@ -5491,6 +5558,24 @@
5491
5558
  "text": "ToolChoiceInput",
5492
5559
  "canonicalReference": "@genesislcap/ai-assistant!ToolChoiceInput:type"
5493
5560
  },
5561
+ {
5562
+ "kind": "Content",
5563
+ "text": ";\n cachePolicy?: import(\"../config/config\")."
5564
+ },
5565
+ {
5566
+ "kind": "Reference",
5567
+ "text": "CachePolicyInput",
5568
+ "canonicalReference": "@genesislcap/ai-assistant!CachePolicyInput:type"
5569
+ },
5570
+ {
5571
+ "kind": "Content",
5572
+ "text": ";\n tailContext?: import(\"../config/config\")."
5573
+ },
5574
+ {
5575
+ "kind": "Reference",
5576
+ "text": "TailContextInput",
5577
+ "canonicalReference": "@genesislcap/ai-assistant!TailContextInput:type"
5578
+ },
5494
5579
  {
5495
5580
  "kind": "Content",
5496
5581
  "text": ";\n onUnresolvedTool?: import(\"../config/config\")."
@@ -5584,7 +5669,7 @@
5584
5669
  "isStatic": false,
5585
5670
  "returnTypeTokenRange": {
5586
5671
  "startIndex": 1,
5587
- "endIndex": 44
5672
+ "endIndex": 48
5588
5673
  },
5589
5674
  "releaseTag": "Beta",
5590
5675
  "isProtected": false,
@@ -9241,6 +9326,74 @@
9241
9326
  "name": "StatefulAgentInit",
9242
9327
  "preserveMemberOrder": false,
9243
9328
  "members": [
9329
+ {
9330
+ "kind": "PropertySignature",
9331
+ "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#cachePolicy:member",
9332
+ "docComment": "/**\n * 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.\n */\n",
9333
+ "excerptTokens": [
9334
+ {
9335
+ "kind": "Content",
9336
+ "text": "cachePolicy?: "
9337
+ },
9338
+ {
9339
+ "kind": "Reference",
9340
+ "text": "CachePolicy",
9341
+ "canonicalReference": "@genesislcap/foundation-ai!CachePolicy:type"
9342
+ },
9343
+ {
9344
+ "kind": "Content",
9345
+ "text": " | ((ctx: "
9346
+ },
9347
+ {
9348
+ "kind": "Reference",
9349
+ "text": "StatefulAgentContext",
9350
+ "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentContext:type"
9351
+ },
9352
+ {
9353
+ "kind": "Content",
9354
+ "text": "<S>) => "
9355
+ },
9356
+ {
9357
+ "kind": "Reference",
9358
+ "text": "CachePolicy",
9359
+ "canonicalReference": "@genesislcap/foundation-ai!CachePolicy:type"
9360
+ },
9361
+ {
9362
+ "kind": "Content",
9363
+ "text": " | "
9364
+ },
9365
+ {
9366
+ "kind": "Reference",
9367
+ "text": "Promise",
9368
+ "canonicalReference": "!Promise:interface"
9369
+ },
9370
+ {
9371
+ "kind": "Content",
9372
+ "text": "<"
9373
+ },
9374
+ {
9375
+ "kind": "Reference",
9376
+ "text": "CachePolicy",
9377
+ "canonicalReference": "@genesislcap/foundation-ai!CachePolicy:type"
9378
+ },
9379
+ {
9380
+ "kind": "Content",
9381
+ "text": ">)"
9382
+ },
9383
+ {
9384
+ "kind": "Content",
9385
+ "text": ";"
9386
+ }
9387
+ ],
9388
+ "isReadonly": false,
9389
+ "isOptional": true,
9390
+ "releaseTag": "Beta",
9391
+ "name": "cachePolicy",
9392
+ "propertyTypeTokenRange": {
9393
+ "startIndex": 1,
9394
+ "endIndex": 11
9395
+ }
9396
+ },
9244
9397
  {
9245
9398
  "kind": "PropertySignature",
9246
9399
  "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#chatInputDuringExecution:member",
@@ -9739,6 +9892,51 @@
9739
9892
  "endIndex": 6
9740
9893
  }
9741
9894
  },
9895
+ {
9896
+ "kind": "PropertySignature",
9897
+ "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#tailContext:member",
9898
+ "docComment": "/**\n * 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.\n */\n",
9899
+ "excerptTokens": [
9900
+ {
9901
+ "kind": "Content",
9902
+ "text": "tailContext?: "
9903
+ },
9904
+ {
9905
+ "kind": "Content",
9906
+ "text": "string | ((ctx: "
9907
+ },
9908
+ {
9909
+ "kind": "Reference",
9910
+ "text": "StatefulAgentContext",
9911
+ "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentContext:type"
9912
+ },
9913
+ {
9914
+ "kind": "Content",
9915
+ "text": "<S>) => string | "
9916
+ },
9917
+ {
9918
+ "kind": "Reference",
9919
+ "text": "Promise",
9920
+ "canonicalReference": "!Promise:interface"
9921
+ },
9922
+ {
9923
+ "kind": "Content",
9924
+ "text": "<string>)"
9925
+ },
9926
+ {
9927
+ "kind": "Content",
9928
+ "text": ";"
9929
+ }
9930
+ ],
9931
+ "isReadonly": false,
9932
+ "isOptional": true,
9933
+ "releaseTag": "Beta",
9934
+ "name": "tailContext",
9935
+ "propertyTypeTokenRange": {
9936
+ "startIndex": 1,
9937
+ "endIndex": 6
9938
+ }
9939
+ },
9742
9940
  {
9743
9941
  "kind": "PropertySignature",
9744
9942
  "canonicalReference": "@genesislcap/ai-assistant!StatefulAgentInit#temperature:member",
@@ -10284,6 +10482,50 @@
10284
10482
  "endIndex": 6
10285
10483
  }
10286
10484
  },
10485
+ {
10486
+ "kind": "TypeAlias",
10487
+ "canonicalReference": "@genesislcap/ai-assistant!TailContextInput:type",
10488
+ "docComment": "/**\n * 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.\n *\n * @beta\n */\n",
10489
+ "excerptTokens": [
10490
+ {
10491
+ "kind": "Content",
10492
+ "text": "export type TailContextInput = "
10493
+ },
10494
+ {
10495
+ "kind": "Content",
10496
+ "text": "string | ((ctx: "
10497
+ },
10498
+ {
10499
+ "kind": "Reference",
10500
+ "text": "SystemPromptContext",
10501
+ "canonicalReference": "@genesislcap/ai-assistant!SystemPromptContext:interface"
10502
+ },
10503
+ {
10504
+ "kind": "Content",
10505
+ "text": ") => string | "
10506
+ },
10507
+ {
10508
+ "kind": "Reference",
10509
+ "text": "Promise",
10510
+ "canonicalReference": "!Promise:interface"
10511
+ },
10512
+ {
10513
+ "kind": "Content",
10514
+ "text": "<string>)"
10515
+ },
10516
+ {
10517
+ "kind": "Content",
10518
+ "text": ";"
10519
+ }
10520
+ ],
10521
+ "fileUrlPath": "src/config/config.ts",
10522
+ "releaseTag": "Beta",
10523
+ "name": "TailContextInput",
10524
+ "typeTokenRange": {
10525
+ "startIndex": 1,
10526
+ "endIndex": 6
10527
+ }
10528
+ },
10287
10529
  {
10288
10530
  "kind": "TypeAlias",
10289
10531
  "canonicalReference": "@genesislcap/ai-assistant!TemperatureInput:type",
@@ -10797,7 +11039,7 @@
10797
11039
  {
10798
11040
  "kind": "PropertySignature",
10799
11041
  "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#systemPrompt:member",
10800
- "docComment": "/**\n * Final system prompt sent to the LLM (post-fold-suffix, post-retry hint).\n */\n",
11042
+ "docComment": "/**\n * 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.\n */\n",
10801
11043
  "excerptTokens": [
10802
11044
  {
10803
11045
  "kind": "Content",
@@ -10821,6 +11063,33 @@
10821
11063
  "endIndex": 2
10822
11064
  }
10823
11065
  },
11066
+ {
11067
+ "kind": "PropertySignature",
11068
+ "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#tailContext:member",
11069
+ "docComment": "/**\n * 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).\n */\n",
11070
+ "excerptTokens": [
11071
+ {
11072
+ "kind": "Content",
11073
+ "text": "tailContext?: "
11074
+ },
11075
+ {
11076
+ "kind": "Content",
11077
+ "text": "string"
11078
+ },
11079
+ {
11080
+ "kind": "Content",
11081
+ "text": ";"
11082
+ }
11083
+ ],
11084
+ "isReadonly": false,
11085
+ "isOptional": true,
11086
+ "releaseTag": "Beta",
11087
+ "name": "tailContext",
11088
+ "propertyTypeTokenRange": {
11089
+ "startIndex": 1,
11090
+ "endIndex": 2
11091
+ }
11092
+ },
10824
11093
  {
10825
11094
  "kind": "PropertySignature",
10826
11095
  "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot#temperature:member",
@@ -1,6 +1,7 @@
1
1
  import { AgentPickerMode } from '@genesislcap/foundation-ai';
2
2
  import { AIProviderRegistry } from '@genesislcap/foundation-ai';
3
3
  import type { AIProviderRegistryStatusEntry } from '@genesislcap/foundation-ai';
4
+ import type { CachePolicy } from '@genesislcap/foundation-ai';
4
5
  import type { ChatAttachment } from '@genesislcap/foundation-ai';
5
6
  import type { ChatConfig } from '@genesislcap/foundation-ai';
6
7
  import type { ChatDriverResult } from '@genesislcap/foundation-ai';
@@ -573,6 +574,27 @@ declare interface BaseAgentConfig {
573
574
  * @beta
574
575
  */
575
576
  toolChoice?: ToolChoiceInput;
577
+ /**
578
+ * Prompt-cache policy for this agent — whether to emit cache breakpoints and how far up the
579
+ * prefix. Either a static value or a function resolved each tool-loop iteration (vary by state).
580
+ * Resolved and applied the same way as {@link BaseAgentConfig.temperature}. Omit to request no
581
+ * caching. Provider-neutral — see {@link CachePolicyInput} / `CachePolicy` for the
582
+ * Anthropic-vs-Gemini behaviour. See {@link CachePolicyInput}.
583
+ *
584
+ * @beta
585
+ */
586
+ cachePolicy?: CachePolicyInput;
587
+ /**
588
+ * Volatile per-turn context injected at the tail of every model-call (after the history and any
589
+ * cache breakpoint), so it is seen each turn without busting the cached prefix — the place to put
590
+ * the changing parts (current file/spec, diagnostics, live state) that would otherwise
591
+ * destabilize a cached system prompt. Provide *raw* content; the framework frames it (wraps it in
592
+ * a `<system-reminder>` marker). Resolved per turn like {@link BaseAgentConfig.temperature}. See
593
+ * {@link TailContextInput}.
594
+ *
595
+ * @beta
596
+ */
597
+ tailContext?: TailContextInput;
576
598
  /**
577
599
  * Optional hook consulted when the model calls a tool the driver cannot
578
600
  * dispatch — either a *stale* tool (advertised earlier this activation but
@@ -641,6 +663,18 @@ declare interface BaseAgentConfig {
641
663
  getDebugSnapshot?: () => unknown;
642
664
  }
643
665
 
666
+ export { CachePolicy }
667
+
668
+ /**
669
+ * Prompt-cache policy for an agent. Either a static `CachePolicy` (resolved once) or a
670
+ * function resolved each tool-loop iteration — pick the function form to vary it by current state
671
+ * (e.g. cache `'history'` in a long generating phase, `'default'` in short low-touch ones). Omit
672
+ * to request no caching. Resolved and applied the same way as {@link TemperatureInput}.
673
+ *
674
+ * @beta
675
+ */
676
+ export declare type CachePolicyInput = CachePolicy | ((ctx: SystemPromptContext) => CachePolicy | Promise<CachePolicy>);
677
+
644
678
  /**
645
679
  * Plain TS class that drives a multi-turn chat conversation, including the tool-call loop.
646
680
  * Owned by `FoundationAiAssistant` — created in `connectedCallback`, torn down in `disconnectedCallback`.
@@ -746,6 +780,15 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
746
780
  * collapsed until IT ends.
747
781
  */
748
782
  private currentActivation;
783
+ /**
784
+ * Monotonic phase-epoch counter — the `phaseEnd` clock. Advanced by the
785
+ * handler-context `endPhase()` (an app-declared phase boundary within one
786
+ * activation), never reset. Unlike `currentActivation` it is NOT tied to agent
787
+ * swaps or releases — it ticks only when the agent itself declares a phase
788
+ * done. `phaseEnd` fires for a payload once a LATER epoch is current
789
+ * (`callPhaseEpoch < currentPhaseEpoch`), with an `agentEnd` backstop.
790
+ */
791
+ private currentPhaseEpoch;
749
792
  /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
750
793
  private foldStack;
751
794
  /** Consecutive fold open/close ops without a real tool call. Reset on real tool execution. */
@@ -854,6 +897,16 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
854
897
  * call; top-level turns are `'auto'`).
855
898
  */
856
899
  private activeToolChoiceInput?;
900
+ /**
901
+ * Active agent's prompt-cache policy selector (static value or per-turn resolver).
902
+ * `undefined` requests no caching (equivalent to `{ scope: 'default' }`).
903
+ */
904
+ private activeCachePolicyInput?;
905
+ /**
906
+ * Active agent's tail-context selector (static value or per-turn resolver). The driver frames
907
+ * the resolved string in a `<system-reminder>` marker and injects it at the message tail.
908
+ */
909
+ private activeTailContextInput?;
857
910
  /**
858
911
  * Active agent's unresolved-tool hook, captured from `applyAgent`. Consulted
859
912
  * only when a tool call cannot be dispatched (a stale or hallucinated name);
@@ -1718,6 +1771,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
1718
1771
  turnIndex: string;
1719
1772
  timestamp: string;
1720
1773
  agentName?: string;
1774
+ tailContext?: string;
1721
1775
  toolNames: string[];
1722
1776
  temperature?: number;
1723
1777
  toolChoice?: ChatToolChoice;
@@ -1746,6 +1800,8 @@ export declare class FoundationAiAssistant extends GenesisElement {
1746
1800
  systemPrompt?: SystemPromptInput;
1747
1801
  temperature?: TemperatureInput;
1748
1802
  toolChoice?: ToolChoiceInput;
1803
+ cachePolicy?: CachePolicyInput;
1804
+ tailContext?: TailContextInput;
1749
1805
  onUnresolvedTool?: UnresolvedToolInput;
1750
1806
  primerHistory?: ChatMessage[];
1751
1807
  subAgents?: AgentConfig[];
@@ -2283,6 +2339,19 @@ export declare interface StatefulAgentInit<S> {
2283
2339
  * for the default.
2284
2340
  */
2285
2341
  toolChoice?: ChatToolChoice | ((ctx: StatefulAgentContext<S>) => ChatToolChoice | Promise<ChatToolChoice>);
2342
+ /**
2343
+ * Prompt-cache policy. Either a static `CachePolicy` or a function resolved each tool-loop
2344
+ * iteration with the current `state` — pick the function form to vary it per machine state
2345
+ * (e.g. `'history'` in a long generating phase, `'default'` in short low-touch ones). Omit to
2346
+ * request no caching.
2347
+ */
2348
+ cachePolicy?: CachePolicy | ((ctx: StatefulAgentContext<S>) => CachePolicy | Promise<CachePolicy>);
2349
+ /**
2350
+ * Volatile per-turn tail context (current file/spec, diagnostics, live state). Either a static
2351
+ * string or a function resolved each tool-loop iteration with the current `state`. Provide raw
2352
+ * content; the framework frames it. Omit, or return an empty string, for none.
2353
+ */
2354
+ tailContext?: string | ((ctx: StatefulAgentContext<S>) => string | Promise<string>);
2286
2355
  /**
2287
2356
  * Hook consulted when the model calls a tool that isn't dispatchable in the
2288
2357
  * current state — a *stale* tool (valid in an earlier state of this agent) or
@@ -2374,6 +2443,17 @@ export declare interface SystemPromptContext {
2374
2443
  */
2375
2444
  export declare type SystemPromptInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
2376
2445
 
2446
+ /**
2447
+ * Per-turn tail context for an agent — volatile content (current file/spec, diagnostics, live
2448
+ * state) injected at the tail of every model-call so the model sees it without invalidating the
2449
+ * cached prefix. Either a static string or a function resolved each tool-loop iteration. **Provide
2450
+ * raw content** — the framework frames it (wraps it in a `<system-reminder>` marker) so the model
2451
+ * reads it as ambient context, not user input. Omit, or return an empty string, for none.
2452
+ *
2453
+ * @beta
2454
+ */
2455
+ export declare type TailContextInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
2456
+
2377
2457
  /**
2378
2458
  * Sampling temperature for an agent, normalized to `0`–`1` (`0` = deterministic,
2379
2459
  * `1` = the most random the active provider allows). Either a static number
@@ -2526,8 +2606,22 @@ export declare interface TurnSnapshot {
2526
2606
  timestamp: string;
2527
2607
  /** Name of the agent active when this LLM call ran. */
2528
2608
  agentName?: string;
2529
- /** Final system prompt sent to the LLM (post-fold-suffix, post-retry hint). */
2609
+ /**
2610
+ * The agent's resolved system prompt sent to the LLM, verbatim. NOTE: this is
2611
+ * now the *bare* prompt — the fold-surface suffix and the malformed/empty retry
2612
+ * nudge no longer mutate it (they kept it byte-unstable and busted prompt
2613
+ * caching), so they moved to {@link TurnSnapshot.tailContext}. To reconstruct
2614
+ * exactly what the model saw, read both fields.
2615
+ */
2530
2616
  systemPrompt?: string;
2617
+ /**
2618
+ * The framed `<system-reminder>` tail appended to the final user turn for this
2619
+ * call, verbatim — never part of stored history, so this snapshot is the only
2620
+ * record of it. Carries the framework's volatile additions (fold suffix, retry
2621
+ * nudge) and the agent's per-turn `tailContext` (e.g. current file spec, live
2622
+ * diagnostics). Undefined when the tail was empty (the normal case).
2623
+ */
2624
+ tailContext?: string;
2531
2625
  /** Tool names sent to the LLM, in order — definitions are static per name so names alone suffice. */
2532
2626
  toolNames: string[];
2533
2627
  /**
@@ -33,8 +33,22 @@ export interface TurnSnapshot {
33
33
  timestamp: string;
34
34
  /** Name of the agent active when this LLM call ran. */
35
35
  agentName?: string;
36
- /** Final system prompt sent to the LLM (post-fold-suffix, post-retry hint). */
36
+ /**
37
+ * The agent's resolved system prompt sent to the LLM, verbatim. NOTE: this is
38
+ * now the *bare* prompt — the fold-surface suffix and the malformed/empty retry
39
+ * nudge no longer mutate it (they kept it byte-unstable and busted prompt
40
+ * caching), so they moved to {@link TurnSnapshot.tailContext}. To reconstruct
41
+ * exactly what the model saw, read both fields.
42
+ */
37
43
  systemPrompt?: string;
44
+ /**
45
+ * The framed `<system-reminder>` tail appended to the final user turn for this
46
+ * call, verbatim — never part of stored history, so this snapshot is the only
47
+ * record of it. Carries the framework's volatile additions (fold suffix, retry
48
+ * nudge) and the agent's per-turn `tailContext` (e.g. current file spec, live
49
+ * diagnostics). Undefined when the tail was empty (the normal case).
50
+ */
51
+ tailContext?: string;
38
52
  /** Tool names sent to the LLM, in order — definitions are static per name so names alone suffice. */
39
53
  toolNames: string[];
40
54
  /**
@@ -163,6 +177,15 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
163
177
  * collapsed until IT ends.
164
178
  */
165
179
  private currentActivation;
180
+ /**
181
+ * Monotonic phase-epoch counter — the `phaseEnd` clock. Advanced by the
182
+ * handler-context `endPhase()` (an app-declared phase boundary within one
183
+ * activation), never reset. Unlike `currentActivation` it is NOT tied to agent
184
+ * swaps or releases — it ticks only when the agent itself declares a phase
185
+ * done. `phaseEnd` fires for a payload once a LATER epoch is current
186
+ * (`callPhaseEpoch < currentPhaseEpoch`), with an `agentEnd` backstop.
187
+ */
188
+ private currentPhaseEpoch;
166
189
  /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
167
190
  private foldStack;
168
191
  /** Consecutive fold open/close ops without a real tool call. Reset on real tool execution. */
@@ -271,6 +294,16 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
271
294
  * call; top-level turns are `'auto'`).
272
295
  */
273
296
  private activeToolChoiceInput?;
297
+ /**
298
+ * Active agent's prompt-cache policy selector (static value or per-turn resolver).
299
+ * `undefined` requests no caching (equivalent to `{ scope: 'default' }`).
300
+ */
301
+ private activeCachePolicyInput?;
302
+ /**
303
+ * Active agent's tail-context selector (static value or per-turn resolver). The driver frames
304
+ * the resolved string in a `<system-reminder>` marker and injects it at the message tail.
305
+ */
306
+ private activeTailContextInput?;
274
307
  /**
275
308
  * Active agent's unresolved-tool hook, captured from `applyAgent`. Consulted
276
309
  * only when a tool call cannot be dispatched (a stale or hallucinated name);
@@ -1 +1 @@
1
- {"version":3,"file":"chat-driver.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"chat-driver.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.ts"],"names":[],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"chat-driver.test.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.test.ts"],"names":[],"mappings":"AAmBA,OAAO,uBAAuB,CAAC"}
1
+ {"version":3,"file":"chat-driver.test.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.test.ts"],"names":[],"mappings":"AAoBA,OAAO,uBAAuB,CAAC"}
@@ -1,5 +1,5 @@
1
- import type { ChatInputDuringExecutionMode, ChatMessage, ChatToolChoice, ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
2
- export type { ChatInputDuringExecutionMode, ChatToolChoice };
1
+ import type { CachePolicy, ChatInputDuringExecutionMode, ChatMessage, ChatToolChoice, ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
2
+ export type { CachePolicy, ChatInputDuringExecutionMode, ChatToolChoice };
3
3
  /**
4
4
  * Context passed to `onActivate` / `onDeactivate` lifecycle hooks on an agent.
5
5
  *
@@ -94,6 +94,25 @@ export type TemperatureInput = number | ((ctx: SystemPromptContext) => number |
94
94
  * @beta
95
95
  */
96
96
  export type ToolChoiceInput = ChatToolChoice | ((ctx: SystemPromptContext) => ChatToolChoice | Promise<ChatToolChoice>);
97
+ /**
98
+ * Prompt-cache policy for an agent. Either a static `CachePolicy` (resolved once) or a
99
+ * function resolved each tool-loop iteration — pick the function form to vary it by current state
100
+ * (e.g. cache `'history'` in a long generating phase, `'default'` in short low-touch ones). Omit
101
+ * to request no caching. Resolved and applied the same way as {@link TemperatureInput}.
102
+ *
103
+ * @beta
104
+ */
105
+ export type CachePolicyInput = CachePolicy | ((ctx: SystemPromptContext) => CachePolicy | Promise<CachePolicy>);
106
+ /**
107
+ * Per-turn tail context for an agent — volatile content (current file/spec, diagnostics, live
108
+ * state) injected at the tail of every model-call so the model sees it without invalidating the
109
+ * cached prefix. Either a static string or a function resolved each tool-loop iteration. **Provide
110
+ * raw content** — the framework frames it (wraps it in a `<system-reminder>` marker) so the model
111
+ * reads it as ambient context, not user input. Omit, or return an empty string, for none.
112
+ *
113
+ * @beta
114
+ */
115
+ export type TailContextInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
97
116
  /**
98
117
  * Context passed to an agent's `onUnresolvedTool` hook when the model calls a
99
118
  * tool the driver cannot dispatch.
@@ -231,6 +250,27 @@ interface BaseAgentConfig {
231
250
  * @beta
232
251
  */
233
252
  toolChoice?: ToolChoiceInput;
253
+ /**
254
+ * Prompt-cache policy for this agent — whether to emit cache breakpoints and how far up the
255
+ * prefix. Either a static value or a function resolved each tool-loop iteration (vary by state).
256
+ * Resolved and applied the same way as {@link BaseAgentConfig.temperature}. Omit to request no
257
+ * caching. Provider-neutral — see {@link CachePolicyInput} / `CachePolicy` for the
258
+ * Anthropic-vs-Gemini behaviour. See {@link CachePolicyInput}.
259
+ *
260
+ * @beta
261
+ */
262
+ cachePolicy?: CachePolicyInput;
263
+ /**
264
+ * Volatile per-turn context injected at the tail of every model-call (after the history and any
265
+ * cache breakpoint), so it is seen each turn without busting the cached prefix — the place to put
266
+ * the changing parts (current file/spec, diagnostics, live state) that would otherwise
267
+ * destabilize a cached system prompt. Provide *raw* content; the framework frames it (wraps it in
268
+ * a `<system-reminder>` marker). Resolved per turn like {@link BaseAgentConfig.temperature}. See
269
+ * {@link TailContextInput}.
270
+ *
271
+ * @beta
272
+ */
273
+ tailContext?: TailContextInput;
234
274
  /**
235
275
  * Optional hook consulted when the model calls a tool the driver cannot
236
276
  * dispatch — either a *stale* tool (advertised earlier this activation but