akanjs 3.0.0-alpha.56 → 3.0.0-alpha.58

package/client/csrTypes.ts

@@ -1,9 +1,10 @@
 "use client";
 import type { ReactDOMAttributes } from "@use-gesture/react/dist/declarations/src/types";
 import type { PromiseOrObject } from "akanjs/base";
-import { createContext, type ForwardRefExoticComponent, type ReactNode, type RefObject, useContext } from "react";
+import { type ForwardRefExoticComponent, type ReactNode, type RefObject, useContext } from "react";
 import type { AnimatedComponent, AnimatedProps, Interpolation, SpringValue } from "react-spring";
 import type { RouterInstance } from "./router";
+import { sharedContext } from "./sharedContext";
 import type { ReactFont } from "./types";
 
 export type TransitionType = "none" | "fade" | "bottomUp" | "stack" | "scaleOut";
@@ -349,7 +350,7 @@ export type UseCsrTransition = CsrTransitionStyles & {
 };
 
 export type CsrContextType = RouteState & UseCsrTransition;
-export const csrContext = createContext<CsrContextType>({} as unknown as CsrContextType);
+export const csrContext = sharedContext<CsrContextType>("csr", {} as unknown as CsrContextType);
 export const useCsr = () => {
   const contextValues = useContext(csrContext);
   return contextValues;
@@ -363,7 +364,7 @@ export interface PathContextType {
   setGestureEnabled: (enabled: boolean) => void;
   registerFrameSlot: (slot: FrameSlotRegistration) => () => void;
 }
-export const pathContext = createContext<PathContextType>({} as unknown as PathContextType);
+export const pathContext = sharedContext<PathContextType>("path", {} as unknown as PathContextType);
 export const usePathCtx = () => {
   const contextValues = useContext(pathContext);
   return contextValues;

package/client/index.ts

@@ -11,6 +11,7 @@ export * from "./locale";
 export * from "./makePageProto";
 export * from "./router";
 export * from "./rscNavigation";
+export * from "./sharedContext";
 export * from "./storage";
 export * from "./translator";
 export * from "./types";

package/client/locale.ts

@@ -1,4 +1,4 @@
 "use client";
-import { createContext } from "react";
+import { sharedContext } from "./sharedContext";
 
-export const dictionaryContext = createContext<{ [key: string]: { [key: string]: string } }>({});
+export const dictionaryContext = sharedContext<{ [key: string]: { [key: string]: string } }>("dictionary", {});

package/client/sharedContext.ts

@@ -0,0 +1,30 @@
+import { type Context, createContext } from "react";
+
+/**
+ * A React context interned on `globalThis`, which is how every context this framework owns must be made.
+ *
+ * An akan build does not give an app one copy of `akanjs`: it inlines each reachable module into every client
+ * chunk that reaches it — four copies of the agent runtime in this repo's own docs app. A context is identified
+ * by object identity, so a Provider mounted from one copy is invisible to a consumer holding another, and the
+ * consumer silently reads the context's default instead.
+ *
+ * Silently is the whole problem. `UiOverrideContext` was a plain `createContext`, so a route's `_overrides.tsx`
+ * bound its slots in the chunk holding the generated provider and every overridable component in another chunk
+ * kept rendering the framework default — no throw, no warning, and only *some* slots affected, which reads like
+ * a bug in the app's own component. The same shape cost a zone every tool it declared.
+ *
+ * The rule is therefore mechanical rather than case-by-case: a context whose Provider and consumers can be
+ * bundled apart is every context worth having, so all of them go through here. A test fails if one does not.
+ *
+ * `use-agentic` carries its own twin under a `useAgentic.` prefix, deliberately — it ships as a standalone
+ * package and cannot import this one. The prefixes keep the two namespaces from ever meeting.
+ */
+export const sharedContext = <T>(name: string, initial: T): Context<T> => {
+  const key = Symbol.for(`akanjs.context.${name}`);
+  const holder = globalThis as typeof globalThis & { [slot: symbol]: Context<T> | undefined };
+  const existing = holder[key];
+  if (existing) return existing;
+  const created = createContext(initial);
+  holder[key] = created;
+  return created;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.56",
+  "version": "3.0.0-alpha.58",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/types/client/index.d.ts

@@ -11,6 +11,7 @@ export * from "./locale.d.ts";
 export * from "./makePageProto.d.ts";
 export * from "./router.d.ts";
 export * from "./rscNavigation.d.ts";
+export * from "./sharedContext.d.ts";
 export * from "./storage.d.ts";
 export * from "./translator.d.ts";
 export * from "./types.d.ts";

package/types/client/sharedContext.d.ts

@@ -0,0 +1,21 @@
+import { type Context } from "react";
+/**
+ * A React context interned on `globalThis`, which is how every context this framework owns must be made.
+ *
+ * An akan build does not give an app one copy of `akanjs`: it inlines each reachable module into every client
+ * chunk that reaches it — four copies of the agent runtime in this repo's own docs app. A context is identified
+ * by object identity, so a Provider mounted from one copy is invisible to a consumer holding another, and the
+ * consumer silently reads the context's default instead.
+ *
+ * Silently is the whole problem. `UiOverrideContext` was a plain `createContext`, so a route's `_overrides.tsx`
+ * bound its slots in the chunk holding the generated provider and every overridable component in another chunk
+ * kept rendering the framework default — no throw, no warning, and only *some* slots affected, which reads like
+ * a bug in the app's own component. The same shape cost a zone every tool it declared.
+ *
+ * The rule is therefore mechanical rather than case-by-case: a context whose Provider and consumers can be
+ * bundled apart is every context worth having, so all of them go through here. A test fails if one does not.
+ *
+ * `use-agentic` carries its own twin under a `useAgentic.` prefix, deliberately — it ships as a standalone
+ * package and cannot import this one. The prefixes keep the two namespaces from ever meeting.
+ */
+export declare const sharedContext: <T>(name: string, initial: T) => Context<T>;

package/types/ui/Agent/Chat.d.ts

@@ -31,6 +31,11 @@ export interface ChatProps {
      * button, a menu item — instead of the built-in launcher. Left off, the panel owns the state as before.
      */
     open?: boolean;
+    /**
+     * Left off while `open` is controlled, the panel cannot close itself — so it draws **no close button** rather
+     * than an inert one. That is the shape of a fixed panel with nowhere to close to, and it is also what keeps a
+     * controlled chat assemblable by a server component, since this is the only prop here that is a function.
+     */
     onOpenChange?: (open: boolean) => void;
     /** `false` draws no launcher, for an app that opens the panel from a control of its own. */
     launcher?: boolean;

package/types/ui/Agent/History.d.ts

@@ -0,0 +1,26 @@
+import { type AgentSessionOptions, type SessionHistory } from "../../vendor/use-agentic.d.ts";
+export interface HistoryProps {
+    load: SessionHistory["load"];
+    save: SessionHistory["save"];
+    clear: SessionHistory["clear"];
+    /** Where a host with its own server-side summary moves its watermark — see `onCompact` on the session options. */
+    onCompact?: AgentSessionOptions["onCompact"];
+}
+/**
+ * Puts the enclosing zone's transcript wherever the app keeps it, as a mounted component rather than a prop.
+ *
+ * `persist` does the same thing and has to be passed to whoever builds the session, which makes every ancestor up
+ * to that point a client component — a function cannot cross the server/client boundary as a prop. Mounted here
+ * instead, the only client module an app needs is this leaf, and `Agent.Zone` and the chat inside it can be
+ * assembled by a server component. Same shape as `Agent.Guide`, and it renders nothing.
+ *
+ * Restoring follows the session's one rule: it lands only while nothing has happened to the conversation yet, so
+ * mounting with the zone restores and mounting later saves from there on.
+ *
+ * The store is attached for exactly as long as this is mounted. A zone's own session dies with it, so that is the
+ * whole story there — but a session the app handed in (`Agent.Zone`'s `session` prop) outlives this, and its
+ * saving stops on unmount: nothing is claiming to persist it any more, and a component that is gone should not
+ * still be writing. A host that wants the store to outlive the view calls `session.setHistory` itself, which also
+ * takes the slot, so a later unmount here leaves it alone.
+ */
+export declare const History: ({ load, save, clear, onCompact }: HistoryProps) => null;

package/types/ui/Agent/index.d.ts

@@ -8,6 +8,7 @@ export declare const Agent: {
     Context: typeof Context;
     Dock: ({ className, bridge, surface, open }: import("./Dock.d.ts").DockProps) => import("react/jsx-runtime").JSX.Element;
     Guide: ({ instructions }: import("./Guide.d.ts").GuideProps) => null;
+    History: ({ load, save, clear, onCompact }: import("./History.d.ts").HistoryProps) => null;
     Scope: ({ id, label, kind, children }: import("../../vendor/use-agentic.d.ts").AgentScopeProps) => import("react/jsx-runtime").JSX.Element;
     Section: typeof Section;
     Skip: ({ className, label, children }: import("./Skip.d.ts").SkipProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/Dialog/context.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 export interface DialogContextType {
     open: boolean;
     setOpen: (open: boolean) => void;

package/types/ui/Tab/context.d.ts

@@ -1,4 +1,4 @@
-import { type RefObject } from "react";
+import type { RefObject } from "react";
 interface TabContextType {
     defaultMenu: string | null;
     menu: string | null;

package/types/ui/UiOverride/context.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentType } from "react";
+import type { ComponentType } from "react";
 import type { ClassNameValue as ClassValue } from "tailwind-merge";
 import type { ApprovalProps as AgentApprovalProps } from "../Agent/Approval.d.ts";
 import type { BubbleProps as AgentBubbleProps } from "../Agent/Bubble.d.ts";

package/types/ui/index.d.ts

@@ -8,6 +8,7 @@ export type { ChatProps } from "./Agent/Chat.d.ts";
 export { type ChatCommand, ChatCommands } from "./Agent/ChatCommands.d.ts";
 export { type ComposerProps, DefaultComposer } from "./Agent/Composer.d.ts";
 export { fetchRunner } from "./Agent/fetchRunner.d.ts";
+export type { HistoryProps as AgentHistoryProps } from "./Agent/History.d.ts";
 export { DefaultLauncher, type LauncherProps } from "./Agent/Launcher.d.ts";
 export { type CodeProps, DefaultCode, DefaultMarkdown, type MarkdownProps } from "./Agent/Markdown.d.ts";
 export { DefaultMenu, type MenuProps as AgentMenuProps, type MenuRow } from "./Agent/Menu.d.ts";

package/types/vendor/use-agentic/AgentSession.d.ts

@@ -127,6 +127,19 @@ export declare class AgentSession {
      * is one the winding-down turn appends onto. The returned promise waits for the history to clear too.
      */
     reset: () => Promise<void>;
+    /**
+     * Attaches a transcript store to a session built without one — what `Agent.History` mounts, so a zone can be
+     * assembled by a server component and still keep its transcript wherever the app keeps it. `null` detaches.
+     *
+     * Restoring follows the rule an async `load` already follows: it lands only while nothing has happened to this
+     * session yet. Attach before the first turn and it restores; attach after and it saves from there on, with the
+     * store never asked for a transcript that would be discarded. One rule rather than a mount-order surprise.
+     *
+     * Returns the detach, which clears the slot only while this call's store is still the one in it.
+     */
+    setHistory: (history: SessionHistory | null) => () => void;
+    /** The compaction hook as a setter, for the same reason `setHistory` is one: a host attaches it after the fact. */
+    setOnCompact: (onCompact: AgentSessionOptions["onCompact"] | null) => () => void;
     /**
      * Re-runs the last user message, dropping what the previous attempt produced. Turns fail for reasons that have
      * nothing to do with what was asked — a refused relay, a model that is unavailable — and retyping is otherwise the

package/ui/Agent/Chat.tsx

@@ -69,6 +69,11 @@ export interface ChatProps {
    * button, a menu item — instead of the built-in launcher. Left off, the panel owns the state as before.
    */
   open?: boolean;
+  /**
+   * Left off while `open` is controlled, the panel cannot close itself — so it draws **no close button** rather
+   * than an inert one. That is the shape of a fixed panel with nowhere to close to, and it is also what keeps a
+   * controlled chat assemblable by a server component, since this is the only prop here that is a function.
+   */
   onOpenChange?: (open: boolean) => void;
   /** `false` draws no launcher, for an app that opens the panel from a control of its own. */
   launcher?: boolean;

package/ui/Agent/History.tsx

@@ -0,0 +1,49 @@
+"use client";
+import { useContext, useEffect, useRef } from "react";
+import { type AgentSessionOptions, SessionContext, type SessionHistory } from "../../vendor/use-agentic";
+
+export interface HistoryProps {
+  load: SessionHistory["load"];
+  save: SessionHistory["save"];
+  clear: SessionHistory["clear"];
+  /** Where a host with its own server-side summary moves its watermark — see `onCompact` on the session options. */
+  onCompact?: AgentSessionOptions["onCompact"];
+}
+
+/**
+ * Puts the enclosing zone's transcript wherever the app keeps it, as a mounted component rather than a prop.
+ *
+ * `persist` does the same thing and has to be passed to whoever builds the session, which makes every ancestor up
+ * to that point a client component — a function cannot cross the server/client boundary as a prop. Mounted here
+ * instead, the only client module an app needs is this leaf, and `Agent.Zone` and the chat inside it can be
+ * assembled by a server component. Same shape as `Agent.Guide`, and it renders nothing.
+ *
+ * Restoring follows the session's one rule: it lands only while nothing has happened to the conversation yet, so
+ * mounting with the zone restores and mounting later saves from there on.
+ *
+ * The store is attached for exactly as long as this is mounted. A zone's own session dies with it, so that is the
+ * whole story there — but a session the app handed in (`Agent.Zone`'s `session` prop) outlives this, and its
+ * saving stops on unmount: nothing is claiming to persist it any more, and a component that is gone should not
+ * still be writing. A host that wants the store to outlive the view calls `session.setHistory` itself, which also
+ * takes the slot, so a later unmount here leaves it alone.
+ */
+export const History = ({ load, save, clear, onCompact }: HistoryProps) => {
+  const session = useContext(SessionContext);
+  if (!session) throw new Error("Agent.History needs an enclosing Agent.Zone or AgentProvider to hold the session.");
+  
+  const latest = useRef({ load, save, clear, onCompact });
+  latest.current = { load, save, clear, onCompact };
+  useEffect(() => {
+    const detachHistory = session.setHistory({
+      load: () => latest.current.load(),
+      save: (messages) => latest.current.save(messages),
+      clear: () => latest.current.clear(),
+    });
+    const detachCompact = session.setOnCompact((replaced, summary) => latest.current.onCompact?.(replaced, summary));
+    return () => {
+      detachHistory();
+      detachCompact();
+    };
+  }, [session]);
+  return null;
+};

package/ui/Agent/index.ts

@@ -2,6 +2,7 @@ import { AgentScope } from "../../vendor/use-agentic";
 import Context from "./Context";
 import { Dock } from "./Dock";
 import { Guide } from "./Guide";
+import { History } from "./History";
 import { Chat } from "./index_";
 import Section from "./Section";
 import { Skip } from "./Skip";
@@ -15,6 +16,7 @@ export const Agent = {
   Context,
   Dock,
   Guide,
+  History,
   Scope: AgentScope,
   Section,
   Skip,

package/ui/Dialog/context.ts

@@ -1,5 +1,6 @@
 "use client";
-import { createContext, type ReactNode } from "react";
+import type { ReactNode } from "react";
+import { sharedContext } from "../../client/sharedContext";
 
 export interface DialogContextType {
   open: boolean;
@@ -18,7 +19,7 @@ export interface DialogContextType {
   setAction: (action: ReactNode) => void;
 }
 
-export const DialogContext = createContext<DialogContextType>({
+export const DialogContext = sharedContext<DialogContextType>("dialog", {
   open: false,
   setOpen: (open: boolean) => null,
   openDialog: () => null,

package/ui/DragAction.tsx

@@ -3,8 +3,9 @@ import { useGesture } from "@use-gesture/react";
 import type { ReactDOMAttributes } from "@use-gesture/react/dist/declarations/src/types";
 import { cn } from "akanjs/client";
 import { animated } from "akanjs/ui";
-import { createContext, type ReactNode, useContext, useRef } from "react";
+import { type ReactNode, useContext, useRef } from "react";
 import { SpringValue, useSpring } from "react-spring";
+import { sharedContext } from "../client/sharedContext";
 
 interface DragActionContextType {
   bind: () => ReactDOMAttributes;
@@ -17,7 +18,7 @@ interface DragActionContextType {
   onClick?: () => void;
 }
 
-const DragActionContext = createContext<DragActionContextType>({
+const DragActionContext = sharedContext<DragActionContextType>("dragAction", {
   bind: () => ({}),
   x: new SpringValue(0),
   y: new SpringValue(0),

package/ui/DraggableList.tsx

@@ -4,9 +4,10 @@ import { useGesture } from "@use-gesture/react";
 import { cn } from "akanjs/client";
 import { useFieldTool } from "akanjs/store";
 import { animated } from "akanjs/ui";
-import { createContext, type ReactElement, type ReactNode, useContext, useRef } from "react";
+import { type ReactElement, type ReactNode, useContext, useRef } from "react";
 import { BiTrash } from "react-icons/bi";
 import { MdDragIndicator } from "react-icons/md";
+import { sharedContext } from "../client/sharedContext";
 import { agentAttrs } from "./agentAttrs";
 import { buttonRecipe } from "./Button";
 import { useUiRecipe } from "./UiOverride";
@@ -24,7 +25,7 @@ interface DragListContextType<V> {
   bind: (...args: any[]) => any;
   onRemove: (value: V) => void;
 }
-const dragListContext = createContext<DragListContextType<any>>({} as unknown as DragListContextType<any>);
+const dragListContext = sharedContext<DragListContextType<any>>("dragList", {} as unknown as DragListContextType<any>);
 const useDragList = () => useContext(dragListContext);
 
 interface DragListProps<V> {

package/ui/ScreenNavigator.tsx

@@ -4,8 +4,9 @@ import { cn } from "akanjs/client";
 import { capitalize } from "akanjs/common";
 import { st } from "akanjs/store";
 import { animated } from "akanjs/ui";
-import { createContext, type ReactNode, useContext, useEffect, useRef, useState } from "react";
+import { type ReactNode, useContext, useEffect, useRef, useState } from "react";
 import { SpringValue, useSpringValue } from "react-spring";
+import { sharedContext } from "../client/sharedContext";
 
 interface ScreenNavigatorContextType {
   bind: (...args: any[]) => any;
@@ -16,7 +17,7 @@ interface ScreenNavigatorContextType {
   onClickMenu: (menu: string) => void;
 }
 
-const ScreenNavigatorContext = createContext<ScreenNavigatorContextType>({
+const ScreenNavigatorContext = sharedContext<ScreenNavigatorContextType>("screenNavigator", {
   bind: () => ({}),
   xValue: new SpringValue(0),
   setMenu: null as unknown as (menu: string) => void,

package/ui/Tab/context.ts

@@ -1,5 +1,6 @@
 "use client";
-import { createContext, type RefObject } from "react";
+import type { RefObject } from "react";
+import { sharedContext } from "../../client/sharedContext";
 
 interface TabContextType {
   defaultMenu: string | null;
@@ -10,7 +11,7 @@ interface TabContextType {
   switchTab: (menu: string) => void;
 }
 
-export const TabContext = createContext<TabContextType>({
+export const TabContext = sharedContext<TabContextType>("tab", {
   defaultMenu: null,
   menu: null,
   setMenu: (value: string | null) => null,

package/ui/UiOverride/context.ts

@@ -1,6 +1,7 @@
 "use client";
-import { type ComponentType, createContext } from "react";
+import type { ComponentType } from "react";
 import type { ClassNameValue as ClassValue } from "tailwind-merge";
+import { sharedContext } from "../../client/sharedContext";
 import type { ApprovalProps as AgentApprovalProps } from "../Agent/Approval";
 import type { BubbleProps as AgentBubbleProps } from "../Agent/Bubble";
 import type { ChatProps as AgentChatProps } from "../Agent/Chat";
@@ -130,4 +131,4 @@ export type AkanUiOverrideManifest = Partial<AkanUiOverrides> & { recipes?: Part
  * merged (child wins) by each nested `UiOverrideProvider`, mirroring how nested
  * `_layout.tsx` / `_overrides.tsx` stack down the route tree.
  */
-export const UiOverrideContext = createContext<AkanUiOverrideManifest>({});
+export const UiOverrideContext = sharedContext<AkanUiOverrideManifest>("uiOverride", {});

package/ui/index.ts

@@ -27,6 +27,7 @@ export type { ChatProps } from "./Agent/Chat";
 export { type ChatCommand, ChatCommands } from "./Agent/ChatCommands";
 export { type ComposerProps, DefaultComposer } from "./Agent/Composer";
 export { fetchRunner } from "./Agent/fetchRunner";
+export type { HistoryProps as AgentHistoryProps } from "./Agent/History";
 export { DefaultLauncher, type LauncherProps } from "./Agent/Launcher";
 export { type CodeProps, DefaultCode, DefaultMarkdown, type MarkdownProps } from "./Agent/Markdown";
 export { DefaultMenu, type MenuProps as AgentMenuProps, type MenuRow } from "./Agent/Menu";

package/ui/overlayLayer.ts

@@ -1,5 +1,6 @@
 "use client";
-import { createContext, useContext } from "react";
+import { useContext } from "react";
+import { sharedContext } from "../client/sharedContext";
 
 /**
  * Overlay surfaces render through `createPortal(document.body)`, so they leave the DOM subtree of the
@@ -22,7 +23,7 @@ export const OVERLAY_LAYER_ATTR = "data-akan-overlay";
 export const overlayZ = { select: 90, dropdown: 100, popconfirmScrim: 105, popconfirm: 110 } as const;
 
 /** Scope that rendered the surrounding content — empty at page level. */
-const OverlayOwnerContext = createContext("");
+const OverlayOwnerContext = sharedContext("overlayOwner", "");
 
 /** Wrap the content a dismissable container owns, with the scope from {@link useOverlayScope}. */
 export const OverlayOwnerProvider = OverlayOwnerContext.Provider;

package/vendor/use-agentic/AgentSession.ts

@@ -139,6 +139,9 @@ export class AgentSession {
   #saveTimer: ReturnType<typeof setTimeout> | null = null;
   #saving: Promise<unknown> = Promise.resolve();
   #restoring = false;
+
+  #history: SessionHistory | undefined;
+  #onCompact: AgentSessionOptions["onCompact"];
   #compacting = false;
   /** Size below which auto-compaction stays out of the way, raised when a summary failed to shrink anything. */
   #compactFloor = 0;
@@ -147,6 +150,8 @@ export class AgentSession {
     this.#surface = surface;
     this.#runner = runner;
     this.#options = options;
+    this.#history = options.history;
+    this.#onCompact = options.onCompact;
     const restored = AgentSession.#restored(options.history);
     if (Array.isArray(restored)) this.#messages = restored;
     else {
@@ -291,7 +296,7 @@ export class AgentSession {
       clearTimeout(this.#saveTimer);
       this.#saveTimer = null;
     }
-    const history = this.#options.history;
+    const history = this.#history;
     if (history) {
 
       this.#saving = this.#saving.then(() => history.clear()).catch(() => undefined);
@@ -301,6 +306,39 @@ export class AgentSession {
     for (const listener of this.#listeners) listener();
   };
 
+  /**
+   * Attaches a transcript store to a session built without one — what `Agent.History` mounts, so a zone can be
+   * assembled by a server component and still keep its transcript wherever the app keeps it. `null` detaches.
+   *
+   * Restoring follows the rule an async `load` already follows: it lands only while nothing has happened to this
+   * session yet. Attach before the first turn and it restores; attach after and it saves from there on, with the
+   * store never asked for a transcript that would be discarded. One rule rather than a mount-order surprise.
+   *
+   * Returns the detach, which clears the slot only while this call's store is still the one in it.
+   */
+  setHistory = (history: SessionHistory | null) => {
+    this.#history = history ?? undefined;
+    if (history && this.#version === 0) {
+      const restored = AgentSession.#restored(history);
+      if (restored instanceof Promise) {
+        this.#restoring = true;
+        void this.#hydrate(restored);
+      } else this.#restore(restored);
+    }
+
+    return () => {
+      if (history && this.#history === history) this.#history = undefined;
+    };
+  };
+
+  /** The compaction hook as a setter, for the same reason `setHistory` is one: a host attaches it after the fact. */
+  setOnCompact = (onCompact: AgentSessionOptions["onCompact"] | null) => {
+    this.#onCompact = onCompact ?? undefined;
+    return () => {
+      if (onCompact && this.#onCompact === onCompact) this.#onCompact = undefined;
+    };
+  };
+
   /**
    * Re-runs the last user message, dropping what the previous attempt produced. Turns fail for reasons that have
    * nothing to do with what was asked — a refused relay, a model that is unavailable — and retyping is otherwise the
@@ -378,7 +416,7 @@ export class AgentSession {
       const message = Compaction.message(summary);
       this.#messages = [message, ...this.#messages.slice(at)];
       try {
-        this.#options.onCompact?.(replaced, message);
+        this.#onCompact?.(replaced, message);
       } catch {
       }
       return true;
@@ -657,7 +695,7 @@ export class AgentSession {
 
   /** Debounced: streaming patches the last message on every delta, and a save per delta would thrash storage. */
   #schedulePersist() {
-    const history = this.#options.history;
+    const history = this.#history;
     if (!history) return;
     if (this.#saveTimer) clearTimeout(this.#saveTimer);
     this.#saveTimer = setTimeout(() => {
@@ -696,6 +734,15 @@ export class AgentSession {
     } catch {
     }
     this.#restoring = false;
+    this.#restore(restored);
+  }
+
+  /**
+   * Lands a restore under the one rule — only into a session nothing has happened to yet — and notifies either
+   * way, because `isRestoring` may have turned over with it. Notifies by hand rather than through `#notify`,
+   * which would save the transcript it has just loaded.
+   */
+  #restore(restored: ChatMessage[]) {
     if (this.#version === 0 && restored.length) this.#messages = restored;
     this.#version += 1;
     for (const listener of this.#listeners) listener();