@genesislcap/ai-assistant 14.488.1 → 14.488.2-GENC-1351.2

package/dist/ai-assistant.d.ts

@@ -8,8 +8,8 @@ import type { ChatConfig } from '@genesislcap/foundation-ai';
 import type { ChatDriverResult } from '@genesislcap/foundation-ai';
 import type { ChatInputDuringExecutionMode } from '@genesislcap/foundation-ai';
 import type { ChatMessage } from '@genesislcap/foundation-ai';
-import { ChatToolChoice } from '@genesislcap/foundation-ai';
-import { ChatToolDefinition } from '@genesislcap/foundation-ai';
+import type { ChatToolChoice } from '@genesislcap/foundation-ai';
+import type { ChatToolDefinition } from '@genesislcap/foundation-ai';
 import type { ChatToolHandlers } from '@genesislcap/foundation-ai';
 import { GenesisElement } from '@genesislcap/web-core';
 import type { InteractionRequestOptions } from '@genesislcap/foundation-ai';
@@ -217,6 +217,40 @@ export declare interface AgentLifecycleContext {
     previousAgentName?: string;
     /** Aborted if the session disconnects mid-activation. */
     signal: AbortSignal;
+    /**
+     * A previously-serialized state image for this agent (from the agent's
+     * `serialize`), passed only on `onActivate` when resuming a persisted
+     * session. A stateful
+     * agent's `init` rebuilds from it — e.g. via `restoreMachine` — or starts
+     * fresh when it is `undefined`.
+     */
+    restored?: unknown;
+}
+
+/**
+ * Context passed to an agent's `resumable` predicate (GENC-1351 §5.9), evaluated
+ * at session-save time on the active agent (which, for a locked guided flow, is
+ * the flow-owner).
+ *
+ * @beta
+ */
+export declare interface AgentPersistenceContext {
+    /** The agent being consulted. */
+    agentName: string;
+    /** The assistant session key — stable across reloads. */
+    sessionKey: string;
+    /**
+     * This agent's just-serialized state image — the value its `serialize()`
+     * returned for this save (or the carried-forward image). Inspect the machine
+     * step here. Derive the decision from this (not live closure state): the
+     * predicate must be a pure function of the state so a resumable snapshot stays
+     * resumable when re-evaluated on restore.
+     */
+    state: unknown;
+    /** Full conversation transcript at save time. */
+    messages: ReadonlyArray<ChatMessage>;
+    /** True when this agent currently owns the guided flow (`name === flowOwnerAgentName`). */
+    isFlowOwner: boolean;
 }
 
 /**
@@ -306,6 +340,41 @@ export declare interface AiAssistantAnimationDef {
     category: string;
 }
 
+/**
+ * DOM events the `<foundation-ai-assistant>` element dispatches to its host.
+ * All bubble and are `composed` (they cross the shadow boundary), so a host can
+ * listen on the element — or any ancestor — to react. Use these constants to
+ * wire listeners instead of hand-typing event-name strings.
+ *
+ * An `as const` map (not a TS `enum` — this package ships none), so it serves as
+ * both the listener-name value and, via the same-named type below, a union.
+ *
+ * @example
+ * ```ts
+ * import { AiAssistantEvent, type SessionClearedDetail } from '@genesislcap/ai-assistant';
+ *
+ * el.addEventListener(AiAssistantEvent.SessionCleared, (e) => {
+ *   const { agentName, agentSnapshot } = (e as CustomEvent<SessionClearedDetail>).detail;
+ *   // …clean up external state the agent was working on…
+ * });
+ * ```
+ *
+ * @beta
+ */
+export declare const AiAssistantEvent: {
+    /** Session wiped via the lifecycle menu's Clear. `detail`: `SessionClearedDetail`. */
+    readonly SessionCleared: "session-cleared";
+    /** Header pressed in `popout-mode="expand"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */
+    readonly ChatHeaderMouseDown: "chat-header-mousedown";
+};
+
+/**
+ * One of the `AiAssistantEvent` event-name values.
+ *
+ * @beta
+ */
+export declare type AiAssistantEvent = (typeof AiAssistantEvent)[keyof typeof AiAssistantEvent];
+
 /**
  * State of the AI assistant component.
  *
@@ -401,10 +470,41 @@ export declare interface AiDriver extends EventTarget {
      * Seed the driver's message history (called on state restore / pop-in).
      */
     loadHistory(messages: ChatMessage[]): void;
+    /**
+     * Prime per-agent restored state for a session being rehydrated. Each entry
+     * (keyed by agent name) is handed to that agent's `onActivate`/`init` as
+     * `ctx.restored` on its next activation, then consumed. Optional — only
+     * multi-agent drivers that own agent activation implement it.
+     */
+    primeRestoredAgentState?(snapshots: Record<string, unknown>): void;
     /**
      * Return the full, unredacted conversation history.
      */
     getRawHistory?(): readonly ChatMessage[];
+    /**
+     * The live `AgentConfig` currently active in the driver — the instance whose
+     * `onActivate` ran, so its `serialize`/`getDebugSnapshot` closures hold live
+     * state. Prefer this over looking the agent up in the host's `agents` array,
+     * which may mint fresh, never-activated configs. Optional — only drivers that
+     * retain the active config implement it.
+     */
+    getActiveAgent?(): AgentConfig | undefined;
+    /**
+     * Destructively compact older conversation turns into a single
+     * `compacted-summary` message (GENC-1351 §5.7), summarizing them via the
+     * default provider's one-shot `prompt()`. Atomic: history changes only on
+     * success. Resolves to the created summary message, or `null` when there is
+     * nothing worth compacting or the provider cannot summarize. Optional — only
+     * drivers that own history implement it.
+     */
+    compact?(): Promise<ChatMessage | null>;
+    /**
+     * Whether `compact()` would compact something right now — a summarizable run of
+     * older turns exists behind a clean boundary. The UI gates its "Compact"
+     * affordance on this, so the button reflects the exact history `compact()` acts
+     * on (GENC-1351). Optional — only history-owning drivers implement it.
+     */
+    canCompact?(): boolean;
     /**
      * Returns true if the driver is currently processing a request.
      */
@@ -528,6 +628,20 @@ export declare const ANIMATION_DEFS: {
     };
 };
 
+/**
+ * Reassemble diagnostic entries into the `{ readme, timeline, meta }` debug-log
+ * shape (GENC-1351 §5.8). `timeline` = the `message`/`turn`/`event` entries sorted
+ * by ISO `timestamp` (kind-rank tie-break). `meta` = the **newest** `meta-snapshot`'s
+ * block only — a "state at export" photo, matching the single-page log. The older
+ * snapshots are intentionally dropped: the per-turn evolution they would show is
+ * already in the timeline (`turn.agentSnapshot` + `context.updated` events), so
+ * keeping them would just repeat the bulky, near-static `agentSummary`. `readme` =
+ * the passed (current) constant. Pure — reused for both the live current-page log
+ * and the reassembled lifetime log stitched from the persisted stream, so both
+ * come out shape-identical.
+ */
+export declare function assembleDebugLog(entries: DiagnosticEntry[], readme: readonly string[]): DebugLog;
+
 /**
  * App-supplied settings for the platform settings modal UI Builder section.
  * Register a concrete implementation on the DI token at app bootstrap; the
@@ -742,6 +856,43 @@ declare interface BaseAgentConfig {
      * @beta
      */
     getDebugSnapshot?: () => unknown;
+    /**
+     * Returns a lossless, JSON-serializable image of the agent's state for session
+     * persistence — distinct from `getDebugSnapshot`, which may abbreviate for
+     * readability. Pass the value back to the agent on restore (as
+     * `ctx.restored` in its `init`) to resume. {@link defineStatefulAgent} wires a
+     * default that snapshots any machine-shaped state via `getPersistedSnapshot()`
+     * and returns plain state as-is.
+     *
+     * @beta
+     */
+    serialize?: () => unknown;
+    /**
+     * Whether the agent's current state is resumable — i.e. worth persisting so the
+     * session can be restored mid-flow (GENC-1351 §5.9). Consulted at save time on
+     * the active agent (the flow-owner during a locked flow). Return `true`
+     * (or leave the field absent) to persist and resume normally; return `false`
+     * for a point that shouldn't be resumed — the session is not persisted, and on
+     * return the assistant shows {@link AgentConfig.notResumableMessage} (or a
+     * default) and pre-fills the composer with the prompt that started the flow so
+     * the user can re-run it.
+     *
+     * Only consulted when the user has persistence enabled. Must be a **pure
+     * function of `ctx.state`** — it may be re-evaluated on a restored snapshot, so
+     * a resumable state must stay resumable. A thrown error is treated as `true`
+     * (fail-safe: never drop a resumable chat on a predicate bug).
+     *
+     * @beta
+     */
+    resumable?: (ctx: AgentPersistenceContext) => boolean | Promise<boolean>;
+    /**
+     * Message shown on return when {@link AgentConfig.resumable} returned `false`
+     * and the user comes back to a non-resumable session (GENC-1351 §5.9). Falls
+     * back to a built-in default when omitted.
+     *
+     * @beta
+     */
+    notResumableMessage?: string;
 }
 
 export { CachePolicy }
@@ -1195,6 +1346,22 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     /** Returns the current fold stack names for debugging. */
     getActiveFoldNames(): string[];
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
+    /**
+     * Whether `compact()` would do anything right now — a summarizable run of older
+     * turns exists behind a clean boundary. Uses the same `history` `compact()`
+     * acts on, so the UI's gate can't disagree with the action (GENC-1351 follow-up).
+     */
+    canCompact(): boolean;
+    /**
+     * Destructively compact older turns into a single `compacted-summary` message
+     * (GENC-1351 §5.7). Summarizes everything before a clean recent-tail boundary
+     * via the registry-default provider's one-shot `prompt()`, then **atomically**
+     * replaces the covered turns with one summary message at the head — history is
+     * mutated only on success. Rolling: any existing head summary is folded into
+     * the new one. Returns the created summary message, or `null` when there is
+     * nothing worth compacting or the default provider cannot summarize.
+     */
+    compact(): Promise<ChatMessage | null>;
     isBusy(): boolean;
     /** Register an assistant view (host) wired to this shared driver. @internal */
     registerHost(hostId: string): void;
@@ -1329,6 +1496,16 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private appendToHistory;
 }
 
+/**
+ * `detail` of the `AiAssistantEvent.ChatHeaderMouseDown` event.
+ *
+ * @beta
+ */
+export declare interface ChatHeaderMouseDownDetail {
+    clientX: number;
+    clientY: number;
+}
+
 /**
  * Detail payload for the `chat-header-mousedown` event fired by the assistant
  * in `popout-mode="expand"`.
@@ -1439,6 +1616,13 @@ export declare function createToolFold(config: {
     exclusive?: boolean;
 }): ToolFoldResult;
 
+/** The reassembled debug log — the exact shape `getDebugLog()` returns. @public */
+export declare interface DebugLog {
+    readme: readonly string[];
+    timeline: DiagnosticEntry[];
+    meta: unknown;
+}
+
 /**
  * Animations enabled by default when a consumer opts into the animations
  * feature without specifying an explicit `enabled` list. Keeps the dots loading
@@ -1492,6 +1676,25 @@ export declare function defineAgent<const T extends AgentConfig>(config: T): T;
  */
 export declare function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig;
 
+/**
+ * One entry in the diagnostics stream — the debug-log timeline-entry union
+ * (`message` / `turn` / `event`, as `getDebugLog()` builds) plus a point-in-time
+ * **`meta-snapshot`** carrying the export-time `meta` block (agent summary,
+ * context, active debug snapshot, …). Kept permissive: a provider stores and
+ * returns these opaquely, and reassembly reads only `kind`, `timestamp` (for
+ * ordering), and `meta` (on a snapshot).
+ *
+ * @public
+ */
+export declare interface DiagnosticEntry {
+    kind: 'message' | 'turn' | 'event' | 'meta-snapshot';
+    /** ISO timestamp — string-comparable, so it orders the stream chronologically. */
+    timestamp?: string;
+    /** Present on `meta-snapshot` entries: the export-time `meta` block. */
+    meta?: unknown;
+    [key: string]: unknown;
+}
+
 /**
  * Expands a flat list of tool definitions into a nested tree by resolving fold
  * metadata from the corresponding handlers. Use this for debug output so the
@@ -1581,6 +1784,15 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     agents?: AgentConfig[];
     chatConfig: ChatConfig;
+    /**
+     * Optional session persistence (GENC-1351). Off by default — set `enabled`
+     * and a `provider` (e.g. a `WebStorageSessionProvider`) to have the assistant
+     * autosave on idle and auto-restore the conversation on page reload. Exposed
+     * as a top-level property (like `agents`/`providerRegistry`) rather than via
+     * `chatConfig`, since the provider type lives in this package while
+     * `ChatConfig` lives in `foundation-ai`.
+     */
+    persistence: SessionPersistenceConfig;
     /**
      * Resolved agent picker mode from `chatConfig.picker.mode`. Defaults to
      * `'disabled'`.
@@ -1654,6 +1866,27 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     get agentPickerOpen(): boolean;
     set agentPickerOpen(value: boolean);
+    /**
+     * Whether the lifecycle (session) menu slide-out panel is open. Like the
+     * agent picker, lives on the session store so bubble/popout stay in sync.
+     */
+    get sessionMenuOpen(): boolean;
+    set sessionMenuOpen(value: boolean);
+    /**
+     * Whether a manual compaction is in flight (GENC-1351 §5.7). On the session
+     * store (not element-local) so the "Compacting…" view + input-disable stay in
+     * sync across pop-in/out, like the panel flags.
+     */
+    get compacting(): boolean;
+    set compacting(value: boolean);
+    /**
+     * Whether a page-reload restore is in flight (GENC-1351 §6). On the session
+     * store (like `compacting`) so the "Restoring…" view + input-disable stay in
+     * sync across pop-in/out. Gating input while true prevents a mid-load send from
+     * being clobbered when the restored history loads.
+     */
+    get restoring(): boolean;
+    set restoring(value: boolean);
     /**
      * Name of the agent the user has pinned via the agent picker. `null` means
      * automatic routing (Auto). Persisted on the session store, so it survives
@@ -1747,6 +1980,14 @@ export declare class FoundationAiAssistant extends GenesisElement {
     appSettingsRevision: number;
     /** Whether the settings modal is open. */
     settingsOpen: boolean;
+    /**
+     * True while `downloadDebugLog` is building the log (GENC-1351 §5.8). Drives the
+     * download button's disabled + spinner state — the lifetime-stitch path is async
+     * (a provider `loadDiagnostics` round-trip), so without feedback a click looks
+     * like nothing happened. Per-instance and transient (not shared/persisted): each
+     * element has its own settings modal.
+     */
+    downloadingDebugLog: boolean;
     /** Active tab inside the settings modal. */
     settingsModalTab: SettingsModalTab;
     /** Bound to the design-system modal via the template ref. */
@@ -1840,6 +2081,21 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * originating `send()` ran on a different element instance.
      */
     private _executionCompletionUnsub?;
+    /**
+     * True while UI preferences are being applied programmatically (config defaults
+     * on connect, or a loaded-preferences restore) — suppresses the save hook so we
+     * don't persist config defaults or re-persist what we just loaded. Cleared once
+     * the apply completes; a genuine *user* toggle (menu switch) runs with it false
+     * and saves (GENC-1351).
+     */
+    private _applyingPreferences;
+    /**
+     * Fresh-store flag (`= isNewStore`) captured in `connectedCallback`. Only a
+     * freshly created store takes the config/stored-prefs baseline; an existing
+     * store — a reload with a live in-realm store, or the popped-out second instance
+     * — already holds the correct state, so `applyPreferenceBaseline` no-ops for it.
+     */
+    private _freshStore;
     showHalo: 'no' | 'orchestrating' | 'agent';
     private syncShowHalo;
     /** True when there is a pending (unresolved) interaction. */
@@ -1949,6 +2205,95 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private logMeta;
     private readonly _agentPickerToggle;
     toggleAgentPicker(): void;
+    /** Two-step confirm for the destructive Clear action; reset whenever the menu toggles. */
+    confirmingClear: boolean;
+    confirmingCompact: boolean;
+    private readonly _sessionMenuToggle;
+    /**
+     * Whether the lifecycle-menu button shows. It occupies the stop-button slot,
+     * so it only appears when idle (mutually exclusive with Stop). Needs
+     * something to act on: a chat to clear/compact, or a provider to toggle.
+     */
+    get sessionMenuEnabled(): boolean;
+    /** The persistence toggle row renders only when a provider is configured. */
+    get persistenceToggleable(): boolean;
+    /** Whether persistence is currently active (on + a provider) for this session. */
+    get persistenceActive(): boolean;
+    /**
+     * Whether the menu's "Compact" action would do anything (GENC-1351 §5.7).
+     * Delegates to `driver.canCompact()` so the gate uses the exact same history
+     * `compact()` acts on — one source of truth. Also reads `messages`, purely to
+     * stay reactive as the conversation grows: the driver's history isn't a tracked
+     * observable, so the button keys its re-evaluation off the Redux mirror.
+     */
+    get compactable(): boolean;
+    toggleSessionMenu(): void;
+    /**
+     * Set persistence on/off for this session (the menu switch). Reassigns the
+     * `persistence` object so the `@observable` fires. Turning it **off** drops the
+     * stored snapshot; **on** captures the current chat immediately. Either way the
+     * *choice* is remembered in the preferences blob (`persistPreferences`) — stored
+     * independently of the snapshot, so it survives the clear and re-applies on the
+     * next load (GENC-1351).
+     */
+    setPersistenceEnabled(enabled: boolean): void;
+    /** Toggle persistence (convenience / programmatic). */
+    togglePersistence(): void;
+    /** Snapshot the user-changeable settings into a persistable preferences blob. */
+    private gatherPreferences;
+    /**
+     * Persist the current UI preferences whenever the user changes a setting
+     * (GENC-1351). Fires **regardless of "remember chat"** — display choices are the
+     * user's, not tied to whether the chat is remembered — needing only a provider
+     * that implements `savePreferences`. No-op while preferences are being applied
+     * programmatically (`_applyingPreferences`), so config defaults and loaded prefs
+     * aren't re-saved.
+     */
+    private persistPreferences;
+    /**
+     * Apply the effective UI-preference baseline onto the live toggles for a fresh
+     * store (GENC-1351 #2). Precedence, lowest → highest:
+     *
+     *   slice defaults  <  `chatConfig.ui` defaults  <  stored user preferences
+     *
+     * Recomputed from scratch (not layered) on every call, because its two inputs
+     * arrive at unpredictable times: `chatConfig` is a parent-supplied `@observable`
+     * that may bind *after* `connectedCallback`, and stored prefs load asynchronously.
+     * So it re-runs from `connectedCallback`, `chatConfigChanged`, and once
+     * `loadPreferences` resolves — whichever order they happen in, the final state is
+     * the same. No-op once the store isn't fresh (an existing/popped-out store owns
+     * its state) or the user has toggled something (their choice then wins, and
+     * `chatConfig` doesn't change post-startup in practice). Save hook suppressed so
+     * applying the baseline never persists as if it were a user choice.
+     *
+     * This is the fix for "nuking server prefs drops to all-disabled instead of the
+     * `chatConfig` defaults": stored prefs are simply absent, so the baseline falls
+     * through to the config layer — which the old apply-once-on-connect path missed
+     * whenever `chatConfig` hadn't bound yet.
+     */
+    private applyPreferenceBaseline;
+    /**
+     * Compact the conversation (GENC-1351 §5.7) — the menu's "Compact" action.
+     * Delegates to the driver, which summarizes older turns into a single
+     * `compacted-summary` message (destructive, atomic). On success records a
+     * high-importance `context.compacted` meta-event capturing the summary; the
+     * normal `history-updated` → autosave path then persists the smaller
+     * transcript. No-op when there is nothing to compact or the provider cannot
+     * summarize (the driver returns `null`).
+     */
+    compactSession(): Promise<void>;
+    /**
+     * Clear the session — the "New chat" action (GENC-1351 §5.6). Tears down the
+     * active driver (firing the stateful agent's `onDeactivate` → `machine.stop()`),
+     * resets the store, rebuilds a fresh driver with no history, and wipes durable
+     * storage. Mirrors `agentsChanged`'s teardown, minus the history reseed.
+     *
+     * @fires session-cleared - After the session is wiped. `detail`:
+     *   `{ sessionKey, agentName?, agentSnapshot? }` — captured *before* teardown
+     *   so the host can clean up any external state the active agent was working
+     *   on (generated files, server-side scratch, etc.). Bubbles and composed.
+     */
+    clearSession(): Promise<void>;
     /**
      * Programmatically pin an agent by name. Returns `true` if the pin was
      * applied, `false` if the agent isn't in the configured agents array or
@@ -2038,68 +2383,45 @@ export declare class FoundationAiAssistant extends GenesisElement {
     toggleShowNarration(): void;
     toggleShowAgentSwitchIndicator(): void;
     setEnabledAnimations(animations: AiAssistantAnimation[]): void;
-    getDebugLog(): {
-        readme: readonly string[];
-        timeline: (TimelineMessage | {
-            systemPrompt: string;
-            turnIndex: string;
-            timestamp: string;
-            agentName?: string;
-            tailContext?: string;
-            toolNames: string[];
-            temperature?: number;
-            toolChoice?: ChatToolChoice;
-            agentLabel?: string;
-            agentSnapshot?: unknown;
-            kind: "turn";
-        } | {
-            index: number;
-            timestamp: string;
-            type: MetaEventType;
-            importance: MetaEventImportance;
-            detail?: Record<string, unknown>;
-            kind: "event";
-        })[];
-        meta: {
-            timestamp: string;
-            host: string;
-            agentSummary: {
-                toolDefinitions: string | ChatToolDefinition[];
-                name: string;
-                provider?: ProviderInput;
-                chatInputDuringExecution?: ChatInputDuringExecutionMode;
-                description?: string;
-                fallback?: true;
-                displayName?: SystemPromptInput;
-                systemPrompt?: SystemPromptInput;
-                temperature?: TemperatureInput;
-                toolChoice?: ToolChoiceInput;
-                cachePolicy?: CachePolicyInput;
-                tailContext?: TailContextInput;
-                onUnresolvedTool?: UnresolvedToolInput;
-                primerHistory?: ChatMessage[];
-                subAgents?: AgentConfig[];
-                manualSelection?: ManualSelectionConfig;
-                onActivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
-                onDeactivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
-                getDebugSnapshot?: () => unknown;
-            }[];
-            activeSystemPrompt: string;
-            activePrimerHistory: ChatMessage[];
-            activeFoldStack: string[];
-            context: {
-                model: string;
-                contextTokens: number;
-                contextLimit: number;
-                contextUsagePercent: number;
-                sessionCostUsd: number;
-                sessionTokensConsumed: number;
-            };
-            activeDebugSnapshot: unknown;
-            debug: unknown;
-        };
-    };
-    downloadDebugLog(): void;
+    /** The live current-page debug log (`{ readme, timeline, meta }`). @public */
+    getDebugLog(): DebugLog;
+    /**
+     * Build the current page's diagnostic entries (GENC-1351 §5.8) — the debug-log
+     * timeline entries (`message`/`turn`/`event`) plus one `meta-snapshot` carrying
+     * the export-time `meta` block. `getDebugLog()` reassembles these into the live
+     * log; the persister's forward-capture path (`SessionPersister.flushDiagnostics`,
+     * fed these via the `getDiagnosticEntries` dep) diffs them against what's already
+     * been appended to the persisted stream.
+     */
+    private buildDiagnosticEntries;
+    downloadDebugLog(): Promise<void>;
+    /**
+     * The log to download (GENC-1351 §5.8). When the provider persists diagnostics,
+     * stitch the **whole lifetime** stream (every page load) rather than just the
+     * current page's in-memory view: flush the current delta first so it's included,
+     * then reassemble everything `loadDiagnostics` returns. Independent of "remember
+     * chat" — diagnostics are a forensic stream keyed on provider capability, not on
+     * whether the *chat* is remembered (like preferences). Falls back to the live
+     * current-page log when diagnostics isn't available or the fetch fails.
+     */
+    private buildDownloadLog;
+    /**
+     * The shared per-session `SessionPersister` that owns restore-core
+     * save/restore/freeze (GENC-1351 §5.10). Created once per `stateKey` and shared by
+     * every element view (bubble + panel) via the registry, so there is a single save
+     * timer + carry-forward cache — no per-view double-writes. The deps are getters so
+     * the persister always reads the current driver/store/config and never holds a
+     * stale reference. `undefined` before the session key is available.
+     */
+    private persister;
+    /**
+     * First-load persistence init for a freshly created store (GENC-1351). Restores
+     * the user's remembered persistence-toggle choice — kept independently of the
+     * session snapshot so it survives a clear; the host-configured `enabled` is only
+     * the default for a first-ever load — then auto-restores the session when
+     * persistence is (now) on.
+     */
+    private initPersistenceForNewStore;
     triggerFileInput(): void;
     handleFileSelect(e: Event): void;
     removeAttachment(attachment: ChatAttachment): void;
@@ -2285,44 +2607,6 @@ export declare interface ManualSelectionConfig {
     hint?: string;
 }
 
-/**
- * How much a reader should care about an event — lets a consumer (or an AI
- * agent) filter the timeline: skip `low` UI/bookkeeping noise, skim `normal`
- * session flow, or jump straight to `high` problem/limit signals when triaging.
- */
-declare type MetaEventImportance = 'high' | 'normal' | 'low';
-
-/**
- * Module-level append-only timeline of meta/lifecycle events, keyed by session
- * identity (the same `stateKey` space used by the driver registry and the
- * session store).
- *
- * Why a module registry rather than the redux store or the driver:
- * - **Survives the pop-in/pop-out element churn.** A single session can be
- *   emitted from up to two element instances (an `expand` bubble + a `collapse`
- *   panel) sharing one driver; keying by `stateKey` unifies them into one
- *   timeline.
- * - **Survives driver rebuilds.** The driver is torn down and recreated when the
- *   host swaps the agents array (see `agentsChanged` / `deleteDriver`), so a
- *   driver-owned buffer would lose the timeline mid-session. The `stateKey`
- *   outlives the driver.
- * - **Stays out of redux reactivity.** These appends never drive the UI, so
- *   there's no reason to pay immutable-reducer cost or flood the Redux DevTools
- *   action log with debug noise.
- *
- * Surfaced in `getDebugLog().timeline`, merged chronologically with messages and
- * turn snapshots. Ring-buffered — the oldest non-`high` events are evicted first
- * while `high`-importance failure events are retained — so a long-lived session
- * stays bounded in normal use without ever dropping a failure signal.
- *
- * @internal
- */
-/**
- * Catalogue of meta event names. This is the documented surface — extend it as
- * new events are wired in (Tier 2/3 lifecycle, interaction, provider events).
- */
-declare type MetaEventType = 'assistant.connected' | 'assistant.disconnected' | 'assistant.popout' | 'assistant.popin' | 'driver.created' | 'driver.wired' | 'driver.unwired' | 'state.changed' | 'turn.start' | 'turn.end' | 'turn.retry' | 'turn.error' | 'tool.failed' | 'tool.unresolved' | 'subagent.started' | 'subagent.completed' | 'subagent.failed' | 'agent.handoff' | 'agent.pinned' | 'agent.unpinned' | 'provider.selected' | 'interaction.requested' | 'interaction.resolved' | 'context.updated' | 'context.threshold-crossed' | 'context.condensed' | 'panel.toggled' | 'attachment.added' | 'file.read-failed' | 'suggestions.failed';
-
 export { ModelTagAppearance }
 
 /**
@@ -2368,6 +2652,13 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
      * choice.
      */
     private flowOwnerAgentName;
+    /**
+     * Per-agent restored state for a rehydrated session, keyed by agent name.
+     * Primed by the host on restore; each entry is passed to that agent's
+     * `onActivate` as `ctx.restored` on its next activation, then deleted so a
+     * later re-activation starts fresh.
+     */
+    private restoredAgentStates;
     activeAgent?: AgentConfig;
     constructor(providerRegistry: AIProviderRegistry, agents: AgentConfig[], options?: {
         sessionKey?: string;
@@ -2402,11 +2693,19 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     setFlowOwner(name: string | null): void;
     loadHistory(messages: ChatMessage[]): void;
     getRawHistory(): readonly ChatMessage[];
+    /** {@inheritDoc AiDriver.compact} */
+    compact(): Promise<ChatMessage | null>;
+    /** {@inheritDoc AiDriver.canCompact} */
+    canCompact(): boolean;
     /** Delegates to the inner {@link ChatDriver} — turns are captured there. */
     getTurnSnapshots(): ReadonlyArray<TurnSnapshot>;
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
     sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
     continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
+    /** {@inheritDoc AiDriver.primeRestoredAgentState} */
+    primeRestoredAgentState(snapshots: Record<string, unknown>): void;
+    /** {@inheritDoc AiDriver.getActiveAgent} */
+    getActiveAgent(): AgentConfig | undefined;
     private applyAgent;
     /**
      * Release the current stateful agent: fire `onDeactivate`, clear the
@@ -2445,6 +2744,75 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     private appendInlineMessage;
 }
 
+/**
+ * Schema version of the persisted session shape. Bump on an incompatible
+ * change; a snapshot whose `version` doesn't match is discarded on load rather
+ * than risk feeding a stale shape into restore.
+ *
+ * @public
+ */
+export declare const PERSISTED_SESSION_VERSION = 1;
+
+/**
+ * A durable, restorable snapshot of one chat session — the *restorable core* of
+ * the debug log (GENC-1351 §5.1/D1), captured losslessly and independently of
+ * the diagnostic timeline. Written by a `SessionPersistenceProvider` and read
+ * back on page-reload restore.
+ *
+ * @public
+ */
+export declare interface PersistedSession {
+    /** Schema version — see {@link PERSISTED_SESSION_VERSION}. */
+    version: number;
+    /** ISO timestamp the snapshot was written. */
+    savedAt: string;
+    /** `window.location.host` at save time — restore refuses a cross-host snapshot. */
+    host: string;
+    /** The session this snapshot belongs to (the assistant's state key). */
+    sessionKey: string;
+    /** Full conversation transcript (`driver.getRawHistory()`) — the source of truth. */
+    messages: ChatMessage[];
+    /** Name of the agent active at save time, if any. */
+    activeAgentName?: string;
+    /** User's pinned agent (sticky picker choice); `null` = Auto. */
+    pinnedAgentName: string | null;
+    /** Agent that owned a guided flow at save time; `null` = none. */
+    flowOwnerAgentName: string | null;
+    /** Aggregated USD cost across the session. */
+    sessionCostUsd: number;
+    /** Provider-reported context-window usage on the last turn. */
+    contextTokens?: number;
+    /** Context-window limit for the active model. */
+    contextLimit?: number;
+    /** Active model id (e.g. `claude-sonnet-4-6`). */
+    activeModel?: string;
+    /** Name of the provider used on the last turn. */
+    activeProviderName?: string;
+    /**
+     * Per-stateful-agent serialized state images (each from an agent's
+     * `serialize()`), keyed by agent name. Handed back to the agent's
+     * `init({ restored })` on restore. Typically holds at most the active
+     * flow-owner — other stateful agents are disposed when switched away. The
+     * value shape is the agent's own, hence `unknown`.
+     */
+    agentSnapshots: Record<string, unknown>;
+    /**
+     * Interrupted-flow marker (GENC-1351 §5.9). Present when the session was saved
+     * while an agent declared its current state non-resumable (`resumable === false`).
+     * The **conversation is still persisted and restored in full** — only the running
+     * agent's flow-state is dropped (`agentSnapshots` empty, `flowOwnerAgentName`
+     * null), so restore does not rehydrate the mid-flight flow. On restore the
+     * assistant appends `message` as a normal assistant bubble and pre-fills the
+     * composer with `prompt` so the user can re-run it.
+     */
+    interrupted?: {
+        /** Shown as an assistant message on return. */
+        message: string;
+        /** The prompt that started the flow, pre-filled into the composer on return. */
+        prompt?: string;
+    };
+}
+
 /**
  * Controls the pop-out button shown in the assistant header.
  * - `"expand"` — assistant is embedded in the bubble dialog; button expands it to a layout panel.
@@ -2487,6 +2855,147 @@ declare interface ResolvedCostHistoryConfig {
     badgeLabel: string;
 }
 
+/**
+ * Restore a foundation-state-machine instance from a snapshot produced by the
+ * default serializer (or `machine.getPersistedSnapshot()`). Call inside a
+ * stateful agent's `init` to resume the machine in its exact prior place:
+ *
+ * ```ts
+ * init: ({ restored }) => {
+ *   const machine = new MyMachine();
+ *   restoreMachine(machine, restored); // resume, or no-op on a fresh start
+ *   return { machine };
+ * }
+ * ```
+ *
+ * No-ops when there is nothing to restore (a fresh session), leaving the
+ * freshly-constructed machine in its initial state.
+ *
+ * @param machine - the machine to restore (already constructed/started).
+ * @param restored - the agent's serialized image (`ctx.restored` in `init`).
+ * @param key - the property the machine occupies in the snapshot; defaults to
+ *   `'machine'` to match the conventional `{ machine }` state bag.
+ * @beta
+ */
+export declare function restoreMachine(machine: {
+    stop: () => void;
+    start: (options?: {
+        state?: unknown;
+    }) => void;
+}, restored: unknown, key?: string): void;
+
+/**
+ * `detail` of the `AiAssistantEvent.SessionCleared` event. Captured *before*
+ * teardown so a host can tidy up whatever the active agent was working on
+ * (generated files, server-side scratch, …). `agentSnapshot` is the agent's
+ * `serialize()` output (a state-machine image for machine-backed agents).
+ *
+ * @beta
+ */
+export declare interface SessionClearedDetail {
+    sessionKey: string | undefined;
+    agentName: string | undefined;
+    agentSnapshot: unknown;
+}
+
+/**
+ * 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 declare interface SessionPersistenceConfig {
+    /** Master switch — persistence does nothing unless this is true. */
+    enabled?: boolean;
+    /** Storage backend. Required for persistence to take effect. */
+    provider?: SessionPersistenceProvider;
+}
+
+/**
+ * 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 declare 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>;
+    /**
+     * 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 declare 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[];
+}
+
 /** Settings vs Cost tab identifiers for the modal tab bar. */
 declare type SettingsModalTab = 'settings' | 'cost';
 
@@ -2576,6 +3085,10 @@ export declare interface StatefulAgentInit<S> {
     /**
      * Construct the agent-scoped state. Called by the framework when this agent
      * becomes active (`onActivate`). Awaited before the agent's first turn runs.
+     *
+     * On a persisted-session restore, `ctx.restored` carries this agent's previous
+     * `serialize` output — rebuild from it (e.g. via `restoreMachine`), or start
+     * fresh when it is `undefined`.
      */
     init: (ctx: AgentLifecycleContext) => S | Promise<S>;
     /**
@@ -2689,8 +3202,49 @@ export declare interface StatefulAgentInit<S> {
      * Return value must be JSON-serializable.
      */
     getDebugSnapshot?: (state: S) => unknown;
+    /**
+     * Lossless serializer for session persistence — infra-agnostic. Return any
+     * JSON/structured-clone-safe image of `state`.
+     *   • Machine agents (`{ machine }`): omit — the default snapshots every
+     *     machine-shaped property via `getPersistedSnapshot()`.
+     *   • Plain-data agents (e.g. `{ plan, cursor }`): omit too — the default
+     *     returns plain state as-is. Provide one only when the state holds
+     *     something the default can't capture.
+     * Distinct from `getDebugSnapshot` (which may be lossy by design). Pair with
+     * `init` reading `ctx.restored` to rebuild.
+     */
+    serialize?: (state: S) => unknown;
+    /**
+     * Whether the agent's current state is resumable — worth persisting so the
+     * session restores mid-flow (GENC-1351 §5.9). Receives the **live** state bag
+     * `S` (like the other per-turn resolvers), so a machine agent gates on its step
+     * directly: `resumable: ({ state }) => state.machine.state !== 'confirm'`.
+     * Return `false` for a point that shouldn't resume — the session isn't persisted,
+     * and on return the assistant shows {@link StatefulAgentInit.notResumableMessage}
+     * (or a default) and pre-fills the composer with the prompt that started the flow.
+     * Only consulted with persistence enabled; a thrown error is treated as `true`
+     * (fail-safe — never drop a resumable chat on a predicate bug).
+     */
+    resumable?: (ctx: StatefulAgentPersistenceContext<S>) => boolean | Promise<boolean>;
+    /**
+     * Message shown on return when {@link StatefulAgentInit.resumable} returned
+     * `false`. Falls back to a built-in default when omitted.
+     */
+    notResumableMessage?: string;
 }
 
+/**
+ * Context passed to a stateful agent's `resumable` predicate (GENC-1351 §5.9) —
+ * the standard {@link AgentPersistenceContext} but with `state` as the **live**
+ * state bag `S` (not the serialized image), so a machine agent can gate on its
+ * current step directly.
+ *
+ * @beta
+ */
+export declare type StatefulAgentPersistenceContext<S> = Omit<AgentPersistenceContext, 'state'> & {
+    state: S;
+};
+
 /**
  * A brief, professional fallback agent. States what is available without
  * elaboration. The `{{agents}}` placeholder is replaced at runtime by
@@ -3001,4 +3555,39 @@ export declare type UnresolvedToolInput = (ctx: UnresolvedToolContext) => string
 /** Person silhouette — default user avatar. */
 export declare const userIconSvg = "<svg viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z\" fill=\"currentColor\"/></svg>";
 
+/**
+ * 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 declare class WebStorageSessionProvider implements SessionPersistenceProvider {
+    private readonly storage;
+    private readonly keyPrefix;
+    /**
+     * 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;
+    });
+    private storageKey;
+    /** Preferences key, namespaced apart from the session key so `clear` leaves it. */
+    private preferencesKey;
+    load(sessionKey: string): Promise<PersistedSession | null>;
+    save(sessionKey: string, snapshot: PersistedSession): Promise<void>;
+    clear(sessionKey: string): Promise<void>;
+    loadPreferences(sessionKey: string): Promise<SessionPreferences | undefined>;
+    savePreferences(sessionKey: string, preferences: SessionPreferences): Promise<void>;
+}
+
 export { }