@genesislcap/ai-assistant 15.19.0 → 15.19.1

package/src/state/driver-registry.ts

@@ -1,79 +0,0 @@
-import type { AiDriver } from '../components/ai-driver/ai-driver';
-
-/**
- * Module-level registry of AI drivers keyed by session identity string.
- *
- * Driver lifetime is tied to the conversation session, not the DOM.
- * Components look up or create drivers on connect and only unwire
- * event listeners on disconnect — the driver is never destroyed by
- * a lifecycle event.
- *
- * @internal
- */
-interface DriverRegistryEntry {
-  driver: AiDriver;
-  /**
-   * Fingerprint (see `FoundationAiAssistant.getAgentsKey`) of the agents array
-   * the driver was built for. Lets a second component sharing the same session
-   * key recognise that the registry driver already matches its desired agents
-   * and ADOPT it, instead of tearing it down and recreating — which would evict
-   * the sibling's driver and orphan whichever element is mid-turn on it
-   * (GENC-1388).
-   */
-  agentsKey: string;
-}
-
-const driverRegistry = new Map<string, DriverRegistryEntry>();
-
-/**
- * Returns the existing driver for the given key, or calls the factory to create
- * and register a new one. `agentsKey` is the fingerprint of the agents the
- * driver is being built for; it is recorded only when a driver is created (a
- * reused driver keeps the fingerprint it was originally built with).
- */
-export function getOrCreateDriver(
-  key: string,
-  agentsKey: string,
-  factory: () => AiDriver,
-): AiDriver {
-  const existing = driverRegistry.get(key);
-  if (existing) return existing.driver;
-  const driver = factory();
-  driverRegistry.set(key, { driver, agentsKey });
-  return driver;
-}
-
-/**
- * Returns the existing driver for the given key, or `undefined`.
- */
-export function getDriver(key: string): AiDriver | undefined {
-  return driverRegistry.get(key)?.driver;
-}
-
-/**
- * The agents fingerprint the registry driver for `key` was built with, or
- * `undefined` if no driver is registered. Used by `agentsChanged` to decide
- * whether a sibling has already rebuilt the shared driver to the desired agents.
- */
-export function getDriverAgentsKey(key: string): string | undefined {
-  return driverRegistry.get(key)?.agentsKey;
-}
-
-/**
- * Removes and returns the driver for the given key.
- * Used when agents change (driver must be rebuilt) or on explicit session teardown.
- */
-export function deleteDriver(key: string): AiDriver | undefined {
-  const entry = driverRegistry.get(key);
-  driverRegistry.delete(key);
-  return entry?.driver;
-}
-
-/**
- * Removes all entries. Exposed for test isolation only — not part of the public API.
- *
- * @internal
- */
-export function clearDriverRegistry(): void {
-  driverRegistry.clear();
-}

package/src/state/interaction-context.test.ts

@@ -1,90 +0,0 @@
-import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { createInteractionContext } from './interaction-context';
-
-const suite = createLogicSuite('interaction-context factory');
-
-suite('once runs the factory a single time and memoises the result', () => {
-  const { context } = createInteractionContext('id-1');
-  let calls = 0;
-  const first = context.once('ws', () => {
-    calls += 1;
-    return { socket: true };
-  });
-  const second = context.once('ws', () => {
-    calls += 1;
-    return { socket: false };
-  });
-  assert.is(calls, 1, 'factory ran once');
-  assert.is(second, first, 'the memoised value is returned on the second call');
-});
-
-suite('subscribe/notify fans out to listeners; unsubscribe stops them', () => {
-  const { context } = createInteractionContext('id-2');
-  let a = 0;
-  let b = 0;
-  const unsubA = context.subscribe(() => (a += 1));
-  context.subscribe(() => (b += 1));
-
-  context.notify();
-  assert.is(a, 1);
-  assert.is(b, 1);
-
-  unsubA();
-  context.notify();
-  assert.is(a, 1, 'unsubscribed listener no longer fires');
-  assert.is(b, 2, 'remaining listener still fires');
-});
-
-suite('a throwing subscriber does not stop the others', () => {
-  const { context } = createInteractionContext('id-3');
-  let reached = false;
-  context.subscribe(() => {
-    throw new Error('boom');
-  });
-  context.subscribe(() => (reached = true));
-  context.notify();
-  assert.ok(reached, 'later subscriber still ran after an earlier one threw');
-});
-
-suite('dispose runs every onDispose callback once, then is idempotent', () => {
-  const { context, dispose } = createInteractionContext('id-4');
-  let count = 0;
-  context.onDispose(() => (count += 1));
-  context.onDispose(() => (count += 1));
-
-  dispose();
-  assert.is(count, 2, 'both disposers ran');
-  dispose();
-  assert.is(count, 2, 'a second dispose is a no-op');
-});
-
-suite('onDispose registered after dispose runs immediately', () => {
-  const { context, dispose } = createInteractionContext('id-5');
-  dispose();
-  let ran = false;
-  context.onDispose(() => (ran = true));
-  assert.ok(ran, 'late onDispose runs immediately so no resource leaks');
-});
-
-suite('notify after dispose is a no-op (listeners cleared)', () => {
-  const { context, dispose } = createInteractionContext('id-6');
-  let fired = 0;
-  context.subscribe(() => (fired += 1));
-  dispose();
-  context.notify();
-  assert.is(fired, 0, 'no listeners fire after dispose');
-});
-
-suite('once after dispose returns null without running the factory', () => {
-  const { context, dispose } = createInteractionContext('id-7');
-  dispose();
-  let calls = 0;
-  const result = context.once('late', () => {
-    calls += 1;
-    return { socket: true };
-  });
-  assert.is(calls, 0, 'the factory never ran on an ended interaction (no leaked resource)');
-  assert.is(result, null, 'once returns null after dispose');
-});
-
-suite.run();

package/src/state/interaction-context.ts

@@ -1,101 +0,0 @@
-import type { InteractionContext } from '../types/interaction-context';
-import { logger } from '../utils/logger';
-
-/**
- * A created {@link InteractionContext} plus the host-only `dispose` handle. The
- * driver keeps the handle (so it can tear the context down on resolve/evict) and
- * hands only `context` to the widget — widgets must not dispose their own context.
- *
- * @internal
- */
-export interface InteractionContextHandle {
-  readonly context: InteractionContext;
-  /**
-   * Run every registered `onDispose` callback once (in registration order), then
-   * clear listeners. Idempotent. Called by the driver from `resolveInteraction`
-   * and on driver teardown — never on element unmount.
-   */
-  dispose(): void;
-}
-
-/**
- * Create a live, per-interaction context (GENC-1390). Framework-agnostic: the
- * `subscribe`/`notify` pair is a plain observer set, not FAST reactivity. See
- * {@link InteractionContext} for the lifetime/semantics contract.
- *
- * @internal
- */
-export function createInteractionContext(interactionId: string): InteractionContextHandle {
-  const state: Record<string, unknown> = {};
-  const onceCache = new Map<string, unknown>();
-  const listeners = new Set<() => void>();
-  const disposers = new Set<() => void>();
-  let disposed = false;
-
-  const context: InteractionContext = {
-    interactionId,
-    state,
-    once<T>(key: string, factory: () => T): T | null {
-      if (onceCache.has(key)) return onceCache.get(key) as T;
-      // Interaction already ended (resolve/timeout/evict): refuse to run the factory.
-      // A resource created here would leak — dispose has already run every `onDispose`
-      // and won't run again. Return null so a stray late call (e.g. an async callback
-      // that lands after a `timeoutMs` timeout) degrades instead of crashing or leaking.
-      if (disposed) {
-        logger.warn(
-          `InteractionContext.once("${key}") called after dispose; not creating a resource on an ended interaction.`,
-        );
-        return null;
-      }
-      const value = factory();
-      onceCache.set(key, value);
-      return value;
-    },
-    notify(): void {
-      // A Set tolerates a listener unsubscribing mid-walk (matches
-      // interaction-panel-session's forEach); a throwing subscriber must not stop the rest.
-      for (const listener of listeners) {
-        try {
-          listener();
-        } catch (e) {
-          logger.error('InteractionContext subscriber threw during notify()', e);
-        }
-      }
-    },
-    subscribe(listener: () => void): () => void {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    },
-    onDispose(fn: () => void): void {
-      // Late registration after the interaction already ended: run immediately so
-      // callers never leak a resource by registering a beat too late.
-      if (disposed) {
-        fn();
-        return;
-      }
-      disposers.add(fn);
-    },
-  };
-
-  return {
-    context,
-    dispose(): void {
-      if (disposed) return;
-      disposed = true;
-      for (const fn of disposers) {
-        try {
-          fn();
-        } catch (e) {
-          logger.error('InteractionContext onDispose callback threw', e);
-        }
-      }
-      disposers.clear();
-      listeners.clear();
-      // Release memoised `once` values (sockets, timers, service handles) for GC — the resources
-      // themselves are closed via their `onDispose`, but drop the references too.
-      onceCache.clear();
-    },
-  };
-}

package/src/state/persistence/build-timeline-entries.ts

@@ -1,66 +0,0 @@
-/**
- * Shared, pure builder for the debug-log timeline entries (`message` / `turn` / `event`) — the
- * common core of the host element's `buildDiagnosticEntries` and any HEADLESS consumer that drives
- * a `ChatDriver` of its own (e.g. `ai-service` running the engine server-side) and needs to harvest
- * that engine's debug log for the client to fold into its own download / persisted stream
- * (GENC-1461 unified diagnostics). DOM-clean and dependency-light so it works in bare Node.
- *
- * It deliberately excludes the `meta-snapshot` entry: that block is host/DOM-specific (it reads
- * `window.location.host`, the element's agent list, live context/cost), and a merged log keeps only
- * the newest snapshot anyway — a headless source's agent/prompt/tools are already captured in its
- * `turn` entries.
- *
- * @packageDocumentation
- */
-
-import type { ChatMessage } from '@genesislcap/foundation-ai';
-import { flattenSubAgentMessages } from '../../utils/flatten-sub-agent-messages';
-import type { MetaEvent } from '../debug-event-log';
-import type { DiagnosticEntry } from './diagnostics';
-
-/**
- * The minimal shape this builder reads off a turn snapshot. The driver's full `TurnSnapshot` is a
- * structural superset, so it assigns to this without the builder depending on the component layer.
- */
-export interface TurnSnapshotLike {
-  turnIndex: string;
-  systemPrompt?: string;
-}
-
-/**
- * Build the `message` / `turn` / `event` timeline entries from a driver's pull surfaces
- * (`getRawHistory()` / `getTurnSnapshots()` / `getMetaEvents(sessionKey)`). Order within the array
- * is message → turn → event; the caller (`assembleDebugLog`) sorts the whole timeline by timestamp,
- * so this ordering only sets the co-timestamp tie-break. Pure.
- */
-export function buildTimelineEntries(input: {
-  turnSnapshots: readonly TurnSnapshotLike[];
-  messages: readonly ChatMessage[];
-  metaEvents: readonly MetaEvent[];
-}): DiagnosticEntry[] {
-  const { turnSnapshots, messages, metaEvents } = input;
-
-  // Collapse a turn's systemPrompt when byte-identical to the previous turn's — a stable agent
-  // repeats the same (often multi-KB) prompt every turn, while a stateful agent's changes. The
-  // prompt is shown in full whenever it changes, so prompt evolution stays visible.
-  let lastFullPrompt: string | undefined;
-  let lastFullIndex = '';
-  const turns = turnSnapshots.map((t) => {
-    let { systemPrompt } = t;
-    if (systemPrompt != null && systemPrompt === lastFullPrompt) {
-      systemPrompt = `<repeated — identical to turn ${lastFullIndex}>`;
-    } else if (systemPrompt != null) {
-      lastFullPrompt = systemPrompt;
-      lastFullIndex = t.turnIndex;
-    }
-    return { kind: 'turn' as const, ...t, systemPrompt };
-  });
-
-  // Sub-agent conversations are stored nested on the parent tool call's `subAgentTrace`;
-  // `flattenSubAgentMessages` hoists them to top-level `kind: 'message'` entries (breadcrumbed +
-  // correlated, the nested copy moved out — not duplicated) so the timeline reads chronologically.
-  const messageEntries = flattenSubAgentMessages(messages);
-  const eventEntries = metaEvents.map((e) => ({ kind: 'event' as const, ...e }));
-
-  return [...messageEntries, ...turns, ...eventEntries] as DiagnosticEntry[];
-}

package/src/state/persistence/diagnostics-cursors.test.ts

@@ -1,53 +0,0 @@
-import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import {
-  clearDiagnosticsCursorRegistry,
-  deleteDiagnosticsCursorsFor,
-  getDiagnosticsCursors,
-  resetDiagnosticsCursorsFor,
-} from './diagnostics-cursors';
-
-// GENC-1351 §5.8/§5.12 (#9): the forward-capture cursors, and the crucial difference
-// between the Clear reset (keep the event high-water) and the in-place-switch delete
-// (fresh cursors, because the meta-event buffer is torn down and its indices restart).
-
-const KEY = 'session-1';
-
-const Suite = createLogicSuite('diagnostics-cursors');
-
-Suite.before.each(() => {
-  clearDiagnosticsCursorRegistry();
-});
-
-Suite('resetDiagnosticsCursorsFor KEEPS lastEventIndex (Clear: meta buffer keeps climbing)', () => {
-  const c = getDiagnosticsCursors(KEY);
-  c.lastEventIndex = 40;
-  c.emittedMsgKeys.add('m');
-  c.restoredMsgKeys.add('r');
-  resetDiagnosticsCursorsFor(KEY);
-  const after = getDiagnosticsCursors(KEY);
-  assert.is(
-    after.lastEventIndex,
-    40,
-    'event high-water kept — Clear does not reset the meta buffer',
-  );
-  assert.is(after.emittedMsgKeys.size, 0, 'per-conversation message cursors restarted');
-  assert.is(after.restoredMsgKeys.size, 0, 'restore watermark restarted');
-});
-
-Suite(
-  'deleteDiagnosticsCursorsFor RESETS lastEventIndex (switch: meta buffer restarts at 0)',
-  () => {
-    const c = getDiagnosticsCursors(KEY);
-    c.lastEventIndex = 40;
-    deleteDiagnosticsCursorsFor(KEY);
-    // A later return re-creates fresh cursors on first access.
-    const after = getDiagnosticsCursors(KEY);
-    assert.is(
-      after.lastEventIndex,
-      -1,
-      'fresh cursor — a returning session whose events restart at 0 is NOT skipped',
-    );
-  },
-);
-
-Suite.run();

package/src/state/persistence/diagnostics-cursors.ts

@@ -1,80 +0,0 @@
-/**
- * Per-session forward-capture cursors for the server-saved diagnostics stream
- * (GENC-1351 §5.8). Module-level and keyed by the session `stateKey` — exactly like
- * the meta-event buffer — so the (up to two) element instances that share one
- * session (a collapsed bubble + a popped-out panel) share ONE set of cursors.
- *
- * Without this each instance keeps its own cursors and both independently append
- * the shared driver's activity, double-writing the stream — and, worse, the second
- * instance (which never runs restore, so its message watermark stays empty)
- * re-appends the *entire* restored history on every reload. Module state dies with
- * the JS realm, so these reset for free on a real page reload (like the meta
- * buffer), which is exactly the "fresh capture per page load" behaviour we want.
- *
- * @internal
- */
-export interface DiagnosticsCursors {
-  /** Message identities present at restore — never appended (they live in a prior load's stream). */
-  restoredMsgKeys: Set<string>;
-  /** Message identities already appended this load. */
-  emittedMsgKeys: Set<string>;
-  /** Turn indices already appended this load. */
-  emittedTurnKeys: Set<string>;
-  /** Highest meta-event index already appended. */
-  lastEventIndex: number;
-  /** JSON of the last meta-snapshot appended — skip re-appending an unchanged block. */
-  lastMetaJson: string;
-}
-
-const cursorsByKey = new Map<string, DiagnosticsCursors>();
-
-const freshCursors = (): DiagnosticsCursors => ({
-  restoredMsgKeys: new Set(),
-  emittedMsgKeys: new Set(),
-  emittedTurnKeys: new Set(),
-  lastEventIndex: -1,
-  lastMetaJson: '',
-});
-
-/** The shared cursors for `key`, created (empty) on first access. @internal */
-export function getDiagnosticsCursors(key: string): DiagnosticsCursors {
-  let cursors = cursorsByKey.get(key);
-  if (!cursors) {
-    cursors = freshCursors();
-    cursorsByKey.set(key, cursors);
-  }
-  return cursors;
-}
-
-/**
- * Restart the per-conversation cursors for `key` on Clear — a new conversation in
- * the same page load. `lastEventIndex` is intentionally kept: Clear does NOT reset
- * the meta-event buffer, so its indices keep climbing and mustn't be re-emitted.
- *
- * @internal
- */
-export function resetDiagnosticsCursorsFor(key: string): void {
-  const cursors = getDiagnosticsCursors(key);
-  cursors.restoredMsgKeys = new Set();
-  cursors.emittedMsgKeys = new Set();
-  cursors.emittedTurnKeys = new Set();
-}
-
-/**
- * Drop the cursors for `key` entirely — the in-place session switch teardown
- * (GENC-1351 §5.12). Unlike {@link resetDiagnosticsCursorsFor}, this does NOT keep
- * `lastEventIndex`: a switch also tears down the session's meta-event buffer (its
- * indices restart at 0 on a later return), so a kept high-water index would skip
- * every event of the resumed session. A return re-creates fresh cursors on first
- * access.
- *
- * @internal
- */
-export function deleteDiagnosticsCursorsFor(key: string): void {
-  cursorsByKey.delete(key);
-}
-
-/** Drop all cursors — test isolation only. @internal */
-export function clearDiagnosticsCursorRegistry(): void {
-  cursorsByKey.clear();
-}