akanjs 3.0.0-alpha.55 → 3.0.0-alpha.57

package/package.json

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

package/service/agent.service.ts

@@ -7,15 +7,18 @@ import type {
 } from "./predefinedAdaptor/llm.adaptor";
 import { LlmAdaptorRole } from "./predefinedAdaptor/role.adaptor";
 import { serve } from "./serve";
+import { ToolNames } from "./toolNames";
 
 export class AgentService extends serve("agent" as const, ({ plug }) => ({
   llm: plug(LlmAdaptorRole),
 })) {
   async runTurn(request: LlmTurnRequest, onDelta?: (delta: string) => void) {
-    const prepared = AgentService.readable(AgentService.explained(request), this.llm.accepts);
+
+    const names = ToolNames.of(request);
+    const prepared = names.encode(AgentService.readable(AgentService.explained(request), this.llm.accepts));
     const answer = await this.llm.chat(prepared, onDelta);
     if (!answer) throw new Err("agent.error.llmUnavailable");
-    return { text: answer.text ?? "", toolCalls: answer.toolCalls ?? [], stop: answer.stop };
+    return { text: answer.text ?? "", toolCalls: names.decode(answer.toolCalls ?? []), stop: answer.stop };
   }
 
   /**

package/service/toolNames.ts

@@ -0,0 +1,119 @@
+import type { AgentWireMessage, AgentWireToolCall, LlmTurnRequest } from "./predefinedAdaptor/llm.adaptor";
+
+const wireSafe = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Renames a turn's tools onto what a provider's function-calling wire accepts, and reads the answer back.
+ *
+ * A zone publishes its tools scope-prefixed — `videoProjectDraft.createVideoProject` — which is legal for MCP,
+ * where `.` is an allowed character and the scope join. Every OpenAI-compatible and Anthropic function schema is
+ * narrower: `[A-Za-z0-9_-]`, at most 64 characters. A provider that validates answers 400; DeepSeek does not, and
+ * what happened instead was worse to debug — the model normalized the illegal name itself, called the bare
+ * `createVideoProject`, and the browser answered `Unknown tool`, spending a turn on a tool that was published all
+ * along.
+ *
+ * Renamed here rather than in each adaptor for the reason `AgentService.explained` gives: every adaptor would
+ * otherwise have to remember, and forgetting is silent. A name the wire already accepts is left alone, so the
+ * root agent's request is byte-for-byte what it was.
+ */
+export class ToolNames {
+  /** Both dialects reject a longer name, and neither says so in terms of the tool you wrote. */
+  static readonly limit = 64;
+
+  readonly #toWire = new Map<string, string>();
+  readonly #toSurface = new Map<string, string>();
+
+  /**
+   * Every name the request carries, not just the published ones: the transcript holds calls to tools that have
+   * since left the screen, and one of those reaching the wire unrenamed is the same failure a turn later.
+   */
+  static of(request: LlmTurnRequest): ToolNames {
+    return new ToolNames([
+      ...request.tools.map((tool) => tool.name),
+      ...request.messages.flatMap((message) => ToolNames.#namesIn(message)),
+    ]);
+  }
+
+  constructor(names: Iterable<string>) {
+    const all = [...new Set(names)];
+    
+    const taken = new Set(all.filter((name) => ToolNames.#fits(name)));
+
+    for (const name of all.filter((candidate) => !ToolNames.#fits(candidate)).sort((a, b) => (a < b ? -1 : 1))) {
+      const wire = ToolNames.#unique(ToolNames.#fold(name), taken);
+      taken.add(wire);
+      this.#toWire.set(name, wire);
+      this.#toSurface.set(wire, name);
+    }
+  }
+
+  get renamed() {
+    return this.#toWire.size > 0;
+  }
+
+  wire(name: string) {
+    return this.#toWire.get(name) ?? name;
+  }
+
+  /**
+   * Unknown stays as it came. A model that invented a name is answered by the surface's own `Unknown tool`, which
+   * lands in the transcript as a tool result it can correct from — guessing which tool it meant would run one.
+   */
+  surface(name: string) {
+    return this.#toSurface.get(name) ?? name;
+  }
+
+  encode(request: LlmTurnRequest): LlmTurnRequest {
+    if (!this.renamed) return request;
+    return {
+      ...request,
+      tools: request.tools.map((tool) => ({ ...tool, name: this.wire(tool.name) })),
+      messages: request.messages.map((message) => this.#encoded(message)),
+    };
+  }
+
+  decode(calls: AgentWireToolCall[]): AgentWireToolCall[] {
+    if (!this.renamed) return calls;
+    return calls.map((call) => ({ ...call, name: this.surface(call.name) }));
+  }
+
+  #encoded(message: AgentWireMessage): AgentWireMessage {
+    if (!message.toolCalls?.length && !message.toolResults?.length) return message;
+    return {
+      ...message,
+      ...(message.toolCalls?.length
+        ? { toolCalls: message.toolCalls.map((call) => ({ ...call, name: this.wire(call.name) })) }
+        : {}),
+      ...(message.toolResults?.length
+        ? { toolResults: message.toolResults.map((result) => ({ ...result, name: this.wire(result.name) })) }
+        : {}),
+    };
+  }
+
+  static #namesIn(message: AgentWireMessage): string[] {
+    return [
+      ...(message.toolCalls ?? []).map((call) => call.name),
+      ...(message.toolResults ?? []).map((result) => result.name),
+    ];
+  }
+
+  static #fits(name: string) {
+    return name.length <= ToolNames.limit && wireSafe.test(name);
+  }
+
+  /** `.` is the one character the surface itself adds, so it folds to the `__` every MCP client already reads. */
+  static #fold(name: string) {
+    const folded = name.replaceAll(".", "__").replace(/[^A-Za-z0-9_-]/g, "-");
+    
+    return folded.length <= ToolNames.limit ? folded : folded.slice(folded.length - ToolNames.limit);
+  }
+
+  static #unique(candidate: string, taken: Set<string>) {
+    if (!taken.has(candidate)) return candidate;
+    for (let idx = 2; ; idx += 1) {
+      const suffix = `_${idx}`;
+      const next = `${candidate.slice(0, ToolNames.limit - suffix.length)}${suffix}`;
+      if (!taken.has(next)) return next;
+    }
+  }
+}

package/types/service/toolNames.d.ts

@@ -0,0 +1,35 @@
+import type { AgentWireToolCall, LlmTurnRequest } from "./predefinedAdaptor/llm.adaptor";
+/**
+ * Renames a turn's tools onto what a provider's function-calling wire accepts, and reads the answer back.
+ *
+ * A zone publishes its tools scope-prefixed — `videoProjectDraft.createVideoProject` — which is legal for MCP,
+ * where `.` is an allowed character and the scope join. Every OpenAI-compatible and Anthropic function schema is
+ * narrower: `[A-Za-z0-9_-]`, at most 64 characters. A provider that validates answers 400; DeepSeek does not, and
+ * what happened instead was worse to debug — the model normalized the illegal name itself, called the bare
+ * `createVideoProject`, and the browser answered `Unknown tool`, spending a turn on a tool that was published all
+ * along.
+ *
+ * Renamed here rather than in each adaptor for the reason `AgentService.explained` gives: every adaptor would
+ * otherwise have to remember, and forgetting is silent. A name the wire already accepts is left alone, so the
+ * root agent's request is byte-for-byte what it was.
+ */
+export declare class ToolNames {
+    #private;
+    /** Both dialects reject a longer name, and neither says so in terms of the tool you wrote. */
+    static readonly limit = 64;
+    /**
+     * Every name the request carries, not just the published ones: the transcript holds calls to tools that have
+     * since left the screen, and one of those reaching the wire unrenamed is the same failure a turn later.
+     */
+    static of(request: LlmTurnRequest): ToolNames;
+    constructor(names: Iterable<string>);
+    get renamed(): boolean;
+    wire(name: string): string;
+    /**
+     * Unknown stays as it came. A model that invented a name is answered by the surface's own `Unknown tool`, which
+     * lands in the transcript as a tool result it can correct from — guessing which tool it meant would run one.
+     */
+    surface(name: string): string;
+    encode(request: LlmTurnRequest): LlmTurnRequest;
+    decode(calls: AgentWireToolCall[]): AgentWireToolCall[];
+}

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/Context.d.ts

@@ -2,8 +2,12 @@ interface ContextProps {
     className?: string;
 }
 /**
- * Assembles and shows the exact context blocks a turn would carry, on demand — the one preview of "what does the
- * agent see on this screen" that no amount of reading the source answers.
+ * Assembles and shows exactly what a turn would carry, on demand — the one preview of "what does the agent see on
+ * this screen" that no amount of reading the source answers.
+ *
+ * The tool list leads, by name only: a zone publishes its tools scope-prefixed, and instructions that name a tool
+ * without its prefix name a tool that does not exist. That is invisible in the source of either file and obvious
+ * here.
  */
 export default function Context({ className }: ContextProps): import("react/jsx-runtime").JSX.Element;
 export {};

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/Zone.d.ts

@@ -40,5 +40,9 @@ export interface ZoneProps {
  * inside — hook tools, `st.use` subscriptions, guides — belongs to this zone's session *and* to the root agent:
  * zones are views, never walls. An `Agent.Chat` mounted inside binds to this session automatically, so two zones
  * on one screen run two conversations in parallel, each seeing only its own subtree.
+ *
+ * **Everything a zone publishes is named `<id>.<name>`.** Instructions that name a tool must carry the prefix —
+ * a bare name is a tool that does not exist, and the model calling it spends a turn on `Unknown tool`. Build the
+ * name from the id rather than writing it twice, and read `Agent.Context`'s Assemble to see the published list.
  */
 export declare const Zone: ({ className, id, label, instructions, runner, maxTurns, compact, builtins, persist, onCompact, session: provided, onSession, children, }: ZoneProps) => import("react/jsx-runtime").JSX.Element;

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/Field.d.ts

@@ -33,7 +33,7 @@ export declare const Field: {
     Price: import("react").MemoExoticComponent<({ label, desc, labelClassName, className, value, onChange, placeholder, nullable, disabled, minlength, maxlength, transform, validate, onPressEnter, inputClassName, inputStyleType, }: PriceProps) => import("react/jsx-runtime").JSX.Element>;
     TextArea: import("react").MemoExoticComponent<({ label, desc, labelClassName, className, value, onChange, placeholder, nullable, disabled, rows, minlength, maxlength, transform, validate, onPressEnter, cache, inputClassName, }: TextAreaProps) => import("react/jsx-runtime").JSX.Element>;
     Switch: ({ label, desc, labelClassName, className, value, onChange, disabled, inputClassName, onDesc, offDesc, }: SwitchProps) => import("react/jsx-runtime").JSX.Element;
-    ToggleSelect: <I extends string | number | boolean | null>({ className, labelClassName, label, desc, items, value, validate, onChange, nullable, disabled, btnClassName, }: ToggleSelectProps<I>) => import("react/jsx-runtime").JSX.Element;
+    ToggleSelect: <I extends string | number | boolean | null, Nullable extends boolean = false>({ className, labelClassName, label, desc, items, value, validate, onChange, nullable, disabled, btnClassName, }: ToggleSelectProps<I, Nullable>) => import("react/jsx-runtime").JSX.Element;
     MultiToggleSelect: <I extends string | number | boolean>({ className, labelClassName, label, desc, items, value, minlength, maxlength, validate, onChange, disabled, }: MultiToggleSelectProps<I>) => import("react/jsx-runtime").JSX.Element;
     TextList: ({ label, desc, labelClassName, className, value, onChange, placeholder, disabled, transform, minlength, maxlength, minTextlength, maxTextlength, cache, validate, inputClassName, }: TextListProps) => import("react/jsx-runtime").JSX.Element;
     Tags: ({ label, desc, labelClassName, className, value, onChange, placeholder, disabled, transform, minlength, maxlength, minTextlength, maxTextlength, validate, inputClassName, }: TagsProps) => import("react/jsx-runtime").JSX.Element;
@@ -71,7 +71,7 @@ interface ListProps<Item> {
     label?: string;
     desc?: string;
     nullable?: boolean;
-    value: Item[];
+    value: Item[] | null;
     onChange: (value: Item[]) => void;
     onAdd: () => void;
     renderItem: (item: Item, idx: number) => ReactNode;
@@ -137,14 +137,14 @@ interface SwitchProps {
     desc?: string;
     labelClassName?: string;
     className?: string;
-    value: boolean;
+    value: boolean | null;
     onChange: (value: boolean) => void;
     inputClassName?: string;
     onDesc?: string;
     offDesc?: string;
     disabled?: boolean;
 }
-interface ToggleSelectProps<I> {
+interface ToggleSelectProps<I, Nullable extends boolean> {
     className?: string;
     labelClassName?: string;
     label?: string;
@@ -156,11 +156,11 @@ interface ToggleSelectProps<I> {
         value: I;
         disabled?: boolean;
     }[] | readonly I[] | I[] | EnumInstance<string, I>;
-    value: I;
-    nullable?: boolean;
+    value: I | null;
+    nullable?: Nullable;
     disabled?: boolean;
     validate?: (value: I) => boolean | string;
-    onChange: (value: I) => void;
+    onChange: (value: Nullable extends true ? I | null : I) => void;
     btnClassName?: string;
 }
 interface MultiToggleSelectProps<I extends string | number | boolean> {
@@ -173,7 +173,7 @@ interface MultiToggleSelectProps<I extends string | number | boolean> {
         value: I;
         disabled?: boolean;
     }[] | readonly I[] | I[];
-    value: I[];
+    value: I[] | null;
     disabled?: boolean;
     minlength?: number;
     maxlength?: number;
@@ -185,7 +185,7 @@ interface TextListProps {
     desc?: string;
     labelClassName?: string;
     className?: string;
-    value: string[];
+    value: string[] | null;
     onChange: (value: string[]) => void;
     inputClassName?: string;
     placeholder?: string;
@@ -203,7 +203,7 @@ interface TagsProps {
     desc?: string;
     labelClassName?: string;
     className?: string;
-    value: string[];
+    value: string[] | null;
     onChange: (value: string[]) => void;
     inputClassName?: string;
     placeholder?: string;
@@ -386,7 +386,7 @@ interface ChildrenProps<T extends string, State, Input, Full, Light> {
     disabled?: boolean;
     nullable?: boolean;
     initArgs?: any[];
-    value: Light[];
+    value: Light[] | null;
     onChange: (value: Light[]) => void;
     onSearch?: (text: string) => void;
     slice: SliceMeta;
@@ -402,7 +402,7 @@ interface ChildrenIdProps<T extends string, State, Input, Full, Light> {
     disabled?: boolean;
     nullable?: boolean;
     initArgs?: any[];
-    value: string[];
+    value: string[] | null;
     slice: SliceMeta;
     onChange: (value: string[]) => void;
     onSearch?: (text: string) => void;

package/types/ui/ToggleSelect.d.ts

@@ -11,6 +11,7 @@ export interface ToggleSelectProps<I extends string | number | boolean | null> {
     nullable: boolean;
     validate: (value: I) => boolean | string;
     onChange: (value: I, idx: number) => void;
+    onClear?: () => void;
     disabled?: boolean;
 }
 export interface MultiProps {

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/types/vendor/use-agentic/index.d.ts

@@ -7,6 +7,7 @@ export * from "./AgentScope.d.ts";
 export * from "./AgentSession.d.ts";
 export * from "./Compaction.d.ts";
 export * from "./httpRunner.d.ts";
+export * from "./sharedContext.d.ts";
 export * from "./surfaceContext.d.ts";
 export * from "./ToolOutput.d.ts";
 export * from "./Transcript.d.ts";

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

@@ -0,0 +1,15 @@
+import { type Context } from "react";
+/**
+ * A React context interned on `globalThis`, for the reason `AgenticSurface.shared` is: an app does not get one
+ * copy of this package. An akan build inlines it into every client bundle that reaches it — four of them in this
+ * repo's own docs app — and a context is identified by object identity, so a `ScopeContext.Provider` rendered by
+ * `Agent.Zone` in one copy is invisible to the `st.tool` reading it from another.
+ *
+ * That failure is silent, which is what makes it worth a global: the read falls back to the context's default, so
+ * the tool registers at the root scope instead of the zone's, the zone session filters it out as belonging to a
+ * different view, and the model is handed the built-ins with nothing thrown and nothing logged.
+ *
+ * Every context this package owns goes through here. Adding one the plain way would work in the monorepo — one
+ * copy, one object — and fail only once bundled, which is exactly the bug this replaced.
+ */
+export declare const sharedContext: <T>(name: string, initial: T) => Context<T>;

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/Context.tsx

@@ -9,16 +9,25 @@ interface ContextProps {
 }
 
 /**
- * Assembles and shows the exact context blocks a turn would carry, on demand — the one preview of "what does the
- * agent see on this screen" that no amount of reading the source answers.
+ * Assembles and shows exactly what a turn would carry, on demand — the one preview of "what does the agent see on
+ * this screen" that no amount of reading the source answers.
+ *
+ * The tool list leads, by name only: a zone publishes its tools scope-prefixed, and instructions that name a tool
+ * without its prefix name a tool that does not exist. That is invisible in the source of either file and obvious
+ * here.
  */
 export default function Context({ className }: ContextProps) {
   const [shown, setShown] = useState("");
   const assemble = () => {
     try {
-      const { guides } = AgenticSurface.shared.snapshot();
+      const { guides, tools } = AgenticSurface.shared.snapshot();
       const context = AgentContext.of().blocks(AgenticSurface.shared);
-      setShown(JSON.stringify(guides.length ? { guides, context } : context, null, 2));
+      const assembled = {
+        tools: tools.map((tool) => tool.name),
+        ...(guides.length ? { guides } : {}),
+        context,
+      };
+      setShown(JSON.stringify(assembled, null, 2));
     } catch (thrown) {
       setShown(thrown instanceof Error ? thrown.message : String(thrown));
     }

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/Zone.tsx

@@ -56,6 +56,10 @@ export interface ZoneProps {
  * inside — hook tools, `st.use` subscriptions, guides — belongs to this zone's session *and* to the root agent:
  * zones are views, never walls. An `Agent.Chat` mounted inside binds to this session automatically, so two zones
  * on one screen run two conversations in parallel, each seeing only its own subtree.
+ *
+ * **Everything a zone publishes is named `<id>.<name>`.** Instructions that name a tool must carry the prefix —
+ * a bare name is a tool that does not exist, and the model calling it spends a turn on `Unknown tool`. Build the
+ * name from the id rather than writing it twice, and read `Agent.Context`'s Assemble to see the published list.
  */
 export const Zone = ({
   className,

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/Field.tsx

@@ -86,7 +86,7 @@ interface ListProps<Item> {
   label?: string;
   desc?: string;
   nullable?: boolean;
-  value: Item[];
+  value: Item[] | null;
   onChange: (value: Item[]) => void;
   onAdd: () => void;
   renderItem: (item: Item, idx: number) => ReactNode;
@@ -105,11 +105,12 @@ const List = <Item,>({
   const { l } = usePage();
   const recipe = useUiRecipe("button") ?? buttonRecipe;
   useFieldTool(onChange);
+  const items = value ?? [];
   return (
     <div {...agentAttrs(onChange)} className={cn("flex w-full flex-col", className)}>
       {label ? <Label className={labelClassName} nullable={nullable} label={label} desc={desc} /> : null}
       <div className="mb-2 flex w-full flex-col gap-2 rounded-box border border-border p-2">
-        {value.map((item, idx) => (
+        {items.map((item, idx) => (
           <>
             <div key={idx} className="flex h-full w-full items-center justify-between gap-2">
               {renderItem(item, idx)}
@@ -120,7 +121,7 @@ const List = <Item,>({
                     "size-6 border-destructive p-0 text-destructive hover:bg-destructive hover:text-destructive-foreground",
                   )}
                   onClick={() => {
-                    onChange(value.filter((_, i) => i !== idx));
+                    onChange(items.filter((_, i) => i !== idx));
                   }}
                 >
                   <BiTrash />
@@ -351,7 +352,7 @@ interface SwitchProps {
   desc?: string;
   labelClassName?: string;
   className?: string;
-  value: boolean;
+  value: boolean | null;
   onChange: (value: boolean) => void;
   inputClassName?: string;
   onDesc?: string;
@@ -379,7 +380,7 @@ const Switch = ({
           variant="accent"
           disabled={disabled}
           className={inputClassName}
-          checked={value}
+          checked={value ?? false}
           onChange={(checked) => {
             onChange(checked);
           }}
@@ -391,7 +392,7 @@ const Switch = ({
 };
 Field.Switch = Switch;
 
-interface ToggleSelectProps<I> {
+interface ToggleSelectProps<I, Nullable extends boolean> {
   className?: string;
   labelClassName?: string;
   label?: string;
@@ -399,14 +400,14 @@ interface ToggleSelectProps<I> {
   model?: string;
   field?: string;
   items: { label: string; value: I; disabled?: boolean }[] | readonly I[] | I[] | EnumInstance<string, I>;
-  value: I;
-  nullable?: boolean;
+  value: I | null;
+  nullable?: Nullable;
   disabled?: boolean;
   validate?: (value: I) => boolean | string;
-  onChange: (value: I) => void;
+  onChange: (value: Nullable extends true ? I | null : I) => void;
   btnClassName?: string;
 }
-const ToggleSelect = <I extends string | number | boolean | null>({
+const ToggleSelect = <I extends string | number | boolean | null, Nullable extends boolean = false>({
   className,
   labelClassName,
   label,
@@ -418,14 +419,15 @@ const ToggleSelect = <I extends string | number | boolean | null>({
   nullable,
   disabled,
   btnClassName,
-}: ToggleSelectProps<I>) => {
+}: ToggleSelectProps<I, Nullable>) => {
   useFieldTool(onChange, { disabled });
   const { l } = usePage();
   const isEnumValue = isEnum(items as EnumInstance<string, I>);
+  const change = onChange as (value: I | null) => void;
   return (
     <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
       {label ? <Label className={labelClassName} nullable={nullable} label={label} desc={desc} /> : null}
-      <UtilToggleSelect
+      <UtilToggleSelect<I | null>
         className="mt-2"
         nullable={!!nullable}
         btnClassName={btnClassName}
@@ -438,12 +440,15 @@ const ToggleSelect = <I extends string | number | boolean | null>({
             : (items as { label: string; value: I; disabled?: boolean }[])
         }
         value={value}
-        onChange={(value: I, idx) => {
-          onChange(value);
+        onChange={(selected) => {
+          change(selected);
+        }}
+        onClear={() => {
+          change(null);
         }}
         disabled={disabled}
-        validate={(value: I) => {
-          return validate?.(value) ?? true;
+        validate={(selected) => {
+          return selected === null ? true : (validate?.(selected) ?? true);
         }}
       />
     </div>
@@ -457,7 +462,7 @@ interface MultiToggleSelectProps<I extends string | number | boolean> {
   label?: string;
   desc?: string;
   items: EnumInstance<string, I> | { label: string; value: I; disabled?: boolean }[] | readonly I[] | I[];
-  value: I[];
+  value: I[] | null;
   disabled?: boolean;
   minlength?: number;
   maxlength?: number;
@@ -482,7 +487,7 @@ const MultiToggleSelect = <I extends string | number | boolean>({
   const isEnumValue = isEnum(items as EnumInstance<string, I>);
   return (
     <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
-      {label ? <Label className={labelClassName} nullable={!!minlength} label={label} desc={desc} /> : null}
+      {label ? <Label className={labelClassName} nullable={!minlength} label={label} desc={desc} /> : null}
       <UtilToggleSelect.Multi
         nullable={!minlength}
         items={
@@ -493,7 +498,7 @@ const MultiToggleSelect = <I extends string | number | boolean>({
               })) as { label: string; value: string; disabled?: boolean }[])
             : (items as { label: string; value: string; disabled?: boolean }[])
         }
-        value={value as string[]}
+        value={(value ?? []) as string[]}
         onChange={(values) => {
           onChange(values as I[]);
         }}
@@ -514,7 +519,7 @@ interface TextListProps {
   desc?: string;
   labelClassName?: string;
   className?: string;
-  value: string[];
+  value: string[] | null;
   onChange: (value: string[]) => void;
   inputClassName?: string;
   placeholder?: string;
@@ -548,6 +553,7 @@ const TextList = ({
   useFieldTool(onChange, { transform, disabled, sortable: true });
   const { l } = usePage();
   const recipe = useUiRecipe("button") ?? buttonRecipe;
+  const texts = value ?? [];
   return (
     <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
       {label ? <Label className={labelClassName} nullable={!minlength} label={label} desc={desc} /> : null}
@@ -559,10 +565,10 @@ const TextList = ({
             onChange(sorted);
           }}
           onRemove={(_, idx) => {
-            onChange(value.filter((_, i) => i !== idx));
+            onChange(texts.filter((_, i) => i !== idx));
           }}
         >
-          {value.map((text, idx) => (
+          {texts.map((text, idx) => (
             <DraggableList.Item key={idx} value={text}>
               <div className="flex w-full items-center">
                 <DraggableList.Cursor>
@@ -573,7 +579,7 @@ const TextList = ({
                     value={text}
                     cacheKey={cache ? `${label}-${desc}-textList-[${idx}]` : undefined}
                     onChange={(text) => {
-                      const newValue = [...value];
+                      const newValue = [...texts];
                       newValue[idx] = transform(text);
                       onChange(newValue);
                     }}
@@ -593,7 +599,7 @@ const TextList = ({
                       "size-6 border-destructive p-0 text-destructive hover:bg-destructive hover:text-destructive-foreground",
                     )}
                     onClick={() => {
-                      onChange(value.filter((_, i) => i !== idx));
+                      onChange(texts.filter((_, i) => i !== idx));
                     }}
                   >
                     <BiTrash />
@@ -604,11 +610,11 @@ const TextList = ({
           ))}
         </DraggableList>
         <div className="my-5 h-[0.5px] bg-foreground/20" />
-        {value.length <= maxTextlength ? (
+        {texts.length <= maxTextlength ? (
           <button
             className={recipe({ variant: "outline" }, "w-full")}
             onClick={() => {
-              onChange([...value, ""]);
+              onChange([...texts, ""]);
             }}
           >
             + New
@@ -625,7 +631,7 @@ interface TagsProps {
   desc?: string;
   labelClassName?: string;
   className?: string;
-  value: string[];
+  value: string[] | null;
   onChange: (value: string[]) => void;
   inputClassName?: string;
   placeholder?: string;
@@ -658,11 +664,12 @@ const Tags = ({
   useFieldTool(onChange, { transform, disabled });
   const { l } = usePage();
   const badge = useUiRecipe("badge") ?? badgeRecipe;
+  const tagList = value ?? [];
   const [inputVisible, setInputVisible] = useState(false);
   const [tag, setTag] = useState("");
   const addTag = () => {
     if (!tag.length) return;
-    onChange([...value, tag]);
+    onChange([...tagList, tag]);
     setInputVisible(false);
     setTag("");
   };
@@ -671,14 +678,14 @@ const Tags = ({
     <div {...agentAttrs(onChange)} className={cn("flex flex-col", className)}>
       {label ? <Label className={labelClassName} nullable={!minlength} label={label} desc={desc} /> : null}
       <div className="flex w-full flex-wrap items-center gap-1 rounded-box border border-border p-2">
-        {value.map((val, idx) => (
+        {tagList.map((val, idx) => (
           <span className={badge({ variant: "outline" }, "items-center")} key={idx}>
             <div className="text-xs italic">#</div>
             {val}
             <BiX
               className="ml-1 cursor-pointer opacity-50 duration-200 hover:opacity-100"
               onClick={() => {
-                if (!disabled) onChange(value.filter((v, i) => i !== idx));
+                if (!disabled) onChange(tagList.filter((v, i) => i !== idx));
               }}
             />
           </span>
@@ -1455,7 +1462,7 @@ interface ChildrenProps<T extends string, State, Input, Full, Light> {
   disabled?: boolean;
   nullable?: boolean;
   initArgs?: any[];
-  value: Light[];
+  value: Light[] | null;
   onChange: (value: Light[]) => void;
   onSearch?: (text: string) => void;
   slice: SliceMeta;
@@ -1515,7 +1522,7 @@ const Children = <T extends string, State, Input, Full extends { id: string }, L
         labelClassName={labelClassName}
         selectClassName={selectClassName}
         multiple
-        value={value.map((model) => model.id)}
+        value={(value ?? []).map((model) => model.id)}
         options={modelList.map((model) => {
           const label = renderOption(model);
           return { label: typeof label === "string" ? label : model.id, value: model.id };
@@ -1554,7 +1561,7 @@ interface ChildrenIdProps<T extends string, State, Input, Full, Light> {
   disabled?: boolean;
   nullable?: boolean;
   initArgs?: any[];
-  value: string[];
+  value: string[] | null;
   slice: SliceMeta;
   onChange: (value: string[]) => void;
   onSearch?: (text: string) => void;
@@ -1607,7 +1614,7 @@ const ChildrenId = <T extends string, State, Input, Full extends { id: string },
         labelClassName={labelClassName}
         multiple
         
-        value={value}
+        value={value ?? []}
         options={modelList.map((model) => {
           const label = renderOption(model);
           return { label: typeof label === "string" ? label : model.id, value: model.id };

package/ui/ToggleSelect.tsx

@@ -16,6 +16,7 @@ export interface ToggleSelectProps<I extends string | number | boolean | null> {
   nullable: boolean;
   validate: (value: I) => boolean | string;
   onChange: (value: I, idx: number) => void;
+  onClear?: () => void;
   disabled?: boolean;
 }
 const DefaultToggleSelect = <I extends string | number | boolean | null>({
@@ -26,6 +27,7 @@ const DefaultToggleSelect = <I extends string | number | boolean | null>({
   validate,
   value,
   onChange,
+  onClear,
   disabled,
 }: ToggleSelectProps<I>) => {
   const { l } = usePage();
@@ -61,7 +63,8 @@ const DefaultToggleSelect = <I extends string | number | boolean | null>({
             disabled={isDisabled}
             className={cn(toggleBtn, isSelected && selectedCls, isDisabled && "cursor-not-allowed", btnClassName)}
             onClick={() => {
-              onChange(option.value, idx);
+              if (nullable && isSelected) onClear?.();
+              else onChange(option.value, idx);
             }}
           >
             {option.label}

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();

package/vendor/use-agentic/index.ts

@@ -8,6 +8,7 @@ export * from "./AgentScope";
 export * from "./AgentSession";
 export * from "./Compaction";
 export * from "./httpRunner";
+export * from "./sharedContext";
 export * from "./surfaceContext";
 export * from "./ToolOutput";
 export * from "./Transcript";

package/vendor/use-agentic/sharedContext.ts

@@ -0,0 +1,25 @@
+"use client";
+import { type Context, createContext } from "react";
+
+/**
+ * A React context interned on `globalThis`, for the reason `AgenticSurface.shared` is: an app does not get one
+ * copy of this package. An akan build inlines it into every client bundle that reaches it — four of them in this
+ * repo's own docs app — and a context is identified by object identity, so a `ScopeContext.Provider` rendered by
+ * `Agent.Zone` in one copy is invisible to the `st.tool` reading it from another.
+ *
+ * That failure is silent, which is what makes it worth a global: the read falls back to the context's default, so
+ * the tool registers at the root scope instead of the zone's, the zone session filters it out as belonging to a
+ * different view, and the model is handed the built-ins with nothing thrown and nothing logged.
+ *
+ * Every context this package owns goes through here. Adding one the plain way would work in the monorepo — one
+ * copy, one object — and fail only once bundled, which is exactly the bug this replaced.
+ */
+export const sharedContext = <T>(name: string, initial: T): Context<T> => {
+  const key = Symbol.for(`useAgentic.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/vendor/use-agentic/surfaceContext.ts

@@ -1,9 +1,10 @@
 "use client";
-import { createContext, useContext } from "react";
+import { useContext } from "react";
 import { AgenticSurface } from "./AgenticSurface";
+import { sharedContext } from "./sharedContext";
 
-export const SurfaceContext = createContext<AgenticSurface | null>(null);
-export const ScopeContext = createContext<string[]>([]);
+export const SurfaceContext = sharedContext<AgenticSurface | null>("surface", null);
+export const ScopeContext = sharedContext<string[]>("scope", []);
 
 export const useSurface = () => useContext(SurfaceContext) ?? AgenticSurface.shared;
 export const useScopePath = () => useContext(ScopeContext);

package/vendor/use-agentic/useAgent.ts

@@ -1,8 +1,9 @@
 "use client";
-import { createContext, useContext, useSyncExternalStore } from "react";
+import { useContext, useSyncExternalStore } from "react";
 import type { AgentSession } from "./AgentSession";
+import { sharedContext } from "./sharedContext";
 
-export const SessionContext = createContext<AgentSession | null>(null);
+export const SessionContext = sharedContext<AgentSession | null>("session", null);
 
 /** The enclosing session, re-rendering on every session change. `send`/`abort` are safe to destructure. */
 export const useAgent = (): AgentSession => {