@genesislcap/ai-assistant 15.19.0 → 15.19.1

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

@@ -1,154 +0,0 @@
-import type { SubAgentFailureReason, TurnFailureReason } from '@genesislcap/foundation-ai';
-import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import {
-  clearMetaEventRegistry,
-  clearSession,
-  DEBUG_LOG_README,
-  getMetaEvents,
-  type MetaEvent,
-  mergeMetaEvents,
-  recordMetaEvent,
-} from './debug-event-log';
-
-const event = (overrides: Partial<MetaEvent> = {}): MetaEvent => ({
-  index: 0,
-  timestamp: '2026-06-19T16:00:00.000Z',
-  type: 'turn.retry',
-  importance: 'normal',
-  ...overrides,
-});
-
-const suite = createLogicSuite('debug-event-log merge/clear');
-
-suite('mergeMetaEvents is a no-op for an empty batch', () => {
-  clearMetaEventRegistry();
-  mergeMetaEvents('k', []);
-  assert.is(getMetaEvents('k').length, 0);
-});
-
-suite('mergeMetaEvents preserves each event timestamp and re-indexes monotonically', () => {
-  clearMetaEventRegistry();
-  mergeMetaEvents('k', [
-    event({ index: 7, timestamp: '2026-06-19T16:00:01.000Z', detail: { a: 1 } }),
-    event({ index: 99, timestamp: '2026-06-19T16:00:02.000Z', detail: { b: 2 } }),
-  ]);
-  const out = getMetaEvents('k');
-  assert.is(out.length, 2);
-  // original timestamps kept (not re-stamped) ...
-  assert.is(out[0].timestamp, '2026-06-19T16:00:01.000Z');
-  assert.is(out[1].timestamp, '2026-06-19T16:00:02.000Z');
-  // ... indices re-assigned from the target's counter, not carried from source.
-  assert.is(out[0].index, 0);
-  assert.is(out[1].index, 1);
-  assert.equal(out[0].detail, { a: 1 });
-});
-
-suite('mergeMetaEvents appends after existing events with a continuing index', () => {
-  clearMetaEventRegistry();
-  recordMetaEvent('k', 'turn.start'); // index 0, real timestamp
-  mergeMetaEvents('k', [event({ type: 'turn.error', importance: 'high' })]);
-  const out = getMetaEvents('k');
-  assert.is(out.length, 2);
-  assert.is(out[0].type, 'turn.start');
-  assert.is(out[1].type, 'turn.error');
-  assert.is(out[1].index, 1); // continues the monotonic counter
-});
-
-suite('mergeMetaEvents into a fresh key creates the bucket', () => {
-  clearMetaEventRegistry();
-  mergeMetaEvents('brand-new', [event()]);
-  assert.is(getMetaEvents('brand-new').length, 1);
-});
-
-suite('mergeMetaEvents evicts oldest non-high events past the cap but keeps every high', () => {
-  clearMetaEventRegistry();
-  const highStamp = '2026-06-19T16:30:00.000Z';
-  // One `high` failure first, then a flood of `normal` events well past the cap.
-  const batch: MetaEvent[] = [
-    event({ type: 'turn.error', importance: 'high', timestamp: highStamp }),
-  ];
-  for (let i = 0; i < 2000; i += 1) {
-    batch.push(event({ type: 'turn.retry', importance: 'normal' }));
-  }
-  mergeMetaEvents('k', batch);
-  const out = getMetaEvents('k');
-  // Eviction ran (bounded below what we merged) ...
-  assert.ok(out.length < 2001);
-  // ... and the lone high-importance failure was never dropped.
-  assert.is(out.filter((e) => e.importance === 'high').length, 1);
-  assert.ok(out.some((e) => e.timestamp === highStamp));
-});
-
-suite('clearSession drops one key without touching others', () => {
-  clearMetaEventRegistry();
-  recordMetaEvent('child', 'turn.retry');
-  recordMetaEvent('parent', 'turn.start');
-  clearSession('child');
-  assert.is(getMetaEvents('child').length, 0);
-  assert.is(getMetaEvents('parent').length, 1);
-});
-
-// ── README ↔ taxonomy sync (GENC-1464) ─────────────────────────────────────────
-// DEBUG_LOG_README is emitted as the FIRST key of the exported debug log
-// specifically so an agent reading the JSON does not have to reverse-engineer it.
-// Its reason enumerations therefore read as exhaustive and will be trusted — but
-// they had already drifted twice (`refusal` was missing from both) before anyone
-// noticed, because "the doc lives next to the catalogue" is not enforcement.
-//
-// The `Record<..., true>` below is the enforcement: adding a union member without
-// listing it here is a COMPILE error, and listing it without documenting it is a
-// test failure. So the next added reason fails in the one place the drift keeps
-// happening.
-
-const ALL_TURN_FAILURE_REASONS = Object.keys({
-  exception: true,
-  'malformed-function-call': true,
-  'empty-response': true,
-  'unknown-tool-limit': true,
-  'max-iterations': true,
-  'response-truncated': true,
-  refusal: true,
-  'budget-exhausted': true,
-  'provider-refused': true,
-} satisfies Record<TurnFailureReason, true>) as TurnFailureReason[];
-
-const ALL_SUB_AGENT_FAILURE_REASONS = Object.keys({
-  max_iterations: true,
-  malformed_tool_call: true,
-  empty_response: true,
-  unknown_tool_limit: true,
-  timeout: true,
-  response_truncated: true,
-  refusal: true,
-  budget_exhausted: true,
-  provider_refused: true,
-} satisfies Record<SubAgentFailureReason, true>) as SubAgentFailureReason[];
-
-const README_TEXT = DEBUG_LOG_README.join('\n');
-
-suite('DEBUG_LOG_README enumerates every TurnFailureReason', () => {
-  for (const reason of ALL_TURN_FAILURE_REASONS) {
-    assert.ok(
-      README_TEXT.includes(reason),
-      `turn.error reason '${reason}' is missing from DEBUG_LOG_README`,
-    );
-  }
-});
-
-suite('DEBUG_LOG_README enumerates every SubAgentFailureReason', () => {
-  for (const reason of ALL_SUB_AGENT_FAILURE_REASONS) {
-    assert.ok(
-      README_TEXT.includes(reason),
-      `subagent.failed reason '${reason}' is missing from DEBUG_LOG_README`,
-    );
-  }
-});
-
-suite('DEBUG_LOG_README documents the budget diagnostics that ride turn.error', () => {
-  // `recordTurnError('budget-exhausted', …)` attaches these; an agent triaging a
-  // support ticket needs to know to look for them.
-  assert.ok(README_TEXT.includes('budgetUsd'));
-  assert.ok(README_TEXT.includes('spentUsd'));
-});
-
-suite.run();

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

@@ -1,358 +0,0 @@
-/**
- * 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 in `getDebugLog().timeline`, merged chronologically with messages and
- * turn snapshots. Ring-buffered — the oldest non-`high` events are evicted first
- * while `high`-importance failure events are retained — so a long-lived session
- * stays bounded in normal use without ever dropping a failure signal.
- *
- * @internal
- */
-
-import type { TurnFailureReason } from '@genesislcap/foundation-ai';
-
-/**
- * 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.retry'
-  | 'turn.error'
-  | 'tool.failed'
-  | 'tool.unresolved'
-  | 'subagent.started'
-  | 'subagent.completed'
-  | 'subagent.failed'
-  // Routing / providers
-  | 'agent.handoff'
-  | 'agent.pinned'
-  | 'agent.unpinned'
-  | 'provider.selected'
-  // Blocking interactions
-  | 'interaction.requested'
-  | 'interaction.resolved'
-  | 'interaction.external-cost'
-  | 'interaction.external-cost-dropped'
-  // External / unified diagnostics (GENC-1461) — an out-of-band engine's log folded into this session
-  | 'external-diagnostics.folded'
-  // Context / cost
-  | 'context.updated'
-  | 'context.threshold-crossed'
-  | 'context.compacted'
-  | 'context.condensed'
-  // UI + input
-  | 'panel.toggled'
-  | 'attachment.added'
-  | 'file.read-failed'
-  | 'suggestions.failed'
-  // Session lifecycle (GENC-1351)
-  | 'session.cleared'
-  | 'session.switched'
-  | 'session.switch-deferred'
-  | 'persistence.toggled'
-  | 'persistence.saved'
-  | 'persistence.save-failed'
-  | 'persistence.suppressed'
-  | 'persistence.not-resumable'
-  | 'persistence.restored'
-  | 'persistence.restore-orphan';
-
-/**
- * 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',
-  'subagent.failed': 'high',
-  'file.read-failed': 'high',
-  'suggestions.failed': 'high',
-  'context.threshold-crossed': 'high',
-  'context.compacted': 'high',
-  'persistence.restore-orphan': 'high',
-  // A save that did not land is silent data loss in progress: the transcript on screen
-  // is no longer backed by the store, and every later turn widens the gap. GENC-1511.
-  'persistence.save-failed': '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',
-  'turn.retry': 'normal',
-  'tool.unresolved': 'normal',
-  'subagent.started': 'normal',
-  'subagent.completed': 'normal',
-  'agent.handoff': 'normal',
-  'agent.pinned': 'normal',
-  'agent.unpinned': 'normal',
-  'provider.selected': 'normal',
-  'interaction.requested': 'normal',
-  'interaction.resolved': 'normal',
-  // Bookkeeping about an already-finished turn; interesting when reconciling a session total.
-  'interaction.external-cost': 'normal',
-  // Spend that was billed but could NOT be recorded (the message was trimmed/condensed away, or
-  // the value was not real spend). 'high': it is the one way the session total goes quietly
-  // wrong, so it must stand out when reconciling.
-  'interaction.external-cost-dropped': 'high',
-  'external-diagnostics.folded': 'normal',
-  'session.cleared': 'normal',
-  'session.switched': 'low',
-  'session.switch-deferred': 'low',
-  'persistence.restored': 'normal',
-  'persistence.suppressed': 'normal',
-  'persistence.not-resumable': 'normal',
-
-  'driver.wired': 'low',
-  'driver.unwired': 'low',
-  'context.updated': 'low',
-  'context.condensed': 'low',
-  'panel.toggled': 'low',
-  'persistence.toggled': 'low',
-  'persistence.saved': '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>;
-}
-
-/**
- * Soft ring-buffer cap. Once exceeded, the oldest *non-`high`* event is evicted;
- * `high`-importance events (failures and hard limits) are never dropped — they're
- * the whole reason the log exists. So a buffer dominated by `high` events is
- * allowed to float above this cap rather than lose a failure signal; in normal
- * use the frequent `low`/`normal` events keep it near the cap. Entries are cheap.
- */
-const DEFAULT_MAX_META_EVENTS = 800;
-
-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`. Once the buffer exceeds
- * {@link DEFAULT_MAX_META_EVENTS}, evicts the oldest *non-`high`* event;
- * `high`-importance events are never evicted. 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) {
-    // Drop the oldest event that isn't `high` importance. `high` events
-    // (failures/limits) are retained even past the cap — losing a failure
-    // signal is worse than briefly exceeding the buffer size. If every retained
-    // event is `high` (all-failures session), nothing is evicted and the buffer
-    // grows; in practice frequent `low`/`normal` events keep it bounded.
-    const evictAt = buffer.events.findIndex((e) => e.importance !== 'high');
-    if (evictAt !== -1) {
-      buffer.events.splice(evictAt, 1);
-    }
-  }
-}
-
-/**
- * Why a turn failed or was retried — stamped as `detail.reason` on `turn.error`
- * and `turn.retry` events, and (since PTC-0) surfaced at the driver's loop
- * boundary via {@link ChatDriverResult.failureReason}. Re-exported from
- * `@genesislcap/foundation-ai` — where it lives alongside `ChatDriverResult` so
- * the boundary field and this log surface can never drift apart — under its
- * historical name so existing importers are unaffected. Enumerated so the set
- * stays in sync with the README and call sites can't drift to ad-hoc strings.
- */
-export type { TurnFailureReason };
-
-/**
- * Record a turn-ending failure (`turn.error`, importance `high`). The `reason`
- * is typed so the high-importance triage surface stays consistent; pass any
- * diagnostic specifics (attempt counts, offending tool names, etc.) in `detail`.
- */
-export function recordTurnError(
-  key: string,
-  reason: TurnFailureReason,
-  detail?: Record<string, unknown>,
-): void {
-  recordMetaEvent(key, 'turn.error', { reason, ...detail });
-}
-
-/**
- * Record a recoverable retry *within* a turn (`turn.retry`, importance `normal`)
- * — e.g. one malformed/empty attempt that will be retried, as distinct from the
- * final attempt that bails out as a `turn.error`. Include `attempt`/`maxAttempts`
- * in `detail` so the timeline shows which try this was.
- */
-export function recordTurnRetry(
-  key: string,
-  reason: TurnFailureReason,
-  detail?: Record<string, unknown>,
-): void {
-  recordMetaEvent(key, 'turn.retry', { reason, ...detail });
-}
-
-/** 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 ?? [];
-}
-
-/**
- * Merge pre-built meta events into the timeline for `targetKey`, **preserving each
- * event's original `timestamp`** (so it interleaves chronologically on export)
- * while re-indexing onto the target buffer's monotonic counter. Used to fold a
- * sub-agent's harvested events into the parent session — see
- * `ChatDriver.invokeSubAgent`. Unlike {@link recordMetaEvent} it does not stamp a
- * fresh timestamp; the same non-`high` eviction policy is applied once after the
- * batch so the buffer stays bounded.
- */
-export function mergeMetaEvents(targetKey: string, events: readonly MetaEvent[]): void {
-  if (events.length === 0) return;
-  let buffer = registry.get(targetKey);
-  if (!buffer) {
-    buffer = { events: [], next: 0 };
-    registry.set(targetKey, buffer);
-  }
-  for (const event of events) {
-    buffer.events.push({ ...event, index: buffer.next });
-    buffer.next += 1;
-  }
-  // Evict oldest non-`high` events until back under the cap — same policy as
-  // recordMetaEvent; `high` events (failures/limits) are never dropped. Single
-  // pass: take the overflow count, then drop that many of the oldest non-`high`
-  // events in order (if there aren't enough non-`high`, the buffer floats above
-  // the cap rather than losing a failure signal).
-  let toEvict = buffer.events.length - DEFAULT_MAX_META_EVENTS;
-  if (toEvict > 0) {
-    buffer.events = buffer.events.filter((e) => {
-      if (toEvict > 0 && e.importance !== 'high') {
-        toEvict -= 1;
-        return false;
-      }
-      return true;
-    });
-  }
-}
-
-/**
- * Drop the entire timeline for `key`. Used to discard a sub-agent's transient
- * per-invocation session once its events have been harvested into the parent, so
- * the module registry doesn't accumulate one orphaned bucket per sub-agent run.
- */
-export function clearSession(key: string): void {
-  registry.delete(key);
-}
-
-/**
- * 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 — but proximity alone demonstrably did NOT keep the two in sync
- * (`refusal` was missing from both reason lists for a whole release), so
- * `debug-event-log.test.ts` now asserts that every `TurnFailureReason` and every
- * `SubAgentFailureReason` is named here, and fails the build when one is added
- * without a matching sentence. Enumerations below read as exhaustive and WILL be
- * trusted by an agent reading the JSON — keep them so.
- */
-export const DEBUG_LOG_README: readonly string[] = [
-  'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',
-  "`sessionUsage` is what this session spent: `costUsd` (USD, provider-reported per request and summed, cache discounts already applied) plus the four TOKEN BUCKETS — `uncachedInputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `outputTokens`. Those four are disjoint and safe to add up for a total-tokens figure; the per-message fields further down are NOT (see kind:'message'). Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a big token count against a small cost means the prompt was mostly cache hits, not a missing charge. It covers sub-agent turns and spend a compaction banked, so for the CONVERSATION it is the authoritative total: prefer it over re-summing the timeline, which can be short by whatever the ring buffers evicted. The same figures appear under `meta.context`. It is as current as the snapshot it came from: the assistant's own download stamps a fresh one, but a log stitched by another tool can carry an older one — compare `meta.timestamp` with the last timeline entry, and if it is well behind, read these totals as historical and fall back to summing the timeline. One scope caveat: it is derived from the transcript, so it excludes billed calls that produced no message (a blank or refused attempt that was retried — see kind:'turn'.`usage`). Summing the turns can therefore come out HIGHER than this, and the difference is exactly that discarded spend, not a double-count.",
-  "What 'session' means for those figures: the CURRENT conversation under this session key (a host-supplied per-project id, or the element id + header title when the host supplies none) — which is not necessarily everything in `timeline`. It is re-derived from the live transcript, so it spans page loads only when the chat is being remembered, and a Clear resets it to zero. `timeline` is append-only regardless: it keeps every page load and the pre-Clear conversation, with the session.cleared event as the boundary. So on a long-lived log, read these totals as the latest conversation's and the earlier sections as history — not as a total of the whole file.",
-  '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',
-  'Timestamps are millisecond-resolution; entries that share the same millisecond are ordered by a fixed kind rank (event, then turn, then message), which is a heuristic and may not reflect exact causal order within that millisecond — e.g. a user message and the turn it triggered, or a final assistant message and its turn.end event, can appear in either order depending on whether they landed in the same millisecond. Read the logical structure of a turn rather than over-interpreting the micro-ordering of co-timestamped entries of different kinds.',
-  "kind:'message' — the conversation. `role` is user/assistant/tool/system-event/synthetic-user; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message LLM usage, where `inputTokens` is the WHOLE prompt for that request and `cacheReadTokens`/`cacheWriteTokens` BREAK IT DOWN rather than add to it — uncached input is `inputTokens` minus those two, and adding the cache fields to `inputTokens` counts the prompt twice. The cache fields are absent on providers that report no cache split (Gemini reports reads only, since implicit caching bills no write) and on messages persisted before they existed, so read them as 0 when missing. Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a large token count at a small cost means the prompt was mostly cache hits. `externalCostUsd` is any non-LLM cost a widget reported for its own external service calls (folded into the session cost total alongside `cost`). On model-produced assistant messages, `model` is the concrete model id that generated it (e.g. 'gemini-2.5-flash-lite') and `providerName` is the registry slot it resolved under (e.g. a tier name like 'high'/'low', or the default); together they attribute the message — and any tool calls it carries — to an exact model even across a mid-session vendor/tier switch, where one slot name can map to different models before and after the switch. Both are undefined on any entry that is NOT an LLM response: non-assistant roles (user/tool/system-event) and 'synthetic-user' echoes; assistant interaction/widget entries (empty content carrying an `interaction` — a rendered widget, not a model turn); driver-authored assistant fallbacks (the timeout, repeated-malformed-call, and empty-response apology messages); and messages restored from a session persisted before these fields existed. One partial case: on a genuine model turn whose provider exposes no `getStatus` (or reports no model), `providerName` is still set but `model` alone is undefined. A 'synthetic-user' message is a display-only echo of an interaction outcome (e.g. the answer a widget reported): it renders on the user's side of the chat and `agentName` is the agent that created it, but it is never sent to the LLM — so it has no matching 'turn' and the model learns the outcome only from the corresponding tool result.",
-  "Sub-agent messages appear inline. When a tool delegates to a sub-agent (via `requestSubAgent`), the sub-agent's whole conversation — its own assistant/tool messages, each with their own `content`/`thinking`/`toolCalls`/`toolResult` and per-message `model`/`providerName`/`inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheWriteTokens`/`cost` — is hoisted into the timeline as ordinary kind:'message' entries, interleaved by timestamp right after the tool call that spawned them (so you read the delegation top-to-bottom). A hoisted entry is marked: `subAgentDepth` is its delegation depth (1 for a sub-agent, 2 for a sub-agent's sub-agent, …), `subAgentOf` is the id of the parent tool call that spawned it (correlates it back even when two sub-agents run in one parent turn), `subAgentName` is the sub-agent's own name, and `agentName` is rewritten to a `\"<parent> › <sub-agent>\"` breadcrumb (composing when nested, e.g. `\"UI Builder › Planner › Grounding\"`). The sub-agent's per-LLM-call snapshots also surface as kind:'turn' entries with an N-M `turnIndex`, and subagent.started/completed (or subagent.failed) events bracket the run. Per-message `cost` on hoisted entries is already part of the session total (it is summed from the un-flattened history), so summing the top-level timeline does NOT double-count.",
-  "kind:'turn' — one LLM call. `turnIndex` is a string: a top-level turn is the bare counter ('0', '1', …); a sub-agent's turns are numbered under the parent turn that activated them ('3-1', '3-2', …, and a nested sub-agent contributes '3-2-1', …), and `agentName` names the agent that ran the turn. `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'.`model`/`providerName`/`provider` — which model ran that call: the concrete model id, the registry slot it resolved under (a tier name like 'high'/'low', or the default), and the vendor. Recorded per CALL, so an agent whose `provider` selector varies by state — a flow that plans on a high tier and executes on a low one — has every step attributed, including calls that produced no message. `model` is the SERVING model where the provider reports one, so a turn answered by a server-side fallback names the model that answered rather than the one requested; it always matches the `model` on the message that call produced. Absent when the provider exposes no `getStatus` and the transport stamped nothing.",
-  "kind:'turn'.`usage` — what that ONE call cost, in the same four-bucket + `costUsd` shape as `sessionUsage`. Absent while a call is in flight and on providers that report no usage. This is the SAME money as the message the call produced, not extra money: never add turn usage to message usage, and read a turn plus its message as one charge. Its distinct value is the calls that produced NO message — a blank or refused response is billed and then discarded before the retry, so the turn entry is the only record of that spend, and a turn with `usage` but no message after it is exactly that. `costUsd: 0` alongside a nonzero token count means the provider reported no price, not that the call was free.",
-  "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, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. '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.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted/provider-refused, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, for provider-refused the kind (spend|auth) plus the upstream status and error type — the vendor refusing the ACCOUNT rather than us refusing to spend, so the remedy is a top-up or a key rotation rather than a raised cap, and the kind is the only place that distinction survives because the user-facing copy is deliberately cause-free, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted/provider_refused; budget_exhausted and provider_refused are both terminal for the PARENT turn too — the parent stops rather than calling the model again into the same wall), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
-  'Sub-agent meta events: a sub-agent\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `"<parent> › <sub-agent>"` breadcrumb that composes when nested (e.g. `"UI Builder › Planner › Grounding"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\'s span.',
-  "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, contextTokens/contextLimit/contextUsagePercent for the last call, and the session totals — sessionCostUsd, sessionTokensConsumed, and the four-bucket sessionUsage lifted to the top of this log), 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.",
-  'Note the two different scopes in `meta.context`: `contextTokens` is the prompt size of the LAST call (against `contextLimit`, the model context window), while `sessionUsage`/`sessionTokensConsumed` are cumulative BILLED throughput. Every turn resends the conversation, so the cumulative figure counts each turn’s prompt again in the next turn’s and is expected to dwarf the context size — that is not double-counting.',
-  '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();
-}

package/src/state/driver-registry.test.ts

@@ -1,70 +0,0 @@
-import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import type { AiDriver } from '../components/ai-driver/ai-driver';
-import {
-  clearDriverRegistry,
-  deleteDriver,
-  getDriver,
-  getDriverAgentsKey,
-  getOrCreateDriver,
-} from './driver-registry';
-
-// Minimal stub — the registry only stores and returns the reference; it never
-// invokes driver methods, so an opaque object is sufficient.
-const stub = (id: string): AiDriver => ({ id }) as unknown as AiDriver;
-
-const suite = createLogicSuite('driver-registry agents-key tracking');
-
-suite('getOrCreateDriver creates once and records the agents key', () => {
-  clearDriverRegistry();
-  const d = stub('a');
-  const created = getOrCreateDriver('k', 'agentsKeyA', () => d);
-  assert.is(created, d);
-  assert.is(getDriver('k'), d);
-  assert.is(getDriverAgentsKey('k'), 'agentsKeyA');
-});
-
-suite('reuse returns the existing driver and keeps its original agents key', () => {
-  clearDriverRegistry();
-  const first = stub('first');
-  getOrCreateDriver('k', 'agentsKeyA', () => first);
-  // A second component sharing the key, even with a different desired agents
-  // fingerprint, must NOT replace the driver or overwrite the recorded key.
-  let factoryCalled = false;
-  const reused = getOrCreateDriver('k', 'agentsKeyB', () => {
-    factoryCalled = true;
-    return stub('second');
-  });
-  assert.is(reused, first);
-  assert.is(factoryCalled, false);
-  assert.is(getDriverAgentsKey('k'), 'agentsKeyA');
-});
-
-suite('deleteDriver clears both the driver and its recorded agents key', () => {
-  clearDriverRegistry();
-  getOrCreateDriver('k', 'agentsKeyA', () => stub('a'));
-  deleteDriver('k');
-  assert.is(getDriver('k'), undefined);
-  assert.is(getDriverAgentsKey('k'), undefined);
-});
-
-suite('a rebuild under the same key records the new agents key (the adopt signal)', () => {
-  clearDriverRegistry();
-  // Initial driver, built for the old agent set.
-  getOrCreateDriver('k', 'old', () => stub('d-old'));
-  // Rebuild: the host deletes then recreates with the new fingerprint.
-  deleteDriver('k');
-  const rebuilt = stub('d-new');
-  getOrCreateDriver('k', 'new', () => rebuilt);
-  // GENC-1388: a sibling sharing the key can now detect that the registry driver
-  // already matches its desired agents and adopt `rebuilt`, rather than
-  // recreating (which would orphan a driver mid-turn).
-  assert.is(getDriver('k'), rebuilt);
-  assert.is(getDriverAgentsKey('k'), 'new');
-});
-
-suite('getDriverAgentsKey is undefined for an unknown key', () => {
-  clearDriverRegistry();
-  assert.is(getDriverAgentsKey('missing'), undefined);
-});
-
-suite.run();