@genesislcap/ai-assistant 14.490.0 → 14.491.0-FUI-2567.1

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.
  *
@@ -355,12 +424,18 @@ export declare interface AiChatWidget {
  */
 export declare interface AiDockProvider {
     /**
-     * Called when the user expands the bubble. The provider is responsible for inserting
-     * the element into its layout. State is held in the session store and restored
-     * automatically when the element connects.
+     * Called when the user expands the bubble. The provider **moves the given
+     * element** into its layout — e.g. via a layout factory that re-parents it into
+     * a pane. It is the ONE live assistant element, so it must be moved by reference,
+     * **not cloned** (a clone would be a second, dead instance). Session state
+     * survives the move because it lives in module-level registries, not the element.
      */
     onDock(element: HTMLElement): Promise<void>;
-    /** Called when the user collapses the panel or before navigation. */
+    /**
+     * Called when the user collapses the panel or before navigation. By the time
+     * this runs the manager has already moved the assistant element back into the
+     * bubble, so the provider only needs to tear down its now-empty layout slot.
+     */
     onUndock(): Promise<void>;
     /**
      * Called by `collapseIfDocked` before navigation. The provider is responsible for
@@ -401,10 +476,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.
      */
@@ -440,14 +546,6 @@ export declare interface AiDriver extends EventTarget {
      * Optional; the host wires the stop button to it when present.
      */
     cancel?(): void;
-    /** Register an assistant view (host) wired to this driver. */
-    registerHost?(hostId: string): void;
-    /** Deregister a host on unwire/disconnect. */
-    unregisterHost?(hostId: string): void;
-    /** Record the host whose subtree the user most recently interacted in (owner election signal). */
-    setActiveHost?(hostId: string): void;
-    /** First-writer-wins latch: the first host to claim an interaction id runs its side effect. */
-    claimSideEffect?(interactionId: string, hostId: string): boolean;
 }
 
 /**
@@ -528,6 +626,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 +854,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 }
@@ -776,12 +925,6 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     /** Epoch ms when the current turn loop began — drives the `turn.end` duration. */
     private turnStartedAt;
     private pendingInteractions;
-    /** Assistant host ids currently wired to this driver, in registration (insertion) order. */
-    private hosts;
-    /** The host whose subtree the user most recently interacted in — the primary owner signal. */
-    private lastActiveHostId?;
-    /** Interaction id → host id that claimed its side effect (first-writer-wins latch). */
-    private startedSideEffects;
     private systemPrompt?;
     /**
      * Resolved tool definitions visible to the LLM. Folds mutate this in place
@@ -1195,33 +1338,23 @@ 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[]>;
-    isBusy(): boolean;
-    /** Register an assistant view (host) wired to this shared driver. @internal */
-    registerHost(hostId: string): void;
-    /** Deregister a host on unwire/disconnect. @internal */
-    unregisterHost(hostId: string): void;
-    /**
-     * Record the host whose subtree the user most recently interacted in — the primary signal for
-     * electing which single view renders an interaction's widget. Sticky (unlike focus): it only
-     * moves when the user actually uses a different assistant view, not when they click elsewhere
-     * in the layout. @internal
-     */
-    setActiveHost(hostId: string): void;
     /**
-     * First-writer-wins latch guarding a side effect. A host claims before rendering the live
-     * widget: the first host to claim an interaction id gets `true` (run it); a *different* host
-     * gets `false` (render passive, do NOT re-fire). Re-claim by the SAME host returns `true`, so a
-     * benign re-render of the owner keeps its widget. Single-threaded, so check-and-set is race-free
-     * — the backstop that makes duplicate execution impossible even if owner election ever slips. @internal
+     * 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).
      */
-    claimSideEffect(interactionId: string, hostId: string): boolean;
+    canCompact(): boolean;
     /**
-     * Elect the single host that owns (renders + runs) an interaction's widget: the most-recently-
-     * active host if still connected, else a deterministic default (first registered host — `Set`
-     * preserves insertion order) so exactly one owner is always chosen. Returns `undefined` only when
-     * no host is registered, in which case the interaction renders everywhere (fail-open) not nowhere.
+     * 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.
      */
-    private electInteractionOwner;
+    compact(): Promise<ChatMessage | null>;
+    isBusy(): boolean;
     /**
      * Wire a parent driver as the host for this driver's interactions. When set,
      * `requestInteraction` delegates upward so the widget renders in (and
@@ -1330,11 +1463,11 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
 }
 
 /**
- * Detail payload for the `chat-header-mousedown` event fired by the assistant
- * in `popout-mode="expand"`.
+ * `detail` of the `AiAssistantEvent.ChatHeaderMouseDown` event.
+ *
  * @beta
  */
-export declare interface ChatHeaderMousedownEventDetail {
+export declare interface ChatHeaderMouseDownDetail {
     clientX: number;
     clientY: number;
 }
@@ -1439,6 +1572,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 +1632,32 @@ 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;
+    /**
+     * Present on `meta-snapshot` entries: a stable signature of the near-static config
+     * (excludes volatile timestamp/context/debug-snapshot), used by the forward-capture
+     * delta to skip re-appending an unchanged block (GENC-1351 §5.8). Absent on other
+     * kinds and on pre-signature entries (the delta falls back to the full `meta` then).
+     */
+    dedupSignature?: string;
+    [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
@@ -1535,7 +1701,8 @@ export declare interface FallbackAgentConfig extends BaseAgentConfig {
  * element `id`, or `'default'`). Snapshots run on tab close and when the session
  * title changes; hosts may call {@link FoundationAiAssistant.finalizeCostSession}.
  *
- * @fires chat-header-mousedown - Fired when the user presses the chat header in `popout-mode="expand"` (for drag-to-popout hosts). Bubbles and composed. detail: `ChatHeaderMousedownEventDetail`
+ * @fires chat-header-mousedown - Fired when the user presses the chat header in `popout-mode="expand"` (for drag-to-popout hosts). Bubbles and composed. detail: `ChatHeaderMouseDownDetail`
+ * @fires session-cleared - Fired after the session is wiped (the lifecycle menu's Clear). The payload is captured before teardown so the host can clean up any external state the active agent was working on. Bubbles and composed. detail: `SessionClearedDetail`
  *
  * @beta
  */
@@ -1544,6 +1711,18 @@ export declare class FoundationAiAssistant extends GenesisElement {
     appSettingsProvider: AssistantAppSettingsProvider;
     designSystemPrefix: string;
     headerTitle: string;
+    /**
+     * Explicit session/persistence key (GENC-1351 §5.12). When set, this is the
+     * session identity — the key for the driver/store/persister/diagnostics
+     * registries and the `sessionKey` passed to the persistence provider — taking
+     * precedence over the DOM `id`. A host that scopes persistence per-entity
+     * (e.g. one chat session per project) binds this to a stable per-entity id;
+     * changing it on a **connected** element re-keys the session in place — tears
+     * down the current conversation and restores the new key's — via
+     * `switchSession`. Falls back to `id` when unset,
+     * so existing consumers are unaffected.
+     */
+    sessionKey?: string;
     imageSrc?: string;
     userImageSrc?: string;
     /**
@@ -1581,6 +1760,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'`.
@@ -1597,6 +1785,14 @@ export declare class FoundationAiAssistant extends GenesisElement {
     debugStateFactory?: () => unknown;
     /** When set, enables Redux DevTools for this instance's session store. */
     debugRedux: boolean;
+    /**
+     * Pointer to this session's redux store. `@observable` (GENC-1351 §5.12) so that
+     * **swapping** it — the in-place session switch/re-key (`switchSession`) —
+     * forces every store-backed getter binding to re-evaluate against the NEW store.
+     * Without this, FAST's per-store slice tracking would leave the view subscribed
+     * to the old store after a swap and it wouldn't re-render. (A same-store reset via
+     * redux actions re-renders without this; a store *swap* needs it.)
+     */
     private _sessionRef?;
     get messages(): ChatMessage[];
     set messages(value: ChatMessage[]);
@@ -1612,6 +1808,15 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * store-backed `state` changes.
      */
     get busy(): boolean;
+    /**
+     * True when a new send must be refused: a turn is running (`busy`), a page-reload
+     * restore is loading history that would clobber it (`restoring`), or a manual
+     * compaction is rewriting history (`compacting`). Mirrors the composer's
+     * `?disabled` gate so a **programmatic** `send`/`submitMessage` (e.g. a host's
+     * custom input while the built-in composer is hidden) can't slip past it and have
+     * its message wiped when the restored/compacted history lands (GENC-1351 §6).
+     */
+    private get sendBlocked();
     /**
      * Re-runs `agentsChanged` if the live `agents` array no longer matches the
      * fingerprint of the currently installed driver. Used to apply swaps that
@@ -1619,6 +1824,13 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * driver returns to idle.
      */
     private applyDeferredAgentsSwap;
+    /**
+     * Apply a `session-key` re-key that arrived mid-turn and was deferred by
+     * `switchSession`'s busy guard (GENC-1351 §5.12). Run at each point the driver
+     * returns to idle, BEFORE `applyDeferredAgentsSwap` — a switch rebuilds the
+     * driver against the current agents, so a pending agents-swap then no-ops.
+     */
+    private applyDeferredSessionSwitch;
     /**
      * Focus the main chat input if the user is still engaged with the assistant.
      * Deferred to the next frame so any conditional re-render (e.g. unhiding the
@@ -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. */
@@ -1774,10 +2015,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private _activeCostSessionTitle;
     /** Prevents double-finalize for the same session instance (pagehide + title change). */
     private _costSessionFinalizedForInstance;
-    /** Only the visible assistant instance should snapshot on tab close (bubble vs docked panel). */
-    private _finalizeCostSessionOnPageHide;
     private _handlePageHide;
-    private _syncFinalizeCostSessionOnPageHide;
     private haloStartPublished;
     /** Fingerprint of the agents array used to build the current driver. Used by agentsChanged to skip spurious rebuilds. */
     private _driverAgentsKey?;
@@ -1807,12 +2045,6 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * to avoid stealing focus from elsewhere on the page.
      */
     isEngaged: boolean;
-    /**
-     * GENC-1410 (Error 3): stable id for this assistant view. Reported to the shared driver so it
-     * can elect a single owner to render (and run) each interaction's widget when more than one view
-     * (e.g. a bubble and a docked panel) is wired to the same driver — so it fires once, not per view.
-     */
-    private readonly hostId;
     private _handleGlobalInteraction;
     /** True when the user has intentionally scrolled away from the bottom — suppresses auto-scroll. */
     private _userScrolledAway;
@@ -1840,6 +2072,43 @@ 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;
+    /**
+     * True once `connectedCallback` has fully wired the initial session (GENC-1351
+     * §5.12). Guards `sessionKeyChanged` so the initial, pre-connect `session-key`
+     * set doesn't trigger a re-key — only a genuine change to a connected element
+     * switches the session. Reset on disconnect.
+     */
+    private _sessionActive;
+    /**
+     * The key of the session currently WIRED to this element (its driver/store/
+     * `_sessionRef`). Authoritative for `getStateKey()` once a session is active,
+     * because the `session-key` attr can run ahead of an actual switch: a mid-turn
+     * rebind is deferred to idle (§5.12), and reading the attr in that window would
+     * retarget autosave/diagnostics at a not-yet-activated key and silently drop the
+     * rest of the live turn. Set by `activateSession`. Undefined before first connect.
+     */
+    private _activeStateKey?;
+    /**
+     * Target key of a `session-key` rebind that arrived mid-turn and was deferred
+     * (§5.12). Applied by `applyDeferredSessionSwitch` once the driver goes idle. The
+     * latest rebind wins if several land while busy. Undefined = no switch pending.
+     */
+    private _deferredSwitchToKey?;
     showHalo: 'no' | 'orchestrating' | 'agent';
     private syncShowHalo;
     /** True when there is a pending (unresolved) interaction. */
@@ -1897,11 +2166,75 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * the driver or remove it from the registry.
      */
     private unwireDriver;
+    /**
+     * Tear down the session's currently-wired driver (GENC-1351): unwire this view, drop
+     * the driver from the registry, and dispose it — which fires the active agent's
+     * `onDeactivate` → `machine.stop()`. Shared by `agentsChanged`, `clearSession`, and
+     * `switchSession` so the teardown stays identical. `unwireDriver` does not clear
+     * `this.driver`, so the instance is still readable here for disposal.
+     */
+    private teardownDriver;
+    /**
+     * Build (or adopt from the registry) a fresh driver for `key` against the current
+     * agents and wire it to this view (GENC-1351). Records the agents fingerprint so a
+     * later `agentsChanged` skips a spurious rebuild. Shared by `agentsChanged` and
+     * `clearSession`.
+     */
+    private rebuildDriver;
+    /**
+     * Wire up the session identified by `key` on this element: preference baseline,
+     * driver (build/reuse) + wiring, restore (fresh store only), and the per-session
+     * view state (splash, loading-resume, suggestions, context/provider status, cost
+     * history). Extracted from `connectedCallback` (GENC-1351 §5.12) so an in-place
+     * session switch (`switchSession`) can re-run exactly this against a new
+     * key without re-adding element-lifetime listeners. Session-scoped only — the
+     * element-lifetime wiring (DOM/document/window listeners, provider-registry
+     * subscription, app-settings, pagehide) stays in `connectedCallback`.
+     */
+    private activateSession;
     connectedCallback(): void;
+    /**
+     * Switch this element to a different session **in place**, without a page reload
+     * (GENC-1351 §5.12) — the load-a-different-project flow. Tears down the current
+     * session's driver + per-key registries and restores the target key's session
+     * (its transcript and any mid-flow stateful agent). Fired automatically by
+     * `sessionKeyChanged` when a host rebinds
+     * `session-key` on a connected element; may also be called directly.
+     *
+     * Clobber-safe: the outgoing session's pending autosave is cancelled BEFORE the
+     * store swaps, so its transcript can never be written to the incoming session's
+     * file. Idle-only — a switch while a turn is running is refused.
+     *
+     * @param oldKey - the state key being switched away from.
+     * @param newKey - the state key to activate.
+     * @public
+     */
+    switchSession(oldKey: string, newKey: string): void;
+    /**
+     * FAST reflection hook for the `session-key` attr: a change on a **connected**
+     * element re-keys the session in place (GENC-1351 §5.12). Guarded by
+     * `_sessionActive` so the initial, pre-connect set does not switch — the first
+     * key is wired by `connectedCallback`.
+     */
+    sessionKeyChanged(_oldValue: string | undefined, _newValue: string | undefined): void;
     disconnectedCallback(): void;
     private resolveContextLimit;
     private loadProviderStatuses;
     chatConfigChanged(): void;
+    /**
+     * `persistence` (like `chatConfig`) can bind after `connectedCallback` — a host may
+     * resolve the `provider` asynchronously (an auth token, a feature flag). The connect
+     * path gates the whole persistence init on a provider being present *at connect*, and
+     * nothing else re-triggers it — so a late provider would silently never restore the
+     * session or load stored preferences (GENC-1351 #13). Mirror `chatConfigChanged`: when
+     * a provider first appears on a connected element whose store is still fresh, run the
+     * fresh-store init now. Guards keep it a one-shot:
+     *  - pre-connect sets are handled by `connectedCallback` (`_sessionActive` is false);
+     *  - a provider that was already present (incl. the internal `enabled`-only
+     *    reassignments) is a no-op (`oldValue?.provider`);
+     *  - a non-fresh (restored) store already holds its session (`_freshStore`).
+     */
+    persistenceChanged(oldValue: SessionPersistenceConfig | undefined, newValue: SessionPersistenceConfig | undefined): void;
     showingSplashChanged(): void;
     private syncShowingSplash;
     /**
@@ -1918,27 +2251,20 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private clearLoadingTimer;
     private stopLoadingTimer;
     /** Called when the user clicks the popout button. */
-    /**
-     * GENC-1410 (Error 3): claim the right to run a side-effecting interaction's server work for
-     * THIS view, via the shared driver's first-writer-wins latch. Returns `true` when this view may
-     * run it (first/owning claimant, or a re-render of the same view), `false` when another view
-     * already holds it. Fail-open when the driver has no latch. Called by `ai-chat-interaction-wrapper`.
-     */
-    claimSideEffect(interactionId: string): boolean;
-    /**
-     * GENC-1410 (Error 3): mark THIS view as the interaction owner on the shared driver, so it (not a
-     * sibling view sharing the same driver) is elected to render side-effecting widgets. The bubble
-     * and docked panel normally claim this automatically on the pop-in / dock lifecycle, but that
-     * lifecycle only runs once `popout-mode` is active. A host that establishes a view outside that
-     * lifecycle — e.g. a page that restores a docked assistant from a persisted layout before the
-     * pop-out affordance is enabled — calls this to seize ownership deterministically rather than
-     * leaving it to the last-interaction / first-registered fallback. Idempotent; safe to call on
-     * every layout (re)establish. No-op if the driver was never wired.
-     */
-    claimInteractionOwnership(): void;
     handlePopout(): void;
     /** Returns a cache key for this instance, or undefined if the component has no identity. */
     private getStateKey;
+    /**
+     * The session key implied by the element's current attributes (GENC-1351 §5.12).
+     * An explicit `session-key` IS the complete session identity — the host fully
+     * qualifies it (e.g. a per-project id), so `headerTitle` is NOT appended
+     * (appending it was multi-window disambiguation, obsolete under the single-window
+     * orchestration/pinning model for keyed hosts). Without a `session-key`, fall back
+     * to `id` + `headerTitle` (the original scheme, kept so existing consumers — e.g. a
+     * title-only key with no `id` — aren't re-keyed). This is the *desired* key;
+     * `getStateKey` returns the *wired* key, which can lag during a deferred switch.
+     */
+    private computeStateKeyFromAttrs;
     /**
      * Record a meta/lifecycle event onto this session's debug-log timeline
      * (exported via {@link FoundationAiAssistant.getDebugLog}). Every event
@@ -1949,6 +2275,99 @@ 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). Gated on
+     * persistence — the menu's actions (Compact, Clear, the "remember chat" toggle)
+     * only make sense with a provider configured, so it's hidden entirely without
+     * one. A host can additionally force it off via `chatConfig.ui.showSessionMenu:
+     * false` even when a provider is present (e.g. a guided onboarding flow where
+     * clearing/compacting mid-journey would be disruptive).
+     */
+    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.
+     *
+     * Emits `session-cleared` (`SessionClearedDetail`, declared on the class `@fires`)
+     * with `sessionKey`, `agentName`, and `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 +2457,53 @@ 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;
+    /**
+     * The `SessionPersister` dependency getters bound to THIS element + `key`.
+     * The host-owned getters (`getPersistence`/`getAgentNames`/`getDiagnosticEntries`)
+     * read the live element; `getDriver`/`getStore` resolve by key from the registries.
+     * Rebound onto the shared persister on every activation (see `activateSession`) so
+     * a remounted element becomes the live source, not the torn-down creator (GENC-1351 §5.10 / #7).
+     */
+    private buildPersisterDeps;
+    /**
+     * 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;
@@ -2142,6 +2546,13 @@ export declare class FoundationAiAssistant extends GenesisElement {
         files?: File[];
     }): Promise<SubmitMessageResult>;
     private fetchSuggestions;
+    /**
+     * User text of the message currently being sent, stashed for the lifetime of `send()`.
+     * `flow-owner-changed` fires while the driver routes this turn — before the message is
+     * appended to raw history — so the flow-activation-prompt capture reads this rather than
+     * a stale raw-history lookup. Cleared once the send settles. (GENC-1351 §5.9)
+     */
+    private _pendingSendPrompt?;
     private send;
     onChatHeaderMouseDown(e: MouseEvent): void;
     handleInteractionCompleted(e: Event): void;
@@ -2173,9 +2584,14 @@ export declare const FoundationAiAssistantTemplate: (designSystemPrefix: string)
  *
  * @remarks
  * Place this in the persistent app shell, wrapping a `foundation-ai-chat-bubble` that
- * contains an AI assistant element in the `dialog-content` slot. The component will
- * auto-create a matching collapse-mode element for docking into pages, and will
- * control the expand button visibility based on whether a dock provider is registered.
+ * contains an AI assistant element in the `dialog-content` slot.
+ *
+ * GENC-1351 (Option A — single element): rather than cloning a second assistant to
+ * dock, this manager **moves the one real element** between the bubble and the page
+ * layout. One connected instance means no dual-view coordination (no shared-driver
+ * unwire/rewire, host election, or duplicated side-effects); the session survives the
+ * move because the driver/store/persister live in module-level registries keyed by the
+ * element's identity.
  *
  * Pages that support docking call `aiPopoutManager.registerDockProvider()` on mount
  * and `aiPopoutManager.deregisterDockProvider()` on unmount.
@@ -2194,12 +2610,29 @@ export declare const FoundationAiAssistantTemplate: (designSystemPrefix: string)
 export declare class FoundationAiPopoutManager extends GenesisElement {
     /** True when a dock provider is registered — controls expand button visibility. */
     canDock: boolean;
-    private collapseEl;
+    /**
+     * The single assistant element. Captured while it's in the bubble slot and held
+     * across the move (it's the same instance whether docked or in the bubble), so
+     * pop-in can re-home it even though it's no longer a child of this manager.
+     */
+    private assistantEl;
     private dockProvider;
     private isDocked;
     private unsubBus?;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** Locate the assistant element currently slotted into the bubble. */
+    private findAssistant;
+    /**
+     * Register an externally-created assistant element and its docked state. For
+     * single-element hosts that create the assistant directly in a layout pane (rather
+     * than statically in the bubble), so the manager tracks the one element, whether it's
+     * currently docked (for pop-in re-homing), reflects the right `popout-mode` on it
+     * (drives the header button), and hides the empty bubble.
+     */
+    adoptAssistant(el: HTMLElement, docked: boolean): void;
+    /** Hide the floating bubble unless it currently contains the assistant. */
+    private syncBubbleVisibility;
     canDockChanged(): void;
     registerDockProvider(provider: AiDockProvider): void;
     deregisterDockProvider(): void;
@@ -2254,7 +2687,7 @@ declare interface InputOverride {
  */
 export declare type InteractionCompletedEventDetail = ChatInteractionEventsMap['interaction-completed'];
 
-/** True when the collapse-mode assistant is active in the layout panel. */
+/** True when the assistant is active in the layout panel (docked) rather than the bubble. */
 export declare function isAiAssistantDocked(): boolean;
 
 /**
@@ -2285,44 +2718,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 +2763,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;
@@ -2380,10 +2782,6 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     });
     resolveInteraction(interactionId: string, result: unknown): void;
     isBusy(): boolean;
-    registerHost(hostId: string): void;
-    unregisterHost(hostId: string): void;
-    setActiveHost(hostId: string): void;
-    claimSideEffect(interactionId: string, hostId: string): boolean;
     /** Currently active provider name from the underlying ChatDriver. */
     getActiveProviderName(): string;
     /**
@@ -2402,11 +2800,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 +2851,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 +2962,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 +3192,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 +3309,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 +3662,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 { }