@genesislcap/ai-assistant 14.450.0 → 14.451.0

package/dist/esm/state/debug-event-log.js

@@ -0,0 +1,118 @@
+/**
+ * Module-level append-only timeline of meta/lifecycle events, keyed by session
+ * identity (the same `stateKey` space used by the driver registry and the
+ * session store).
+ *
+ * Why a module registry rather than the redux store or the driver:
+ * - **Survives the pop-in/pop-out element churn.** A single session can be
+ *   emitted from up to two element instances (an `expand` bubble + a `collapse`
+ *   panel) sharing one driver; keying by `stateKey` unifies them into one
+ *   timeline.
+ * - **Survives driver rebuilds.** The driver is torn down and recreated when the
+ *   host swaps the agents array (see `agentsChanged` / `deleteDriver`), so a
+ *   driver-owned buffer would lose the timeline mid-session. The `stateKey`
+ *   outlives the driver.
+ * - **Stays out of redux reactivity.** These appends never drive the UI, so
+ *   there's no reason to pay immutable-reducer cost or flood the Redux DevTools
+ *   action log with debug noise.
+ *
+ * Surfaced under `getDebugLog().meta.events`. Ring-buffered so a long-lived
+ * session can't grow the timeline unbounded.
+ *
+ * @internal
+ */
+/**
+ * Importance is intrinsic to the event *type*, not the instance, so it's
+ * defined once here and stamped automatically by {@link recordMetaEvent} — call
+ * sites never pass it. The `Record` is exhaustive: adding a `MetaEventType`
+ * without a level here is a compile error.
+ *
+ * - `high`   — failures and hard limits you almost always want to see.
+ * - `normal` — meaningful session flow you read to follow what happened.
+ * - `low`    — frequent UI / bookkeeping noise, usually safe to skip.
+ */
+export const META_EVENT_IMPORTANCE = {
+    'turn.error': 'high',
+    'tool.failed': 'high',
+    'file.read-failed': 'high',
+    'suggestions.failed': 'high',
+    'context.threshold-crossed': 'high',
+    'assistant.connected': 'normal',
+    'assistant.disconnected': 'normal',
+    'assistant.popout': 'normal',
+    'assistant.popin': 'normal',
+    'driver.created': 'normal',
+    'state.changed': 'normal',
+    'turn.start': 'normal',
+    'turn.end': 'normal',
+    'agent.handoff': 'normal',
+    'agent.pinned': 'normal',
+    'agent.unpinned': 'normal',
+    'provider.selected': 'normal',
+    'interaction.requested': 'normal',
+    'interaction.resolved': 'normal',
+    'driver.wired': 'low',
+    'driver.unwired': 'low',
+    'context.updated': 'low',
+    'panel.toggled': 'low',
+    'attachment.added': 'low',
+};
+/** Default ring-buffer cap. ~5× the turn-snapshot cap — entries are cheap. */
+const DEFAULT_MAX_META_EVENTS = 200;
+const registry = new Map();
+/**
+ * Append a meta event to the timeline for `key`. Evicts the oldest entry once
+ * the buffer exceeds {@link DEFAULT_MAX_META_EVENTS}. An empty `key` is bucketed
+ * under `''`, matching how drivers/stores handle an absent session identity, so
+ * callers never need to guard.
+ */
+export function recordMetaEvent(key, type, detail) {
+    let buffer = registry.get(key);
+    if (!buffer) {
+        buffer = { events: [], next: 0 };
+        registry.set(key, buffer);
+    }
+    buffer.events.push({
+        index: buffer.next,
+        timestamp: new Date().toISOString(),
+        type,
+        importance: META_EVENT_IMPORTANCE[type],
+        detail,
+    });
+    buffer.next += 1;
+    if (buffer.events.length > DEFAULT_MAX_META_EVENTS) {
+        buffer.events.shift();
+    }
+}
+/** Returns the meta-event timeline for `key`, or an empty array if none recorded. */
+export function getMetaEvents(key) {
+    var _a, _b;
+    return (_b = (_a = registry.get(key)) === null || _a === void 0 ? void 0 : _a.events) !== null && _b !== void 0 ? _b : [];
+}
+/**
+ * Human/agent-facing guide emitted as the first key of the exported debug log,
+ * so whoever opens the JSON (often an AI agent) knows how to read it without
+ * reverse-engineering the shape. Kept here next to the event catalogue it
+ * describes so the two stay in sync.
+ */
+export const DEBUG_LOG_README = [
+    'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',
+    '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',
+    "kind:'message' — the conversation. `role` is user/assistant/tool/system-event; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message usage.",
+    "kind:'turn' — one LLM call. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.",
+    "kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.",
+    "kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.",
+    "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, handoffs, agent/provider changes, interactions), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. 'message' and 'turn' entries carry no importance — they are the substance, always read them.",
+    'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.error (a turn failed or hit a guardrail — see detail.reason), tool.failed (a tool threw), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps), context.updated/threshold-crossed (token + cost), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
+    "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, token usage, session cost), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.",
+    'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it.',
+];
+/**
+ * Removes all entries. Exposed for test isolation only — not part of the
+ * public API.
+ *
+ * @internal
+ */
+export function clearMetaEventRegistry() {
+    registry.clear();
+}

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/index.ts","../src/channel/ai-activity-bus.ts","../src/channel/ai-activity-channel.ts","../src/components/halo-overlay.ts","../src/components/activity-halo/activity-halo.ts","../src/components/agent-picker/agent-picker.constants.ts","../src/components/agent-picker/agent-picker.styles.ts","../src/components/agent-picker/agent-picker.template.ts","../src/components/agent-picker/agent-picker.ts","../src/components/agent-picker/index.ts","../src/components/ai-driver/ai-driver.ts","../src/components/ai-driver/index.ts","../src/components/chat-bubble/chat-bubble.styles.ts","../src/components/chat-bubble/chat-bubble.template.ts","../src/components/chat-bubble/chat-bubble.ts","../src/components/chat-bubble/index.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/index.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts","../src/components/chat-interaction-wrapper/index.ts","../src/components/chat-markdown/chat-markdown.ts","../src/components/chat-markdown/index.ts","../src/components/orchestrating-driver/index.ts","../src/components/orchestrating-driver/orchestrating-driver.ts","../src/components/popout-manager/index.ts","../src/components/popout-manager/popout-manager.ts","../src/config/config.ts","../src/config/define-stateful-agent.ts","../src/config/fallback-agents.ts","../src/config/index.ts","../src/config/validate-providers.test.ts","../src/config/validate-providers.ts","../src/main/index.ts","../src/main/main.styles.ts","../src/main/main.template.ts","../src/main/main.ts","../src/main/main.types.ts","../src/state/ai-assistant-slice.ts","../src/state/driver-registry.ts","../src/state/session-store.ts","../src/styles/ai-colours.ts","../src/styles/index.ts","../src/styles/styles.ts","../src/suggestions/chat-suggestions.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/utils/animated-panel-toggle.ts","../src/utils/history-transform.ts","../src/utils/index.ts","../src/utils/logger.ts","../src/utils/sum-costs.test.ts","../src/utils/sum-costs.ts","../src/utils/tool-fold.ts"],"version":"5.9.2"}
+{"root":["../src/index.ts","../src/channel/ai-activity-bus.ts","../src/channel/ai-activity-channel.ts","../src/components/halo-overlay.ts","../src/components/activity-halo/activity-halo.ts","../src/components/agent-picker/agent-picker.constants.ts","../src/components/agent-picker/agent-picker.styles.ts","../src/components/agent-picker/agent-picker.template.ts","../src/components/agent-picker/agent-picker.ts","../src/components/agent-picker/index.ts","../src/components/ai-driver/ai-driver.ts","../src/components/ai-driver/index.ts","../src/components/chat-bubble/chat-bubble.styles.ts","../src/components/chat-bubble/chat-bubble.template.ts","../src/components/chat-bubble/chat-bubble.ts","../src/components/chat-bubble/index.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/index.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts","../src/components/chat-interaction-wrapper/index.ts","../src/components/chat-markdown/chat-markdown.ts","../src/components/chat-markdown/index.ts","../src/components/orchestrating-driver/index.ts","../src/components/orchestrating-driver/orchestrating-driver.ts","../src/components/popout-manager/index.ts","../src/components/popout-manager/popout-manager.ts","../src/config/config.ts","../src/config/define-stateful-agent.ts","../src/config/fallback-agents.ts","../src/config/index.ts","../src/config/validate-providers.test.ts","../src/config/validate-providers.ts","../src/main/index.ts","../src/main/main.styles.ts","../src/main/main.template.ts","../src/main/main.ts","../src/main/main.types.ts","../src/state/ai-assistant-slice.ts","../src/state/debug-event-log.ts","../src/state/driver-registry.ts","../src/state/session-store.ts","../src/styles/ai-colours.ts","../src/styles/index.ts","../src/styles/styles.ts","../src/suggestions/chat-suggestions.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/utils/animated-panel-toggle.ts","../src/utils/history-transform.ts","../src/utils/index.ts","../src/utils/logger.ts","../src/utils/sum-costs.test.ts","../src/utils/sum-costs.ts","../src/utils/tool-fold.ts"],"version":"5.9.2"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "14.450.0",
+  "version": "14.451.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.450.0",
-    "@genesislcap/genx": "14.450.0",
-    "@genesislcap/rollup-builder": "14.450.0",
-    "@genesislcap/ts-builder": "14.450.0",
-    "@genesislcap/uvu-playwright-builder": "14.450.0",
-    "@genesislcap/vite-builder": "14.450.0",
-    "@genesislcap/webpack-builder": "14.450.0",
+    "@genesislcap/foundation-testing": "14.451.0",
+    "@genesislcap/genx": "14.451.0",
+    "@genesislcap/rollup-builder": "14.451.0",
+    "@genesislcap/ts-builder": "14.451.0",
+    "@genesislcap/uvu-playwright-builder": "14.451.0",
+    "@genesislcap/vite-builder": "14.451.0",
+    "@genesislcap/webpack-builder": "14.451.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "14.450.0",
-    "@genesislcap/foundation-logger": "14.450.0",
-    "@genesislcap/foundation-redux": "14.450.0",
-    "@genesislcap/foundation-ui": "14.450.0",
-    "@genesislcap/foundation-utils": "14.450.0",
-    "@genesislcap/rapid-design-system": "14.450.0",
-    "@genesislcap/web-core": "14.450.0",
+    "@genesislcap/foundation-ai": "14.451.0",
+    "@genesislcap/foundation-logger": "14.451.0",
+    "@genesislcap/foundation-redux": "14.451.0",
+    "@genesislcap/foundation-ui": "14.451.0",
+    "@genesislcap/foundation-utils": "14.451.0",
+    "@genesislcap/rapid-design-system": "14.451.0",
+    "@genesislcap/web-core": "14.451.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -93,5 +93,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "b9824253dfa64fe2dfe72cad8268b7caacebf0b0"
+  "gitHead": "0e6d8695edfcba1901f3f42f12e9387bee747c60"
 }

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

@@ -22,6 +22,7 @@ import type {
   ToolHandlersInput,
 } from '../../config/config';
 import { resolveChatProvider } from '../../config/validate-providers';
+import { recordMetaEvent } from '../../state/debug-event-log';
 import { applyHistoryCap } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import { TOOL_FOLD_SYMBOL, type ToolFold } from '../../utils/tool-fold';
@@ -99,6 +100,8 @@ interface FoldStackFrame {
 export class ChatDriver extends EventTarget implements AiDriver {
   private history: ChatMessage[] = [];
   private busy = false;
+  /** Epoch ms when the current turn loop began — drives the `turn.end` duration. */
+  private turnStartedAt = 0;
   private pendingInteractions = new Map<
     string,
     {
@@ -233,6 +236,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
     private readonly maxToolIterations: number = DEFAULT_MAX_TOOL_ITERATIONS,
     maxFoldOperations: number = DEFAULT_MAX_FOLD_OPERATIONS,
     maxTurnSnapshots: number = DEFAULT_MAX_TURN_SNAPSHOTS,
+    /** Session identity used to file meta events onto the shared debug-log timeline. */
+    private readonly sessionKey: string = '',
   ) {
     super();
     if (typeof toolHandlers === 'function') {
@@ -348,6 +353,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.lastResolvedProviderName = resolvedName;
     if (resolvedName !== this.lastDispatchedProviderName) {
       this.lastDispatchedProviderName = resolvedName;
+      recordMetaEvent(this.sessionKey, 'provider.selected', {
+        provider: resolvedName,
+        agent: this.activeAgentName,
+      });
       this.dispatchEvent(
         new CustomEvent<{ name: string }>('provider-changed', { detail: { name: resolvedName } }),
       );
@@ -610,6 +619,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
         reject,
         overrideId: chatInputDuringExecution ? interactionId : undefined,
       });
+      recordMetaEvent(this.sessionKey, 'interaction.requested', {
+        interactionId,
+        component: componentName,
+        agent: this.activeAgentName,
+      });
       if (chatInputDuringExecution) {
         this.dispatchEvent(
           new CustomEvent('interaction-start', {
@@ -647,6 +661,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       if (interaction.overrideId) {
         this.dispatchEvent(new CustomEvent('interaction-stop', { detail: { interactionId } }));
       }
+      recordMetaEvent(this.sessionKey, 'interaction.resolved', { interactionId });
       interaction.resolve(result);
       this.pendingInteractions.delete(interactionId);
     } else {
@@ -674,15 +689,31 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.subAgentCompletion = undefined;
     this.agentReleaseRequested = false;
     this.appendToHistory({ role: 'user', content: userInput, attachments });
+    this.turnStartedAt = Date.now();
+    recordMetaEvent(this.sessionKey, 'turn.start', {
+      phase: 'sendMessage',
+      agent: this.activeAgentName,
+    });
     agenticActivityBus.publish('tool-loop-start', undefined);
 
     try {
       return await this.runToolLoop(userInput, attachments);
     } catch (e) {
       logger.error('ChatDriver error:', e);
+      recordMetaEvent(this.sessionKey, 'turn.error', {
+        phase: 'sendMessage',
+        agent: this.activeAgentName,
+        provider: this.lastResolvedProviderName,
+        message: e instanceof Error ? e.message : String(e),
+      });
       this.appendToHistory({ role: 'assistant', content: 'Sorry, something went wrong.' });
       return { reason: 'done' };
     } finally {
+      recordMetaEvent(this.sessionKey, 'turn.end', {
+        phase: 'sendMessage',
+        agent: this.activeAgentName,
+        durationMs: Date.now() - this.turnStartedAt,
+      });
       this.busy = false;
       agenticActivityBus.publish('tool-loop-end', undefined);
     }
@@ -844,14 +875,30 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
     this.busy = true;
     this.subAgentCompletion = undefined;
+    this.turnStartedAt = Date.now();
+    recordMetaEvent(this.sessionKey, 'turn.start', {
+      phase: 'continueFromHistory',
+      agent: this.activeAgentName,
+    });
     agenticActivityBus.publish('tool-loop-start', undefined);
     try {
       return await this.runToolLoop('', undefined, transientPrimer);
     } catch (e) {
       logger.error('ChatDriver error:', e);
+      recordMetaEvent(this.sessionKey, 'turn.error', {
+        phase: 'continueFromHistory',
+        agent: this.activeAgentName,
+        provider: this.lastResolvedProviderName,
+        message: e instanceof Error ? e.message : String(e),
+      });
       this.appendToHistory({ role: 'assistant', content: 'Sorry, something went wrong.' });
       return { reason: 'done' };
     } finally {
+      recordMetaEvent(this.sessionKey, 'turn.end', {
+        phase: 'continueFromHistory',
+        agent: this.activeAgentName,
+        durationMs: Date.now() - this.turnStartedAt,
+      });
       this.busy = false;
       agenticActivityBus.publish('tool-loop-end', undefined);
     }
@@ -1140,6 +1187,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
             continue;
           }
           logger.error('ChatDriver: MALFORMED_FUNCTION_CALL, max retries reached');
+          recordMetaEvent(this.sessionKey, 'turn.error', {
+            reason: 'malformed-function-call',
+            agent: this.activeAgentName,
+            provider: this.lastResolvedProviderName,
+          });
           this.appendToHistory({
             role: 'assistant',
             content:
@@ -1163,6 +1215,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
           continue;
         }
         logger.error('ChatDriver: empty model response after all retries');
+        recordMetaEvent(this.sessionKey, 'turn.error', {
+          reason: 'empty-response',
+          agent: this.activeAgentName,
+          provider: this.lastResolvedProviderName,
+        });
         this.appendToHistory({
           role: 'assistant',
           content: 'Remote agent returned no response.',
@@ -1281,6 +1338,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
               anyRealToolExecuted = true;
             } catch (e) {
               logger.error(`ChatDriver tool "${tc.name}" failed:`, e);
+              recordMetaEvent(this.sessionKey, 'tool.failed', {
+                tool: tc.name,
+                agent: this.activeAgentName,
+                message: e instanceof Error ? e.message : String(e),
+              });
               executedById.set(tc.id, {
                 toolCallId: tc.id,
                 content: `Tool error: ${(e as Error).message}`,
@@ -1361,6 +1423,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
         logger.error(
           `ChatDriver: unknown-tool limit (${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}) reached — stopping`,
         );
+        recordMetaEvent(this.sessionKey, 'turn.error', {
+          reason: 'unknown-tool-limit',
+          agent: this.activeAgentName,
+          provider: this.lastResolvedProviderName,
+        });
         this.appendToHistory({
           role: 'assistant',
           content:
@@ -1387,6 +1454,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
     if (iterations >= this.maxToolIterations) {
       logger.warn('ChatDriver: reached max tool iterations, stopping');
+      recordMetaEvent(this.sessionKey, 'turn.error', {
+        reason: 'max-iterations',
+        agent: this.activeAgentName,
+        provider: this.lastResolvedProviderName,
+      });
       this.appendToHistory({
         role: 'assistant',
         content:
@@ -1398,14 +1470,18 @@ export class ChatDriver extends EventTarget implements AiDriver {
   }
 
   private appendToHistory(message: ChatMessage): void {
-    const tagged: ChatMessage = this.activeAgentName
-      ? {
-          ...message,
-          agentName: this.activeAgentName,
-          // Display-only — falls back to agentName in renderers when unset.
-          agentLabel: this.activeAgentLabel,
-        }
-      : message;
+    const tagged: ChatMessage = {
+      ...message,
+      // Stamp on first append; preserve any caller-supplied timestamp.
+      timestamp: message.timestamp ?? new Date().toISOString(),
+      ...(this.activeAgentName
+        ? {
+            agentName: this.activeAgentName,
+            // Display-only — falls back to agentName in renderers when unset.
+            agentLabel: this.activeAgentLabel,
+          }
+        : {}),
+    };
     this.history = [...this.history, tagged];
     this.dispatchEvent(
       new CustomEvent<ReadonlyArray<ChatMessage>>('history-updated', {

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

@@ -13,6 +13,7 @@ import type {
   SystemPromptInput,
 } from '../../config/config';
 import { validateStaticAgentProviders } from '../../config/validate-providers';
+import { recordMetaEvent } from '../../state/debug-event-log';
 import { transformHistoryForAgent } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
@@ -159,6 +160,7 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
       options.maxToolIterations,
       options.maxFoldOperations,
       options.maxTurnSnapshots,
+      this.sessionKey,
     );
 
     // Proxy events from the shared driver
@@ -340,6 +342,15 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
     const previousAgent = this.activeAgent;
     const isSwitch = !previousAgent || previousAgent.name !== agent.name;
 
+    // Record the agent transition on the debug-log timeline. A `null` `from`
+    // marks the initial activation; a named `from` is a handoff between agents.
+    if (isSwitch) {
+      recordMetaEvent(this.sessionKey, 'agent.handoff', {
+        from: previousAgent?.name ?? null,
+        to: agent.name,
+      });
+    }
+
     // Fire lifecycle hooks around the swap — outgoing first, then incoming.
     // Both are awaited so a heavy `onActivate` (e.g. machine restore) completes
     // before the agent's first turn runs.
@@ -413,7 +424,10 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
 
     if (previousAgent && previousAgent.name !== agent.name) {
       const rawHistory = this.chatDriver.getHistory() as ChatMessage[];
-      this.chatDriver.loadHistory([...rawHistory, { role: 'system-event', content: agent.name }]);
+      this.chatDriver.loadHistory([
+        ...rawHistory,
+        { role: 'system-event', content: agent.name, timestamp: new Date().toISOString() },
+      ]);
     }
 
     this.chatDriver.setProviderHistoryTransform((h) => transformHistoryForAgent(h, agent.name));
@@ -606,7 +620,10 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
 
   private appendInlineMessage(content: string): void {
     const history = this.chatDriver.getHistory() as ChatMessage[];
-    this.chatDriver.loadHistory([...history, { role: 'assistant', content }]);
+    this.chatDriver.loadHistory([
+      ...history,
+      { role: 'assistant', content, timestamp: new Date().toISOString() },
+    ]);
     this.dispatchEvent(
       new CustomEvent('history-updated', { detail: this.chatDriver.getHistory() }),
     );