@genesislcap/ai-assistant 14.450.0 → 14.451.0

package/dist/esm/components/chat-driver/chat-driver.js

@@ -2,6 +2,7 @@ import { __awaiter } from "tslib";
 import { MalformedFunctionCallError } from '@genesislcap/foundation-ai';
 import { agenticActivityBus } from '../../channel/ai-activity-bus';
 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 } from '../../utils/tool-fold';
@@ -27,12 +28,17 @@ const HANDOFF_TOOL_RESULT_PLACEHOLDER = 'Handoff to another specialist — routi
  * @beta
  */
 export class ChatDriver extends EventTarget {
-    constructor(providerRegistry, toolHandlers = {}, toolDefinitions = [], systemPrompt, primerHistory, maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS, maxFoldOperations = DEFAULT_MAX_FOLD_OPERATIONS, maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS) {
+    constructor(providerRegistry, toolHandlers = {}, toolDefinitions = [], systemPrompt, primerHistory, maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS, maxFoldOperations = DEFAULT_MAX_FOLD_OPERATIONS, maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS, 
+    /** Session identity used to file meta events onto the shared debug-log timeline. */
+    sessionKey = '') {
         super();
         this.providerRegistry = providerRegistry;
         this.maxToolIterations = maxToolIterations;
+        this.sessionKey = sessionKey;
         this.history = [];
         this.busy = false;
+        /** Epoch ms when the current turn loop began — drives the `turn.end` duration. */
+        this.turnStartedAt = 0;
         this.pendingInteractions = new Map();
         /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
         this.foldStack = [];
@@ -184,6 +190,10 @@ export class ChatDriver extends EventTarget {
             this.lastResolvedProviderName = resolvedName;
             if (resolvedName !== this.lastDispatchedProviderName) {
                 this.lastDispatchedProviderName = resolvedName;
+                recordMetaEvent(this.sessionKey, 'provider.selected', {
+                    provider: resolvedName,
+                    agent: this.activeAgentName,
+                });
                 this.dispatchEvent(new CustomEvent('provider-changed', { detail: { name: resolvedName } }));
             }
             return provider;
@@ -412,6 +422,11 @@ export class ChatDriver extends EventTarget {
                     reject,
                     overrideId: chatInputDuringExecution ? interactionId : undefined,
                 });
+                recordMetaEvent(this.sessionKey, 'interaction.requested', {
+                    interactionId,
+                    component: componentName,
+                    agent: this.activeAgentName,
+                });
                 if (chatInputDuringExecution) {
                     this.dispatchEvent(new CustomEvent('interaction-start', {
                         detail: { interactionId, chatInputDuringExecution },
@@ -442,6 +457,7 @@ export class ChatDriver extends EventTarget {
             if (interaction.overrideId) {
                 this.dispatchEvent(new CustomEvent('interaction-stop', { detail: { interactionId } }));
             }
+            recordMetaEvent(this.sessionKey, 'interaction.resolved', { interactionId });
             interaction.resolve(result);
             this.pendingInteractions.delete(interactionId);
         }
@@ -467,16 +483,32 @@ export class ChatDriver extends EventTarget {
             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 yield 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);
             }
@@ -601,16 +633,32 @@ export class ChatDriver extends EventTarget {
                 return { reason: 'done' };
             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 yield 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);
             }
@@ -854,6 +902,11 @@ export class ChatDriver extends EventTarget {
                             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: "I'm sorry, I wasn't able to complete that request. Please try rephrasing or breaking it into smaller steps.",
@@ -872,6 +925,11 @@ export class ChatDriver extends EventTarget {
                         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.',
@@ -976,6 +1034,11 @@ export class ChatDriver extends EventTarget {
                         }
                         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.message}`,
@@ -1042,6 +1105,11 @@ export class ChatDriver extends EventTarget {
                 }
                 if (hitUnknownToolLimit) {
                     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: "I'm sorry, I repeatedly tried to use tools that don't exist. Please check your agent configuration or try rephrasing your request.",
@@ -1061,6 +1129,11 @@ export class ChatDriver extends EventTarget {
             }
             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: "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off.",
@@ -1070,10 +1143,16 @@ export class ChatDriver extends EventTarget {
         });
     }
     appendToHistory(message) {
-        const tagged = this.activeAgentName
-            ? Object.assign(Object.assign({}, message), { agentName: this.activeAgentName, 
+        var _a;
+        const tagged = Object.assign(Object.assign(Object.assign({}, message), { 
+            // Stamp on first append; preserve any caller-supplied timestamp.
+            timestamp: (_a = message.timestamp) !== null && _a !== void 0 ? _a : new Date().toISOString() }), (this.activeAgentName
+            ? {
+                agentName: this.activeAgentName,
                 // Display-only — falls back to agentName in renderers when unset.
-                agentLabel: this.activeAgentLabel }) : message;
+                agentLabel: this.activeAgentLabel,
+            }
+            : {}));
         this.history = [...this.history, tagged];
         this.dispatchEvent(new CustomEvent('history-updated', {
             detail: this.history,

package/dist/esm/components/orchestrating-driver/orchestrating-driver.js

@@ -1,5 +1,6 @@
 import { __awaiter } from "tslib";
 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 { ChatDriver, REQUEST_CONTINUATION_TOOL, } from '../chat-driver/chat-driver';
@@ -95,7 +96,7 @@ export class OrchestratingDriver extends EventTarget {
         const rawFallback = fallbacks[0];
         this.fallback = rawFallback
             ? Object.assign(Object.assign({}, rawFallback), { systemPrompt: buildFallbackSystemPrompt(rawFallback, this.specialists) }) : undefined;
-        this.chatDriver = new ChatDriver(providerRegistry, {}, [], undefined, undefined, options.maxToolIterations, options.maxFoldOperations, options.maxTurnSnapshots);
+        this.chatDriver = new ChatDriver(providerRegistry, {}, [], undefined, undefined, options.maxToolIterations, options.maxFoldOperations, options.maxTurnSnapshots, this.sessionKey);
         // Proxy events from the shared driver
         this.chatDriver.addEventListener('history-updated', (e) => {
             this.dispatchEvent(new CustomEvent('history-updated', { detail: e.detail }));
@@ -242,8 +243,17 @@ export class OrchestratingDriver extends EventTarget {
     }
     applyAgent(agent) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             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: (_a = previousAgent === null || previousAgent === void 0 ? void 0 : previousAgent.name) !== null && _a !== void 0 ? _a : 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.
@@ -311,7 +321,10 @@ export class OrchestratingDriver extends EventTarget {
             }
             if (previousAgent && previousAgent.name !== agent.name) {
                 const rawHistory = this.chatDriver.getHistory();
-                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));
             this.chatDriver.applyAgent(agentToApply);
@@ -493,7 +506,10 @@ export class OrchestratingDriver extends EventTarget {
     }
     appendInlineMessage(content) {
         const history = this.chatDriver.getHistory();
-        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() }));
     }
 }

package/dist/esm/main/main.js

@@ -34,7 +34,8 @@ import { AiChatInteractionWrapper } from '../components/chat-interaction-wrapper
 import { AiChatMarkdown } from '../components/chat-markdown/chat-markdown';
 import { AiHaloOverlay } from '../components/halo-overlay';
 import { OrchestratingDriver } from '../components/orchestrating-driver/orchestrating-driver';
-import { getOrCreateDriver, deleteDriver } from '../state/driver-registry';
+import { recordMetaEvent, getMetaEvents, DEBUG_LOG_README, } from '../state/debug-event-log';
+import { getOrCreateDriver, getDriver, deleteDriver } from '../state/driver-registry';
 import { getSessionStore, hasSessionStore } from '../state/session-store';
 import { AI_COLOUR_AMBER, AI_COLOUR_CYAN, AI_COLOUR_PINK, AI_COLOUR_VIOLET, } from '../styles/ai-colours';
 import { ChatSuggestions } from '../suggestions/chat-suggestions';
@@ -130,6 +131,8 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         };
         /** True when the user has intentionally scrolled away from the bottom — suppresses auto-scroll. */
         this._userScrolledAway = false;
+        /** Whether the one-shot ≥80% `context.threshold-crossed` event has fired this session. */
+        this._contextThresholdCrossed = false;
         /**
          * Interaction widgets that grow mid-lifecycle (e.g. expanding a "More info"
          * panel, appending an SSE status row, revealing generated code) bubble a
@@ -190,6 +193,11 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         var _a, _b;
         const prev = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.state;
         (_b = this._sessionRef) === null || _b === void 0 ? void 0 : _b.actions.aiAssistant.setState(value);
+        // Only record a real transition against a live session — a missing
+        // _sessionRef means setState no-op'd, so no transition actually happened.
+        if (this._sessionRef && prev !== value) {
+            this.logMeta('state.changed', { from: prev, to: value });
+        }
         this.syncShowHalo();
         // When the agent finishes (loading → !loading) the input row reappears (or
         // becomes enabled) — refocus it so the user can type immediately, but only
@@ -327,6 +335,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         // Suggestions are scoped to the active routing — resetting forces a fresh
         // fetch when the user pins/unpins so the prompts match the new agent.
         if (previous !== value) {
+            this.logMeta(value ? 'agent.pinned' : 'agent.unpinned', { agent: value !== null && value !== void 0 ? value : previous });
             this.suggestionsState = { status: 'idle' };
             this.fetchSuggestions();
         }
@@ -576,6 +585,10 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         if (history.length)
             this.driver.loadHistory([...history]);
         this._driverAgentsKey = newKey;
+        this.logMeta('driver.created', {
+            reason: 'agents-changed',
+            driverKind: this.driver instanceof OrchestratingDriver ? 'orchestrating' : 'chat',
+        });
     }
     /** Returns a stable fingerprint for an agents array based on agent names and tool handler keys. */
     getAgentsKey(agents) {
@@ -631,7 +644,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         }
     }
     createDriver() {
-        var _a, _b;
+        var _a, _b, _c;
         this.warnUnreachableStatefulAgents();
         const agent = (_a = this.chatConfig.agent) !== null && _a !== void 0 ? _a : {};
         const { agents } = this;
@@ -659,7 +672,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 maxTurnSnapshots: agent.maxTurnSnapshots,
             });
         }
-        return new ChatDriver(this.providerRegistry, {}, [], undefined, undefined, agent.maxToolIterations, agent.maxFoldOperations, agent.maxTurnSnapshots);
+        return new ChatDriver(this.providerRegistry, {}, [], undefined, undefined, agent.maxToolIterations, agent.maxFoldOperations, agent.maxTurnSnapshots, (_c = this.getStateKey()) !== null && _c !== void 0 ? _c : '');
     }
     /**
      * Attaches event listeners to the current driver. Stores a cleanup function
@@ -811,7 +824,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         this.driverCleanup = undefined;
     }
     connectedCallback() {
-        var _a, _b, _c, _d, _e, _f, _j;
+        var _a, _b, _c, _d, _e, _f, _j, _k, _l;
         // Initialise the store reference BEFORE super.connectedCallback() so that
         // the first FAST render has access to the store. The store Proxy calls
         // Observable.track(observableStore, sliceName) whenever a slice is read,
@@ -835,6 +848,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 this.pinnedAgentName = defaultAgent;
             }
         }
+        const driverExisted = !!getDriver(key);
         this.driver = getOrCreateDriver(key, () => this.createDriver());
         this._driverAgentsKey = this.getAgentsKey(this.agents);
         this.wireDriver();
@@ -843,9 +857,11 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             // panel, a collapse-mode element connects and wires to the same shared
             // driver. Unwire this (hidden) instance on popout; re-wire on popin.
             const unsubPopout = agenticActivityBus.subscribe('chat-popout', () => {
+                this.logMeta('driver.unwired', { reason: 'popout' });
                 this.unwireDriver();
             });
             const unsubPopin = agenticActivityBus.subscribe('chat-popin', () => {
+                this.logMeta('driver.wired', { reason: 'popin' });
                 this.wireDriver();
             });
             this.unsubBus = () => {
@@ -896,9 +912,16 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         if (this.state !== 'loading')
             this.maybeAutoFocusChatInput();
         logger.debug('FoundationAiAssistant connected');
+        this.logMeta('assistant.connected', {
+            store: isNewStore ? 'created' : 'restored',
+            restoredMessages: this.messages.length,
+            driver: driverExisted ? 'reused' : 'created',
+            driverKind: this.driver instanceof OrchestratingDriver ? 'orchestrating' : 'chat',
+            driverBusy: (_l = (_k = this.driver) === null || _k === void 0 ? void 0 : _k.isBusy()) !== null && _l !== void 0 ? _l : false,
+        });
     }
     disconnectedCallback() {
-        var _a, _b;
+        var _a, _b, _c, _d;
         super.disconnectedCallback();
         this.stopLoadingTimer();
         this.state = 'idle';
@@ -920,6 +943,8 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         // the panel re-mounts open.
         this._agentPickerToggle.finalize();
         this._settingsToggle.finalize();
+        // Capture before clearing — `wasBusy` reads the driver, which is dropped below.
+        this.logMeta('assistant.disconnected', { wasBusy: (_d = (_c = this.driver) === null || _c === void 0 ? void 0 : _c.isBusy()) !== null && _d !== void 0 ? _d : false });
         // Clear local references only — driver and store stay in their registries.
         this.driver = undefined;
         this._sessionRef = undefined;
@@ -1008,6 +1033,31 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         if (runningCost !== this.sessionCostUsd) {
             this.sessionCostUsd = runningCost;
         }
+        // Record a context.updated meta event when the token count changes (≈once
+        // per LLM call, as a new usage-bearing message arrives), plus a one-shot
+        // threshold-crossed event the first time usage passes 80%.
+        if (this.contextTokens != null && this.contextTokens !== this._lastLoggedContextTokens) {
+            this._lastLoggedContextTokens = this.contextTokens;
+            const usagePercent = this.contextLimit != null && this.contextLimit > 0
+                ? Math.round((this.contextTokens / this.contextLimit) * 100)
+                : undefined;
+            this.logMeta('context.updated', {
+                tokens: this.contextTokens,
+                limit: this.contextLimit,
+                usagePercent,
+                costUsd: this.sessionCostUsd,
+            });
+            if (usagePercent != null &&
+                usagePercent >= FoundationAiAssistant_1.CONTEXT_USAGE_WARN_PERCENT &&
+                !this._contextThresholdCrossed) {
+                this._contextThresholdCrossed = true;
+                this.logMeta('context.threshold-crossed', {
+                    usagePercent,
+                    tokens: this.contextTokens,
+                    limit: this.contextLimit,
+                });
+            }
+        }
         // Publish halo-start whenever a new toolCalls message arrives.
         if (this.showHalo !== 'no' && ((_a = this.enabledAnimations) === null || _a === void 0 ? void 0 : _a.includes('halo'))) {
             const last = this.messages[this.messages.length - 1];
@@ -1067,9 +1117,11 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     /** Called when the user clicks the popout button. */
     handlePopout() {
         if (this.popoutMode === 'expand') {
+            this.logMeta('assistant.popout');
             agenticActivityBus.publish('chat-popout', undefined);
         }
         else if (this.popoutMode === 'collapse') {
+            this.logMeta('assistant.popin');
             agenticActivityBus.publish('chat-popin', undefined);
         }
     }
@@ -1078,10 +1130,30 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         const parts = [this.id, this.headerTitle].filter(Boolean);
         return parts.length ? parts.join('::') : undefined;
     }
+    /**
+     * Record a meta/lifecycle event onto this session's debug-log timeline
+     * (exported via {@link FoundationAiAssistant.getDebugLog}). Every event
+     * auto-carries `placement` so a session emitted from both the bubble and the
+     * layout panel stays disambiguated. Keyed by `stateKey` so the timeline is
+     * shared across pop-in/pop-out and survives driver rebuilds.
+     */
+    logMeta(type, detail) {
+        const key = this.getStateKey();
+        if (!key)
+            return;
+        const placement = this.popoutMode === 'expand'
+            ? 'bubble'
+            : this.popoutMode === 'collapse'
+                ? 'panel'
+                : 'standalone';
+        recordMetaEvent(key, type, Object.assign({ placement }, detail));
+    }
     toggleSettings() {
+        this.logMeta('panel.toggled', { panel: 'settings', open: !this.settingsOpen });
         this._settingsToggle.toggle();
     }
     toggleAgentPicker() {
+        this.logMeta('panel.toggled', { panel: 'agent-picker', open: !this.agentPickerOpen });
         this._agentPickerToggle.toggle();
     }
     /**
@@ -1213,12 +1285,66 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         const contextUsagePercent = this.contextTokens != null && this.contextLimit != null && this.contextLimit > 0
             ? Math.round((this.contextTokens / this.contextLimit) * 100)
             : undefined;
+        const stateKey = this.getStateKey();
+        // Collapse repeated system prompts across consecutive turns. A stateful
+        // agent's prompt changes between turns, but a stable agent repeats the same
+        // (often multi-KB) prompt every turn — so replace a turn's `systemPrompt`
+        // with a sentinel when it's byte-identical to the previous turn's. The
+        // prompt is still shown in full whenever it changes, so prompt evolution
+        // stays visible.
+        let lastFullPrompt;
+        let lastFullIndex = -1;
+        const turns = ((_e = (_d = (_c = this.driver) === null || _c === void 0 ? void 0 : _c.getTurnSnapshots) === null || _d === void 0 ? void 0 : _d.call(_c)) !== null && _e !== void 0 ? _e : []).map((t) => {
+            let { systemPrompt } = t;
+            if (systemPrompt != null && systemPrompt === lastFullPrompt) {
+                systemPrompt = `<repeated — identical to turn ${lastFullIndex}>`;
+            }
+            else if (systemPrompt != null) {
+                lastFullPrompt = systemPrompt;
+                lastFullIndex = t.turnIndex;
+            }
+            return Object.assign(Object.assign({ kind: 'turn' }, t), { systemPrompt });
+        });
+        // Single chronological timeline. The conversation messages, per-LLM-call
+        // turn snapshots, and lifecycle/structural meta events are stored separately
+        // in memory (history on the driver, turn buffer on the driver, meta buffer
+        // keyed by stateKey) but interleaved here so the exported log reads
+        // top-to-bottom as one sequence — no cross-referencing parallel arrays.
+        // Every entry is tagged `kind`. All three streams stamp ISO timestamps in
+        // the same format, so a string compare orders them chronologically; ties
+        // break by `kind` (event → turn → message: the cause, then the call it
+        // triggered, then the output) and are otherwise stable within a stream.
+        const KIND_RANK = {
+            event: 0,
+            turn: 1,
+            message: 2,
+        };
+        const messages = (_k = (_j = (_f = this.driver) === null || _f === void 0 ? void 0 : _f.getRawHistory) === null || _j === void 0 ? void 0 : _j.call(_f)) !== null && _k !== void 0 ? _k : this.messages;
+        const timeline = [
+            ...messages.map((m) => (Object.assign({ kind: 'message' }, m))),
+            ...turns,
+            ...(stateKey ? getMetaEvents(stateKey) : []).map((e) => (Object.assign({ kind: 'event' }, e))),
+        ].sort((a, b) => {
+            var _a, _b;
+            const ta = (_a = a.timestamp) !== null && _a !== void 0 ? _a : '';
+            const tb = (_b = b.timestamp) !== null && _b !== void 0 ? _b : '';
+            if (ta < tb)
+                return -1;
+            if (ta > tb)
+                return 1;
+            return KIND_RANK[a.kind] - KIND_RANK[b.kind];
+        });
         return {
-            messages: (_e = (_d = (_c = this.driver) === null || _c === void 0 ? void 0 : _c.getRawHistory) === null || _d === void 0 ? void 0 : _d.call(_c)) !== null && _e !== void 0 ? _e : this.messages,
+            // First key so it's at the top of the file — tells whoever opens the JSON
+            // (often an AI agent) how to read the rest. See debug-event-log.ts.
+            readme: DEBUG_LOG_README,
+            // The whole session as one readable sequence. The conversation transcript
+            // lives here as `kind: 'message'` entries rather than in a parallel block.
+            timeline,
             meta: {
                 timestamp,
                 host: window.location.host,
-                agentSummary: (_f = this.agents) === null || _f === void 0 ? void 0 : _f.map((a) => {
+                agentSummary: (_l = this.agents) === null || _l === void 0 ? void 0 : _l.map((a) => {
                     var _a;
                     return (Object.assign(Object.assign({}, a), { toolDefinitions: Array.isArray(a.toolDefinitions)
                             ? typeof a.toolHandlers === 'function'
@@ -1230,10 +1356,10 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                                 ? '<dynamic — resolved per turn>'
                                 : [], toolHandlers: undefined, onActivate: undefined, onDeactivate: undefined, getDebugSnapshot: undefined }));
                 }),
-                activeSystemPrompt: typeof ((_j = this.activeAgent) === null || _j === void 0 ? void 0 : _j.systemPrompt) === 'function'
+                activeSystemPrompt: typeof ((_m = this.activeAgent) === null || _m === void 0 ? void 0 : _m.systemPrompt) === 'function'
                     ? '<dynamic — resolved per turn>'
-                    : (_k = this.activeAgent) === null || _k === void 0 ? void 0 : _k.systemPrompt,
-                activePrimerHistory: (_l = this.activeAgent) === null || _l === void 0 ? void 0 : _l.primerHistory,
+                    : (_o = this.activeAgent) === null || _o === void 0 ? void 0 : _o.systemPrompt,
+                activePrimerHistory: (_p = this.activeAgent) === null || _p === void 0 ? void 0 : _p.primerHistory,
                 activeFoldStack: this.driver instanceof ChatDriver ? this.driver.getActiveFoldNames() : undefined,
                 // Context window + cost snapshot. `sessionCostUsd` is the chat-scoped
                 // total (per-message `cost` summed); the transport's lifetime cost is
@@ -1250,9 +1376,6 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 // Snapshot captured fresh at log-export time — reflects state NOW, which
                 // may have transitioned since the last LLM call.
                 activeDebugSnapshot,
-                // Per-LLM-call timeline — pairs each turn with the prompt + tool surface
-                // + agent state that drove it. Capped to the most recent N entries.
-                turnSnapshots: (_p = (_o = (_m = this.driver) === null || _m === void 0 ? void 0 : _m.getTurnSnapshots) === null || _o === void 0 ? void 0 : _o.call(_m)) !== null && _p !== void 0 ? _p : [],
                 debug: (_q = this.debugStateFactory) === null || _q === void 0 ? void 0 : _q.call(this),
             },
         };
@@ -1325,6 +1448,10 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 }
                 catch (readError) {
                     logger.error('Failed to read file:', readError);
+                    this.logMeta('file.read-failed', {
+                        file: file.name,
+                        message: readError instanceof Error ? readError.message : String(readError),
+                    });
                     return { ok: false, message: `Failed to read "${file.name}".` };
                 }
             })));
@@ -1345,8 +1472,13 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             const files = Array.from((_a = input.files) !== null && _a !== void 0 ? _a : []);
             input.value = '';
             const { attachments, errors } = yield this.processFiles(files);
-            if (attachments.length)
+            if (attachments.length) {
                 this.attachments = [...this.attachments, ...attachments];
+                this.logMeta('attachment.added', {
+                    count: attachments.length,
+                    names: attachments.map((a) => a.name),
+                });
+            }
             if (errors.length)
                 this.attachmentErrors = [...this.attachmentErrors, ...errors];
         });
@@ -1474,6 +1606,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                     return;
                 this.suggestionsState = { status: 'error', message: e.message };
                 logger.error('Failed to fetch suggestions:', e);
+                this.logMeta('suggestions.failed', { message: e.message });
             }
         });
     }
@@ -1544,6 +1677,8 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     }
 };
 FoundationAiAssistant.SCROLL_BOTTOM_THRESHOLD_PX = 50;
+/** Context-usage percentage that fires the one-shot `context.threshold-crossed` event. */
+FoundationAiAssistant.CONTEXT_USAGE_WARN_PERCENT = 80;
 FoundationAiAssistant.DEFAULT_LOADING_DELAY_S = 5;
 FoundationAiAssistant.DEFAULT_SUGGESTION_COUNT = 3;
 FoundationAiAssistant.MS_PER_SECOND = 1000;