@genesislcap/ai-assistant 14.495.0 → 14.496.0

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');

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/index.ts","../src/channel/ai-activity-bus.ts","../src/channel/ai-activity-channel.ts","../src/components/flowing-waves-indicator.ts","../src/components/halo-overlay.ts","../src/components/plasma-orb-indicator.ts","../src/components/waves-indicator.ts","../src/components/activity-halo/activity-halo.ts","../src/components/agent-picker/agent-picker.constants.ts","../src/components/agent-picker/agent-picker.styles.ts","../src/components/agent-picker/agent-picker.template.ts","../src/components/agent-picker/agent-picker.ts","../src/components/agent-picker/index.ts","../src/components/ai-driver/ai-driver.ts","../src/components/ai-driver/index.ts","../src/components/chat-bubble/chat-bubble.styles.ts","../src/components/chat-bubble/chat-bubble.template.ts","../src/components/chat-bubble/chat-bubble.ts","../src/components/chat-bubble/index.ts","../src/components/chat-driver/align-event-globals.ts","../src/components/chat-driver/chat-driver.compact.test.ts","../src/components/chat-driver/chat-driver.test.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/index.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.test.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts","../src/components/chat-interaction-wrapper/index.ts","../src/components/chat-markdown/chat-markdown.ts","../src/components/chat-markdown/index.ts","../src/components/orchestrating-driver/index.ts","../src/components/orchestrating-driver/orchestrating-driver.pin.test.ts","../src/components/orchestrating-driver/orchestrating-driver.ts","../src/components/popout-manager/index.ts","../src/components/popout-manager/popout-manager.ts","../src/components/settings-modal/index.ts","../src/components/settings-modal/settings-modal.styles.ts","../src/components/settings-modal/settings-modal.template.ts","../src/config/config.ts","../src/config/define-stateful-agent.test.ts","../src/config/define-stateful-agent.ts","../src/config/fallback-agents.ts","../src/config/index.ts","../src/config/validate-providers.test.ts","../src/config/validate-providers.ts","../src/main/index.ts","../src/main/main.styles.ts","../src/main/main.template.ts","../src/main/main.ts","../src/main/main.types.ts","../src/main/popout-interaction-gate.test.ts","../src/provider/ai-provider-switcher.ts","../src/provider/assistant-app-settings.ts","../src/state/ai-assistant-slice.test.ts","../src/state/ai-assistant-slice.ts","../src/state/debug-event-log.test.ts","../src/state/debug-event-log.ts","../src/state/driver-registry.test.ts","../src/state/driver-registry.ts","../src/state/interaction-context.test.ts","../src/state/interaction-context.ts","../src/state/session-store.ts","../src/state/persistence/diagnostics-cursors.test.ts","../src/state/persistence/diagnostics-cursors.ts","../src/state/persistence/diagnostics.test.ts","../src/state/persistence/diagnostics.ts","../src/state/persistence/index.ts","../src/state/persistence/persister-registry.ts","../src/state/persistence/session-persistence-provider.test.ts","../src/state/persistence/session-persistence-provider.ts","../src/state/persistence/session-persistence.integration.test.ts","../src/state/persistence/session-persister.test.ts","../src/state/persistence/session-persister.ts","../src/state/persistence/session-snapshot.test.ts","../src/state/persistence/session-snapshot.ts","../src/state/persistence/stateful-restore.e2e.test.ts","../src/styles/ai-colours.ts","../src/suggestions/chat-suggestions.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/types/interaction-context.ts","../src/utils/animated-panel-toggle.ts","../src/utils/animation-exclusivity.test.ts","../src/utils/animation-exclusivity.ts","../src/utils/collect-session-models.test.ts","../src/utils/collect-session-models.ts","../src/utils/condense-history.test.ts","../src/utils/condense-history.ts","../src/utils/cost-session-history.test.ts","../src/utils/cost-session-history.ts","../src/utils/derive-cost-session-title.test.ts","../src/utils/derive-cost-session-title.ts","../src/utils/flatten-sub-agent-messages.test.ts","../src/utils/flatten-sub-agent-messages.ts","../src/utils/history-transform.test.ts","../src/utils/history-transform.ts","../src/utils/index.ts","../src/utils/logger.ts","../src/utils/message-partition.test.ts","../src/utils/message-partition.ts","../src/utils/resolve-cost-history-config.test.ts","../src/utils/resolve-cost-history-config.ts","../src/utils/resolve-preference-baseline.test.ts","../src/utils/resolve-preference-baseline.ts","../src/utils/strip-agent-handlers.test.ts","../src/utils/strip-agent-handlers.ts","../src/utils/sum-costs.test.ts","../src/utils/sum-costs.ts","../src/utils/sum-tokens.test.ts","../src/utils/sum-tokens.ts","../src/utils/tool-fold.ts","../src/utils/with-timeout.ts"],"version":"5.9.2"}
+{"root":["../src/chat-driver-node.ts","../src/index.ts","../src/channel/ai-activity-bus.ts","../src/channel/ai-activity-channel.ts","../src/components/flowing-waves-indicator.ts","../src/components/halo-overlay.ts","../src/components/plasma-orb-indicator.ts","../src/components/waves-indicator.ts","../src/components/activity-halo/activity-halo.ts","../src/components/agent-picker/agent-picker.constants.ts","../src/components/agent-picker/agent-picker.styles.ts","../src/components/agent-picker/agent-picker.template.ts","../src/components/agent-picker/agent-picker.ts","../src/components/agent-picker/index.ts","../src/components/ai-driver/ai-driver.ts","../src/components/ai-driver/index.ts","../src/components/chat-bubble/chat-bubble.styles.ts","../src/components/chat-bubble/chat-bubble.template.ts","../src/components/chat-bubble/chat-bubble.ts","../src/components/chat-bubble/index.ts","../src/components/chat-driver/align-event-globals.ts","../src/components/chat-driver/chat-driver.compact.test.ts","../src/components/chat-driver/chat-driver.test.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/index.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.test.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts","../src/components/chat-interaction-wrapper/index.ts","../src/components/chat-markdown/chat-markdown.ts","../src/components/chat-markdown/index.ts","../src/components/orchestrating-driver/index.ts","../src/components/orchestrating-driver/orchestrating-driver.pin.test.ts","../src/components/orchestrating-driver/orchestrating-driver.ts","../src/components/popout-manager/index.ts","../src/components/popout-manager/popout-manager.ts","../src/components/settings-modal/index.ts","../src/components/settings-modal/settings-modal.styles.ts","../src/components/settings-modal/settings-modal.template.ts","../src/config/config.ts","../src/config/define-stateful-agent.test.ts","../src/config/define-stateful-agent.ts","../src/config/fallback-agents.ts","../src/config/index.ts","../src/config/validate-providers.test.ts","../src/config/validate-providers.ts","../src/main/index.ts","../src/main/main.styles.ts","../src/main/main.template.ts","../src/main/main.ts","../src/main/main.types.ts","../src/main/popout-interaction-gate.test.ts","../src/provider/ai-provider-switcher.ts","../src/provider/assistant-app-settings.ts","../src/state/ai-assistant-slice.test.ts","../src/state/ai-assistant-slice.ts","../src/state/debug-event-log.test.ts","../src/state/debug-event-log.ts","../src/state/driver-registry.test.ts","../src/state/driver-registry.ts","../src/state/interaction-context.test.ts","../src/state/interaction-context.ts","../src/state/session-store.ts","../src/state/persistence/diagnostics-cursors.test.ts","../src/state/persistence/diagnostics-cursors.ts","../src/state/persistence/diagnostics.test.ts","../src/state/persistence/diagnostics.ts","../src/state/persistence/index.ts","../src/state/persistence/persister-registry.ts","../src/state/persistence/session-persistence-provider.test.ts","../src/state/persistence/session-persistence-provider.ts","../src/state/persistence/session-persistence.integration.test.ts","../src/state/persistence/session-persister.test.ts","../src/state/persistence/session-persister.ts","../src/state/persistence/session-snapshot.test.ts","../src/state/persistence/session-snapshot.ts","../src/state/persistence/stateful-restore.e2e.test.ts","../src/styles/ai-colours.ts","../src/suggestions/chat-suggestions.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/types/interaction-context.ts","../src/utils/animated-panel-toggle.ts","../src/utils/animation-exclusivity.test.ts","../src/utils/animation-exclusivity.ts","../src/utils/collect-session-models.test.ts","../src/utils/collect-session-models.ts","../src/utils/condense-history.test.ts","../src/utils/condense-history.ts","../src/utils/cost-session-history.test.ts","../src/utils/cost-session-history.ts","../src/utils/derive-cost-session-title.test.ts","../src/utils/derive-cost-session-title.ts","../src/utils/flatten-sub-agent-messages.test.ts","../src/utils/flatten-sub-agent-messages.ts","../src/utils/history-transform.test.ts","../src/utils/history-transform.ts","../src/utils/index.ts","../src/utils/logger.ts","../src/utils/message-partition.test.ts","../src/utils/message-partition.ts","../src/utils/resolve-cost-history-config.test.ts","../src/utils/resolve-cost-history-config.ts","../src/utils/resolve-preference-baseline.test.ts","../src/utils/resolve-preference-baseline.ts","../src/utils/strip-agent-handlers.test.ts","../src/utils/strip-agent-handlers.ts","../src/utils/sum-costs.test.ts","../src/utils/sum-costs.ts","../src/utils/sum-tokens.test.ts","../src/utils/sum-tokens.ts","../src/utils/tool-fold.ts","../src/utils/with-timeout.ts"],"version":"5.9.2"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "14.495.0",
+  "version": "14.496.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -27,6 +27,11 @@
       "types": "./dist/dts/config/index.d.ts",
       "default": "./dist/esm/config/index.js"
     },
+    "./chat-driver": {
+      "types": "./dist/dts/chat-driver-node.d.ts",
+      "import": "./dist/chat-driver.mjs",
+      "require": "./dist/chat-driver.cjs"
+    },
     "./package.json": "./package.json",
     "./react": {
       "types": "./dist/dts/react.d.ts",
@@ -38,11 +43,15 @@
     "*": {
       "config": [
         "./dist/dts/config/index.d.ts"
+      ],
+      "chat-driver": [
+        "./dist/dts/chat-driver-node.d.ts"
       ]
     }
   },
   "scripts": {
-    "build": "genx build -b ts",
+    "build": "genx build -b ts && node ./scripts/build-chat-driver-node.mjs",
+    "build:chat-driver": "node ./scripts/build-chat-driver-node.mjs",
     "build:webpack": "genx build",
     "build:webpack:stats": "genx analyze",
     "circular": "npx -y madge --extensions ts --circular ./src",
@@ -64,25 +73,26 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.495.0",
-    "@genesislcap/genx": "14.495.0",
-    "@genesislcap/rollup-builder": "14.495.0",
-    "@genesislcap/ts-builder": "14.495.0",
-    "@genesislcap/uvu-playwright-builder": "14.495.0",
-    "@genesislcap/vite-builder": "14.495.0",
-    "@genesislcap/webpack-builder": "14.495.0",
+    "@genesislcap/foundation-testing": "14.496.0",
+    "@genesislcap/genx": "14.496.0",
+    "@genesislcap/rollup-builder": "14.496.0",
+    "@genesislcap/ts-builder": "14.496.0",
+    "@genesislcap/uvu-playwright-builder": "14.496.0",
+    "@genesislcap/vite-builder": "14.496.0",
+    "@genesislcap/webpack-builder": "14.496.0",
     "@types/dompurify": "^3.0.5",
-    "@types/marked": "^5.0.2"
+    "@types/marked": "^5.0.2",
+    "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "14.495.0",
-    "@genesislcap/foundation-logger": "14.495.0",
-    "@genesislcap/foundation-notifications": "14.495.0",
-    "@genesislcap/foundation-redux": "14.495.0",
-    "@genesislcap/foundation-ui": "14.495.0",
-    "@genesislcap/foundation-utils": "14.495.0",
-    "@genesislcap/rapid-design-system": "14.495.0",
-    "@genesislcap/web-core": "14.495.0",
+    "@genesislcap/foundation-ai": "14.496.0",
+    "@genesislcap/foundation-logger": "14.496.0",
+    "@genesislcap/foundation-notifications": "14.496.0",
+    "@genesislcap/foundation-redux": "14.496.0",
+    "@genesislcap/foundation-ui": "14.496.0",
+    "@genesislcap/foundation-utils": "14.496.0",
+    "@genesislcap/rapid-design-system": "14.496.0",
+    "@genesislcap/web-core": "14.496.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -95,5 +105,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "24d26a75271717d40c0b6168b983bd8536a3db7f"
+  "gitHead": "2ae3ec60cab8440c6beb1da84e2d47239b11e9b5"
 }

package/scripts/build-chat-driver-node.mjs

@@ -0,0 +1,42 @@
+/**
+ * Bundles the Node-safe `./chat-driver` subpath into self-contained, Node-loadable dual output
+ * (`dist/chat-driver.mjs` + `dist/chat-driver.cjs`).
+ *
+ * Why a bundler and not just tsc: `genx build -b ts` emits bundler-target ESM (extensionless
+ * relative imports + a bare `tslib` import) that Node's own loader can't resolve. This step bundles
+ * `src/chat-driver-node.ts` and its closure (including `@genesislcap/foundation-ai`, `tslib`, and
+ * the logger) inline, so a plain Node/CommonJS host can `require`/`import` the driver stack with no
+ * bundler and no jsdom. The FAST/DOM layer is never in this entry's closure, and `foundation-ai`'s
+ * DI module (its only `@microsoft/fast-foundation` importer) tree-shakes out.
+ *
+ * Runs after `genx build -b ts` (which produces the matching `dist/dts/chat-driver-node.d.ts`).
+ */
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as esbuild from 'esbuild';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const entry = resolve(packageRoot, 'src/chat-driver-node.ts');
+
+/** @type {import('esbuild').BuildOptions} */
+const shared = {
+  entryPoints: [entry],
+  bundle: true,
+  platform: 'node',
+  target: 'node22',
+  // Self-contained: bundle third-party deps (foundation-ai, tslib, logger) inline so the artifact
+  // is Node-loadable standalone. Node built-ins are external automatically under platform: 'node'.
+  sourcemap: 'linked',
+  logLevel: 'info',
+};
+
+await esbuild.build({
+  ...shared,
+  format: 'esm',
+  outfile: resolve(packageRoot, 'dist/chat-driver.mjs'),
+});
+await esbuild.build({
+  ...shared,
+  format: 'cjs',
+  outfile: resolve(packageRoot, 'dist/chat-driver.cjs'),
+});

package/src/channel/ai-activity-bus.ts

@@ -10,10 +10,37 @@ export 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;
 }
 
 type AnyHandler = (detail: any) => void;
 
+/**
+ * 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 interface ActivityBus {
+  publish<K extends keyof AgenticActivityEvents>(type: K, detail: AgenticActivityEvents[K]): void;
+}
+
+/**
+ * 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 const NOOP_ACTIVITY_BUS: ActivityBus = { publish: () => {} };
+
 /**
  * Typed in-process event bus for AI assistant activity events.
  *
@@ -31,7 +58,9 @@ type AnyHandler = (detail: any) => void;
 export class AgenticActivityBus {
   private readonly subscribers = new Map<string, Set<AnyHandler>>();
   private readonly crossTabEvents: Set<string>;
+  private readonly channelNameFactory?: () => string;
   private channel?: BroadcastChannel;
+  private channelInitialised = false;
 
   /**
    * @param config - Optional configuration. Omit to create an in-memory-only bus.
@@ -39,13 +68,28 @@ export class AgenticActivityBus {
    */
   constructor(config?: AgenticActivityBusConfig) {
     this.crossTabEvents = new Set(config?.crossTabEvents ?? []);
-    if (this.crossTabEvents.size > 0 && config?.channelName) {
-      this.channel = new BroadcastChannel(config.channelName);
-      this.channel.onmessage = (ev) => {
-        const { type, detail } = (ev.data ?? {}) as { type?: string; detail?: unknown };
-        if (type) this.notifyLocal(type, detail);
-      };
-    }
+    this.channelNameFactory =
+      config?.channelName != null ? () => config.channelName! : config?.channelNameFactory;
+  }
+
+  /**
+   * 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(): void {
+    if (this.channelInitialised) return;
+    this.channelInitialised = true;
+    const inBrowser = typeof window !== 'undefined' && typeof BroadcastChannel !== 'undefined';
+    if (this.crossTabEvents.size === 0 || !this.channelNameFactory || !inBrowser) return;
+    this.channel = new BroadcastChannel(this.channelNameFactory());
+    this.channel.onmessage = (ev) => {
+      const { type, detail } = (ev.data ?? {}) as { type?: string; detail?: unknown };
+      if (type) this.notifyLocal(type, detail);
+    };
   }
 
   /**
@@ -58,6 +102,9 @@ export class AgenticActivityBus {
     type: K,
     handler: (detail: AgenticActivityEvents[K]) => void,
   ): () => void {
+    // Open the cross-tab channel (browser only) so this subscriber receives events
+    // forwarded from other tabs; no-op off-browser.
+    this.ensureChannel();
     let handlers = this.subscribers.get(type as string);
     if (!handlers) {
       handlers = new Set();
@@ -76,8 +123,9 @@ export class AgenticActivityBus {
    */
   publish<K extends keyof AgenticActivityEvents>(type: K, detail: AgenticActivityEvents[K]): void {
     this.notifyLocal(type as string, detail);
-    if (this.crossTabEvents.has(type as string) && this.channel) {
-      this.channel.postMessage({ type, detail });
+    if (this.crossTabEvents.has(type as string)) {
+      this.ensureChannel();
+      this.channel?.postMessage({ type, detail });
     }
   }
 
@@ -124,6 +172,9 @@ export class AgenticActivityBus {
  *   instances on the same origin.
  */
 function getTabScopedChannelName(base: string): string {
+  // Belt-and-braces: this only runs in a browser (see `ensureChannel`), but guard anyway
+  // so a direct call off-browser never throws a `sessionStorage is not defined` ReferenceError.
+  if (typeof sessionStorage === 'undefined') return `${base}-nostorage`;
   const key = `${base}-tab-id`;
   let id = sessionStorage.getItem(key);
   if (!id) {
@@ -151,5 +202,8 @@ function getTabScopedChannelName(base: string): string {
  */
 export const agenticActivityBus = new AgenticActivityBus({
   crossTabEvents: ['halo-start', 'halo-stop', 'tool-loop-start', 'tool-loop-end'],
-  channelName: getTabScopedChannelName('foundation-ai-activity'),
+  // Lazy: the tab-scoped name (and its `sessionStorage` read) is computed on first
+  // cross-tab use in a browser, not at module-eval — so importing this module is
+  // side-effect-free and Node/test-safe.
+  channelNameFactory: () => getTabScopedChannelName('foundation-ai-activity'),
 });

package/src/chat-driver-node.ts

@@ -0,0 +1,54 @@
+/**
+ * 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';
+export type {
+  AIProvider,
+  AIProviderRegistry,
+  AnthropicModelId,
+  CachePolicy,
+  ChatFallback,
+  ChatMessage,
+  ChatRequestOptions,
+  ChatToolChoice,
+  ChatToolDefinition,
+  ChatToolHandlers,
+  GeminiModelId,
+} from '@genesislcap/foundation-ai';

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

@@ -17,7 +17,7 @@ import {
   ResponseTruncatedError,
 } from '@genesislcap/foundation-ai';
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { agenticActivityBus } from '../../channel/ai-activity-bus';
+import { type ActivityBus, AgenticActivityBus } from '../../channel/ai-activity-bus';
 import type { AgentConfig } from '../../config/config';
 import { clearMetaEventRegistry, getMetaEvents } from '../../state/debug-event-log';
 import { sumCosts } from '../../utils/sum-costs';
@@ -120,18 +120,18 @@ const callsTool = (name: string, id: string): ChatMessage => ({
 const agent = (overrides: Partial<AgentConfig> & { name: string }): AgentConfig =>
   ({ description: 'test agent', ...overrides }) as AgentConfig;
 
-const makeDriver = (config: AgentConfig, provider: AIProvider, sessionKey = ''): ChatDriver => {
-  const driver = new ChatDriver(
-    makeRegistry(provider),
-    {},
-    [],
-    undefined,
-    undefined,
-    50,
-    5,
-    undefined,
+const makeDriver = (
+  config: AgentConfig,
+  provider: AIProvider,
+  sessionKey = '',
+  activityBus?: ActivityBus,
+): ChatDriver => {
+  const driver = new ChatDriver(makeRegistry(provider), {
+    maxToolIterations: 50,
+    maxFoldOperations: 5,
     sessionKey,
-  );
+    activityBus,
+  });
   driver.applyAgent(config);
   return driver;
 };
@@ -159,13 +159,6 @@ const unresolvedEvents = (sessionKey: string): Array<Record<string, unknown>> =>
 
 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', async () => {
   // 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
@@ -363,10 +356,6 @@ stale.run();
 
 const hook = createLogicSuite('ChatDriver onUnresolvedTool hook');
 
-hook.after(() => {
-  agenticActivityBus.close();
-});
-
 hook('replaces the default for a hallucinated tool when the hook returns a string', async () => {
   const config = agent({
     name: 'Hooked',
@@ -722,12 +711,6 @@ cancel.run();
 
 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: unknown): AgentConfig =>
   agent({
@@ -1536,17 +1519,18 @@ interactionContextLifecycle.run();
 
 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', async () => {
   const events: string[] = [];
+  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');
@@ -1562,8 +1546,9 @@ interactionBus('brackets a park with interaction-requested then -resolved', asyn
 
 interactionBus('a timed-out interaction still fires interaction-resolved', async () => {
   const events: string[] = [];
-  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).
@@ -1719,17 +1704,13 @@ const makeObservableRegistry = (initial: AIProvider): ObservableTestRegistry =>
 };
 
 const makeDriverWithRegistry = (config: AgentConfig, registry: AIProviderRegistry): ChatDriver => {
-  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',
   async () => {
@@ -1828,10 +1809,6 @@ const modelProvider = (model: string | undefined, responses: ChatMessage[]): AIP
 
 const modelAttr = createLogicSuite('ChatDriver per-message model attribution');
 
-modelAttr.after(() => {
-  agenticActivityBus.close();
-});
-
 modelAttr('stamps the resolved model and registry name onto an assistant reply', async () => {
   const provider = modelProvider('gemini-2.5-flash-lite', [
     { role: 'assistant', content: 'hi there' },
@@ -1918,9 +1895,6 @@ modelAttr.run();
 // ---------------------------------------------------------------------------
 
 const condense = createLogicSuite('ChatDriver condenseWhen');
-condense.after(() => {
-  agenticActivityBus.close();
-});
 
 const bigBody = 'A'.repeat(2000);
 
@@ -2193,8 +2167,12 @@ condense.run();
 
 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(() => {
-  agenticActivityBus.close();
+  outcomeBus.close();
 });
 
 /**
@@ -2209,7 +2187,7 @@ const captureLoopEnd = (): {
 } => {
   let last: { failureReason?: TurnFailureReason } | undefined;
   let seen = false;
-  const stop = agenticActivityBus.subscribe('tool-loop-end', (d) => {
+  const stop = outcomeBus.subscribe('tool-loop-end', (d) => {
     last = d;
     seen = true;
   });
@@ -2223,17 +2201,12 @@ const makeCappedDriver = (
   maxIterations: number,
   sessionKey = '',
 ): ChatDriver => {
-  const driver = new ChatDriver(
-    makeRegistry(provider),
-    {},
-    [],
-    undefined,
-    undefined,
-    maxIterations,
-    5,
-    undefined,
+  const driver = new ChatDriver(makeRegistry(provider), {
+    maxToolIterations: maxIterations,
+    maxFoldOperations: 5,
     sessionKey,
-  );
+    activityBus: outcomeBus,
+  });
   driver.applyAgent(config);
   return driver;
 };
@@ -2250,7 +2223,7 @@ const assertSurfacesReason = async (
     c,
     p,
     k,
-  ) => makeDriver(c, p, k),
+  ) => makeDriver(c, p, k, outcomeBus),
 ): Promise<void> => {
   clearMetaEventRegistry();
   const sessionKey = `outcome-${label}`;
@@ -2364,6 +2337,7 @@ outcome('a clean turn leaves the legacy shape byte-unchanged (no failureReason)'
     config,
     scriptedProvider([{ role: 'assistant', content: 'hi' }]),
     'outcome-ok',
+    outcomeBus,
   );
   const cap = captureLoopEnd();