@genesislcap/ai-assistant 14.450.0 → 14.451.0

package/src/main/main.ts

@@ -49,7 +49,13 @@ import { AiChatMarkdown } from '../components/chat-markdown/chat-markdown';
 import { AiHaloOverlay } from '../components/halo-overlay';
 import { OrchestratingDriver } from '../components/orchestrating-driver/orchestrating-driver';
 import type { AgentConfig } from '../config/config';
-import { getOrCreateDriver, deleteDriver } from '../state/driver-registry';
+import {
+  recordMetaEvent,
+  getMetaEvents,
+  DEBUG_LOG_README,
+  type MetaEventType,
+} from '../state/debug-event-log';
+import { getOrCreateDriver, getDriver, deleteDriver } from '../state/driver-registry';
 import { getSessionStore, hasSessionStore, type SessionStoreReturn } from '../state/session-store';
 import {
   AI_COLOUR_AMBER,
@@ -228,6 +234,11 @@ export class FoundationAiAssistant extends GenesisElement {
   set state(value: AiAssistantState) {
     const prev = this._sessionRef?.store.aiAssistant.state;
     this._sessionRef?.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
@@ -354,6 +365,7 @@ export class FoundationAiAssistant extends GenesisElement {
     // 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 ?? previous });
       this.suggestionsState = { status: 'idle' };
       this.fetchSuggestions();
     }
@@ -508,6 +520,12 @@ export class FoundationAiAssistant extends GenesisElement {
   private _userScrolledAway = false;
   private _scrollListener?: () => void;
   private static readonly SCROLL_BOTTOM_THRESHOLD_PX = 50;
+  /** Context-usage percentage that fires the one-shot `context.threshold-crossed` event. */
+  private static readonly CONTEXT_USAGE_WARN_PERCENT = 80;
+  /** Last `contextTokens` logged to the timeline — dedupes the `context.updated` event. */
+  private _lastLoggedContextTokens?: number;
+  /** Whether the one-shot ≥80% `context.threshold-crossed` event has fired this session. */
+  private _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
@@ -648,6 +666,10 @@ export class FoundationAiAssistant extends GenesisElement {
     this.wireDriver();
     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. */
@@ -741,6 +763,7 @@ export class FoundationAiAssistant extends GenesisElement {
       agent.maxToolIterations,
       agent.maxFoldOperations,
       agent.maxTurnSnapshots,
+      this.getStateKey() ?? '',
     );
   }
 
@@ -930,6 +953,7 @@ export class FoundationAiAssistant extends GenesisElement {
       }
     }
 
+    const driverExisted = !!getDriver(key);
     this.driver = getOrCreateDriver(key, () => this.createDriver());
     this._driverAgentsKey = this.getAgentsKey(this.agents);
     this.wireDriver();
@@ -939,9 +963,11 @@ export class FoundationAiAssistant extends GenesisElement {
       // 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 = () => {
@@ -994,6 +1020,13 @@ export class FoundationAiAssistant extends GenesisElement {
     // where state is loading and the input may be hidden or disabled).
     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: this.driver?.isBusy() ?? false,
+    });
   }
 
   disconnectedCallback() {
@@ -1018,6 +1051,8 @@ export class FoundationAiAssistant extends GenesisElement {
     // 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: this.driver?.isBusy() ?? false });
     // Clear local references only — driver and store stay in their registries.
     this.driver = undefined;
     this._sessionRef = undefined;
@@ -1101,6 +1136,34 @@ export class FoundationAiAssistant extends GenesisElement {
     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.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' && this.enabledAnimations?.includes('halo')) {
       const last = this.messages[this.messages.length - 1];
@@ -1166,8 +1229,10 @@ export class FoundationAiAssistant extends GenesisElement {
   /** Called when the user clicks the popout button. */
   handlePopout(): void {
     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);
     }
   }
@@ -1178,6 +1243,25 @@ export class FoundationAiAssistant extends GenesisElement {
     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.
+   */
+  private logMeta(type: MetaEventType, detail?: Record<string, unknown>): void {
+    const key = this.getStateKey();
+    if (!key) return;
+    const placement =
+      this.popoutMode === 'expand'
+        ? 'bubble'
+        : this.popoutMode === 'collapse'
+          ? 'panel'
+          : 'standalone';
+    recordMetaEvent(key, type, { placement, ...detail });
+  }
+
   private readonly _settingsToggle = new AnimatedPanelToggle(
     this,
     '.settings-panel',
@@ -1189,6 +1273,7 @@ export class FoundationAiAssistant extends GenesisElement {
   );
 
   toggleSettings() {
+    this.logMeta('panel.toggled', { panel: 'settings', open: !this.settingsOpen });
     this._settingsToggle.toggle();
   }
 
@@ -1203,6 +1288,7 @@ export class FoundationAiAssistant extends GenesisElement {
   );
 
   toggleAgentPicker() {
+    this.logMeta('panel.toggled', { panel: 'agent-picker', open: !this.agentPickerOpen });
     this._agentPickerToggle.toggle();
   }
 
@@ -1337,8 +1423,60 @@ export class FoundationAiAssistant extends GenesisElement {
       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: string | undefined;
+    let lastFullIndex = -1;
+    const turns = (this.driver?.getTurnSnapshots?.() ?? []).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 { kind: 'turn' as const, ...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: Record<'event' | 'turn' | 'message', number> = {
+      event: 0,
+      turn: 1,
+      message: 2,
+    };
+    const messages = this.driver?.getRawHistory?.() ?? this.messages;
+    const timeline = [
+      ...messages.map((m) => ({ kind: 'message' as const, ...m })),
+      ...turns,
+      ...(stateKey ? getMetaEvents(stateKey) : []).map((e) => ({ kind: 'event' as const, ...e })),
+    ].sort((a, b) => {
+      const ta = a.timestamp ?? '';
+      const tb = b.timestamp ?? '';
+      if (ta < tb) return -1;
+      if (ta > tb) return 1;
+      return KIND_RANK[a.kind] - KIND_RANK[b.kind];
+    });
     return {
-      messages: this.driver?.getRawHistory?.() ?? 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,
@@ -1380,9 +1518,6 @@ export class FoundationAiAssistant extends GenesisElement {
         // 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: this.driver?.getTurnSnapshots?.() ?? [],
         debug: this.debugStateFactory?.(),
       },
     };
@@ -1466,6 +1601,10 @@ export class FoundationAiAssistant extends GenesisElement {
           };
         } 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}".` };
         }
       }),
@@ -1486,7 +1625,13 @@ export class FoundationAiAssistant extends GenesisElement {
     const files = Array.from(input.files ?? []);
     input.value = '';
     const { attachments, errors } = await this.processFiles(files);
-    if (attachments.length) this.attachments = [...this.attachments, ...attachments];
+    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];
   }
 
@@ -1619,6 +1764,7 @@ export class FoundationAiAssistant extends GenesisElement {
       if (generation !== this._suggestionsGeneration) return;
       this.suggestionsState = { status: 'error', message: (e as Error).message };
       logger.error('Failed to fetch suggestions:', e);
+      this.logMeta('suggestions.failed', { message: (e as Error).message });
     }
   }
 

package/src/state/debug-event-log.ts

@@ -0,0 +1,194 @@
+/**
+ * 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
+ */
+
+/**
+ * Catalogue of meta event names. This is the documented surface — extend it as
+ * new events are wired in (Tier 2/3 lifecycle, interaction, provider events).
+ */
+export type MetaEventType =
+  // Element lifecycle + window placement
+  | 'assistant.connected'
+  | 'assistant.disconnected'
+  | 'assistant.popout'
+  | 'assistant.popin'
+  // Driver lifecycle / wiring
+  | 'driver.created'
+  | 'driver.wired'
+  | 'driver.unwired'
+  // Turn lifecycle
+  | 'state.changed'
+  | 'turn.start'
+  | 'turn.end'
+  | 'turn.error'
+  | 'tool.failed'
+  // Routing / providers
+  | 'agent.handoff'
+  | 'agent.pinned'
+  | 'agent.unpinned'
+  | 'provider.selected'
+  // Blocking interactions
+  | 'interaction.requested'
+  | 'interaction.resolved'
+  // Context / cost
+  | 'context.updated'
+  | 'context.threshold-crossed'
+  // UI + input
+  | 'panel.toggled'
+  | 'attachment.added'
+  | 'file.read-failed'
+  | 'suggestions.failed';
+
+/**
+ * How much a reader should care about an event — lets a consumer (or an AI
+ * agent) filter the timeline: skip `low` UI/bookkeeping noise, skim `normal`
+ * session flow, or jump straight to `high` problem/limit signals when triaging.
+ */
+export type MetaEventImportance = 'high' | 'normal' | 'low';
+
+/**
+ * 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: Record<MetaEventType, MetaEventImportance> = {
+  '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',
+};
+
+/** One entry in the meta-event timeline. */
+export interface MetaEvent {
+  /** Monotonic counter across the session's lifetime (does not reset on driver rebuild). */
+  index: number;
+  /** ISO timestamp, matching the format used elsewhere in the debug log. */
+  timestamp: string;
+  /** Event name — see {@link MetaEventType}. */
+  type: MetaEventType;
+  /** How much to care about this event — see {@link META_EVENT_IMPORTANCE}. */
+  importance: MetaEventImportance;
+  /** Optional structured payload. */
+  detail?: Record<string, unknown>;
+}
+
+/** Default ring-buffer cap. ~5× the turn-snapshot cap — entries are cheap. */
+const DEFAULT_MAX_META_EVENTS = 200;
+
+interface MetaEventBuffer {
+  events: MetaEvent[];
+  /** Next index to assign — kept separate from `events.length` so it stays monotonic after eviction. */
+  next: number;
+}
+
+const registry = new Map<string, MetaEventBuffer>();
+
+/**
+ * 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: string,
+  type: MetaEventType,
+  detail?: Record<string, unknown>,
+): void {
+  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: string): ReadonlyArray<MetaEvent> {
+  return registry.get(key)?.events ?? [];
+}
+
+/**
+ * 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: readonly string[] = [
+  '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(): void {
+  registry.clear();
+}