@genesislcap/ai-assistant 15.19.0 → 15.19.1

package/src/state/persistence/session-persistence-provider.test.ts

@@ -1,136 +0,0 @@
-import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { WebStorageSessionProvider } from './session-persistence-provider';
-import { createPersistedSession } from './session-snapshot';
-
-// GENC-1351 §5.2: the WebStorageSessionProvider against a fake Storage (no real
-// sessionStorage in Node). Covers round-trip, absent/corrupt entries, clear,
-// and keyPrefix isolation.
-
-/** Minimal in-memory Storage matching the DOM `Storage` shape the provider uses. */
-function fakeStorage(): Storage {
-  const m = new Map<string, string>();
-  return {
-    get length() {
-      return m.size;
-    },
-    clear: () => m.clear(),
-    getItem: (k: string) => (m.has(k) ? m.get(k)! : null),
-    key: (i: number) => [...m.keys()][i] ?? null,
-    removeItem: (k: string) => {
-      m.delete(k);
-    },
-    setItem: (k: string, v: string) => {
-      m.set(k, v);
-    },
-  } as Storage;
-}
-
-const snap = (sessionKey: string) =>
-  createPersistedSession({
-    sessionKey,
-    host: 'app.example',
-    messages: [],
-    pinnedAgentName: null,
-    flowOwnerAgentName: null,
-    sessionCostUsd: 0,
-  });
-
-const Suite = createLogicSuite('web-storage-session-provider');
-
-Suite('save → load round-trips a snapshot', async () => {
-  const provider = new WebStorageSessionProvider(fakeStorage());
-  const s = snap('s1');
-  await provider.save('s1', s);
-  const loaded = await provider.load('s1');
-  // Compare through JSON: createPersistedSession leaves optional keys undefined,
-  // which JSON drops — so normalise both sides the same way.
-  assert.equal(loaded, JSON.parse(JSON.stringify(s)));
-});
-
-Suite('load returns null for an unknown key', async () => {
-  const provider = new WebStorageSessionProvider(fakeStorage());
-  assert.is(await provider.load('missing'), null);
-});
-
-Suite('load returns null (not throw) on a corrupt entry', async () => {
-  const storage = fakeStorage();
-  storage.setItem('genesis-ai-session:s1', '{ not valid json');
-  const provider = new WebStorageSessionProvider(storage);
-  assert.is(await provider.load('s1'), null);
-});
-
-Suite('clear removes the snapshot', async () => {
-  const provider = new WebStorageSessionProvider(fakeStorage());
-  await provider.save('s1', snap('s1'));
-  await provider.clear('s1');
-  assert.is(await provider.load('s1'), null);
-});
-
-Suite('keyPrefix isolates snapshots stored in the same Storage', async () => {
-  const storage = fakeStorage();
-  const a = new WebStorageSessionProvider(storage, { keyPrefix: 'appA' });
-  const b = new WebStorageSessionProvider(storage, { keyPrefix: 'appB' });
-  await a.save('k', snap('k'));
-  assert.is(await b.load('k'), null);
-  assert.ok(await a.load('k'));
-});
-
-Suite('saveDebounceMs defaults to 0 (web storage is sync) and is overridable', () => {
-  assert.is(new WebStorageSessionProvider(fakeStorage()).saveDebounceMs, 0);
-  assert.is(
-    new WebStorageSessionProvider(fakeStorage(), { saveDebounceMs: 1500 }).saveDebounceMs,
-    1500,
-  );
-});
-
-// GENC-1351: user preferences (remember-chat + display toggles) — persisted
-// independently of the snapshot and of the enabled toggle.
-Suite('loadPreferences is undefined until set, then round-trips a blob', async () => {
-  const provider = new WebStorageSessionProvider(fakeStorage());
-  assert.is(
-    await provider.loadPreferences('s1'),
-    undefined,
-    'never saved → undefined (use defaults)',
-  );
-  const prefs = {
-    enabled: false,
-    showToolCalls: true,
-    showThinkingSteps: true,
-    showNarration: false,
-    showAgentSwitchIndicator: true,
-    animations: ['dots'],
-  };
-  await provider.savePreferences('s1', prefs);
-  assert.equal(await provider.loadPreferences('s1'), prefs);
-});
-
-Suite('loadPreferences returns undefined (not throw) on a corrupt entry', async () => {
-  const storage = fakeStorage();
-  storage.setItem('genesis-ai-session:prefs:s1', '{ not valid json');
-  const provider = new WebStorageSessionProvider(storage);
-  assert.is(await provider.loadPreferences('s1'), undefined);
-});
-
-Suite('clear wipes the snapshot but keeps the preferences', async () => {
-  const provider = new WebStorageSessionProvider(fakeStorage());
-  await provider.save('s1', snap('s1'));
-  await provider.savePreferences('s1', { enabled: false, showToolCalls: true });
-  await provider.clear('s1');
-  assert.is(await provider.load('s1'), null, 'snapshot cleared');
-  assert.equal(
-    await provider.loadPreferences('s1'),
-    { enabled: false, showToolCalls: true },
-    'preferences survive clear',
-  );
-});
-
-Suite('preferences are keyPrefix-isolated too', async () => {
-  const storage = fakeStorage();
-  const a = new WebStorageSessionProvider(storage, { keyPrefix: 'appA' });
-  const b = new WebStorageSessionProvider(storage, { keyPrefix: 'appB' });
-  await a.savePreferences('k', { enabled: true });
-  assert.is(await b.loadPreferences('k'), undefined);
-  assert.equal(await a.loadPreferences('k'), { enabled: true });
-});
-
-Suite.run();

package/src/state/persistence/session-persistence-provider.ts

@@ -1,226 +0,0 @@
-import type { CostSessionRecord } from '../../utils/cost-session-history';
-import type { DiagnosticEntry } from './diagnostics';
-import type { PersistedSession } from './session-snapshot';
-
-/**
- * Storage backend for chat-session persistence. The library ships this
- * interface only and wires nothing by default; the host app provides an
- * implementation and opts in via `chatConfig` (GENC-1351 §5.2/D2). Every method
- * is async so a server-backed provider satisfies the same contract as a
- * browser-storage one.
- *
- * @public
- */
-export interface SessionPersistenceProvider {
-  /**
-   * Minimum milliseconds between autosaves for this backend — a throttle the
-   * assistant applies to its "save on every transcript change" signal. `0`
-   * means save as soon as the current tick settles (coalescing only writes
-   * within the same tick), which is right for synchronous, cheap storage like
-   * `sessionStorage`/`localStorage`. A network/server backend should set a
-   * higher value (e.g. 1000–2000) so it doesn't hammer the wire mid tool-loop.
-   *
-   * **Required** — not optional — so every implementation makes a deliberate
-   * choice for its own write-cost profile rather than inheriting a guess.
-   */
-  saveDebounceMs: number;
-  /** Load the snapshot for `sessionKey`, or `null` if none / unreadable. */
-  load(sessionKey: string): Promise<PersistedSession | null>;
-  /** Persist `snapshot` for `sessionKey`, overwriting any existing one. */
-  save(sessionKey: string, snapshot: PersistedSession): Promise<void>;
-  /** Remove any stored snapshot for `sessionKey`. */
-  clear(sessionKey: string): Promise<void>;
-  /**
-   * Load the user's remembered UI preferences for `sessionKey` (GENC-1351) — the
-   * "remember chat" toggle plus the cog-menu display switches. Stored
-   * **independently of the session snapshot** (survives `clear`) and **independently
-   * of the `enabled` toggle** — a user's display choices persist whether or not
-   * they remember the chat. `undefined` means none were ever saved → the host's
-   * configured `chatConfig.ui` defaults apply. Only the fields the user has changed
-   * are present; absent fields keep their config default. Optional: a provider that
-   * omits it simply doesn't remember preferences across reloads.
-   */
-  loadPreferences?(sessionKey: string): Promise<SessionPreferences | undefined>;
-  /** Persist the user's UI preferences for `sessionKey` (kept across `clear`). */
-  savePreferences?(sessionKey: string, preferences: SessionPreferences): Promise<void>;
-
-  /**
-   * Scoped cost/build history — the per-project usage rows behind the Usage tab.
-   *
-   * ‼️ **Keyed by SCOPE, not `sessionKey`**, unlike every other method on this interface.
-   * A row holds one project's lifetime usage and the list spans projects, so keying it
-   * per session would defeat the model. The scope comes from
-   * `chatConfig.costHistory.scope`, falling back to the element `id`, then `'default'`.
-   *
-   * Optional: when a provider omits these, the assistant falls back to `localStorage`, so
-   * hosts that don't implement them are unaffected. Implementing them moves the ledger to
-   * the host's own backend, which is what stops it being stranded in one browser.
-   *
-   * Read/written **independently of the `enabled` toggle** (as with preferences and
-   * diagnostics): usage accounting is not conversation content, so a user turning off
-   * chat retention should not lose their cost ledger. Best-effort — a failed write must
-   * never affect the chat.
-   *
-   * `undefined` from `loadCostHistory` means "nothing stored", the same as `[]`.
-   */
-  loadCostHistory?(scope: string): Promise<CostSessionRecord[] | undefined>;
-  /** Replace the stored row list for `scope`. See {@link SessionPersistenceProvider.loadCostHistory}. */
-  saveCostHistory?(scope: string, records: CostSessionRecord[]): Promise<void>;
-
-  /**
-   * Server-saved diagnostics (GENC-1351 §5.8) — a **forward-only append** stream
-   * that lets the downloadable debug log span the whole session lifetime, not just
-   * the current page load. Optional and **capacious-backends-only**: `WebStorage`
-   * omits it (the log dwarfs the restore core), so the feature is simply off there.
-   * The element emits *what happened* (new entries since the last flush); the
-   * provider owns *how it's filed* (one object per session / per run / per day —
-   * its call). Best-effort: a failed write must never affect the chat.
-   *
-   * Captured **independently of the `enabled` toggle** (like preferences): the
-   * forensic log is orthogonal to whether the *chat* is remembered, so it runs
-   * whenever a provider implements this — even with "remember chat" off.
-   */
-  appendDiagnostics?(sessionKey: string, entries: DiagnosticEntry[]): Promise<void>;
-  /** Load the full diagnostics stream for `sessionKey` (all appends, any run), for download-reassembly. */
-  loadDiagnostics?(sessionKey: string): Promise<DiagnosticEntry[]>;
-  /** Hard-delete the diagnostics stream for `sessionKey`. Host/GDPR use — NOT wired to the UI Clear. */
-  clearDiagnostics?(sessionKey: string): Promise<void>;
-  /**
-   * Min ms between diagnostics appends — coarser than `saveDebounceMs` because
-   * the log is heavy. Defaults to a sensible coarse value if omitted.
-   */
-  diagnosticsDebounceMs?: number;
-}
-
-/**
- * User-changeable settings that persist across reloads, independently of the chat
- * snapshot and of the "remember chat" toggle (GENC-1351). All optional — an absent
- * field keeps its `chatConfig.ui` default rather than being forced off.
- *
- * @public
- */
-export interface SessionPreferences {
-  /** "Remember chat" — whether the session snapshot itself is persisted. */
-  enabled?: boolean;
-  showToolCalls?: boolean;
-  showThinkingSteps?: boolean;
-  showNarration?: boolean;
-  showAgentSwitchIndicator?: boolean;
-  /** Enabled loading-animation ids (`AiAssistantAnimation` values, as plain strings). */
-  animations?: string[];
-}
-
-/**
- * Host-supplied persistence configuration, passed to the assistant via its
- * `persistence` property. Persistence stays inert unless `enabled` is true and
- * a `provider` is set — so existing consumers are unaffected (GENC-1351 D2/D3).
- *
- * @public
- */
-export interface SessionPersistenceConfig {
-  /** Master switch — persistence does nothing unless this is true. */
-  enabled?: boolean;
-  /** Storage backend. Required for persistence to take effect. */
-  provider?: SessionPersistenceProvider;
-}
-
-const DEFAULT_KEY_PREFIX = 'genesis-ai-session';
-
-/**
- * A {@link SessionPersistenceProvider} backed by a Web Storage area. Both
- * `window.sessionStorage` and `window.localStorage` implement the `Storage`
- * API, so one class serves both: point it at `sessionStorage` for
- * refresh-survival that clears on tab close (the showcase default, O6), or at
- * `localStorage` for durable local persistence.
- *
- * Opt-in: a host constructs it and passes it through `chatConfig`; the library
- * never instantiates it on its own.
- *
- * @public
- */
-export class WebStorageSessionProvider implements SessionPersistenceProvider {
-  private readonly storage: Storage;
-  private readonly keyPrefix: string;
-  /**
-   * Web storage is synchronous and cheap, so the default is `0` — save as
-   * soon as the tick settles, no throttle. Override via `options.saveDebounceMs`
-   * (e.g. if pointing at `localStorage` and you'd rather coalesce large writes).
-   */
-  readonly saveDebounceMs: number;
-
-  constructor(storage: Storage, options: { keyPrefix?: string; saveDebounceMs?: number } = {}) {
-    this.storage = storage;
-    this.keyPrefix = options.keyPrefix ?? DEFAULT_KEY_PREFIX;
-    this.saveDebounceMs = options.saveDebounceMs ?? 0;
-  }
-
-  private storageKey(sessionKey: string): string {
-    return `${this.keyPrefix}:${sessionKey}`;
-  }
-
-  /** Preferences key, namespaced apart from the session key so `clear` leaves it. */
-  private preferencesKey(sessionKey: string): string {
-    return `${this.keyPrefix}:prefs:${sessionKey}`;
-  }
-
-  async load(sessionKey: string): Promise<PersistedSession | null> {
-    const raw = this.storage.getItem(this.storageKey(sessionKey));
-    if (!raw) return null;
-    try {
-      return JSON.parse(raw) as PersistedSession;
-    } catch {
-      // A corrupt or partially-written entry is treated as absent rather than
-      // throwing — a bad snapshot must never block the assistant from starting.
-      return null;
-    }
-  }
-
-  async save(sessionKey: string, snapshot: PersistedSession): Promise<void> {
-    const serialized = JSON.stringify(snapshot);
-    try {
-      this.storage.setItem(this.storageKey(sessionKey), serialized);
-    } catch (e) {
-      if (isQuotaExceeded(e)) {
-        throw new Error(
-          `WebStorageSessionProvider: storage quota exceeded saving session "${sessionKey}" ` +
-            `(${serialized.length} chars). Compact the conversation or use a server-backed provider.`,
-        );
-      }
-      throw e;
-    }
-  }
-
-  async clear(sessionKey: string): Promise<void> {
-    this.storage.removeItem(this.storageKey(sessionKey));
-  }
-
-  async loadPreferences(sessionKey: string): Promise<SessionPreferences | undefined> {
-    const raw = this.storage.getItem(this.preferencesKey(sessionKey));
-    if (raw === null) return undefined;
-    try {
-      return JSON.parse(raw) as SessionPreferences;
-    } catch {
-      // A corrupt entry is treated as "no preferences" — never block startup.
-      return undefined;
-    }
-  }
-
-  async savePreferences(sessionKey: string, preferences: SessionPreferences): Promise<void> {
-    // Small blob — quota is a non-issue, so no QuotaExceeded guard.
-    this.storage.setItem(this.preferencesKey(sessionKey), JSON.stringify(preferences));
-  }
-}
-
-/**
- * Web Storage signals an exceeded quota with different `name`s across browsers
- * (`QuotaExceededError` everywhere modern; `NS_ERROR_DOM_QUOTA_REACHED` on
- * older Firefox). The legacy numeric `code`s (22 / 1014) are intentionally not
- * checked — they add nothing for the browsers this app targets.
- */
-function isQuotaExceeded(e: unknown): boolean {
-  return (
-    typeof DOMException !== 'undefined' &&
-    e instanceof DOMException &&
-    (e.name === 'QuotaExceededError' || e.name === 'NS_ERROR_DOM_QUOTA_REACHED')
-  );
-}

package/src/state/persistence/session-persistence.integration.test.ts

@@ -1,141 +0,0 @@
-import type { ChatMessage } from '@genesislcap/foundation-ai';
-import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { aiAssistantSlice, createDefaultSessionState } from '../ai-assistant-slice';
-import { WebStorageSessionProvider } from './session-persistence-provider';
-import {
-  createPersistedSession,
-  isRestorableSession,
-  toLoadSessionPayload,
-  trimToRestorableBoundary,
-} from './session-snapshot';
-
-// GENC-1351 Phase 1 integration: the page-reload cycle the element wires —
-// save on idle → reload drops the in-memory store + provider → restore hydrates
-// a fresh store. Exercises the REAL provider + schema + reducer composed; the
-// custom-element glue (connectedCallback → maybeRestoreSession) is covered by a
-// manual app test.
-
-/** In-memory Storage that survives the simulated reload (like sessionStorage does). */
-function fakeStorage(): Storage {
-  const m = new Map<string, string>();
-  return {
-    get length() {
-      return m.size;
-    },
-    clear: () => m.clear(),
-    getItem: (k: string) => (m.has(k) ? m.get(k)! : null),
-    key: (i: number) => [...m.keys()][i] ?? null,
-    removeItem: (k: string) => {
-      m.delete(k);
-    },
-    setItem: (k: string, v: string) => {
-      m.set(k, v);
-    },
-  } as Storage;
-}
-
-const asMsg = (o: Record<string, unknown>): ChatMessage => o as unknown as ChatMessage;
-const reduce = aiAssistantSlice.reducer;
-const { loadSession } = aiAssistantSlice.actions;
-
-const Suite = createLogicSuite('session-persistence-integration');
-
-Suite('save → reload → restore brings back messages, selection, counters', async () => {
-  const storage = fakeStorage(); // persists across the simulated reload
-  const host = 'app.example';
-  const key = 'assistant::Title';
-
-  // 1. A live session reaches idle with history + a pinned agent.
-  const messages = [
-    asMsg({ role: 'user', content: 'book a trade' }),
-    asMsg({ role: 'assistant', content: 'sure' }),
-  ];
-  await new WebStorageSessionProvider(storage).save(
-    key,
-    createPersistedSession({
-      sessionKey: key,
-      host,
-      messages,
-      activeAgentName: 'Guided Booking',
-      pinnedAgentName: 'Guided Booking',
-      flowOwnerAgentName: null,
-      sessionCostUsd: 0.5,
-      contextTokens: 800,
-      contextLimit: 200000,
-      activeModel: 'claude-sonnet-4-6',
-      activeProviderName: 'anthropic',
-    }),
-  );
-
-  // 2. "Reload": the in-memory store + provider instance are gone; storage remains.
-  const freshStore = createDefaultSessionState();
-  const snapshot = await new WebStorageSessionProvider(storage).load(key);
-  assert.ok(snapshot, 'snapshot survives the reload');
-  assert.ok(isRestorableSession(snapshot, { host }), 'snapshot is restorable for this host');
-
-  // 3. Restore into the fresh store (what maybeRestoreSession does).
-  const restored = reduce(freshStore, loadSession(toLoadSessionPayload(snapshot!)));
-  assert.is(restored.messages.length, 2);
-  assert.is(restored.pinnedAgentName, 'Guided Booking');
-  // Cost comes from the restored transcript, NOT the snapshot's stored counter — so it
-  // is whatever the messages actually carry. Computed independently here rather than
-  // by calling the summing helper under test.
-  const expectedCost = restored.messages.reduce(
-    (sum, m) => sum + (m.cost ?? 0) + (m.externalCostUsd ?? 0),
-    0,
-  );
-  assert.is(restored.sessionUsage.costUsd, expectedCost);
-  assert.is(restored.contextTokens, 800);
-  assert.is(restored.contextLimit, 200000);
-  assert.is(restored.activeModel, 'claude-sonnet-4-6');
-  assert.is(restored.activeProviderName, 'anthropic');
-  assert.is(restored.state, 'idle');
-});
-
-Suite('a cross-host snapshot is rejected on restore', async () => {
-  const storage = fakeStorage();
-  const provider = new WebStorageSessionProvider(storage);
-  await provider.save(
-    'k',
-    createPersistedSession({
-      sessionKey: 'k',
-      host: 'app.example',
-      messages: [asMsg({ role: 'user', content: 'x' })],
-      pinnedAgentName: null,
-      flowOwnerAgentName: null,
-      sessionCostUsd: 0,
-    }),
-  );
-  const snapshot = await provider.load('k');
-  assert.ok(snapshot);
-  assert.ok(!isRestorableSession(snapshot, { host: 'evil.example' }));
-});
-
-Suite('a dangling interaction tail is scrubbed before restore', async () => {
-  const storage = fakeStorage();
-  const provider = new WebStorageSessionProvider(storage);
-  const messages = [
-    asMsg({ role: 'user', content: 'hi' }),
-    asMsg({
-      role: 'assistant',
-      content: '',
-      interaction: { interactionId: '1', componentName: 'x', data: {} },
-    }),
-  ];
-  await provider.save(
-    'k',
-    createPersistedSession({
-      sessionKey: 'k',
-      host: 'h',
-      messages,
-      pinnedAgentName: null,
-      flowOwnerAgentName: null,
-      sessionCostUsd: 0,
-    }),
-  );
-  const snapshot = await provider.load('k');
-  const scrubbed = trimToRestorableBoundary(snapshot!.messages);
-  assert.is(scrubbed.length, 1, 'the unresolved interaction message is dropped');
-});
-
-Suite.run();