@genesislcap/ai-assistant 14.455.0 → 14.455.1

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

@@ -4,6 +4,7 @@ import type {
   ChatMessage,
   ChatRequestOptions,
   ChatToolCall,
+  ChatToolChoice,
   ChatToolDefinition,
 } from '@genesislcap/foundation-ai';
 import { isChatToolCallUnknown } from '@genesislcap/foundation-ai';
@@ -33,16 +34,20 @@ interface ScriptedProvider extends AIProvider {
   /** Tool names advertised to the model on each `chat()` call, in order. */
   advertisedPerCall: string[][];
   /** `toolChoice` seen on each `chat()` call, in order (sub-agents force it). */
-  toolChoicePerCall: Array<'auto' | 'required' | undefined>;
+  toolChoicePerCall: Array<ChatToolChoice | undefined>;
+  /** `temperature` seen on each `chat()` call, in order. */
+  temperaturePerCall: Array<number | undefined>;
 }
 
 const scriptedProvider = (responses: ChatMessage[]): ScriptedProvider => {
   const queue = [...responses];
   const advertisedPerCall: string[][] = [];
-  const toolChoicePerCall: Array<'auto' | 'required' | undefined> = [];
+  const toolChoicePerCall: Array<ChatToolChoice | undefined> = [];
+  const temperaturePerCall: Array<number | undefined> = [];
   return {
     advertisedPerCall,
     toolChoicePerCall,
+    temperaturePerCall,
     chat: async (
       _history: ChatMessage[],
       _userMessage: string,
@@ -50,6 +55,7 @@ const scriptedProvider = (responses: ChatMessage[]): ScriptedProvider => {
     ): Promise<ChatMessage> => {
       advertisedPerCall.push((options?.tools ?? []).map((t) => t.name));
       toolChoicePerCall.push(options?.toolChoice);
+      temperaturePerCall.push(options?.temperature);
       // Once the script is exhausted, end the turn with a plain text reply.
       return queue.shift() ?? { role: 'assistant', content: 'done' };
     },
@@ -723,3 +729,109 @@ subagent(
 );
 
 subagent.run();
+
+// ---------------------------------------------------------------------------
+// per-agent / per-state temperature & tool-call mode (GENC-1321)
+//
+// The driver resolves `temperature` and `toolChoice` the same way it resolves
+// `provider`: a static value, or a function of the turn context (which carries
+// the live state for stateful agents). These tests assert both forms reach the
+// provider call, and that the per-turn (function) form re-resolves each call.
+// ---------------------------------------------------------------------------
+
+const settings = createLogicSuite('ChatDriver temperature & toolChoice');
+
+settings('passes a static agent temperature and tool-call mode to the provider', async () => {
+  const provider = scriptedProvider([]);
+  const driver = makeDriver(agent({ name: 'a', temperature: 0.3, toolChoice: 'none' }), provider);
+
+  await driver.sendMessage('hi');
+
+  assert.is(provider.temperaturePerCall[0], 0.3);
+  assert.equal(provider.toolChoicePerCall[0], 'none');
+  // ...and surfaced in the per-turn debug snapshot (the effective values sent).
+  const snap = driver.getTurnSnapshots()[0];
+  assert.is(snap.temperature, 0.3);
+  assert.equal(snap.toolChoice, 'none');
+});
+
+settings('re-resolves the function form per turn (carrying turn context)', async () => {
+  const provider = scriptedProvider([callsTool('tool_a', 't1')]);
+  const config = agent({
+    name: 'b',
+    toolDefinitions: [def('tool_a')],
+    toolHandlers: { tool_a: async () => 'ok' },
+    // turnIndex: 0 on the first LLM call, > 0 on subsequent tool-loop iterations.
+    temperature: (ctx) => (ctx.turnIndex === 0 ? 0.1 : 0.9),
+    toolChoice: (ctx) => (ctx.turnIndex === 0 ? { tool: 'tool_a' } : 'auto'),
+  });
+
+  await makeDriver(config, provider).sendMessage('go');
+
+  // First call forces the named tool at a low temperature...
+  assert.is(provider.temperaturePerCall[0], 0.1);
+  assert.equal(provider.toolChoicePerCall[0], { tool: 'tool_a' });
+  // ...the follow-up call (after the tool result) sees the other branch.
+  assert.is(provider.temperaturePerCall[1], 0.9);
+  assert.equal(provider.toolChoicePerCall[1], 'auto');
+});
+
+settings(
+  'leaves temperature and toolChoice unset when the agent does not configure them',
+  async () => {
+    const provider = scriptedProvider([]);
+
+    await makeDriver(agent({ name: 'c' }), provider).sendMessage('hi');
+
+    assert.is(provider.temperaturePerCall[0], undefined);
+    assert.is(provider.toolChoicePerCall[0], undefined);
+  },
+);
+
+settings.run();
+
+// ---------------------------------------------------------------------------
+// empty-response diagnostics (GENC-1321)
+//
+// The transport surfaces a provider diagnostic (Gemini: finishReason,
+// thoughtsTokens, parts, blockReason) on the message; the driver must fold it
+// into the empty-response meta events so the debug-log timeline shows *why* a
+// turn came back blank — not just that it did.
+// ---------------------------------------------------------------------------
+
+const emptyDiag = createLogicSuite('ChatDriver empty-response diagnostics');
+
+emptyDiag('folds the provider responseMeta into the empty-response meta events', async () => {
+  clearMetaEventRegistry();
+  const provider: AIProvider = {
+    chat: async (): Promise<ChatMessage> => ({
+      role: 'assistant',
+      content: '',
+      responseMeta: {
+        finishReason: 'STOP',
+        thoughtsTokens: 999,
+        parts: { functionCall: 0, thought: 0, text: 0 },
+      },
+    }),
+  };
+  const sessionKey = 'empty-diag';
+
+  await makeDriver(agent({ name: 'Static' }), provider, sessionKey).sendMessage('go');
+
+  // Both the in-turn retries and the final bail carry the diagnostic.
+  const retry = getMetaEvents(sessionKey).find(
+    (e) => e.type === 'turn.retry' && e.detail?.reason === 'empty-response',
+  );
+  assert.ok(retry, 'an empty-response turn.retry should be recorded');
+  assert.is(retry!.detail?.finishReason, 'STOP');
+  assert.is(retry!.detail?.thoughtsTokens, 999);
+
+  const err = getMetaEvents(sessionKey).find(
+    (e) => e.type === 'turn.error' && e.detail?.reason === 'empty-response',
+  );
+  assert.ok(err, 'an empty-response turn.error should be recorded after retries');
+  assert.is(err!.detail?.finishReason, 'STOP');
+  assert.is(err!.detail?.thoughtsTokens, 999);
+});
+
+emptyDiag.run();

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

@@ -6,6 +6,7 @@ import type {
   ChatMessage,
   ChatRequestOptions,
   ChatToolCall,
+  ChatToolChoice,
   ChatToolDefinition,
   ChatToolHandlers,
   InteractionRequestOptions,
@@ -19,6 +20,8 @@ import type {
   ProviderInput,
   SystemPromptContext,
   SystemPromptInput,
+  TemperatureInput,
+  ToolChoiceInput,
   ToolDefinitionsInput,
   ToolHandlersInput,
 } from '../../config/config';
@@ -98,6 +101,18 @@ export interface TurnSnapshot {
   systemPrompt?: string;
   /** Tool names sent to the LLM, in order — definitions are static per name so names alone suffice. */
   toolNames: string[];
+  /**
+   * Normalized `0`–`1` sampling temperature in effect for this call, if the
+   * agent (or its current state) configured one. Undefined → provider/model
+   * default. Mirrors the value resolved from `BaseAgentConfig.temperature`.
+   */
+  temperature?: number;
+  /**
+   * Tool-call mode actually sent to the provider this call — the effective
+   * value, including the sub-agent `'required'` default. Undefined → `'auto'`.
+   * Mirrors the value resolved from `BaseAgentConfig.toolChoice`.
+   */
+  toolChoice?: ChatToolChoice;
   /**
    * Per-turn display label resolved from the agent's `displayName`, e.g.
    * "Guided Booking (Counterparties)". `agentName` stays as the canonical
@@ -300,6 +315,17 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * `undefined` means "use the registry default".
    */
   private activeProviderInput?: ProviderInput;
+  /**
+   * Active agent's temperature selector (static number or per-turn resolver),
+   * normalized to `0`–`1`. `undefined` means "use the provider/model default".
+   */
+  private activeTemperatureInput?: TemperatureInput;
+  /**
+   * Active agent's tool-call mode selector (static value or per-turn resolver).
+   * `undefined` falls back to the per-turn default (sub-agents force a tool
+   * call; top-level turns are `'auto'`).
+   */
+  private activeToolChoiceInput?: ToolChoiceInput;
   /**
    * Caches validated provider lookups per name within the current agent. Cleared
    * by `applyAgent` so each new agent's static/function-resolved names are
@@ -440,6 +466,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.debugSnapshotter = config.getDebugSnapshot;
     this.subAgentsMap = new Map((config.subAgents ?? []).map((s) => [s.name, s]));
     this.activeProviderInput = config.provider;
+    this.activeTemperatureInput = config.temperature;
+    this.activeToolChoiceInput = config.toolChoice;
     this.resolvedProviderCache.clear();
     this.lastResolvedProviderName = undefined;
     // Static validation: resolve the name now so unknown-provider and missing-
@@ -513,6 +541,21 @@ export class ChatDriver extends EventTarget implements AiDriver {
     return provider;
   }
 
+  /**
+   * 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`,
+   * `temperature`, and `toolChoice`. Returns undefined when the input is unset.
+   */
+  private async resolveTurnInput<T>(
+    input: T | ((ctx: SystemPromptContext) => T | Promise<T>) | undefined,
+    ctx: SystemPromptContext,
+  ): Promise<T | undefined> {
+    if (input === undefined) return undefined;
+    return typeof input === 'function'
+      ? (input as (ctx: SystemPromptContext) => T | Promise<T>)(ctx)
+      : input;
+  }
+
   /**
    * Returns the early-stop result set by `completeSubAgent`, if any.
    * Called by a parent `ChatDriver` after running this instance as a sub-agent.
@@ -615,7 +658,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * before each LLM call — that's the latest point where the prompt, tool
    * surface, and agent state line up with what the model is about to see.
    */
-  private recordTurnSnapshot(resolvedSystemPrompt: string | undefined): void {
+  private recordTurnSnapshot(
+    resolvedSystemPrompt: string | undefined,
+    temperature: number | undefined,
+    toolChoice: ChatToolChoice | undefined,
+  ): void {
     let agentSnapshot: unknown;
     if (this.debugSnapshotter) {
       try {
@@ -636,6 +683,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
       agentLabel: this.activeAgentLabel,
       systemPrompt: resolvedSystemPrompt,
       toolNames: this.toolDefinitions.map((t) => t.name),
+      temperature,
+      toolChoice,
       agentSnapshot,
     });
     if (this.turnSnapshots.length > this.maxTurnSnapshots) {
@@ -1463,7 +1512,22 @@ export class ChatDriver extends EventTarget implements AiDriver {
             ? `${baseSystemPrompt ?? ''}\n\nIMPORTANT: You must respond to the user's message. Call the appropriate tool or provide a text response — do not return an empty response.`
             : baseSystemPrompt;
 
-      this.recordTurnSnapshot(systemPrompt);
+      // Resolve the per-turn temperature and tool-call mode the same way the
+      // provider is resolved — static value or a function of the turn context
+      // (which carries the live state for stateful agents). Resolved before the
+      // snapshot so the debug log records the exact request config the model saw.
+      // oxlint-disable-next-line no-await-in-loop
+      const [resolvedTemperature, resolvedToolChoice] = await Promise.all([
+        this.resolveTurnInput<number>(this.activeTemperatureInput, promptCtx),
+        this.resolveTurnInput<ChatToolChoice>(this.activeToolChoiceInput, promptCtx),
+      ]);
+      // An agent/state-configured tool-call mode wins. Otherwise sub-agents must
+      // finish by calling a tool (their completion tool) so the turn can't end
+      // on a free-text answer; top-level agents stay 'auto'. (Transports no-op a
+      // force when no tools are advertised.)
+      const effectiveToolChoice = resolvedToolChoice ?? (this.isSubAgent ? 'required' : undefined);
+
+      this.recordTurnSnapshot(systemPrompt, resolvedTemperature, effectiveToolChoice);
 
       // Capture the pending user input, then clear the slots BEFORE the chat
       // call. `sendMessage` already appended the user message to `this.history`,
@@ -1484,11 +1548,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
         // Per-turn signal: aborts on user cancel, and (via beginTurn's chain)
         // on driver dispose. Cancels the in-flight request either way.
         signal: this.turnController.signal,
-        // Sub-agents must finish by calling a tool (their completion tool), never
-        // by emitting a free-text turn — force tool use so the provider can't
-        // return a bare text answer. Top-level agents stay on the default 'auto'.
-        // (Transports no-op the force when no tools are advertised.)
-        toolChoice: this.isSubAgent ? 'required' : undefined,
+        toolChoice: effectiveToolChoice,
+        // Agent/state-configured sampling temperature (normalized 0–1); each
+        // transport translates it to its native range. Undefined → provider default.
+        temperature: resolvedTemperature,
       };
 
       // Resolve the active provider for this turn. Static names were validated
@@ -1594,6 +1657,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
             provider: this.lastResolvedProviderName,
             attempt: emptyResponseAttempts,
             maxAttempts: MAX_EMPTY_RESPONSE_RETRIES,
+            // Provider diagnostic (Gemini: finishReason, thoughtsTokens, parts,
+            // blockReason) so the timeline shows *why* the turn came back blank —
+            // e.g. a high thoughtsTokens with a 'STOP' finish is "thought, then
+            // stopped without answering".
+            ...response.responseMeta,
           });
           iterations -= 1;
           continue;
@@ -1604,6 +1672,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
           provider: this.lastResolvedProviderName,
           attempts: emptyResponseAttempts,
           isSubAgent: this.isSubAgent,
+          ...response.responseMeta,
         });
         if (this.isSubAgent) {
           this.failSubAgent('empty_response');

package/src/config/config.ts

@@ -1,11 +1,12 @@
 import type {
   ChatInputDuringExecutionMode,
   ChatMessage,
+  ChatToolChoice,
   ChatToolDefinition,
   ChatToolHandlers,
 } from '@genesislcap/foundation-ai';
 
-export type { ChatInputDuringExecutionMode };
+export type { ChatInputDuringExecutionMode, ChatToolChoice };
 
 /**
  * Context passed to `onActivate` / `onDeactivate` lifecycle hooks on an agent.
@@ -89,6 +90,32 @@ export type ToolHandlersInput =
  */
 export type ProviderInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
 
+/**
+ * Sampling temperature for an agent, normalized to `0`–`1` (`0` = deterministic,
+ * `1` = the most random the active provider allows). Either a static number
+ * (resolved once) or a function resolved each tool-loop iteration — pick the
+ * function form to vary it by current state (e.g. a lower temperature for a
+ * precise extraction step, higher for brainstorming). Each transport translates
+ * the normalized value into its own native range. Omit to use the
+ * provider/model default. See `ChatRequestOptions.temperature`.
+ *
+ * @beta
+ */
+export type TemperatureInput = number | ((ctx: SystemPromptContext) => number | Promise<number>);
+
+/**
+ * Tool-call mode for an agent. Either a static `ChatToolChoice` (resolved
+ * once) or a function resolved each tool-loop iteration — pick the function form
+ * to vary it by current state (e.g. force a classifier tool in an intake step,
+ * then `'auto'` everywhere multi-step work happens). Omit to use the default
+ * (`'auto'`, except sub-agent turns which force `'required'`).
+ *
+ * @beta
+ */
+export type ToolChoiceInput =
+  | ChatToolChoice
+  | ((ctx: SystemPromptContext) => ChatToolChoice | Promise<ChatToolChoice>);
+
 /**
  * Opts an agent in to manual selection from the assistant's agent picker.
  *
@@ -170,6 +197,27 @@ interface BaseAgentConfig {
    * @beta
    */
   provider?: ProviderInput;
+  /**
+   * Sampling temperature for this agent, normalized to `0`–`1`. Either a static
+   * number or a function resolved each tool-loop iteration — pick the function
+   * form to vary it by current state. Omit to use the provider/model default.
+   * Resolved and applied the same way as {@link BaseAgentConfig.provider}.
+   * See {@link TemperatureInput}.
+   *
+   * @beta
+   */
+  temperature?: TemperatureInput;
+  /**
+   * Tool-call mode for this agent — whether the model may, must, or must not
+   * call a tool this turn (and optionally which one). Either a static value or
+   * a function resolved each tool-loop iteration — pick the function form to
+   * vary it by current state (e.g. force a single tool at a known juncture).
+   * Omit to use the default (`'auto'`, except sub-agent turns which force
+   * `'required'`). See {@link ToolChoiceInput}.
+   *
+   * @beta
+   */
+  toolChoice?: ToolChoiceInput;
   /**
    * Optional primer history prepended to every call (not visible to the user).
    * Used to establish agent identity and behavioural rules.

package/src/config/define-stateful-agent.ts

@@ -1,4 +1,9 @@
-import type { ChatMessage, ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
+import type {
+  ChatMessage,
+  ChatToolChoice,
+  ChatToolDefinition,
+  ChatToolHandlers,
+} from '@genesislcap/foundation-ai';
 import { TOOL_FOLD_SYMBOL } from '../utils/tool-fold';
 import type {
   AgentConfig,
@@ -8,6 +13,8 @@ import type {
   ProviderInput,
   SystemPromptContext,
   SystemPromptInput,
+  TemperatureInput,
+  ToolChoiceInput,
   ToolDefinitionsInput,
   ToolHandlersInput,
 } from './config';
@@ -127,6 +134,25 @@ export interface StatefulAgentInit<S> {
    */
   provider?: string | ((ctx: StatefulAgentContext<S>) => string | Promise<string>);
 
+  /**
+   * Sampling temperature, normalized to `0`–`1`. Either a static number or a
+   * function resolved each tool-loop iteration with the current `state` — pick
+   * the function form to vary it per machine state (e.g. low for a precise
+   * extraction step, higher for free-form drafting). Omit for the default.
+   */
+  temperature?: number | ((ctx: StatefulAgentContext<S>) => number | Promise<number>);
+
+  /**
+   * Tool-call mode. Either a static `ChatToolChoice` or a function
+   * resolved each tool-loop iteration with the current `state` — pick the
+   * function form to force a specific tool in one state (e.g. a classifier in
+   * intake) and leave `'auto'` in states where multi-step work happens. Omit
+   * for the default.
+   */
+  toolChoice?:
+    | ChatToolChoice
+    | ((ctx: StatefulAgentContext<S>) => ChatToolChoice | Promise<ChatToolChoice>);
+
   /**
    * Optional getter for the debug-log snapshot. Defaults to auto-snapshotting
    * any property on `state` that looks like a foundation-state-machine
@@ -273,6 +299,35 @@ export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig
         }
       : opts.provider;
 
+  // `temperature` and `toolChoice` thread `state` in exactly like `provider`;
+  // static values pass through unchanged.
+  const wrappedTemperature: TemperatureInput | undefined =
+    typeof opts.temperature === 'function'
+      ? async (ctx: SystemPromptContext) => {
+          if (!state) {
+            throw new Error(`Stateful agent "${opts.name}" temperature called before init`);
+          }
+          return (opts.temperature as (ctx: StatefulAgentContext<S>) => number | Promise<number>)({
+            ...ctx,
+            state,
+          });
+        }
+      : opts.temperature;
+
+  const wrappedToolChoice: ToolChoiceInput | undefined =
+    typeof opts.toolChoice === 'function'
+      ? async (ctx: SystemPromptContext) => {
+          if (!state) {
+            throw new Error(`Stateful agent "${opts.name}" toolChoice called before init`);
+          }
+          return (
+            opts.toolChoice as (
+              ctx: StatefulAgentContext<S>,
+            ) => ChatToolChoice | Promise<ChatToolChoice>
+          )({ ...ctx, state });
+        }
+      : opts.toolChoice;
+
   const base = {
     name: opts.name,
     displayName: wrappedDisplayName,
@@ -283,6 +338,8 @@ export function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig
     toolDefinitions: wrappedTools,
     toolHandlers: wrappedHandlers,
     provider: wrappedProvider,
+    temperature: wrappedTemperature,
+    toolChoice: wrappedToolChoice,
 
     onActivate: async (ctx: AgentLifecycleContext) => {
       state = await opts.init(ctx);

package/src/main/main.ts

@@ -116,9 +116,11 @@ avoidTreeShaking(
  *  - `toolHandlers` (functions),
  *  - `onActivate` / `onDeactivate` (lifecycle hooks, functions),
  *  - `getDebugSnapshot` (function),
- *  - function-form `systemPrompt` / `toolDefinitions` / `displayName` / `provider`
+ *  - function-form `systemPrompt` / `toolDefinitions` / `displayName` / `provider` /
+ *    `temperature` / `toolChoice`
  *    (downgraded to `undefined` in the snapshot — the live config on the driver
  *    is still the source of truth; the slice only stores a serializable projection).
+ *    Static forms (string / number / plain-object `toolChoice`) pass through.
  */
 function stripHandlers(agent: AgentConfig): Omit<AgentConfig, 'toolHandlers'> {
   const {
@@ -131,6 +133,8 @@ function stripHandlers(agent: AgentConfig): Omit<AgentConfig, 'toolHandlers'> {
     toolDefinitions,
     displayName,
     provider,
+    temperature,
+    toolChoice,
     ...rest
   } = agent;
   const stripped = {
@@ -139,6 +143,8 @@ function stripHandlers(agent: AgentConfig): Omit<AgentConfig, 'toolHandlers'> {
     toolDefinitions: typeof toolDefinitions === 'function' ? undefined : toolDefinitions,
     displayName: typeof displayName === 'function' ? undefined : displayName,
     provider: typeof provider === 'function' ? undefined : provider,
+    temperature: typeof temperature === 'function' ? undefined : temperature,
+    toolChoice: typeof toolChoice === 'function' ? undefined : toolChoice,
   };
   return subAgents?.length
     ? { ...stripped, subAgents: subAgents.map(stripHandlers) as AgentConfig[] }

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

@@ -247,7 +247,7 @@ export const DEBUG_LOG_README: readonly string[] = [
   "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, retries, 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. 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), 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, plus reason-specific diagnostics: attempts, finishMessage, 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, 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), 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.',
+  '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, 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, 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, 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), 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.',
 ];