akanjs 3.0.0-alpha.56 → 3.0.0-alpha.57

package/package.json

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

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,20 @@
+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.
+ */
+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/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,17 @@ 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.
+     */
+    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,44 @@
+"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.
+ */
+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(() => {
+    session.setHistory({
+      load: () => latest.current.load(),
+      save: (messages) => latest.current.save(messages),
+      clear: () => latest.current.clear(),
+    });
+    session.setOnCompact((replaced, summary) => latest.current.onCompact?.(replaced, summary));
+    return () => {
+      
+      session.setHistory(null);
+      session.setOnCompact(null);
+    };
+  }, [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/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/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,31 @@ 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.
+   */
+  setHistory = (history: SessionHistory | null) => {
+    this.#history = history ?? undefined;
+    if (!history || this.#version !== 0) return;
+    const restored = AgentSession.#restored(history);
+    if (!(restored instanceof Promise)) {
+      this.#restore(restored);
+      return;
+    }
+    this.#restoring = true;
+    void this.#hydrate(restored);
+  };
+
+  /** 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;
+  };
+
   /**
    * 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 +408,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 +687,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 +726,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();