@genesislcap/ai-assistant 14.494.0 → 14.496.0

package/dist/esm/chat-driver-node.js

@@ -0,0 +1,33 @@
+/**
+ * Node-safe headless entry point for the AI assistant driver stack (`@genesislcap/ai-assistant/chat-driver`).
+ *
+ * Re-exports ONLY the framework-agnostic pieces — {@link ChatDriver}, `OrchestratingDriver`, the
+ * agent-config surface (`defineAgent`, `defineStatefulAgent`, and the config/input types), and the
+ * activity-bus types/`NOOP_ACTIVITY_BUS` — WITHOUT the DOM/FAST component layer that the package's
+ * main entry (`.`) pulls in via `main/main`. This lets a Node / CommonJS host (server, unit tests,
+ * benches) construct and drive `ChatDriver` over `foundation-ai` providers with no jsdom and no
+ * custom-element registration.
+ *
+ * Every module re-exported here is DOM-clean at import time (no `window`/`document`/`sessionStorage`
+ * eval-time access, no `@genesislcap/web-core`). The activity bus is imported for its types and the
+ * no-op default; its cross-tab `BroadcastChannel` is created lazily and only in a browser, so
+ * pulling this entry into Node opens nothing.
+ *
+ * @packageDocumentation
+ * @beta
+ */
+export * from './components/chat-driver';
+export * from './components/orchestrating-driver';
+export * from './channel/ai-activity-channel';
+export * from './channel/ai-activity-bus';
+export * from './config/config';
+export * from './config/define-stateful-agent';
+export * from './config/fallback-agents';
+// Provider-construction surface, re-exported from `@genesislcap/foundation-ai` so a headless
+// consumer builds its registry from the SAME bundled foundation-ai instance the driver uses. That
+// shared identity matters: `ChatDriver`'s malformed/truncated handling does `instanceof` on the
+// transports' error classes, so a second foundation-ai copy (a separate dep) would silently break
+// those checks. NAMED re-exports only — `export *` would drag in the FAST-DI module
+// (`@microsoft/fast-foundation` → `fast-element` → `document` at eval); by naming just these,
+// esbuild tree-shakes the DI module out and the bundle stays Node-loadable.
+export { AnthropicProvider, AnthropicTransport, GeminiProvider, GeminiTransport, MutableAIProviderRegistry, isObservableAIProviderRegistry, } from '@genesislcap/foundation-ai';

package/dist/esm/components/chat-driver/chat-driver.js

@@ -1,6 +1,6 @@
 import { __awaiter, __rest } from "tslib";
 import { isObservableAIProviderRegistry, MalformedFunctionCallError, ResponseTruncatedError, } from '@genesislcap/foundation-ai';
-import { agenticActivityBus } from '../../channel/ai-activity-bus';
+import { NOOP_ACTIVITY_BUS } from '../../channel/ai-activity-bus';
 import { resolveChatProvider } from '../../config/validate-providers';
 import { clearSession, getMetaEvents, mergeMetaEvents, recordMetaEvent, recordTurnError, recordTurnRetry, } from '../../state/debug-event-log';
 import { createInteractionContext, } from '../../state/interaction-context';
@@ -65,13 +65,9 @@ const HANDOFF_TOOL_RESULT_PLACEHOLDER = 'Handoff to another specialist — routi
  * @beta
  */
 export class ChatDriver extends EventTarget {
-    constructor(providerRegistry, toolHandlers = {}, toolDefinitions = [], systemPrompt, primerHistory, maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS, maxFoldOperations = DEFAULT_MAX_FOLD_OPERATIONS, maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS, 
-    /** Session identity used to file meta events onto the shared debug-log timeline. */
-    sessionKey = '') {
+    constructor(providerRegistry, config = {}) {
         super();
         this.providerRegistry = providerRegistry;
-        this.maxToolIterations = maxToolIterations;
-        this.sessionKey = sessionKey;
         this.history = [];
         this.busy = false;
         /** Epoch ms when the current turn loop began — drives the `turn.end` duration. */
@@ -216,6 +212,10 @@ export class ChatDriver extends EventTarget {
          * picked up on the next turn.
          */
         this.resolvedStatusCache = new Map();
+        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 = {};
@@ -337,6 +337,30 @@ export class ChatDriver extends EventTarget {
         }
         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' }`.
+     */
+    turnDone(failureReason) {
+        return failureReason ? { reason: 'done', failureReason } : { reason: 'done' };
+    }
+    /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
+    static failureReasonOf(result) {
+        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.
+     */
+    static loopEndDetail(result) {
+        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.
@@ -385,6 +409,8 @@ export class ChatDriver extends EventTarget {
         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;
@@ -931,7 +957,7 @@ export class ChatDriver extends EventTarget {
                 // "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', {
                         detail: { interactionId, chatInputDuringExecution },
@@ -996,7 +1022,7 @@ export class ChatDriver extends EventTarget {
             // 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
@@ -1061,9 +1087,12 @@ export class ChatDriver extends EventTarget {
                 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 = { reason: 'done' };
             try {
-                return yield this.runToolLoop(userInput, attachments);
+                result = yield this.runToolLoop(userInput, attachments);
+                return result;
             }
             catch (e) {
                 logger.error('ChatDriver error:', e);
@@ -1078,7 +1107,8 @@ export class ChatDriver extends EventTarget {
                     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', {
@@ -1088,7 +1118,7 @@ export class ChatDriver extends EventTarget {
                 });
                 this.busy = false;
                 this.endTurn();
-                agenticActivityBus.publish('tool-loop-end', undefined);
+                this.activityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
             }
         });
     }
@@ -1211,7 +1241,12 @@ export class ChatDriver extends EventTarget {
             // 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();
@@ -1372,9 +1407,12 @@ export class ChatDriver extends EventTarget {
                 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 = { reason: 'done' };
             try {
-                return yield this.runToolLoop('', undefined, transientPrimer);
+                result = yield this.runToolLoop('', undefined, transientPrimer);
+                return result;
             }
             catch (e) {
                 logger.error('ChatDriver error:', e);
@@ -1389,7 +1427,8 @@ export class ChatDriver extends EventTarget {
                     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', {
@@ -1399,7 +1438,7 @@ export class ChatDriver extends EventTarget {
                 });
                 this.busy = false;
                 this.endTurn();
-                agenticActivityBus.publish('tool-loop-end', undefined);
+                this.activityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
             }
         });
     }
@@ -1686,13 +1725,14 @@ export class ChatDriver extends EventTarget {
                 // 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
                 yield Promise.all([
                     this.resolveTurnInput(this.activeTemperatureInput, promptCtx),
                     this.resolveTurnInput(this.activeToolChoiceInput, promptCtx),
                     this.resolveTurnInput(this.activeCachePolicyInput, promptCtx),
                     this.resolveTurnInput(this.activeTailContextInput, promptCtx),
+                    this.resolveTurnInput(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
@@ -1740,6 +1780,12 @@ export class ChatDriver extends EventTarget {
                     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
                 // in `applyAgent`; function-form names are validated on first resolution
@@ -1784,7 +1830,7 @@ export class ChatDriver extends EventTarget {
                                 content: '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.
@@ -1813,7 +1859,7 @@ export class ChatDriver extends EventTarget {
                                 content: '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
@@ -1839,7 +1885,9 @@ export class ChatDriver extends EventTarget {
                                 content: '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
@@ -1899,7 +1947,7 @@ export class ChatDriver extends EventTarget {
                             content: '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
@@ -2213,7 +2261,7 @@ export class ChatDriver extends EventTarget {
                             content: "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];
                 if (firstContinuation) {
@@ -2223,9 +2271,12 @@ export class ChatDriver extends EventTarget {
                 // 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;
             if (iterations >= this.maxToolIterations) {
                 logger.warn('ChatDriver: reached max tool iterations, stopping');
                 recordTurnError(this.sessionKey, 'max-iterations', {
@@ -2244,8 +2295,9 @@ export class ChatDriver extends EventTarget {
                         content: "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);
         });
     }
     appendToHistory(message) {

package/dist/esm/components/chat-driver/chat-driver.test.js

@@ -1,7 +1,7 @@
 import { __awaiter } from "tslib";
-import { isChatToolCallUnknown } from '@genesislcap/foundation-ai';
+import { isChatToolCallUnknown, MalformedFunctionCallError, ResponseTruncatedError, } from '@genesislcap/foundation-ai';
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { agenticActivityBus } from '../../channel/ai-activity-bus';
+import { AgenticActivityBus } from '../../channel/ai-activity-bus';
 import { clearMetaEventRegistry, getMetaEvents } from '../../state/debug-event-log';
 import { sumCosts } from '../../utils/sum-costs';
 import { sumTokens } from '../../utils/sum-tokens';
@@ -65,8 +65,13 @@ const callsTool = (name, id) => ({
     toolCalls: [{ id, name, args: {} }],
 });
 const agent = (overrides) => (Object.assign({ description: 'test agent' }, overrides));
-const makeDriver = (config, provider, sessionKey = '') => {
-    const driver = new ChatDriver(makeRegistry(provider), {}, [], undefined, undefined, 50, 5, undefined, sessionKey);
+const makeDriver = (config, provider, sessionKey = '', activityBus) => {
+    const driver = new ChatDriver(makeRegistry(provider), {
+        maxToolIterations: 50,
+        maxFoldOperations: 5,
+        sessionKey,
+        activityBus,
+    });
     driver.applyAgent(config);
     return driver;
 };
@@ -85,12 +90,6 @@ const unresolvedEvents = (sessionKey) => getMetaEvents(sessionKey)
 // stale tool detection — stateful agent advances past a tool's state
 // ---------------------------------------------------------------------------
 const stale = createLogicSuite('ChatDriver stale-tool detection');
-// The driver imports the `agenticActivityBus` singleton, which opens a
-// BroadcastChannel at module load. An open channel keeps the test page alive
-// and hangs the runner, so close it once the suite finishes.
-stale.after(() => {
-    agenticActivityBus.close();
-});
 stale('guides the model when it calls a tool that an earlier state exposed', () => __awaiter(void 0, void 0, void 0, function* () {
     // State A exposes tool_a; calling it advances to state B, which exposes only
     // tool_b. A factory-form agent narrows the tool set per turn, mirroring how
@@ -220,9 +219,6 @@ stale.run();
 // onUnresolvedTool hook — an agent can redirect an unresolved tool call
 // ---------------------------------------------------------------------------
 const hook = createLogicSuite('ChatDriver onUnresolvedTool hook');
-hook.after(() => {
-    agenticActivityBus.close();
-});
 hook('replaces the default for a hallucinated tool when the hook returns a string', () => __awaiter(void 0, void 0, void 0, function* () {
     const config = agent({
         name: 'Hooked',
@@ -498,11 +494,6 @@ cancel.run();
 // worker's turn(s), in order.
 // ---------------------------------------------------------------------------
 const subagent = createLogicSuite('ChatDriver sub-agents');
-subagent.after(() => {
-    // Safe to call again even if `stale` already closed it — close() is
-    // idempotent and cross-tab publishes are guarded by `&& this.channel`.
-    agenticActivityBus.close();
-});
 /** A sub-agent named `worker` that finishes by calling `completeSubAgent`. */
 const completingWorker = (result) => agent({
     name: 'worker',
@@ -1116,16 +1107,17 @@ interactionContextLifecycle.run();
 // 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();
-});
+// These two tests need to observe what the driver publishes, so they inject a local
+// in-memory bus (no `crossTabEvents` → no BroadcastChannel is ever opened, nothing to close)
+// rather than the shared singleton. Every other suite lets the driver default to the no-op bus.
 interactionBus('brackets a park with interaction-requested then -resolved', () => __awaiter(void 0, void 0, void 0, function* () {
     const events = [];
+    const bus = new AgenticActivityBus();
     const unsubs = [
-        agenticActivityBus.subscribe('interaction-requested', () => events.push('requested')),
-        agenticActivityBus.subscribe('interaction-resolved', () => events.push('resolved')),
+        bus.subscribe('interaction-requested', () => events.push('requested')),
+        bus.subscribe('interaction-resolved', () => events.push('resolved')),
     ];
-    const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]));
+    const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]), '', bus);
     const pending = driver.requestInteraction('w', {});
     assert.equal(events, ['requested'], 'parking fires interaction-requested');
     const id = driver.getHistory().at(-1).interaction.interactionId;
@@ -1137,8 +1129,9 @@ interactionBus('brackets a park with interaction-requested then -resolved', () =
 }));
 interactionBus('a timed-out interaction still fires interaction-resolved', () => __awaiter(void 0, void 0, void 0, function* () {
     const events = [];
-    const unsub = agenticActivityBus.subscribe('interaction-resolved', () => events.push('resolved'));
-    const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]));
+    const bus = new AgenticActivityBus();
+    const unsub = bus.subscribe('interaction-resolved', () => events.push('resolved'));
+    const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]), '', bus);
     // 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 });
@@ -1239,14 +1232,11 @@ const makeObservableRegistry = (initial) => {
     };
 };
 const makeDriverWithRegistry = (config, registry) => {
-    const driver = new ChatDriver(registry, {}, [], undefined, undefined, 50, 5, undefined, '');
+    const driver = new ChatDriver(registry, { maxToolIterations: 50, maxFoldOperations: 5 });
     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', () => __awaiter(void 0, void 0, void 0, function* () {
     const providerA = scriptedProvider([{ role: 'assistant', content: 'A' }]);
     const providerB = scriptedProvider([{ role: 'assistant', content: 'B' }]);
@@ -1323,9 +1313,6 @@ const modelProvider = (model, responses) => {
     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', () => __awaiter(void 0, void 0, void 0, function* () {
     const provider = modelProvider('gemini-2.5-flash-lite', [
         { role: 'assistant', content: 'hi there' },
@@ -1392,9 +1379,6 @@ modelAttr.run();
 // condenseWhen — tool-declared context condensation (wiring through the loop)
 // ---------------------------------------------------------------------------
 const condense = createLogicSuite('ChatDriver condenseWhen');
-condense.after(() => {
-    agenticActivityBus.close();
-});
 const bigBody = 'A'.repeat(2000);
 /** An assistant turn calling `read` with a path arg (so `by: args.path` resolves). */
 const readsPath = (id, path) => ({
@@ -1621,3 +1605,143 @@ condense('phaseEnd: collapses at endPhase() while the agent keeps running', () =
     assert.is((_a = events[0].detail) === null || _a === void 0 ? void 0 : _a.trigger, 'phaseEnd');
 }));
 condense.run();
+// ---------------------------------------------------------------------------
+// turn-outcome surfacing (PTC-0) — the typed failure reason must reach BOTH
+// the loop-boundary result (`ChatDriverResult.failureReason`) and the
+// `tool-loop-end` activity-bus event detail. Historically every exit flattened
+// to `{ reason: 'done' }` and the bus detail was `undefined`; these lock the
+// two seams together, one per `TurnFailureReason`, plus a happy-path compat
+// check that the legacy shape is byte-unchanged.
+// ---------------------------------------------------------------------------
+const outcome = createLogicSuite('ChatDriver turn-outcome surfacing');
+// This branch routes activity events to an INJECTED bus (default NOOP), not the module
+// singleton, so these tests inject a local bus and observe the same seam the driver publishes to.
+const outcomeBus = new AgenticActivityBus();
+outcome.after(() => {
+    outcomeBus.close();
+});
+/**
+ * Subscribe to `tool-loop-end` and expose the most recent detail seen. `fired()` reports
+ * whether the event was seen at all — distinct from `detail()`, which is `undefined` both
+ * when no event fired and when a clean turn fired with the historical `undefined` detail.
+ */
+const captureLoopEnd = () => {
+    let last;
+    let seen = false;
+    const stop = outcomeBus.subscribe('tool-loop-end', (d) => {
+        last = d;
+        seen = true;
+    });
+    return { detail: () => (seen ? last : undefined), fired: () => seen, stop };
+};
+/** A ChatDriver with an explicit (small) tool-iteration cap. */
+const makeCappedDriver = (config, provider, maxIterations, sessionKey = '') => {
+    const driver = new ChatDriver(makeRegistry(provider), {
+        maxToolIterations: maxIterations,
+        maxFoldOperations: 5,
+        sessionKey,
+        activityBus: outcomeBus,
+    });
+    driver.applyAgent(config);
+    return driver;
+};
+/**
+ * Assert that a turn driven by `provider` surfaces `expected` at BOTH seams.
+ * `driverFor` lets the max-iterations case swap in a low cap.
+ */
+const assertSurfacesReason = (label_1, provider_1, expected_1, ...args_1) => __awaiter(void 0, [label_1, provider_1, expected_1, ...args_1], void 0, function* (label, provider, expected, driverFor = (c, p, k) => makeDriver(c, p, k, outcomeBus)) {
+    var _a;
+    clearMetaEventRegistry();
+    const sessionKey = `outcome-${label}`;
+    const config = agent({
+        name: 'Static',
+        toolDefinitions: [def('noop')],
+        toolHandlers: { noop: () => __awaiter(void 0, void 0, void 0, function* () { return 'ok'; }) },
+    });
+    const driver = driverFor(config, provider, sessionKey);
+    const cap = captureLoopEnd();
+    const result = yield driver.sendMessage('go');
+    // Seam 1 — the loop-boundary result. Discriminant stays 'done' (compat).
+    assert.is(result.reason, 'done', `[${label}] discriminant stays 'done'`);
+    assert.is(result.reason === 'done' ? result.failureReason : undefined, expected, `[${label}] result.failureReason surfaces the typed reason`);
+    // Seam 2 — the activity-bus tool-loop-end detail.
+    assert.ok(cap.detail(), `[${label}] a tool-loop-end event fired`);
+    assert.is(cap.detail().failureReason, expected, `[${label}] the bus detail carries the same reason`);
+    // Consistency: the debug-log turn.error records the same taxonomy.
+    const err = getMetaEvents(sessionKey).find((e) => e.type === 'turn.error');
+    assert.ok(err, `[${label}] a turn.error is recorded`);
+    assert.is((_a = err.detail) === null || _a === void 0 ? void 0 : _a.reason, expected, `[${label}] the debug-log reason matches`);
+    cap.stop();
+});
+/** A provider that returns a MALFORMED_FUNCTION_CALL on every call. */
+const malformedProvider = () => ({
+    chat: () => __awaiter(void 0, void 0, void 0, function* () {
+        throw new MalformedFunctionCallError('bad call');
+    }),
+});
+/** A provider that returns an empty response on every call. */
+const emptyProvider = () => ({
+    chat: () => __awaiter(void 0, void 0, void 0, function* () { return ({ role: 'assistant', content: '' }); }),
+});
+/** A provider that throws a ResponseTruncatedError (deterministic, no retry). */
+const truncatedProvider = () => ({
+    chat: () => __awaiter(void 0, void 0, void 0, function* () {
+        throw new ResponseTruncatedError('test-model', 1024, 1024, ['noop']);
+    }),
+});
+/** A provider that throws a generic error (the sendMessage catch-all → 'exception'). */
+const throwingProvider = () => ({
+    chat: () => __awaiter(void 0, void 0, void 0, function* () {
+        throw new Error('boom');
+    }),
+});
+/** A provider that never stops calling a valid tool (drives the iteration cap). */
+const neverStopsProvider = () => {
+    let n = 0;
+    return {
+        chat: () => __awaiter(void 0, void 0, void 0, function* () {
+            const id = `noop-${n}`;
+            n += 1;
+            return { role: 'assistant', content: '', toolCalls: [{ id, name: 'noop', args: {} }] };
+        }),
+    };
+};
+/** A provider that keeps calling a tool with no handler (hallucinated → limit). */
+const hallucinatedProvider = () => scriptedProvider(Array.from({ length: 6 }, (_u, i) => callsTool('ghost', `ghost-${i}`)));
+outcome('malformed-function-call surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('malformed', malformedProvider(), 'malformed-function-call');
+}));
+outcome('empty-response surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('empty', emptyProvider(), 'empty-response');
+}));
+outcome('response-truncated surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('truncated', truncatedProvider(), 'response-truncated');
+}));
+outcome('exception surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('exception', throwingProvider(), 'exception');
+}));
+outcome('unknown-tool-limit surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('unknown-tool', hallucinatedProvider(), 'unknown-tool-limit');
+}));
+outcome('max-iterations surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('max-iter', neverStopsProvider(), 'max-iterations', (c, p, k) => makeCappedDriver(c, p, 2, k));
+}));
+outcome('a clean turn leaves the legacy shape byte-unchanged (no failureReason)', () => __awaiter(void 0, void 0, void 0, function* () {
+    clearMetaEventRegistry();
+    const config = agent({ name: 'Static' });
+    // Plain-text reply ends the turn cleanly on the first call.
+    const driver = makeDriver(config, scriptedProvider([{ role: 'assistant', content: 'hi' }]), 'outcome-ok', outcomeBus);
+    const cap = captureLoopEnd();
+    const result = yield driver.sendMessage('go');
+    // The result is exactly `{ reason: 'done' }` — no `failureReason` key added.
+    assert.equal(result, { reason: 'done' }, 'happy-path result is the historical shape');
+    assert.not.ok('failureReason' in result, 'no failureReason key is present on a clean turn');
+    // The bus event still fires, and its detail is the historical `undefined` — a clean
+    // turn emits no detail object at all (byte-shape compat), not `{ failureReason: undefined }`.
+    assert.ok(cap.fired(), 'a tool-loop-end event fired');
+    assert.is(cap.detail(), undefined, 'a clean turn emits the historical undefined detail');
+    // And no turn.error was recorded.
+    assert.not.ok(getMetaEvents('outcome-ok').some((e) => e.type === 'turn.error'), 'a clean turn records no turn.error');
+    cap.stop();
+}));
+outcome.run();

package/dist/esm/components/orchestrating-driver/orchestrating-driver.js

@@ -109,7 +109,13 @@ export class OrchestratingDriver extends EventTarget {
         const rawFallback = fallbacks[0];
         this.fallback = rawFallback
             ? Object.assign(Object.assign({}, 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) => {
             this.dispatchEvent(new CustomEvent('history-updated', { detail: e.detail }));

package/dist/esm/main/main.js

@@ -1056,9 +1056,16 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 maxToolIterations: agent.maxToolIterations,
                 maxFoldOperations: agent.maxFoldOperations,
                 maxTurnSnapshots: agent.maxTurnSnapshots,
+                activityBus: agenticActivityBus,
             });
         }
-        return new ChatDriver(this.providerRegistry, {}, [], undefined, undefined, agent.maxToolIterations, agent.maxFoldOperations, agent.maxTurnSnapshots, (_c = this.getStateKey()) !== null && _c !== void 0 ? _c : '');
+        return new ChatDriver(this.providerRegistry, {
+            maxToolIterations: agent.maxToolIterations,
+            maxFoldOperations: agent.maxFoldOperations,
+            maxTurnSnapshots: agent.maxTurnSnapshots,
+            sessionKey: (_c = this.getStateKey()) !== null && _c !== void 0 ? _c : '',
+            activityBus: agenticActivityBus,
+        });
     }
     /**
      * Attaches event listeners to the current driver. Stores a cleanup function

package/dist/esm/main/popout-interaction-gate.test.js

@@ -1,5 +1,4 @@
 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.
 FoundationAiAssistant;
@@ -11,16 +10,13 @@ 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, messages) {
     const el = document.createElement('foundation-ai-assistant');