@genesislcap/ai-assistant 14.494.0 → 14.496.0

package/dist/ai-assistant.d.ts

@@ -6,6 +6,7 @@ import type { CachePolicy } from '@genesislcap/foundation-ai';
 import type { ChatAttachment } from '@genesislcap/foundation-ai';
 import type { ChatConfig } from '@genesislcap/foundation-ai';
 import type { ChatDriverResult } from '@genesislcap/foundation-ai';
+import type { ChatFallback } from '@genesislcap/foundation-ai';
 import type { ChatInputDuringExecutionMode } from '@genesislcap/foundation-ai';
 import type { ChatMessage } from '@genesislcap/foundation-ai';
 import type { ChatToolChoice } from '@genesislcap/foundation-ai';
@@ -18,8 +19,21 @@ import { InterfaceSymbol } from '@microsoft/fast-foundation';
 import type { Modal } from '@genesislcap/rapid-design-system';
 import { ModelTagAppearance } from '@genesislcap/foundation-ai';
 import type { SubAgentFailureReason } from '@genesislcap/foundation-ai';
+import type { TurnFailureReason } from '@genesislcap/foundation-ai';
 import { ViewTemplate } from '@genesislcap/web-core';
 
+/**
+ * Minimal activity-bus surface the drivers depend on. `ChatDriver`/`OrchestratingDriver`
+ * only ever *publish* — accepting this narrow interface (rather than importing the module
+ * singleton) lets a headless/server or unit-test host omit the bus entirely, so no live
+ * `BroadcastChannel` is ever opened on that path. See {@link NOOP_ACTIVITY_BUS}.
+ *
+ * @beta
+ */
+export declare interface ActivityBus {
+    publish<K extends keyof AgenticActivityEvents>(type: K, detail: AgenticActivityEvents[K]): void;
+}
+
 /** Sentinel value used by the segmented control / select to represent "Auto". */
 export declare const AGENT_PICKER_AUTO_VALUE = "__auto__";
 
@@ -50,12 +64,23 @@ export declare type AgentConfig = SpecialistAgentConfig | FallbackAgentConfig;
 export declare class AgenticActivityBus {
     private readonly subscribers;
     private readonly crossTabEvents;
+    private readonly channelNameFactory?;
     private channel?;
+    private channelInitialised;
     /**
      * @param config - Optional configuration. Omit to create an in-memory-only bus.
      * @beta
      */
     constructor(config?: AgenticActivityBusConfig);
+    /**
+     * Lazily open the cross-tab `BroadcastChannel` on first use. Deferred (rather than
+     * created in the constructor) so that importing this module, or constructing the bus
+     * off-browser (Node, tests, headless server), never opens a live channel or reads
+     * `sessionStorage` — both would keep a Node event loop alive and hang the process.
+     * Cross-tab forwarding is inherently browser-only, so channel creation is gated on a
+     * browser environment; elsewhere the bus stays purely in-process.
+     */
+    private ensureChannel;
     /**
      * Subscribe to an event. Returns an unsubscribe function — call it in
      * `disconnectedCallback` to avoid memory leaks.
@@ -114,6 +139,13 @@ export declare interface AgenticActivityBusConfig {
     crossTabEvents?: (keyof AgenticActivityEvents)[];
     /** BroadcastChannel name. Only used when crossTabEvents is non-empty. */
     channelName?: string;
+    /**
+     * Lazy alternative to {@link AgenticActivityBusConfig.channelName}: called the first
+     * time a cross-tab channel is actually needed, in a browser only. Deferring the name
+     * computation keeps side effects (e.g. `sessionStorage` reads) out of module-eval and
+     * off the non-browser path. Ignored if `channelName` is also set.
+     */
+    channelNameFactory?: () => string;
 }
 
 /**
@@ -179,8 +211,16 @@ export declare interface AgenticActivityEvents {
      * spinner animation lifecycle (which can flap mid-turn as tool calls resolve), whereas
      * this event is a one-shot per turn boundary. Use this for hooks tied to a turn ending
      * (telemetry flushes, post-turn workspace transitions, deferred state recomputation).
+     *
+     * The detail carries the turn's outcome (PTC-0): on a failure it is `{ failureReason }`
+     * with the typed `TurnFailureReason`; on a clean completion, a user cancel, a
+     * driver dispose, and an agent handoff the detail is `undefined` — the historical shape,
+     * kept byte-identical so subscribers that only care about the boundary can keep ignoring
+     * it. Structured-cloneable so it survives the cross-tab BroadcastChannel hop.
      */
-    'tool-loop-end': undefined;
+    'tool-loop-end': {
+        failureReason?: TurnFailureReason;
+    } | undefined;
     /**
      * Fired when a tool handler hands a widget to the user mid-loop and parks awaiting it
      * (`requestInteraction`) — the turn is suspended between provider calls, with no request
@@ -826,6 +866,25 @@ declare 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
@@ -955,9 +1014,6 @@ export declare type CachePolicyInput = CachePolicy | ((ctx: SystemPromptContext)
  */
 export declare class ChatDriver extends EventTarget implements AiDriver {
     private readonly providerRegistry;
-    private readonly maxToolIterations;
-    /** Session identity used to file meta events onto the shared debug-log timeline. */
-    private readonly sessionKey;
     private history;
     private busy;
     /** Epoch ms when the current turn loop began — drives the `turn.end` duration. */
@@ -1185,6 +1241,16 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * the resolved string in a `<system-reminder>` marker and injects it at the message tail.
      */
     private activeTailContextInput?;
+    /**
+     * 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?;
+    /**
+     * 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?;
     /**
      * Active agent's unresolved-tool hook, captured from `applyAgent`. Consulted
      * only when a tool call cannot be dispatched (a stale or hallucinated name);
@@ -1229,9 +1295,13 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * teardown in `runSubAgent`.
      */
     private unsubscribeRegistry?;
-    constructor(providerRegistry: AIProviderRegistry, toolHandlers?: ToolHandlersInput, toolDefinitions?: ToolDefinitionsInput, systemPrompt?: SystemPromptInput, primerHistory?: ChatMessage[], maxToolIterations?: number, maxFoldOperations?: number, maxTurnSnapshots?: number, 
+    /** Hard cap on tool-loop iterations. */
+    private readonly maxToolIterations;
     /** Session identity used to file meta events onto the shared debug-log timeline. */
-    sessionKey?: string);
+    private readonly sessionKey;
+    /** Injected activity bus; defaults to a no-op off-browser (Node/tests/headless). */
+    private readonly activityBus;
+    constructor(providerRegistry: AIProviderRegistry, config?: ChatDriverConfig);
     /**
      * Tear down the driver: aborts the lifecycle signal so any in-flight provider
      * request (and prompt/tool factories awaiting it) cancels instead of running
@@ -1268,6 +1338,23 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * cached history would otherwise gain a stray marker on remount).
      */
     private completeAbortedTurn;
+    /**
+     * 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;
+    /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
+    private static failureReasonOf;
+    /**
+     * 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;
     /**
      * 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.
@@ -1516,6 +1603,41 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private appendToHistory;
 }
 
+/**
+ * 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 declare 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;
+}
+
+export { ChatFallback }
+
 /**
  * `detail` of the `AiAssistantEvent.ChatHeaderMouseDown` event.
  *
@@ -2860,6 +2982,14 @@ export declare interface ManualSelectionConfig {
 
 export { ModelTagAppearance }
 
+/**
+ * No-op {@link ActivityBus}. The default when no bus is injected (Node, tests, headless
+ * server use) — publishing goes nowhere and nothing is left open to tear down.
+ *
+ * @beta
+ */
+export declare const NOOP_ACTIVITY_BUS: ActivityBus;
+
 /**
  * Orchestrates multiple specialist agents. Sits between `FoundationAiAssistant`
  * and `ChatDriver`, classifying each user message and routing it to the right
@@ -2919,6 +3049,8 @@ export declare 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;
     });
     resolveInteraction(interactionId: string, result: unknown): void;
     getInteractionContext(interactionId: string): InteractionContext | undefined;
@@ -3103,6 +3235,23 @@ declare interface ResolvedCostHistoryConfig {
     badgeLabel: 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 declare type ResponseSchemaInput = object | ((ctx: SystemPromptContext) => object | undefined | Promise<object | undefined>);
+
 /**
  * Restore a foundation-state-machine instance from a snapshot produced by the
  * default serializer (or `machine.getPersistedSnapshot()`). Call inside a
@@ -3698,6 +3847,8 @@ export declare interface ToolTreeNode extends ChatToolDefinition {
     tools?: ToolTreeNode[];
 }
 
+export { TurnFailureReason }
+
 /**
  * One captured frame of what the LLM saw on a single tool-loop iteration.
  * The driver records these as a ring buffer (cap: configurable via