@genesislcap/ai-assistant 14.461.2 → 14.462.0

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

@@ -1094,6 +1094,56 @@ interactionPresentation('presentation is absent when the option is omitted', asy
 
 interactionPresentation.run();
 
+// ---------------------------------------------------------------------------
+// interaction activity-bus signals (GENC-1346) — the driver brackets a parked
+// widget interaction with `interaction-requested` / `interaction-resolved`, so
+// turn-aware UI can distinguish "actively computing" from "parked awaiting the
+// user". No tool-loop event fires at a park boundary, so these are the signal.
+// ---------------------------------------------------------------------------
+
+const interactionBus = createLogicSuite('ChatDriver interaction activity-bus signals');
+
+interactionBus.after(() => {
+  agenticActivityBus.close();
+});
+
+interactionBus('brackets a park with interaction-requested then -resolved', async () => {
+  const events: string[] = [];
+  const unsubs = [
+    agenticActivityBus.subscribe('interaction-requested', () => events.push('requested')),
+    agenticActivityBus.subscribe('interaction-resolved', () => events.push('resolved')),
+  ];
+  const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]));
+
+  const pending = driver.requestInteraction('w', {});
+  assert.equal(events, ['requested'], 'parking fires interaction-requested');
+
+  const id = driver.getHistory().at(-1)!.interaction!.interactionId;
+  driver.resolveInteraction(id, { status: 'approved' });
+  await pending;
+  assert.equal(events, ['requested', 'resolved'], 'resolving fires interaction-resolved');
+
+  unsubs.forEach((u) => u());
+  driver.dispose();
+});
+
+interactionBus('a timed-out interaction still fires interaction-resolved', async () => {
+  const events: string[] = [];
+  const unsub = agenticActivityBus.subscribe('interaction-resolved', () => events.push('resolved'));
+  const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]));
+
+  // Never resolved by a user — the timeout path runs the same teardown, so it
+  // must signal the bus too (else the button would stay enabled after a timeout).
+  const pending = driver.requestInteraction('w', {}, { timeoutMs: 1 });
+  await pending;
+  assert.equal(events, ['resolved'], 'the timeout resolution path also signals the bus');
+
+  unsub();
+  driver.dispose();
+});
+
+interactionBus.run();
+
 // ---------------------------------------------------------------------------
 // interaction timeout — requestInteraction({ timeoutMs }) resolves with a
 // status:'timeout' result (never rejects) and closes the widget read-only.
@@ -1187,3 +1237,243 @@ interactionCost(
 );
 
 interactionCost.run();
+
+// ---------------------------------------------------------------------------
+// observable provider registry — runtime provider switching (GENC-1346)
+//
+// When the host registers an observable registry and swaps providers at
+// runtime, the driver must drop its memoised lookups so the next turn resolves
+// the new provider, re-emit `provider-changed` even when the resolved *name* is
+// unchanged, and (critically) never leak its subscription — including for child
+// sub-agent drivers that complete normally.
+// ---------------------------------------------------------------------------
+
+interface ObservableTestRegistry extends AIProviderRegistry {
+  subscribe(listener: () => void): () => void;
+  /** Swap the provider returned by `get`/`default` and notify subscribers. */
+  swap(provider: AIProvider): void;
+  /** Live subscriber count — lets tests assert there's no listener leak. */
+  listenerCount(): number;
+}
+
+/**
+ * A single-name (`'high'`) observable registry. `get`/`default` always return
+ * the current provider, so swapping it mid-session models a same-name vendor
+ * switch (the tier name stays `'high'`, the provider underneath changes).
+ */
+const makeObservableRegistry = (initial: AIProvider): ObservableTestRegistry => {
+  let current = initial;
+  const listeners = new Set<() => void>();
+  return {
+    get: () => current,
+    default: () => current,
+    defaultName: () => 'high',
+    names: () => ['high'],
+    getStatus: async () => null,
+    listStatuses: async () => [],
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    swap(provider: AIProvider) {
+      current = provider;
+      for (const l of Array.from(listeners)) l();
+    },
+    listenerCount: () => listeners.size,
+  };
+};
+
+const makeDriverWithRegistry = (config: AgentConfig, registry: AIProviderRegistry): ChatDriver => {
+  const driver = new ChatDriver(registry, {}, [], undefined, undefined, 50, 5, undefined, '');
+  driver.applyAgent(config);
+  return driver;
+};
+
+const observable = createLogicSuite('ChatDriver observable provider registry');
+
+observable.after(() => {
+  agenticActivityBus.close();
+});
+
+observable(
+  'a registry change clears the resolved-provider cache so the next turn uses the new provider',
+  async () => {
+    const providerA = scriptedProvider([{ role: 'assistant', content: 'A' }]);
+    const providerB = scriptedProvider([{ role: 'assistant', content: 'B' }]);
+    const registry = makeObservableRegistry(providerA);
+    // A static provider name means lookups go through `resolvedProviderCache` —
+    // the cache that must self-invalidate on a registry change.
+    const driver = makeDriverWithRegistry(agent({ name: 'tiered', provider: 'high' }), registry);
+
+    await driver.sendMessage('first');
+    assert.is(providerA.advertisedPerCall.length, 1, 'turn 1 resolves the original provider');
+    assert.is(providerB.advertisedPerCall.length, 0);
+
+    registry.swap(providerB); // notify → cache cleared
+
+    await driver.sendMessage('second');
+    assert.is(providerB.advertisedPerCall.length, 1, 'turn 2 resolves the swapped-in provider');
+    assert.is(providerA.advertisedPerCall.length, 1, 'the stale provider is not reused');
+
+    driver.dispose();
+  },
+);
+
+observable('re-emits provider-changed on a same-name swap', async () => {
+  const providerA = scriptedProvider([{ role: 'assistant', content: 'A' }]);
+  const providerB = scriptedProvider([{ role: 'assistant', content: 'B' }]);
+  const registry = makeObservableRegistry(providerA);
+  const driver = makeDriverWithRegistry(agent({ name: 'tiered', provider: 'high' }), registry);
+
+  const names: string[] = [];
+  driver.addEventListener('provider-changed', (e) => {
+    names.push((e as CustomEvent<{ name: string }>).detail.name);
+  });
+
+  await driver.sendMessage('first');
+  registry.swap(providerB);
+  await driver.sendMessage('second');
+
+  // The resolved name ('high') never changes, but the swap resets the
+  // last-dispatched name so the cog can refresh — two events, not one.
+  assert.equal(names, ['high', 'high']);
+
+  driver.dispose();
+});
+
+observable('a non-observable registry is a no-op — turn runs, dispose does not throw', async () => {
+  const provider = scriptedProvider([{ role: 'assistant', content: 'hi' }]);
+  const driver = makeDriverWithRegistry(agent({ name: 'plain' }), makeRegistry(provider));
+  await driver.sendMessage('go');
+  assert.is(provider.advertisedPerCall.length, 1);
+  driver.dispose(); // no subscription was wired — must still be safe
+});
+
+observable('a child sub-agent driver unsubscribes on completion — no listener leak', async () => {
+  const provider = scriptedProvider([callsTool('delegate', 'd1'), callsTool('finish', 'f1')]);
+  const registry = makeObservableRegistry(provider);
+  const parent = delegatingParent(completingWorker({ ok: true }), () => {});
+  const driver = makeDriverWithRegistry(parent, registry);
+
+  assert.is(registry.listenerCount(), 1, 'the parent driver subscribed on construction');
+
+  await driver.sendMessage('go');
+  // The child subscribed during the run; if it didn't clean up on its (normal)
+  // completion the registry would now hold two listeners.
+  assert.is(registry.listenerCount(), 1, 'the completed child unsubscribed');
+
+  driver.dispose();
+  assert.is(registry.listenerCount(), 0, 'the parent unsubscribed on dispose');
+});
+
+observable.run();
+
+// ---------------------------------------------------------------------------
+// per-message model attribution (GENC-1346)
+//
+// Each model-produced assistant message carries `model` (the concrete model id
+// the active provider's getStatus reports) and `providerName` (the registry slot
+// it resolved under), so the exported debug log shows which model produced each
+// message — and, since tool calls ride on the assistant message, each tool call.
+// ---------------------------------------------------------------------------
+
+/** A provider that replays scripted replies and reports `model` via getStatus
+ *  (omitted entirely when `model` is undefined, to model a provider with no
+ *  status). */
+const modelProvider = (model: string | undefined, responses: ChatMessage[]): AIProvider => {
+  const queue = [...responses];
+  const provider: AIProvider = {
+    chat: async (): Promise<ChatMessage> => queue.shift() ?? { role: 'assistant', content: 'done' },
+  };
+  if (model !== undefined) {
+    provider.getStatus = async () => ({ provider: 'gemini', model });
+  }
+  return provider;
+};
+
+const modelAttr = createLogicSuite('ChatDriver per-message model attribution');
+
+modelAttr.after(() => {
+  agenticActivityBus.close();
+});
+
+modelAttr('stamps the resolved model and registry name onto an assistant reply', async () => {
+  const provider = modelProvider('gemini-2.5-flash-lite', [
+    { role: 'assistant', content: 'hi there' },
+  ]);
+  const driver = makeDriver(agent({ name: 'plain' }), provider);
+
+  await driver.sendMessage('hello');
+
+  const reply = driver.getHistory().find((m) => m.role === 'assistant');
+  assert.ok(reply, 'assistant reply present');
+  assert.is(reply!.model, 'gemini-2.5-flash-lite', 'model id read from provider getStatus');
+  // makeRegistry registers a single provider under the name 'test'.
+  assert.is(reply!.providerName, 'test', 'registry slot the turn resolved under');
+
+  driver.dispose();
+});
+
+modelAttr(
+  'attributes a tool-calling assistant message (and so its tool calls) to the model',
+  async () => {
+    const provider = modelProvider('claude-haiku-4-5-20251001', [
+      callsTool('noop', 't1'),
+      { role: 'assistant', content: 'finished' },
+    ]);
+    const config = agent({
+      name: 'withTool',
+      toolDefinitions: [def('noop')],
+      toolHandlers: { noop: async () => 'ok' },
+    });
+    const driver = makeDriver(config, provider);
+
+    await driver.sendMessage('go');
+
+    const toolCallMsg = driver.getHistory().find((m) => (m.toolCalls?.length ?? 0) > 0);
+    assert.ok(toolCallMsg, 'an assistant message with tool calls is present');
+    assert.is(toolCallMsg!.model, 'claude-haiku-4-5-20251001');
+    assert.is(toolCallMsg!.providerName, 'test');
+
+    driver.dispose();
+  },
+);
+
+modelAttr('picks up a model swapped behind a stable name', async () => {
+  const before = modelProvider('gemini-2.5-flash-lite', [{ role: 'assistant', content: 'A' }]);
+  const after = modelProvider('gemini-2.5-pro', [{ role: 'assistant', content: 'B' }]);
+  const registry = makeObservableRegistry(before);
+  const driver = makeDriverWithRegistry(agent({ name: 'tiered', provider: 'high' }), registry);
+
+  await driver.sendMessage('first');
+  registry.swap(after); // notify → model cache cleared, next turn re-resolves
+  await driver.sendMessage('second');
+
+  const replies = driver.getHistory().filter((m) => m.role === 'assistant');
+  assert.is(replies.at(-2)?.model, 'gemini-2.5-flash-lite', 'first turn keeps the original model');
+  assert.is(replies.at(-1)?.model, 'gemini-2.5-pro', 'after the swap the new model is stamped');
+  // The tier name ('high') never changed across the swap — only the model behind it.
+  assert.is(replies.at(-1)?.providerName, 'high');
+
+  driver.dispose();
+});
+
+modelAttr('omits the model key entirely when the provider reports no status', async () => {
+  const provider = modelProvider(undefined, [{ role: 'assistant', content: 'no status here' }]);
+  const driver = makeDriver(agent({ name: 'plain' }), provider);
+
+  await driver.sendMessage('hi');
+
+  const reply = driver.getHistory().find((m) => m.role === 'assistant');
+  assert.ok(reply, 'assistant reply present');
+  // No getStatus → no model. The key is left off, not set to undefined, so the
+  // exported log carries no dead `model` line for this message.
+  assert.not.ok('model' in reply!, 'model key is absent, not present-as-undefined');
+  assert.is(reply!.providerName, 'test', 'provider name is still recorded');
+
+  driver.dispose();
+});
+
+modelAttr.run();

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

@@ -14,7 +14,10 @@ import type {
   SubAgentFailureReason,
   SubAgentRequestOptions,
 } from '@genesislcap/foundation-ai';
-import { MalformedFunctionCallError } from '@genesislcap/foundation-ai';
+import {
+  isObservableAIProviderRegistry,
+  MalformedFunctionCallError,
+} from '@genesislcap/foundation-ai';
 import { agenticActivityBus } from '../../channel/ai-activity-bus';
 import type {
   AgentConfig,
@@ -339,6 +342,27 @@ export class ChatDriver extends EventTarget implements AiDriver {
   private lastResolvedProviderName?: string;
   /** Last dispatched `provider-changed` name; avoids duplicate events on stable turns. */
   private lastDispatchedProviderName?: string;
+  /**
+   * Concrete model id of the provider resolved for the current turn, read from
+   * its `getStatus()` and stamped onto the resulting assistant message so the
+   * debug log carries per-message model lineage. Re-resolved each turn in
+   * `resolveProviderForTurn`.
+   */
+  private lastResolvedModel?: string;
+  /**
+   * Memoised `name → model id` lookups, so the per-turn model resolution doesn't
+   * re-await `getStatus()` every turn. Cleared (with `resolvedProviderCache`) on
+   * an observable-registry change, so a model swapped behind a stable name is
+   * picked up on the next turn.
+   */
+  private resolvedModelCache = new Map<string, string | undefined>();
+  /**
+   * Unsubscribe handle for the provider-registry change listener (only set when
+   * the injected registry is observable). Called in `dispose` so the long-lived
+   * registry doesn't retain this driver — see the constructor and the sub-agent
+   * teardown in `runSubAgent`.
+   */
+  private unsubscribeRegistry?: () => void;
 
   constructor(
     private readonly providerRegistry: AIProviderRegistry,
@@ -371,6 +395,24 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.primerHistory = primerHistory;
     this.maxFoldOperations = maxFoldOperations;
     this.maxTurnSnapshots = maxTurnSnapshots;
+    // Runtime provider switching: when the host registered an observable
+    // registry, drop our memoised provider lookups whenever its mapping/default
+    // changes so the next turn re-resolves against the new providers. Resetting
+    // `lastDispatchedProviderName` forces the next `resolveProviderForTurn` to
+    // re-emit `provider-changed` even when the resolved *name* is unchanged
+    // (e.g. a tier name like 'high' kept, but the vendor underneath swapped) —
+    // that's what lets status UI refresh on a same-name switch. Feature-detect
+    // means immutable/empty registries are a no-op. Child sub-agent drivers get
+    // the same registry and so subscribe here too; each cleans up in `dispose`.
+    if (isObservableAIProviderRegistry(this.providerRegistry)) {
+      this.unsubscribeRegistry = this.providerRegistry.subscribe(() => {
+        this.resolvedProviderCache.clear();
+        this.resolvedModelCache.clear();
+        this.lastResolvedProviderName = undefined;
+        this.lastResolvedModel = undefined;
+        this.lastDispatchedProviderName = undefined;
+      });
+    }
   }
 
   /**
@@ -390,6 +432,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
    */
   dispose(): void {
     this.lifecycleController.abort(new DOMException('AI assistant driver disposed', 'AbortError'));
+    // Detach from the provider registry so the long-lived registry doesn't pin
+    // this driver (and its closure) after teardown. Guard-cleared so a second
+    // dispose is a no-op, matching this method's idempotent contract.
+    this.unsubscribeRegistry?.();
+    this.unsubscribeRegistry = undefined;
   }
 
   /**
@@ -540,6 +587,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       resolvedName = name;
     }
     this.lastResolvedProviderName = resolvedName;
+    this.lastResolvedModel = await this.resolveModelForProvider(resolvedName, provider);
     if (resolvedName !== this.lastDispatchedProviderName) {
       this.lastDispatchedProviderName = resolvedName;
       recordMetaEvent(this.sessionKey, 'provider.selected', {
@@ -553,6 +601,27 @@ export class ChatDriver extends EventTarget implements AiDriver {
     return provider;
   }
 
+  /**
+   * Resolve the concrete model id for a provider via its optional `getStatus()`,
+   * memoised by registry name. Used to stamp `model` onto outgoing messages.
+   * Best-effort: a provider without `getStatus`, a null status, or a throw all
+   * yield `undefined` — model attribution is diagnostic, never load-bearing.
+   */
+  private async resolveModelForProvider(
+    name: string,
+    provider: AIProvider,
+  ): Promise<string | undefined> {
+    if (this.resolvedModelCache.has(name)) return this.resolvedModelCache.get(name);
+    let model: string | undefined;
+    try {
+      model = (await provider.getStatus?.())?.model;
+    } catch {
+      model = undefined;
+    }
+    this.resolvedModelCache.set(name, model);
+    return model;
+  }
+
   /**
    * Resolve a per-turn config input that is either a static value or a function
    * of the turn context — the value-or-resolver shape shared by `provider`,
@@ -921,6 +990,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
         component: componentName,
         agent: this.activeAgentName,
       });
+      // Signal the park boundary on the activity bus so turn-aware UI can tell
+      // "actively computing" from "parked awaiting the user" — the latter is a
+      // safe window for actions disallowed mid-request (e.g. switching provider
+      // during a long journey step). Paired with `interaction-resolved`.
+      agenticActivityBus.publish('interaction-requested', undefined);
       if (chatInputDuringExecution) {
         this.dispatchEvent(
           new CustomEvent('interaction-start', {
@@ -989,6 +1063,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
         this.dispatchEvent(new CustomEvent('interaction-stop', { detail: { interactionId } }));
       }
       recordMetaEvent(this.sessionKey, 'interaction.resolved', { interactionId });
+      // The park is ending and the loop is about to resume computing — paired
+      // with `interaction-requested`. Fires for every resolution path (user
+      // completion, timeout, cancellation), since all route through here.
+      agenticActivityBus.publish('interaction-resolved', undefined);
       interaction.resolve(result);
       this.pendingInteractions.delete(interactionId);
     } else {
@@ -1262,6 +1340,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
       this.lifecycleController.signal.removeEventListener('abort', disposeChild);
       child.removeEventListener('history-updated', forwardTrace);
       child.removeEventListener('provider-changed', forwardProviderChanged);
+      // Tear the child down on every exit path, not just timeout/parent-abort.
+      // A child that completes normally is otherwise never disposed, so its
+      // provider-registry subscription (wired in the ChatDriver constructor)
+      // would leak — the long-lived registry would retain every completed
+      // sub-agent driver. dispose() is idempotent and only aborts the (already
+      // settled) lifecycle, so the snapshot/completion reads below still work.
+      child.dispose();
       this.dispatchEvent(new CustomEvent('sub-agent-stop', { detail: lifecycleDetail }));
     }
 
@@ -1767,6 +1852,22 @@ export class ChatDriver extends EventTarget implements AiDriver {
         throw e;
       }
 
+      // Attribute the response to the concrete model + registry slot that
+      // produced it (resolved for this turn in `resolveProviderForTurn`). Carried
+      // on the assistant message so the debug-log timeline shows per-message
+      // model lineage — and thus per-tool-call, since tool calls ride on the
+      // assistant message that requests them. Harmless on a response later
+      // discarded as empty/retried; only kept copies reach history.
+      //
+      // Attach each key only when resolved: a provider with no `getStatus` (etc.)
+      // leaves the key off entirely rather than carrying it as `undefined`.
+      // JSON.stringify already drops undefined from the exported log, so this is
+      // chiefly about keeping the in-memory message shape honest.
+      if (this.lastResolvedModel !== undefined) response.model = this.lastResolvedModel;
+      if (this.lastResolvedProviderName !== undefined) {
+        response.providerName = this.lastResolvedProviderName;
+      }
+
       const isThinkingStep = response.content && response.toolCalls?.length;
       const isEmptyResponse = !response.content?.trim() && !response.toolCalls?.length;
 

package/src/main/main.ts

@@ -28,7 +28,7 @@ import type {
   ChatInputDuringExecutionMode,
   ChatMessage,
 } from '@genesislcap/foundation-ai';
-import { AIProviderRegistry } from '@genesislcap/foundation-ai';
+import { AIProviderRegistry, isObservableAIProviderRegistry } from '@genesislcap/foundation-ai';
 import { avoidTreeShaking } from '@genesislcap/foundation-utils';
 import {
   customElement,
@@ -592,6 +592,8 @@ export class FoundationAiAssistant extends GenesisElement {
   private driverCleanup?: () => void;
   private loadingTimer: ReturnType<typeof setTimeout> | undefined;
   private unsubBus?: () => void;
+  /** Unsubscribe handle for the provider-registry change listener (observable registries only). */
+  private unsubProviderRegistry?: () => void;
   private haloStartPublished = false;
   /** Fingerprint of the agents array used to build the current driver. Used by agentsChanged to skip spurious rebuilds. */
   private _driverAgentsKey?: string;
@@ -1117,6 +1119,21 @@ export class FoundationAiAssistant extends GenesisElement {
     this.fetchSuggestions();
     void this.resolveContextLimit();
     void this.loadProviderStatuses();
+    // When the host registered an observable registry (runtime provider
+    // switching), refresh the displayed model/limit and the provider list the
+    // instant its contents change — so the header reflects the new provider
+    // immediately on switch, not only when the next turn re-emits
+    // `provider-changed`. Feature-detected: a no-op for immutable registries.
+    // Re-subscribed per connect (docking/popout remounts); balanced in
+    // disconnectedCallback.
+    this.unsubProviderRegistry?.();
+    this.unsubProviderRegistry = undefined;
+    if (isObservableAIProviderRegistry(this.providerRegistry)) {
+      this.unsubProviderRegistry = this.providerRegistry.subscribe(() => {
+        void this.resolveContextLimit();
+        void this.loadProviderStatuses();
+      });
+    }
     if (this.messagesEl) {
       this._scrollListener = () => {
         this._userScrolledAway =
@@ -1150,6 +1167,8 @@ export class FoundationAiAssistant extends GenesisElement {
     this.unwireDriver();
     this.unsubBus?.();
     this.unsubBus = undefined;
+    this.unsubProviderRegistry?.();
+    this.unsubProviderRegistry = undefined;
     this._executionCompletionUnsub?.();
     this._executionCompletionUnsub = undefined;
     if (this.messagesEl && this._scrollListener) {

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

@@ -247,7 +247,7 @@ 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`.',
   '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, and `externalCostUsd` is any non-LLM cost a widget reported for its own external service calls (folded into the session cost total alongside `cost`). 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.",
+  "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, and `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.",
   "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'.`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'.",