@genesislcap/ai-assistant 15.26.0 → 15.27.0

package/dist/custom-elements.json

@@ -1775,6 +1775,12 @@
       "kind": "javascript-module",
       "path": "src/main/main.template.ts",
       "declarations": [
+        {
+          "kind": "variable",
+          "name": "messageTimestampTemplate",
+          "default": "html<ChatMessage, FoundationAiAssistant>`\n  <time\n    class=\"message-timestamp\"\n    part=\"message-timestamp\"\n    datetime=\"${(m) => messageTimestampDateTime(m.timestamp)}\"\n  >\n    <span aria-hidden=\"true\">\n      ${(m, c) => formatMessageTimestamp(m.timestamp, c.parent.timestampClock)}\n    </span>\n    <span class=\"visually-hidden\">${(m) => formatAbsoluteTimestamp(m.timestamp)}</span>\n  </time>\n`",
+          "description": "The timestamp shown beside the sender name (GENC-1257).\n\nTwo strings, not one. A screen reader announces a `<time>` element's TEXT — it has no\nimplicit ARIA role, and the `datetime` attribute is never surfaced to the user — so the\nrelative text is hidden from assistive tech and paired with a visually-hidden absolute\nstring. Otherwise AT would hear \"5 minutes ago\" with nothing to anchor it, and in\n`'hover'` mode would hear it for a timestamp sighted users never asked to see.\n`datetime` stays because it is correct HTML and useful to tooling, not for a11y.\n\nOnly the VISUAL reveal is hover-gated, in CSS — see `.message-timestamp`. `opacity: 0`\nleaves the element in the accessibility tree, so AT gets a time in both visible modes;\n`'off'` is the only mode that removes it.\n\nReads `timestampClock` rather than `Date.now()` so every row shares one invalidatable\nclock and a tick re-evaluates them all; see `FoundationAiAssistant.timestampClock`."
+        },
         {
           "kind": "function",
           "name": "FoundationAiAssistantTemplate",
@@ -1794,6 +1800,14 @@
         }
       ],
       "exports": [
+        {
+          "kind": "js",
+          "name": "messageTimestampTemplate",
+          "declaration": {
+            "name": "messageTimestampTemplate",
+            "module": "src/main/main.template.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "FoundationAiAssistantTemplate",
@@ -2232,6 +2246,42 @@
               },
               "description": "Current user-facing toggle state for agent switch indicator visibility."
             },
+            {
+              "kind": "field",
+              "name": "timestampDisplay",
+              "type": {
+                "text": "TimestampDisplay"
+              },
+              "description": "When each message shows its timestamp — `'off'`, `'hover'` (default) or `'always'`.\n\nFalls back to `DEFAULT_TIMESTAMP_DISPLAY` rather than `'off'` when there is no\nstore yet: this preference defaults ON, so the pre-store render must match the state\nthe baseline is about to resolve to, or timestamps would visibly pop in on connect."
+            },
+            {
+              "kind": "field",
+              "name": "timestampClock",
+              "type": {
+                "text": "number"
+              },
+              "description": "Epoch ms the transcript's relative timestamps are measured against.\n\nA relative label is only correct at the instant it renders: FAST evaluates the\nbinding once, and an idle conversation never re-renders, so \"2 minutes ago\" would\nstill read \"2 minutes ago\" an hour later. Making the formatter read this observable\ninstead of `Date.now()` gives every row one shared, invalidatable clock — a tick\nre-evaluates them all."
+            },
+            {
+              "kind": "field",
+              "name": "_timestampClockTimer",
+              "type": {
+                "text": "ReturnType<typeof setInterval> | undefined"
+              },
+              "privacy": "private",
+              "description": "Handle for the `TIMESTAMP_CLOCK_INTERVAL_MS` ticker; undefined while stopped."
+            },
+            {
+              "kind": "method",
+              "name": "syncTimestampClock",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Start or stop the timestamp clock to match the current mode and connection state.\n\nIdempotent, and safe to call from either lifecycle end — it is driven from\n`connectedCallback`, `disconnectedCallback` and the `timestampDisplay` setter, which\ncan fire in any order. Nothing runs while the mode is `'off'` (no binding reads the\nclock) or while disconnected (a timer outliving its element is a leak, and a\npopped-out view disconnects without the session ending)."
+            },
             {
               "kind": "field",
               "name": "enabledAnimations",
@@ -5848,18 +5898,6 @@
       "declarations": [],
       "exports": []
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/types/ai-chat-widget.ts",
-      "declarations": [],
-      "exports": []
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/types/interaction-context.ts",
-      "declarations": [],
-      "exports": []
-    },
     {
       "kind": "javascript-module",
       "path": "src/utils/agents-key.ts",
@@ -6785,6 +6823,119 @@
       "declarations": [],
       "exports": []
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/format-message-timestamp.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "ABSOLUTE_FORMAT_OPTIONS",
+          "type": {
+            "text": "Intl.DateTimeFormatOptions"
+          },
+          "default": "{\n  day: 'numeric',\n  month: 'short',\n  year: 'numeric',\n  hour: '2-digit',\n  minute: '2-digit',\n  hourCycle: 'h23',\n}",
+          "description": "Field selection for the absolute tier.\n\nExported so tests can build their expectation from the same options rather than from a\nliteral: every field below renders differently per locale and time zone, so asserting\n`\"Sep\"` or `\"10\"` only asserts the machine the test happened to run on.\n\nLocale is left undefined so it follows the user's, and `hourCycle: 'h23'` pins the clock\nto 24-hour regardless — a locale-chosen 12-hour clock would add \"am\"/\"pm\" and widen the\nstring next to the sender name."
+        },
+        {
+          "kind": "function",
+          "name": "formatMessageTimestamp",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "iso",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "ISO-8601 timestamp, as stamped by the driver on append."
+            },
+            {
+              "name": "now",
+              "type": {
+                "text": "number"
+              },
+              "description": "Current epoch ms. Passed in rather than read, so tests pin the clock."
+            }
+          ],
+          "description": "Display text for a message timestamp, per the tiers above.\n\nA timestamp slightly in the future (clock skew between a server-stamped message and the\nbrowser) reads `Now` rather than a negative count — \"-3 minutes ago\" looks broken and\ntells the user nothing. That indulgence is bounded at an hour: beyond it the stamp is\nnot skew but bad data (a machine with a badly wrong clock, a hand-edited session), and\nshowing `Now` forever on every message would hide that. Past the bound it falls through\nto the absolute tier, which shows the user what the data actually says."
+        },
+        {
+          "kind": "function",
+          "name": "formatAbsoluteTimestamp",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "iso",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "ISO-8601 timestamp, as stamped by the driver on append."
+            }
+          ],
+          "description": "The absolute rendering of a stamp, whatever its age — the accessible text behind a\nmessage timestamp.\n\nExists because the visible text is relative and a screen reader announces the element's\nTEXT, not its `datetime` attribute: `<time>` carries no implicit ARIA role, so the\nmachine-readable value reaches tooling and nobody else. The template pairs this with\n`aria-hidden` on the relative string so assistive tech hears one unambiguous time\ninstead of \"5 minutes ago\" with no anchor."
+        },
+        {
+          "kind": "function",
+          "name": "messageTimestampDateTime",
+          "return": {
+            "type": {
+              "text": "string | null"
+            }
+          },
+          "parameters": [
+            {
+              "name": "iso",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "ISO-8601 timestamp, as stamped by the driver on append."
+            }
+          ],
+          "description": "The `datetime` attribute value for the rendered `<time>` element — the raw ISO string,\nwhich is what the HTML spec wants and what date-aware tooling reads. It is NOT an\naccessibility affordance: screen readers announce the element's text content instead.\n\nReturns `null`, not `''`, for a missing or unparseable stamp: FAST removes an attribute\nonly for `null`/`undefined` (see `DOM.setAttribute`), so an empty string would emit\n`datetime=\"\"`, which is invalid per spec and flagged by HTML validators."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ABSOLUTE_FORMAT_OPTIONS",
+          "declaration": {
+            "name": "ABSOLUTE_FORMAT_OPTIONS",
+            "module": "src/utils/format-message-timestamp.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "formatMessageTimestamp",
+          "declaration": {
+            "name": "formatMessageTimestamp",
+            "module": "src/utils/format-message-timestamp.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "formatAbsoluteTimestamp",
+          "declaration": {
+            "name": "formatAbsoluteTimestamp",
+            "module": "src/utils/format-message-timestamp.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "messageTimestampDateTime",
+          "declaration": {
+            "name": "messageTimestampDateTime",
+            "module": "src/utils/format-message-timestamp.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/format-usd.ts",
@@ -7407,8 +7558,27 @@
     {
       "kind": "javascript-module",
       "path": "src/utils/resolve-preference-baseline.ts",
-      "declarations": [],
-      "exports": []
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "DEFAULT_TIMESTAMP_DISPLAY",
+          "type": {
+            "text": "TimestampDisplay"
+          },
+          "default": "'hover'",
+          "description": "The mode used when neither the host config nor stored prefs name a valid one."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DEFAULT_TIMESTAMP_DISPLAY",
+          "declaration": {
+            "name": "DEFAULT_TIMESTAMP_DISPLAY",
+            "module": "src/utils/resolve-preference-baseline.ts"
+          }
+        }
+      ]
     },
     {
       "kind": "javascript-module",
@@ -7738,6 +7908,18 @@
       "declarations": [],
       "exports": []
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/types/ai-chat-widget.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/types/interaction-context.ts",
+      "declarations": [],
+      "exports": []
+    },
     {
       "kind": "javascript-module",
       "path": "src/components/activity-halo/activity-halo.ts",
@@ -9095,16 +9277,14 @@
             },
             {
               "kind": "field",
-              "name": "pendingInteractions",
-              "privacy": "private",
-              "default": "new Map<\n    string,\n    {\n      resolve: (value: any) => void;\n      reject: (reason?: any) => void;\n      /** Present when the call requested a chat-input override. */\n      overrideId?: string;\n      /** Present when the call set `timeoutMs`; cleared on resolution. */\n      timeoutHandle?: ReturnType<typeof setTimeout>;\n    }\n  >()"
-            },
-            {
-              "kind": "field",
-              "name": "interactionContexts",
+              "name": "interactions",
+              "type": {
+                "text": "InteractionController"
+              },
               "privacy": "private",
-              "default": "new Map<string, InteractionContextHandle>()",
-              "description": "Live per-interaction contexts (GENC-1390), keyed by interactionId. Created in\n`requestInteraction` alongside the pending entry, disposed + removed in\n`resolveInteraction`. Non-serialisable (sockets, timers, subscriber sets), so\nthey live here on the driver — not on the DOM, not in the persisted store — and\ntherefore survive the element remounts (layout reflow/drag, transcript\nre-render) that this feature exists to make harmless. At most one is live at a\ntime (see the one-interaction-at-a-time guard in `requestInteraction`)."
+              "readonly": true,
+              "description": "Custom UI interactions: the pending call, its live context, and any host to delegate to.",
+              "default": "new InteractionController({\n      sessionKey,\n      activityBus,\n      activeAgentName: () => this.activeAgentName,\n      appendToHistory: (message) => this.appendToHistory(message),\n      patchInteractionMessage: (interactionId, patch) =>\n        this.patchInteractionMessage(interactionId, patch),\n      notifyHistoryUpdated: () => this.notifyHistoryUpdated(),\n      emit: (event) => this.dispatchEvent(event),\n      foldDiagnostics: (interactionId, harvested) =>\n        this.turnRecorder.foldDiagnostics(interactionId, harvested),\n    })"
             },
             {
               "kind": "field",
@@ -9194,15 +9374,6 @@
               },
               "privacy": "private"
             },
-            {
-              "kind": "field",
-              "name": "hostInteractionRequester",
-              "type": {
-                "text": "<T>(\n    componentName: string,\n    data: any,\n    options?: InteractionRequestOptions,\n  ) => Promise<T> | undefined"
-              },
-              "privacy": "private",
-              "description": "When set, `requestInteraction` delegates to this callback instead of using\nthis driver's own pending map. Wired by `invokeSubAgent` so a sub-agent's\nwidget renders in — and resolves through — the parent (ultimately the\nroot) driver, where the main UI is listening."
-            },
             {
               "kind": "field",
               "name": "providerHistoryTransform",
@@ -9362,63 +9533,14 @@
             },
             {
               "kind": "field",
-              "name": "turnSnapshots",
-              "type": {
-                "text": "TurnSnapshot[]"
-              },
-              "privacy": "private",
-              "default": "[]",
-              "description": "Ring buffer of per-LLM-call snapshots. Cap is configurable via\n`chatConfig.agent.maxTurnSnapshots`; older entries drop off as new ones\narrive. See TurnSnapshot for the captured shape."
-            },
-            {
-              "kind": "field",
-              "name": "externalDiagnostics",
-              "type": {
-                "text": "DiagnosticEntry[]"
-              },
-              "privacy": "private",
-              "readonly": true,
-              "default": "[]",
-              "description": "`turn` + `message` diagnostic-log entries harvested from an out-of-band source (a resolved\ninteraction whose widget returned `InteractionResult.diagnostics` — e.g. a server-side\nChatDriver's debug log). `event` entries are NOT kept here — they're folded into the session's\nmeta-event registry via `mergeMetaEvents` (see `resolveInteraction`) so they inherit fresh host\nindices, and reach the log through `getMetaEvents`. Append-only; the host folds these into its\ndebug log alongside this driver's own timeline. Not cleared here — it lives with the driver\ninstance, like `turnSnapshots`, so a new chat (fresh driver) starts empty while a compaction\n(same instance) keeps it. (GENC-1461.)"
-            },
-            {
-              "kind": "field",
-              "name": "externalDiagnosticsBatches",
-              "type": {
-                "text": "number"
-              },
-              "privacy": "private",
-              "default": "0",
-              "description": "Monotonic count of external-diagnostics batches harvested this driver-lifetime. Namespaces each\nbatch's re-keyed `turn` entries so distinct server generations in one chat session can't collide\non `turnIndex` in the forward-capture persister (which dedups turns by that key). (GENC-1461.)"
-            },
-            {
-              "kind": "field",
-              "name": "globalTurnIndex",
-              "type": {
-                "text": "number"
-              },
-              "privacy": "private",
-              "default": "0",
-              "description": "Monotonic counter that survives agent swaps — useful for cross-referencing with history."
-            },
-            {
-              "kind": "field",
-              "name": "debugSnapshotter",
-              "type": {
-                "text": "() => unknown | undefined"
-              },
-              "privacy": "private",
-              "description": "Captured from `applyAgent` so we don't store the whole `AgentConfig`."
-            },
-            {
-              "kind": "field",
-              "name": "maxTurnSnapshots",
+              "name": "turnRecorder",
               "type": {
-                "text": "number"
+                "text": "TurnRecorder"
               },
               "privacy": "private",
               "readonly": true,
-              "default": "maxTurnSnapshots"
+              "description": "Per-turn snapshots, forwarded sub-agent snapshots, and harvested external diagnostics —\neverything the exported debug log draws from this driver.",
+              "default": "new TurnRecorder(sessionKey, maxTurnSnapshots)"
             },
             {
               "kind": "field",
@@ -9727,7 +9849,7 @@
                   "text": "Promise<void>"
                 }
               },
-              "description": "Tear down the driver: aborts the lifecycle signal so any in-flight provider\nrequest (and prompt/tool factories awaiting it) cancels instead of running\non to completion or the transport timeout. Called by the host on driver\nswap and by `OrchestratingDriver.dispose()`. Idempotent.\n\nDeliberately does NOT settle `pendingInteractions` here: dispose is never\nreached while one is pending. The only host-level dispose is the agent-swap\nrebuild, which is guarded by `isBusy()` — a pending interaction keeps the\ntool loop suspended (`busy === true`), so the swap is deferred until the\nwidget resolves. Sub-agent child disposes always have an empty pending map\n(widgets park on the parent via `setHostInteractionRequester`). A pending\ninteraction is instead settled by `resolveInteraction` (user response or\ntimeout), which also stamps history and reverts the chat-input override."
+              "description": "Tear down the driver: aborts the lifecycle signal so any in-flight provider\nrequest (and prompt/tool factories awaiting it) cancels instead of running\non to completion or the transport timeout. Called by the host on driver\nswap and by `OrchestratingDriver.dispose()`. Idempotent.\n\nDeliberately does NOT settle pending interactions here: dispose is never\nreached while one is pending. The only host-level dispose is the agent-swap\nrebuild, which is guarded by `isBusy()` — a pending interaction keeps the\ntool loop suspended (`busy === true`), so the swap is deferred until the\nwidget resolves. Sub-agent child disposes always have an empty pending map\n(widgets park on the parent via `setHostInteractionRequester`). A pending\ninteraction is instead settled by `resolveInteraction` (user response or\ntimeout), which also stamps history and reverts the chat-input override."
             },
             {
               "kind": "method",
@@ -10174,7 +10296,7 @@
                   "text": "ReadonlyArray<TurnSnapshot>"
                 }
               },
-              "description": "Return the per-turn snapshots captured so far. Used by the host's debug\nlog exporter to show what the LLM saw on each turn — system prompt, tool\nsurface, and agent-supplied state (e.g. a machine snapshot).\n\nRing-buffered at `MAX_TURN_SNAPSHOTS`; older entries are dropped."
+              "description": "Return the per-turn snapshots captured so far. Used by the host's debug\nlog exporter to show what the LLM saw on each turn — system prompt, tool\nsurface, and agent-supplied state (e.g. a machine snapshot).\n\nRing-buffered at `maxTurnSnapshots`; older entries are dropped."
             },
             {
               "kind": "method",
@@ -10184,12 +10306,29 @@
                   "text": "ReadonlyArray<DiagnosticEntry>"
                 }
               },
-              "description": "The `turn` + `message` diagnostic-log entries harvested from resolved interactions'\n`InteractionResult.diagnostics` (e.g. a server-side ChatDriver's collated debug log). The host\nconcatenates these into its own debug log so `downloadDebugLog`/the persisted diagnostics stream\ninclude external-engine logs; `event` entries are excluded here because they're merged into the\nsession's meta-event registry instead (see `resolveInteraction`) and reach the log via\n`getMetaEvents`. Opaque, chronologically sorted by the host at assemble time. (GENC-1461.)"
+              "description": "The `turn` + `message` diagnostic-log entries harvested from resolved interactions'\n`InteractionResult.diagnostics` (e.g. a server-side ChatDriver's collated debug log). The host\nconcatenates these into its own debug log so `downloadDebugLog`/the persisted diagnostics stream\ninclude external-engine logs; `event` entries are excluded here because they're merged into the\nsession's meta-event registry instead and reach the log via `getMetaEvents`. Opaque,\nchronologically sorted by the host at assemble time. (GENC-1461.)"
             },
             {
-              "kind": "method",
-              "name": "forwardSubAgentSnapshots",
+              "kind": "field",
+              "name": "contextGuard",
+              "type": {
+                "text": "ContextGuardPolicy | undefined"
+              },
+              "privacy": "private",
+              "description": "Mid-loop context guard policy (GENC-1567). `undefined` disables the guard.\n\nCarries a MARGIN rather than an absolute threshold, and the difference is the\nwhole point: the threshold depends on the window of whichever provider the\nnext call resolves to, which the driver learns during the call and the host\ncannot know until afterwards. The host owns the policy; the driver applies it\nagainst the model actually being addressed."
+            },
+            {
+              "kind": "field",
+              "name": "lastResolvedContextLimit",
+              "type": {
+                "text": "number | undefined"
+              },
               "privacy": "private",
+              "description": "Window of the provider the current call resolved to, if it reports one."
+            },
+            {
+              "kind": "method",
+              "name": "setContextGuard",
               "return": {
                 "type": {
                   "text": "void"
@@ -10197,109 +10336,36 @@
               },
               "parameters": [
                 {
-                  "name": "childSnapshots",
+                  "name": "policy",
+                  "optional": true,
                   "type": {
-                    "text": "ReadonlyArray<TurnSnapshot>"
+                    "text": "ContextGuardPolicy"
                   }
                 }
               ],
-              "description": "Merge a sub-agent's turn snapshots into this driver's buffer so they surface\nas `kind:'turn'` entries in the exported debug log. The child runs as a\nseparate, discarded driver, so its snapshots would otherwise be lost. Each is\nre-labelled under the parent turn that activated the sub-agent: the child's\nown (numeric) turns become `\"<parentTurn>-1\"`, `\"-2\"`, … (1-based, in order);\nany already-forwarded grand-child labels (strings) have their leading segment\nremapped the same way, so nesting composes (`\"5-2\"` → `\"5-2-1\"`).\n\nNote: two sub-agents invoked in the *same* parent turn share the prefix, so\ntheir labels can repeat — `agentName` on each snapshot disambiguates them."
+              "description": "Set the mid-loop context guard. Its margin is deliberately far smaller than\nthe reserve that blocks NEW turns: that reserve exists so an accepted turn can\nspend it, and a guard set at the same line would kill every turn that used\nthe headroom it was given."
             },
             {
               "kind": "method",
-              "name": "recordTurnSnapshot",
+              "name": "contextExhausted",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "TurnSnapshot"
+                  "text": "{ estimated: number; threshold: number } | undefined"
                 }
               },
               "parameters": [
                 {
-                  "name": "resolvedSystemPrompt",
-                  "type": {
-                    "text": "string | undefined"
-                  }
-                },
-                {
-                  "name": "temperature",
+                  "name": "requestHistory",
                   "type": {
-                    "text": "number | undefined"
+                    "text": "readonly ChatMessage[]"
                   }
                 },
                 {
-                  "name": "toolChoice",
+                  "name": "pendingInput",
+                  "optional": true,
                   "type": {
-                    "text": "ChatToolChoice | undefined"
-                  }
-                },
-                {
-                  "name": "tailContext",
-                  "type": {
-                    "text": "string | undefined"
-                  }
-                }
-              ],
-              "description": "Push one snapshot to the ring buffer. Called inside `runToolLoop` just\nbefore each LLM call — that's the latest point where the prompt, tool\nsurface, and agent state line up with what the model is about to see.\n\nReturns the pushed object so the caller can back-fill what only the response\nknows (`usage`). Mutating it after the fact is safe whether or not the ring\nbuffer has since evicted it — an evicted snapshot is simply no longer exported."
-            },
-            {
-              "kind": "field",
-              "name": "contextGuard",
-              "type": {
-                "text": "ContextGuardPolicy | undefined"
-              },
-              "privacy": "private",
-              "description": "Mid-loop context guard policy (GENC-1567). `undefined` disables the guard.\n\nCarries a MARGIN rather than an absolute threshold, and the difference is the\nwhole point: the threshold depends on the window of whichever provider the\nnext call resolves to, which the driver learns during the call and the host\ncannot know until afterwards. The host owns the policy; the driver applies it\nagainst the model actually being addressed."
-            },
-            {
-              "kind": "field",
-              "name": "lastResolvedContextLimit",
-              "type": {
-                "text": "number | undefined"
-              },
-              "privacy": "private",
-              "description": "Window of the provider the current call resolved to, if it reports one."
-            },
-            {
-              "kind": "method",
-              "name": "setContextGuard",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "policy",
-                  "optional": true,
-                  "type": {
-                    "text": "ContextGuardPolicy"
-                  }
-                }
-              ],
-              "description": "Set the mid-loop context guard. Its margin is deliberately far smaller than\nthe reserve that blocks NEW turns: that reserve exists so an accepted turn can\nspend it, and a guard set at the same line would kill every turn that used\nthe headroom it was given."
-            },
-            {
-              "kind": "method",
-              "name": "contextExhausted",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "{ estimated: number; threshold: number } | undefined"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "requestHistory",
-                  "type": {
-                    "text": "readonly ChatMessage[]"
-                  }
-                },
-                {
-                  "name": "pendingInput",
-                  "optional": true,
-                  "type": {
-                    "text": "{ content: string; attachments?: ChatAttachment[] }"
+                    "text": "{ content: string; attachments?: ChatAttachment[] }"
                   }
                 }
               ],
@@ -10321,7 +10387,8 @@
                     "text": "(history: ChatMessage[]) => ChatMessage[]"
                   }
                 }
-              ]
+              ],
+              "description": "Optional transform applied to conversation history immediately before each LLM request.\nCleared when `undefined`. Does not alter stored history."
             },
             {
               "kind": "method",
@@ -10553,7 +10620,7 @@
                   "description": "a positive delta in USD. Non-finite, zero and negative values are ignored."
                 }
               ],
-              "description": "Add external (non-LLM) spend to an interaction's message AFTER it has resolved.\n\n**Why this exists separately from `resolveInteraction`.** A widget's spend reaches the session\ntotal only through `InteractionResult.costUsd`, which is read exactly once — `resolveInteraction`\ndoes its whole job inside `if (interaction)` and then deletes the entry from\n`pendingInteractions`. That is correct for the resolution itself, but it assumes a widget stops\ncosting money when it resolves, and several deliberately do not: a widget that resolves EARLY so\nthe assistant stops waiting (options shown, a preview rendered) may stay interactive for minutes\nafterwards and do more paid work on the user's behalf. Re-emitting `interaction-completed` does\nnot help — with the interaction gone from the map the call is a silent no-op — so that spend had\nnowhere to go and was simply missing from the figure shown to the user.\n\nAdditive by design: the caller reports a DELTA, not a running total, so repeated calls sum. It\ntouches only `externalCostUsd`; the recorded `interaction.resolved` payload is left exactly as\nthe resolution wrote it, because this is not a second resolution and must not read like one.\n\nDeliberately does NOT require the interaction to be pending, does not resurrect it, and has no\nloading/turn side effects — this is bookkeeping about a turn that already happened."
+              "description": "Add external (non-LLM) spend to an interaction's message AFTER it has resolved — for a widget\nthat resolves early so the assistant stops waiting, then keeps doing paid work on the user's\nbehalf. `InteractionController.recordExternalCost` explains why the resolution path cannot\ncarry this.\n\nAdditive by design: the caller reports a DELTA, not a running total, so repeated calls sum.\n\nDeliberately does NOT require the interaction to be pending, does not resurrect it, and has no\nloading/turn side effects — this is bookkeeping about a turn that already happened."
             },
             {
               "kind": "method",
@@ -10601,22 +10668,28 @@
             },
             {
               "kind": "method",
-              "name": "cancelPendingInteractions",
+              "name": "patchInteractionMessage",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "void"
+                  "text": "boolean"
                 }
               },
               "parameters": [
                 {
-                  "name": "message",
+                  "name": "interactionId",
                   "type": {
                     "text": "string"
                   }
+                },
+                {
+                  "name": "patch",
+                  "type": {
+                    "text": "(message: ChatMessage) => ChatMessage"
+                  }
                 }
               ],
-              "description": "Resolve every in-flight interaction with a `'timeout'` result, closing its\nwidget read-only. Used when a sub-agent that owns the open widget times out:\nthe widget is parked in *this* driver's map (interactions resolve on the\nhost, not the child), so cancelling it here unblocks the sub-agent handler\nawaiting it. The \"one interaction at a time\" invariant means there is at\nmost one."
+              "description": "Replace the history message owning `interactionId`. `false` when it is no longer in history.\nDoes not announce the change — the interaction paths differ on whether they should."
             },
             {
               "kind": "method",
@@ -10798,6 +10871,17 @@
                   }
                 }
               ]
+            },
+            {
+              "kind": "method",
+              "name": "notifyHistoryUpdated",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Announce the current history to the host."
             }
           ],
           "events": [
@@ -10808,43 +10892,25 @@
               }
             },
             {
-              "name": "interaction-start",
-              "type": {
-                "text": "CustomEvent"
-              }
-            },
-            {
-              "name": "external-cost-recorded",
-              "type": {
-                "text": "CustomEvent"
-              }
-            },
-            {
-              "name": "history-updated",
-              "type": {
-                "text": "CustomEvent"
-              }
-            },
-            {
-              "name": "interaction-stop",
+              "name": "sub-agent-history-updated",
               "type": {
                 "text": "CustomEvent"
               }
             },
             {
-              "name": "sub-agent-history-updated",
+              "name": "sub-agent-start",
               "type": {
                 "text": "CustomEvent"
               }
             },
             {
-              "name": "sub-agent-start",
+              "name": "sub-agent-stop",
               "type": {
                 "text": "CustomEvent"
               }
             },
             {
-              "name": "sub-agent-stop",
+              "name": "history-updated",
               "type": {
                 "text": "CustomEvent"
               }
@@ -10881,6 +10947,14 @@
             "module": "./chat-driver.constants"
           }
         },
+        {
+          "kind": "js",
+          "name": "TurnSnapshot",
+          "declaration": {
+            "name": "TurnSnapshot",
+            "module": "./turn-recorder"
+          }
+        },
         {
           "kind": "js",
           "name": "ChatDriver",
@@ -11166,6 +11240,196 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/chat-driver/interaction-controller.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Custom UI interactions: parking a tool handler on a widget, and settling it when the user (or a\ntimeout) answers.\n\nOwns the pending call and its live context, which are created and destroyed together. Everything\nelse it needs is the driver's history and event target, reached through `InteractionDeps`.",
+          "name": "InteractionController",
+          "members": [
+            {
+              "kind": "field",
+              "name": "pending",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new Map<string, PendingInteraction>()"
+            },
+            {
+              "kind": "field",
+              "name": "contexts",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new Map<string, InteractionContextHandle>()",
+              "description": "Live per-interaction contexts (GENC-1390), keyed by interactionId. Created in `request`\nalongside the pending entry, disposed + removed in `resolve`. Non-serialisable (sockets,\ntimers, subscriber sets), so they live here — not on the DOM, not in the persisted store — and\ntherefore survive the element remounts (layout reflow/drag, transcript re-render) that this\nfeature exists to make harmless. At most one is live at a time (see the\none-interaction-at-a-time guard in `request`)."
+            },
+            {
+              "kind": "field",
+              "name": "hostRequester",
+              "type": {
+                "text": "<T>(\n    componentName: string,\n    data: any,\n    options?: InteractionRequestOptions,\n  ) => Promise<T> | undefined"
+              },
+              "privacy": "private",
+              "description": "When set, `request` delegates to this callback instead of using this controller's own pending\nmap. Wired by `invokeSubAgent` so a sub-agent's widget renders in — and resolves through — the\nparent (ultimately the root) driver, where the main UI is listening."
+            },
+            {
+              "kind": "method",
+              "name": "setHostRequester",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "fn",
+                  "type": {
+                    "text": "<T>(componentName: string, data: any, options?: InteractionRequestOptions) => Promise<T>"
+                  }
+                }
+              ],
+              "description": "See `ChatDriver.setHostInteractionRequester`."
+            },
+            {
+              "kind": "method",
+              "name": "request",
+              "return": {
+                "type": {
+                  "text": "Promise<T>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "componentName",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "data",
+                  "type": {
+                    "text": "any"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "InteractionRequestOptions"
+                  }
+                }
+              ],
+              "description": "See `ChatDriver.requestInteraction`."
+            },
+            {
+              "kind": "method",
+              "name": "resolve",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "interactionId",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "result",
+                  "type": {
+                    "text": "any"
+                  }
+                }
+              ],
+              "description": "See `ChatDriver.resolveInteraction`. Warns and returns when the id is unknown — a widget can\nreport twice, and the second report has nothing left to settle."
+            },
+            {
+              "kind": "method",
+              "name": "recordExternalCost",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "interactionId",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "costUsd",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "See `ChatDriver.recordExternalCost`.\n\n**Why this exists separately from `resolve`.** A widget's spend reaches the session total only\nthrough `InteractionResult.costUsd`, which is read exactly once — `resolve` does its whole job\nagainst a live pending entry and then deletes it. That is correct for the resolution itself,\nbut it assumes a widget stops costing money when it resolves, and several deliberately do not:\na widget that resolves EARLY so the assistant stops waiting (options shown, a preview\nrendered) may stay interactive for minutes afterwards and do more paid work on the user's\nbehalf. Re-emitting `interaction-completed` does not help — with the interaction gone from the\nmap the call is a silent no-op — so that spend had nowhere to go and was simply missing from\nthe figure shown to the user.\n\nTouches only `externalCostUsd`: the recorded `interaction.resolved` payload is left exactly as\nthe resolution wrote it, because this is not a second resolution and must not read like one."
+            },
+            {
+              "kind": "method",
+              "name": "context",
+              "return": {
+                "type": {
+                  "text": "InteractionContext | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "interactionId",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "See `ChatDriver.getInteractionContext`."
+            },
+            {
+              "kind": "method",
+              "name": "cancelAll",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "message",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Resolve every in-flight interaction with a `'timeout'` result, closing its\nwidget read-only. Used when a sub-agent that owns the open widget times out:\nthe widget is parked in *this* driver's map (interactions resolve on the\nhost, not the child), so cancelling it here unblocks the sub-agent handler\nawaiting it. The \"one interaction at a time\" invariant means there is at\nmost one."
+            },
+            {
+              "kind": "method",
+              "name": "disposeContexts",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Drop any live interaction contexts on driver teardown. Normally empty (a context is created\nand destroyed with its pending interaction, and dispose is not reached mid-interaction);\ndisposed defensively so a stray context can never leak an open socket/timer."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "InteractionController",
+          "declaration": {
+            "name": "InteractionController",
+            "module": "src/components/chat-driver/interaction-controller.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/components/chat-driver/turn-failures.ts",
@@ -11258,6 +11522,190 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/chat-driver/turn-recorder.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Everything the exported debug log draws from one driver: its own per-LLM-call snapshots, the\nones forwarded up from sub-agents, and the diagnostics harvested from resolved interactions.\n\nAll three feed the same timeline and all three are keyed in this driver's turn space, which is\nwhy they share an owner — a forwarded child turn and a harvested server turn are both re-labelled\nagainst the counter kept here.",
+          "name": "TurnRecorder",
+          "members": [
+            {
+              "kind": "field",
+              "name": "buffer",
+              "type": {
+                "text": "TurnSnapshot[]"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "default": "[]",
+              "description": "Ring buffer of per-LLM-call snapshots, capped at `maxSnapshots`; older entries drop off as\nnew ones arrive."
+            },
+            {
+              "kind": "field",
+              "name": "turnIndex",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "Monotonic counter that survives agent swaps — useful for cross-referencing with history."
+            },
+            {
+              "kind": "field",
+              "name": "externalEntries",
+              "type": {
+                "text": "DiagnosticEntry[]"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "default": "[]",
+              "description": "`turn` + `message` diagnostic entries harvested from an out-of-band source. `event` entries\nare NOT kept here — they are folded into the session's meta-event registry so they inherit\nfresh host indices, and reach the log through `getMetaEvents`. Append-only, and never cleared:\nit lives with the recorder, so a new chat (fresh driver) starts empty while a compaction (same\ninstance) keeps it. (GENC-1461.)"
+            },
+            {
+              "kind": "field",
+              "name": "externalBatches",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "Monotonic count of external-diagnostics batches folded this driver-lifetime. Namespaces each\nbatch's re-keyed `turn` entries so distinct server generations in one chat session can't\ncollide on `turnIndex` in the forward-capture persister (which dedups turns by that key)."
+            },
+            {
+              "kind": "field",
+              "name": "snapshotter",
+              "type": {
+                "text": "() => unknown | undefined"
+              },
+              "privacy": "private",
+              "description": "The active agent's `getDebugSnapshot`, captured on install so the whole config isn't held."
+            },
+            {
+              "kind": "method",
+              "name": "setSnapshotter",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "snapshotter",
+                  "optional": true,
+                  "type": {
+                    "text": "() => unknown"
+                  }
+                }
+              ],
+              "description": "Point at the incoming agent's `getDebugSnapshot`, or clear it when the agent supplies none."
+            },
+            {
+              "kind": "method",
+              "name": "snapshots",
+              "return": {
+                "type": {
+                  "text": "ReadonlyArray<TurnSnapshot>"
+                }
+              },
+              "description": "The per-turn snapshots captured so far — what the LLM saw on each turn: system prompt, tool\nsurface, and agent-supplied state (e.g. a machine snapshot)."
+            },
+            {
+              "kind": "method",
+              "name": "externalDiagnostics",
+              "return": {
+                "type": {
+                  "text": "ReadonlyArray<DiagnosticEntry>"
+                }
+              },
+              "description": "The harvested `turn` + `message` diagnostic entries. Opaque, and chronologically sorted by the\nhost at assemble time."
+            },
+            {
+              "kind": "method",
+              "name": "record",
+              "return": {
+                "type": {
+                  "text": "TurnSnapshot"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "turn",
+                  "type": {
+                    "text": "RecordedTurn"
+                  }
+                }
+              ],
+              "description": "Push one snapshot to the ring buffer. Called inside `runToolLoop` just\nbefore each LLM call — that's the latest point where the prompt, tool\nsurface, and agent state line up with what the model is about to see.\n\nReturns the pushed object so the caller can back-fill what only the response\nknows (`usage`). Mutating it after the fact is safe whether or not the ring\nbuffer has since evicted it — an evicted snapshot is simply no longer exported."
+            },
+            {
+              "kind": "method",
+              "name": "forwardSubAgent",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "childSnapshots",
+                  "type": {
+                    "text": "ReadonlyArray<TurnSnapshot>"
+                  }
+                }
+              ],
+              "description": "Merge a sub-agent's turn snapshots into this driver's buffer so they surface\nas `kind:'turn'` entries in the exported debug log. The child runs as a\nseparate, discarded driver, so its snapshots would otherwise be lost. Each is\nre-labelled under the parent turn that activated the sub-agent: the child's\nown (numeric) turns become `\"<parentTurn>-1\"`, `\"-2\"`, … (1-based, in order);\nany already-forwarded grand-child labels (strings) have their leading segment\nremapped the same way, so nesting composes (`\"5-2\"` → `\"5-2-1\"`).\n\nNote: two sub-agents invoked in the *same* parent turn share the prefix, so\ntheir labels can repeat — `agentName` on each snapshot disambiguates them."
+            },
+            {
+              "kind": "method",
+              "name": "foldDiagnostics",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "interactionId",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "harvested",
+                  "type": {
+                    "text": "unknown"
+                  }
+                }
+              ],
+              "description": "Fold a widget's out-of-band diagnostics into this session — typically a server-side\nChatDriver's collated log, arriving on `InteractionResult.diagnostics` — so the host's debug\nlog and persisted diagnostics stream include them. Independent of the interaction's own\nmessage: these describe the widget's work, not that message. A non-array or empty harvest is\na no-op."
+            },
+            {
+              "kind": "method",
+              "name": "trim",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Hold the ring buffer at its cap, dropping oldest-first."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "TurnRecorder",
+          "declaration": {
+            "name": "TurnRecorder",
+            "module": "src/components/chat-driver/turn-recorder.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts",
@@ -12646,6 +13094,30 @@
       "kind": "javascript-module",
       "path": "src/components/settings-modal/settings-modal.template.ts",
       "declarations": [
+        {
+          "kind": "function",
+          "name": "timestampModePickerTemplate",
+          "return": {
+            "type": {
+              "text": "ViewTemplate<FoundationAiAssistant>"
+            }
+          },
+          "parameters": [
+            {
+              "name": "segmentedControlTag",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "segmentedItemTag",
+              "type": {
+                "text": "string"
+              }
+            }
+          ],
+          "description": "Three-way picker for TimestampDisplay (GENC-1257).\n\nThe design system's segmented control rather than the `switch` every other row uses,\nbecause the setting genuinely has three states — and rather than hand-rolled buttons\ncarrying `role=\"radio\"`, because ARIA roles supply semantics but never behaviour:\npromising a radio group means owning roving `tabindex` and arrow-key navigation.\n\n`SegmentedControl extends FASTRadioGroup` (and `SegmentedItem extends FASTRadio`), so\nthis IS the DS radio group — it inherits the whole keyboard pattern — just skinned as\nsegments rather than dots, which is the right affordance for three short mode labels.\n\nThe usual reason to avoid a DS control here does not apply. `RadioGroup.valueChanged`\nemits `change` whenever `value` is written — including the write this template's own\nbinding performs on render, exactly the phantom-change footgun the DS switch has\n(GENC-1351 #1). It is harmless because the `timestampDisplay` setter guards on\n`preferenceUnchanged`, as every preference setter does, so a render-time echo returns early\nand never reaches the store or marks preferences user-changed."
+        },
         {
           "kind": "function",
           "name": "SettingsModalTemplate",
@@ -12666,6 +13138,14 @@
         }
       ],
       "exports": [
+        {
+          "kind": "js",
+          "name": "timestampModePickerTemplate",
+          "declaration": {
+            "name": "timestampModePickerTemplate",
+            "module": "src/components/settings-modal/settings-modal.template.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "SettingsModalTemplate",