@genesislcap/ai-assistant 14.495.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,
@@ -24,11 +25,12 @@ import {
   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,
@@ -192,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`.
@@ -454,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);
@@ -499,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 = {};
@@ -705,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;
@@ -1297,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', {
@@ -1372,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
@@ -1440,7 +1500,7 @@ 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' };
@@ -1470,7 +1530,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       });
       this.busy = false;
       this.endTurn();
-      agenticActivityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
+      this.activityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
     }
   }
 
@@ -1636,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();
@@ -1815,7 +1870,7 @@ 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 {
@@ -1844,7 +1899,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       });
       this.busy = false;
       this.endTurn();
-      agenticActivityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
+      this.activityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
     }
   }
 
@@ -2178,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
@@ -2235,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

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/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;