@genesislcap/ai-assistant 14.494.0 → 14.496.0

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

@@ -5,6 +5,7 @@ import type {
   CachePolicy,
   ChatAttachment,
   ChatDriverResult,
+  ChatFallback,
   ChatMessage,
   ChatRequestOptions,
   ChatToolCall,
@@ -17,17 +18,19 @@ import type {
   InteractionResult,
   SubAgentFailureReason,
   SubAgentRequestOptions,
+  TurnFailureReason,
 } from '@genesislcap/foundation-ai';
 import {
   isObservableAIProviderRegistry,
   MalformedFunctionCallError,
   ResponseTruncatedError,
 } from '@genesislcap/foundation-ai';
-import { agenticActivityBus } from '../../channel/ai-activity-bus';
+import { type ActivityBus, NOOP_ACTIVITY_BUS } from '../../channel/ai-activity-bus';
 import type {
   AgentConfig,
   CachePolicyInput,
   ProviderInput,
+  ResponseSchemaInput,
   SystemPromptContext,
   SystemPromptInput,
   TailContextInput,
@@ -191,6 +194,39 @@ interface FoldStackFrame {
   previousHandlers: ChatToolHandlers;
 }
 
+/**
+ * Construction-time configuration for {@link ChatDriver}. Everything except the provider
+ * registry is optional — most fields are also settable per-agent via `applyAgent`, so a
+ * bare `new ChatDriver(registry)` is valid. Mirrors the `(registry, options)` shape of
+ * `OrchestratingDriver`.
+ *
+ * @beta
+ */
+export interface ChatDriverConfig {
+  /** Initial tool handlers (static map or per-turn factory). Default `{}`. */
+  toolHandlers?: ToolHandlersInput;
+  /** Initial tool definitions (static array or per-turn factory). Default `[]`. */
+  toolDefinitions?: ToolDefinitionsInput;
+  /** Initial system prompt (string or per-turn resolver). */
+  systemPrompt?: SystemPromptInput;
+  /** Primer history prepended to the conversation. */
+  primerHistory?: ChatMessage[];
+  /** Hard cap on tool-loop iterations. Default `50`. */
+  maxToolIterations?: number;
+  /** Hard cap on fold operations. Default `5`. */
+  maxFoldOperations?: number;
+  /** Ring-buffer size for per-turn snapshots. Default `400`. */
+  maxTurnSnapshots?: number;
+  /** Session identity used to file meta events onto the shared debug-log timeline. */
+  sessionKey?: string;
+  /**
+   * Activity bus for lifecycle/halo/tool-loop events. Injected by the browser host
+   * (the shared cross-tab singleton); omitted off-browser (Node, tests, headless), where
+   * it defaults to {@link NOOP_ACTIVITY_BUS} so no `BroadcastChannel` is ever opened.
+   */
+  activityBus?: ActivityBus;
+}
+
 /**
  * Plain TS class that drives a multi-turn chat conversation, including the tool-call loop.
  * Owned by `FoundationAiAssistant` — created in `connectedCallback`, torn down in `disconnectedCallback`.
@@ -453,6 +489,16 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * the resolved string in a `<system-reminder>` marker and injects it at the message tail.
    */
   private activeTailContextInput?: TailContextInput;
+  /**
+   * Active agent's structured-output schema selector (static value or per-turn resolver).
+   * When it resolves to a schema, the model's final answer is constrained to it this turn.
+   */
+  private activeResponseSchemaInput?: ResponseSchemaInput;
+  /**
+   * Active agent's refusal-fallback chain (static). Passed through to the provider so a refused
+   * turn (e.g. Fable 5) is re-run on the next model server-side.
+   */
+  private activeFallbacks?: ChatFallback[];
   /**
    * Active agent's unresolved-tool hook, captured from `applyAgent`. Consulted
    * only when a tool call cannot be dispatched (a stale or hallucinated name);
@@ -498,19 +544,32 @@ export class ChatDriver extends EventTarget implements AiDriver {
    */
   private unsubscribeRegistry?: () => void;
 
+  /** Hard cap on tool-loop iterations. */
+  private readonly maxToolIterations: number;
+  /** Session identity used to file meta events onto the shared debug-log timeline. */
+  private readonly sessionKey: string;
+  /** Injected activity bus; defaults to a no-op off-browser (Node/tests/headless). */
+  private readonly activityBus: ActivityBus;
+
   constructor(
     private readonly providerRegistry: AIProviderRegistry,
-    toolHandlers: ToolHandlersInput = {},
-    toolDefinitions: ToolDefinitionsInput = [],
-    systemPrompt?: SystemPromptInput,
-    primerHistory?: ChatMessage[],
-    private readonly maxToolIterations: number = DEFAULT_MAX_TOOL_ITERATIONS,
-    maxFoldOperations: number = DEFAULT_MAX_FOLD_OPERATIONS,
-    maxTurnSnapshots: number = DEFAULT_MAX_TURN_SNAPSHOTS,
-    /** Session identity used to file meta events onto the shared debug-log timeline. */
-    private readonly sessionKey: string = '',
+    config: ChatDriverConfig = {},
   ) {
     super();
+    const {
+      toolHandlers = {},
+      toolDefinitions = [],
+      systemPrompt,
+      primerHistory,
+      maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS,
+      maxFoldOperations = DEFAULT_MAX_FOLD_OPERATIONS,
+      maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS,
+      sessionKey = '',
+      activityBus = NOOP_ACTIVITY_BUS,
+    } = config;
+    this.maxToolIterations = maxToolIterations;
+    this.sessionKey = sessionKey;
+    this.activityBus = activityBus;
     if (typeof toolHandlers === 'function') {
       this.toolHandlersFactory = toolHandlers;
       this.toolHandlers = {};
@@ -631,6 +690,35 @@ export class ChatDriver extends EventTarget implements AiDriver {
     return { reason: 'done' };
   }
 
+  /**
+   * Build the `done` loop result, carrying the typed failure reason when the turn
+   * bailed (PTC-0). The discriminant stays `'done'` either way — the same value a
+   * clean turn returns — so consumers matching on `reason === 'done'` are unchanged;
+   * `failureReason` is simply present on a failure and absent on success. Omitted
+   * (rather than set to `undefined`) so a happy-path result stays byte-identical to
+   * the historical `{ reason: 'done' }`.
+   */
+  private turnDone(failureReason?: TurnFailureReason): ChatDriverResult {
+    return failureReason ? { reason: 'done', failureReason } : { reason: 'done' };
+  }
+
+  /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
+  private static failureReasonOf(result: ChatDriverResult): TurnFailureReason | undefined {
+    return result.reason === 'done' ? result.failureReason : undefined;
+  }
+
+  /**
+   * Build the `tool-loop-end` event detail for a turn's result. A failure carries a
+   * `{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,
+   * kept byte-identical so subscribers see exactly what they always have.
+   */
+  private static loopEndDetail(
+    result: ChatDriverResult,
+  ): { failureReason: TurnFailureReason } | undefined {
+    const failureReason = ChatDriver.failureReasonOf(result);
+    return failureReason ? { failureReason } : undefined;
+  }
+
   /**
    * Swap in a new agent's configuration. Called by OrchestratingDriver before
    * each specialist turn so the shared driver runs with the right tools and prompt.
@@ -675,6 +763,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.activeToolChoiceInput = config.toolChoice;
     this.activeCachePolicyInput = config.cachePolicy;
     this.activeTailContextInput = config.tailContext;
+    this.activeResponseSchemaInput = config.responseSchema;
+    this.activeFallbacks = config.fallbacks;
     this.activeOnUnresolvedTool = config.onUnresolvedTool;
     this.resolvedProviderCache.clear();
     this.lastResolvedProviderName = undefined;
@@ -1267,7 +1357,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // "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);
+      this.activityBus.publish('interaction-requested', undefined);
       if (chatInputDuringExecution) {
         this.dispatchEvent(
           new CustomEvent('interaction-start', {
@@ -1342,7 +1432,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // 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);
+      this.activityBus.publish('interaction-resolved', undefined);
       interaction.resolve(result);
       this.pendingInteractions.delete(interactionId);
       // Tear down the live context on RESOLVE (not on element unmount) — this closes
@@ -1410,10 +1500,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
       phase: 'sendMessage',
       agent: this.activeAgentName,
     });
-    agenticActivityBus.publish('tool-loop-start', undefined);
+    this.activityBus.publish('tool-loop-start', undefined);
 
+    // Captured so the `finally` can carry the turn's outcome onto `tool-loop-end`.
+    let result: ChatDriverResult = { reason: 'done' };
     try {
-      return await this.runToolLoop(userInput, attachments);
+      result = await this.runToolLoop(userInput, attachments);
+      return result;
     } catch (e) {
       logger.error('ChatDriver error:', e);
       recordTurnError(this.sessionKey, 'exception', {
@@ -1427,7 +1520,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
         role: 'assistant',
         content: 'Sorry, something went wrong on my end. Please try again in a moment.',
       });
-      return { reason: 'done' };
+      result = this.turnDone('exception');
+      return result;
     } finally {
       recordMetaEvent(this.sessionKey, 'turn.end', {
         phase: 'sendMessage',
@@ -1436,7 +1530,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       });
       this.busy = false;
       this.endTurn();
-      agenticActivityBus.publish('tool-loop-end', undefined);
+      this.activityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
     }
   }
 
@@ -1602,17 +1696,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
     // be harvested into THIS session on completion and then discarded.
     const invocationId = crypto.randomUUID();
     const childSessionKey = `${this.sessionKey}::sub:${invocationId}`;
-    const child = new ChatDriver(
-      this.providerRegistry,
-      {},
-      [],
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      childSessionKey,
-    );
+    const child = new ChatDriver(this.providerRegistry, {
+      sessionKey: childSessionKey,
+      // Inherit the parent's bus so the sub-agent's tool-loop events still surface
+      // (off-browser this is the shared no-op).
+      activityBus: this.activityBus,
+    });
     // Mark before the first turn so the child forces tool use and reports a
     // typed failure (rather than user-facing text) if it never completes.
     child.markAsSubAgent();
@@ -1781,9 +1870,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
       phase: 'continueFromHistory',
       agent: this.activeAgentName,
     });
-    agenticActivityBus.publish('tool-loop-start', undefined);
+    this.activityBus.publish('tool-loop-start', undefined);
+    // Captured so the `finally` can carry the turn's outcome onto `tool-loop-end`.
+    let result: ChatDriverResult = { reason: 'done' };
     try {
-      return await this.runToolLoop('', undefined, transientPrimer);
+      result = await this.runToolLoop('', undefined, transientPrimer);
+      return result;
     } catch (e) {
       logger.error('ChatDriver error:', e);
       recordTurnError(this.sessionKey, 'exception', {
@@ -1797,7 +1889,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
         role: 'assistant',
         content: 'Sorry, something went wrong on my end. Please try again in a moment.',
       });
-      return { reason: 'done' };
+      result = this.turnDone('exception');
+      return result;
     } finally {
       recordMetaEvent(this.sessionKey, 'turn.end', {
         phase: 'continueFromHistory',
@@ -1806,7 +1899,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       });
       this.busy = false;
       this.endTurn();
-      agenticActivityBus.publish('tool-loop-end', undefined);
+      this.activityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
     }
   }
 
@@ -2140,13 +2233,20 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // 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.
-      const [resolvedTemperature, resolvedToolChoice, resolvedCachePolicy, resolvedTailContext] =
+      const [
+        resolvedTemperature,
+        resolvedToolChoice,
+        resolvedCachePolicy,
+        resolvedTailContext,
+        resolvedResponseSchema,
+      ] =
         // oxlint-disable-next-line no-await-in-loop
         await Promise.all([
           this.resolveTurnInput<number>(this.activeTemperatureInput, promptCtx),
           this.resolveTurnInput<ChatToolChoice>(this.activeToolChoiceInput, promptCtx),
           this.resolveTurnInput<CachePolicy>(this.activeCachePolicyInput, promptCtx),
           this.resolveTurnInput<string>(this.activeTailContextInput, promptCtx),
+          this.resolveTurnInput<object | undefined>(this.activeResponseSchemaInput, promptCtx),
         ]);
       // The system prompt is always just the agent's resolved prompt — byte-stable, so it can be
       // cached. The framework's volatile additions (fold suffix, retry nudge) and the agent's tail
@@ -2197,6 +2297,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
         cachePolicy: resolvedCachePolicy,
         // Framed volatile context injected at the message tail (never stored). Undefined → none.
         tailContext,
+        // Structured-output schema for this turn (agent/state-resolved). When set, the transport
+        // constrains the final answer to it natively where the model supports it. Undefined → free text.
+        responseSchema: resolvedResponseSchema,
+        // Refusal-fallback chain (e.g. Fable 5 → Opus 4.8). Passed to the provider; applied
+        // server-side where supported. Undefined → no fallback.
+        fallbacks: this.activeFallbacks,
       };
 
       // Resolve the active provider for this turn. Static names were validated
@@ -2244,7 +2350,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 'While working on your request, I repeatedly called my tools incorrectly. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
             });
           }
-          return { reason: 'done' };
+          return this.turnDone('malformed-function-call');
         }
         // The response was truncated at the provider's output-token cap while it
         // still carried a tool call — its arguments are incomplete and unusable.
@@ -2273,7 +2379,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 'My response was cut off because a single step reached the model output limit. This usually means one step tried to produce too much at once — try breaking your request into smaller steps.',
             });
           }
-          return { reason: 'done' };
+          return this.turnDone('response-truncated');
         }
         // A request timeout from the transport (tagged `TimeoutError`) is not a
         // bug on our end — surface it distinctly instead of letting it fall
@@ -2299,7 +2405,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 'The request timed out. You can ask me to try again, or break this into a smaller step.',
             });
           }
-          return { reason: 'done' };
+          // Recorded as `exception` above (there is no separate `timeout` member of
+          // TurnFailureReason for the main turn); surface the same reason here.
+          return this.turnDone('exception');
         }
         // The request was aborted: either a user cancel (turnController) or a
         // driver dispose (lifecycleController, chained into the turn). A user
@@ -2380,7 +2488,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
               'While working on your request, I repeatedly generated a blank response. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
           });
         }
-        return { reason: 'done' };
+        return this.turnDone('empty-response');
       } else {
         // Split one model response into separate, individually-toggleable messages so each has its
         // own visibility toggle and debug-log category:
@@ -2744,7 +2852,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
               "I'm sorry, I repeatedly tried to use tools that aren't available to me, so I couldn't complete that. If a 'Download agent log' option appears in the Settings (cog) menu, you can download the log and share it with whoever set up this assistant to help fix the issue.",
           });
         }
-        return { reason: 'done' };
+        return this.turnDone('unknown-tool-limit');
       }
 
       const firstContinuation = systemCalls[0];
@@ -2759,10 +2867,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // Sub-agent early exit — checked here so the exit point mirrors the
       // system-call pattern above. Set by completeSubAgent() in a tool handler.
       if (this.subAgentCompletion) {
-        return { reason: 'done' };
+        return this.turnDone();
       }
     }
 
+    // The loop fell through: either it hit the iteration cap (a failure) or it
+    // broke on a clean final answer (success). Only the former carries a reason.
+    let failureReason: TurnFailureReason | undefined;
     if (iterations >= this.maxToolIterations) {
       logger.warn('ChatDriver: reached max tool iterations, stopping');
       recordTurnError(this.sessionKey, 'max-iterations', {
@@ -2781,9 +2892,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
             "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off.",
         });
       }
+      failureReason = 'max-iterations';
     }
 
-    return { reason: 'done' };
+    return this.turnDone(failureReason);
   }
 
   private appendToHistory(message: ChatMessage): void {

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

@@ -5,6 +5,7 @@ import type {
   ChatMessage,
   ChatRequestOptions,
 } from '@genesislcap/foundation-ai';
+import type { ActivityBus } from '../../channel/ai-activity-bus';
 import type {
   AgentConfig,
   FallbackAgentConfig,
@@ -137,6 +138,8 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
       maxToolIterations?: number;
       maxFoldOperations?: number;
       maxTurnSnapshots?: number;
+      /** Activity bus passed through to the inner ChatDriver (browser host injects the singleton). */
+      activityBus?: ActivityBus;
     } = {},
   ) {
     super();
@@ -166,17 +169,13 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
       ? { ...rawFallback, systemPrompt: buildFallbackSystemPrompt(rawFallback, this.specialists) }
       : undefined;
 
-    this.chatDriver = new ChatDriver(
-      providerRegistry,
-      {},
-      [],
-      undefined,
-      undefined,
-      options.maxToolIterations,
-      options.maxFoldOperations,
-      options.maxTurnSnapshots,
-      this.sessionKey,
-    );
+    this.chatDriver = new ChatDriver(providerRegistry, {
+      maxToolIterations: options.maxToolIterations,
+      maxFoldOperations: options.maxFoldOperations,
+      maxTurnSnapshots: options.maxTurnSnapshots,
+      sessionKey: this.sessionKey,
+      activityBus: options.activityBus,
+    });
 
     // Proxy events from the shared driver
     this.chatDriver.addEventListener('history-updated', (e: Event) => {

package/src/config/config.ts

@@ -1,5 +1,6 @@
 import type {
   CachePolicy,
+  ChatFallback,
   ChatInputDuringExecutionMode,
   ChatMessage,
   ChatToolChoice,
@@ -7,7 +8,7 @@ import type {
   ChatToolHandlers,
 } from '@genesislcap/foundation-ai';
 
-export type { CachePolicy, ChatInputDuringExecutionMode, ChatToolChoice };
+export type { CachePolicy, ChatFallback, ChatInputDuringExecutionMode, ChatToolChoice };
 
 /**
  * Context passed to `onActivate` / `onDeactivate` lifecycle hooks on an agent.
@@ -174,6 +175,25 @@ export type CachePolicyInput =
  */
 export type TailContextInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
 
+/**
+ * Structured-output schema for an agent. When set, the model's final (non-tool) answer is
+ * constrained to this JSON Schema instead of free text. Either a static schema or a function
+ * resolved each tool-loop iteration — return the schema on the turn(s) it should apply and
+ * `undefined` otherwise, so "whole-loop" vs "finalize-turn" enforcement is just what the
+ * resolver returns (e.g. `({ state }) => state.machine.matches('finalizing') ? schema : undefined`).
+ *
+ * Orthogonal to {@link ToolChoiceInput}: an agent can carry both `tools` and a `responseSchema`.
+ * Each provider applies it natively where possible (Anthropic `output_config.format`, Gemini
+ * JSON mode) and degrades gracefully otherwise. The schema is a plain JSON Schema object; keep to
+ * the portable subset providers share (`additionalProperties: false`, explicit `required`, enums,
+ * `anyOf` for nullables — no numeric/string constraints or recursion).
+ *
+ * @beta
+ */
+export type ResponseSchemaInput =
+  | object
+  | ((ctx: SystemPromptContext) => object | undefined | Promise<object | undefined>);
+
 /**
  * Context passed to an agent's `onUnresolvedTool` hook when the model calls a
  * tool the driver cannot dispatch.
@@ -337,6 +357,25 @@ interface BaseAgentConfig {
    * @beta
    */
   tailContext?: TailContextInput;
+  /**
+   * Structured-output schema for this agent. When resolved to a schema on a turn, the model's
+   * final (non-tool) answer is constrained to it instead of free text. Composes with `tools`;
+   * resolved per turn like {@link BaseAgentConfig.cachePolicy}, so returning `undefined` on
+   * working turns and the schema on the finalize turn gives finalize-turn enforcement for free.
+   * See {@link ResponseSchemaInput}.
+   *
+   * @beta
+   */
+  responseSchema?: ResponseSchemaInput;
+  /**
+   * Refusal-fallback chain for this agent (provider-neutral). If the model declines a turn
+   * (`stop_reason: 'refusal'` — e.g. Fable 5 safety classifiers), the provider re-runs it on the
+   * next listed model. Typical use: a Fable 5 agent with `[{ model: 'claude-opus-4-8' }]`. Static
+   * (not per-turn); providers that support it apply it server-side, others ignore it.
+   *
+   * @beta
+   */
+  fallbacks?: ChatFallback[];
   /**
    * Optional hook consulted when the model calls a tool the driver cannot
    * dispatch — either a *stale* tool (advertised earlier this activation but

package/src/index.ts

@@ -16,6 +16,7 @@ export * from './state/persistence';
 export * from './provider/ai-provider-switcher';
 export * from './provider/assistant-app-settings';
 export * from './utils/tool-fold';
+export type { TurnFailureReason } from './state/debug-event-log';
 export type { TimelineMessage } from './utils/flatten-sub-agent-messages';
 export type { CostSessionModelEntry, CostSessionRecord } from './utils/cost-session-history';
 export type { ModelTagAppearance } from '@genesislcap/foundation-ai';

package/src/main/main.ts

@@ -1249,20 +1249,17 @@ export class FoundationAiAssistant extends GenesisElement {
         maxToolIterations: agent.maxToolIterations,
         maxFoldOperations: agent.maxFoldOperations,
         maxTurnSnapshots: agent.maxTurnSnapshots,
+        activityBus: agenticActivityBus,
       });
     }
 
-    return new ChatDriver(
-      this.providerRegistry,
-      {},
-      [],
-      undefined,
-      undefined,
-      agent.maxToolIterations,
-      agent.maxFoldOperations,
-      agent.maxTurnSnapshots,
-      this.getStateKey() ?? '',
-    );
+    return new ChatDriver(this.providerRegistry, {
+      maxToolIterations: agent.maxToolIterations,
+      maxFoldOperations: agent.maxFoldOperations,
+      maxTurnSnapshots: agent.maxTurnSnapshots,
+      sessionKey: this.getStateKey() ?? '',
+      activityBus: agenticActivityBus,
+    });
   }
 
   /**

package/src/main/popout-interaction-gate.test.ts

@@ -1,6 +1,5 @@
 import type { ChatMessage } from '@genesislcap/foundation-ai';
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { agenticActivityBus } from '../channel/ai-activity-bus';
 import { FoundationAiAssistant } from './main';
 
 // Hold a reference so the custom-element registration isn't tree-shaken.
@@ -14,19 +13,15 @@ FoundationAiAssistant;
 // (`main.template.ts`). This suite pins the GATE LOGIC (`hasActivePendingInteraction`)
 // that binding depends on, so a change to when the gate opens/closes is caught.
 //
-// Note: this deliberately does NOT mount the assistant. Mounting runs
-// `connectedCallback`, which activates the `agenticActivityBus` `BroadcastChannel` and
-// leaves the runner's event loop open (the suite hangs on exit). A getter-level test
-// needs no mount and stays fast + reliable. `document.createElement` only upgrades the
-// element (constructor) — it does not connect — so no bus subscription is created;
-// importing the module still opens the module-load channel, so close it after the suite.
+// Note: this deliberately does NOT mount the assistant. Mounting runs `connectedCallback`,
+// which subscribes to `agenticActivityBus` — opening a cross-tab `BroadcastChannel` in a browser
+// env and leaving the runner's event loop open. A getter-level test needs no mount and stays fast
+// + reliable. `document.createElement` only upgrades the element (constructor) — it does not
+// connect — so nothing subscribes, and the bus opens its channel lazily on first use, so none is
+// ever created here (no teardown needed).
 
 const Suite = createLogicSuite('FoundationAiAssistant popout interaction gate');
 
-Suite.after(() => {
-  agenticActivityBus.close();
-});
-
 /** A fresh (unconnected) element with a fake session store wired in. */
 function elementWith(state: string, messages: ChatMessage[]): FoundationAiAssistant {
   const el = document.createElement('foundation-ai-assistant') as FoundationAiAssistant;

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

@@ -24,6 +24,8 @@
  * @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).
@@ -211,25 +213,14 @@ export function recordMetaEvent(
 
 /**
  * Why a turn failed or was retried — stamped as `detail.reason` on `turn.error`
- * and `turn.retry` events. Enumerated so the set stays in sync with the README
- * and call sites can't drift to ad-hoc strings.
- *
- * - `exception`              — an uncaught error escaped the tool loop (catch-all).
- * - `malformed-function-call`— the provider returned an unparseable tool call.
- * - `empty-response`         — the model returned no content and no tool calls.
- * - `unknown-tool-limit`     — the model repeatedly called tools it couldn't dispatch,
- *                              whether hallucinated or stale (real earlier, retired now).
- * - `max-iterations`         — the tool loop hit its iteration cap.
- * - `response-truncated`     — a turn stopped at the provider's output-token cap with an
- *                              incomplete tool call; deterministic, so it bails without retry.
+ * 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 =
-  | 'exception'
-  | 'malformed-function-call'
-  | 'empty-response'
-  | 'unknown-tool-limit'
-  | 'max-iterations'
-  | 'response-truncated';
+export type { TurnFailureReason };
 
 /**
  * Record a turn-ending failure (`turn.error`, importance `high`). The `reason`