akanjs 3.0.0-alpha.11 → 3.0.0-alpha.13

package/types/store/agent/types.d.ts

@@ -0,0 +1,49 @@
+import type { SerializedArg } from "akanjs/signal";
+import type { SliceActionKey } from "../sliceRole.d.ts";
+import type { SliceStateKey } from "../state.d.ts";
+/** Which generated form-setter a store key is, when it is one. */
+export type FormSetterRole = "set" | "add" | "sub" | "addOrSub";
+/** What calling a store action reaches. `state` never leaves the browser. */
+export type StoreActionEffect = "state" | "query" | "mutation";
+export interface SerializedStoreAction {
+    args: SerializedArg[];
+    effect: StoreActionEffect;
+    /** The model this key belongs to, when the key identifies one. */
+    refName?: string;
+    /** The endpoint whose arguments it borrows, when it is named after one. */
+    endpoint?: string;
+    /** The generated role, absent on an action a module wrote itself. */
+    role?: SliceActionKey | FormSetterRole;
+    /** The model field it writes, on a form setter. */
+    field?: string;
+}
+export interface SerializedStoreState {
+    /**
+     * What the live value is. A store declares no types — `STATE_META` holds initial values — so this is read off the
+     * value the store is holding, and a key initialized to `null` or `[]` says nothing about what may go into it.
+     */
+    type: "string" | "number" | "boolean" | "date" | "list" | "map" | "object" | "unknown";
+    /** The model this key holds, when it holds one. What a read of it is masked by. */
+    refName?: string;
+    /** Which of the model's five classes, which is what decides the fields a read may carry. */
+    modelType?: "input" | "full" | "light" | "insight";
+    /** Materialized from a computation, the URL, or storage. Writing one throws, so it is read-only by construction. */
+    derived: boolean;
+    role?: SliceStateKey;
+}
+/**
+ * One store instance described for an agent: every key it can read and every action it may call.
+ *
+ * Flat rather than grouped by model, because that is what the store is — `st.use.x` and `st.do.y` are one namespace,
+ * so a key means the same thing to every reader and two models cannot both claim one. It is the store's answer to
+ * `SerializedSignal`, and it is derived on the client from the built store rather than shipped from the server: the
+ * store classes are in the bundle already, and a second copy over the wire is a second thing to keep in step.
+ */
+export interface SerializedStore {
+    state: {
+        [key: string]: SerializedStoreState;
+    };
+    action: {
+        [key: string]: SerializedStoreAction;
+    };
+}

package/types/store/agent.d.ts

@@ -0,0 +1 @@
+export * from "./agent/index.d.ts";

package/types/store/databaseStateNames.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The state keys every model store holds, and which of the model's five classes each one is an instance of.
+ *
+ * Shared with the agent catalogue, which needs the class rather than the key: a value read out of the store is
+ * masked by the model it belongs to, and `immerify` drops the constructor, so the live value cannot say what it is.
+ * `modelForm` is the one that matters most — it is an `Input` holding whatever the user has typed, credentials
+ * included, and it reaches the catalogue as a plain object.
+ */
+export declare const databaseStateNames: (refName: string) => {
+    model: string;
+    modelLoading: string;
+    modelForm: string;
+    modelFormLoading: string;
+    modelSubmit: string;
+    modelViewAt: string;
+    modelModal: string;
+    modelOperation: string;
+    defaultModel: string;
+};
+/** Which of the model's classes each generated state key holds, for the keys that hold one at all. */
+export declare const databaseStateModelTypes: {
+    readonly model: "full";
+    readonly modelForm: "input";
+    readonly defaultModel: "full";
+};

package/types/store/formSetterNames.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The keys `makeFormSetter` publishes for one field of one model.
+ *
+ * Shared with the agent catalogue, which has to answer what `setNameOnUser` takes without parsing the name apart —
+ * `set(.+)On(.+)` has more than one reading whenever a field or a model name contains `On`. Computing the same names
+ * forward from the same field metadata is unambiguous, and keeps the two from drifting when a name changes here.
+ */
+export declare const formSetterNames: (className: string, key: string) => {
+    field: string;
+    Field: string;
+    setFieldOnModel: string;
+    addFieldOnModel: string;
+    subFieldOnModel: string;
+    addOrSubFieldOnModel: string;
+    uploadFieldOnModel: string;
+};

package/types/store/index.d.ts

@@ -1,8 +1,14 @@
 export * from "./action.d.ts";
+export * from "./actionTag.d.ts";
+export * from "./agent.d.ts";
 export * from "./baseSt.d.ts";
+export * from "./databaseStateNames.d.ts";
+export * from "./formSetterNames.d.ts";
 export * from "./rootStore.d.ts";
+export * from "./sliceRole.d.ts";
 export * from "./state.d.ts";
 export * from "./stateBuilder.d.ts";
 export * from "./store.d.ts";
+export { StoreInstance } from "./storeInstance.d.ts";
 export * from "./storeRegistry.d.ts";
 export * from "./types.d.ts";

package/types/store/rootStore.d.ts

@@ -1,4 +1,4 @@
-import type { ACTION_META, Cls, STATE_DERIVED_META, STATE_INIT_META, STATE_META } from "akanjs/base";
+import type { ACTION_META, ACTION_OWNER_META, Cls, STATE_DERIVED_META, STATE_INIT_META, STATE_META } from "akanjs/base";
 import type { SerializedSlice } from "akanjs/signal";
 import type { StateDerivedMeta, StateInitializerMap } from "./stateBuilder.d.ts";
 import type { SetGetWritable } from "./types.d.ts";
@@ -13,6 +13,9 @@ export type RootStoreCls<RefName extends string = any, WritableState = any, Acti
     [ACTION_META]: {
         [key: string]: (...args: any[]) => any;
     };
+    [ACTION_OWNER_META]: {
+        [key: string]: string;
+    };
     slice: {
         [key: string]: {
             [key: string]: SerializedSlice;

package/types/store/sliceRole.d.ts

@@ -0,0 +1,25 @@
+import type { SerializedArg } from "akanjs/signal";
+import type { SliceStateKey } from "./state.d.ts";
+/** The generated slice actions, named by what they do rather than by the key any one slice publishes them under. */
+export type SliceActionKey = "initModel" | "refreshModel" | "selectModel" | "setPageOfModel" | "addPageOfModel" | "setLimitOfModel" | "setQueryArgsOfModel" | "setSortOfModel";
+/**
+ * What a generated key on `st.do` / `st.use` actually is.
+ *
+ * A slice publishes its keys with the model and the suffix spliced into the role name — `setPageOfUserInOrg` for the
+ * `setPageOfModel` role of `user`'s `inOrg` slice — and the splicing is string replacement over capitalized names.
+ * Recording the role while the key is being built is what saves a reader of the finished store from running that
+ * replacement backwards, which does not have one answer: on a model named `page`, `setPageOfPage` is both the
+ * paging action and a field setter.
+ */
+export interface SliceActionRole {
+    role: SliceActionKey;
+    refName: string;
+    sliceName: string;
+    /** The slice's own arguments, which the `initModel` and `setQueryArgsOfModel` roles take positionally. */
+    args: SerializedArg[];
+}
+export interface SliceStateRole {
+    role: SliceStateKey;
+    refName: string;
+    sliceName: string;
+}

package/types/store/store.d.ts

@@ -1,4 +1,4 @@
-import { ACTION_META, type Cls, type MergeAllActionTypes, type MergeAllKeyOfObjects, type SLICE_META, STATE_DERIVED_META, STATE_INIT_META, STATE_META } from "akanjs/base";
+import { ACTION_META, ACTION_OWNER_META, type Cls, type MergeAllActionTypes, type MergeAllKeyOfObjects, type SLICE_META, STATE_DERIVED_META, STATE_INIT_META, STATE_META } from "akanjs/base";
 import type { FilterInstance } from "akanjs/document";
 import type { ClientSignal } from "akanjs/fetch";
 import type { SerializedSlice, SlceCnstCapitalizedRefName, SlceCnstDefault, SlceCnstFull, SlceCnstInput, SlceCnstInsight, SlceCnstLight, SlceDbFilter, SlceDbSort, SliceCls } from "akanjs/signal";
@@ -33,6 +33,9 @@ export type StoreCls<RefName extends string = string, WritableState = any, Actio
     [ACTION_META]: {
         [key: string]: (...args: any[]) => any;
     };
+    [ACTION_OWNER_META]: {
+        [key: string]: string;
+    };
     slice: {
         [key: string]: SerializedSlice;
     };

package/types/store/storeInstance.d.ts

@@ -1,5 +1,6 @@
 import type { RefObject } from "react";
 import type { RootStoreCls } from "./rootStore.d.ts";
+import type { SliceActionRole, SliceStateRole } from "./sliceRole.d.ts";
 type StoreStateRecord = Record<string, unknown>;
 type StoreAction = (...args: unknown[]) => unknown;
 export type ReactAPI = {
@@ -32,6 +33,21 @@ export declare class StoreInstance {
     slice: {
         [key: string]: unknown;
     };
+    /** Which module declared each action. The dictionary node its words are written in is named after it. */
+    get actionOwners(): ReadonlyMap<string, string>;
+    /**
+     * How many arguments each action declares.
+     *
+     * Recorded because `do[key]` is a rest-argument wrapper around the real method, so its own `length` is zero for
+     * everything — the arity is gone by the time anyone holding the instance could ask. A rest parameter on the method
+     * itself still reads as zero; nothing can recover that.
+     */
+    get actionArity(): ReadonlyMap<string, number>;
+    /** What each generated slice key is, for a reader that has only the finished store. See `SliceActionRole`. */
+    get sliceActionRoles(): ReadonlyMap<string, SliceActionRole>;
+    get sliceStateRoles(): ReadonlyMap<string, SliceStateRole>;
+    /** Keys the store materializes from a computation, the URL, or storage. `set` throws on them. */
+    get derivedKeys(): ReadonlySet<string>;
     constructor(store?: RootStoreCls);
     addStore(store: RootStoreCls): this;
 }

package/types/store/storeRegistry.d.ts

@@ -1,11 +1,14 @@
 import { type MergeAllKeyOfObjects, type MergeAllKeyOfTypes, type MergeAllTypes, STATE_META } from "akanjs/base";
 import type { RootStoreCls } from "./rootStore.d.ts";
 import type { StoreCls } from "./store.d.ts";
+import { StoreInstance } from "./storeInstance.d.ts";
 export type { ReactAPI } from "./storeInstance.d.ts";
 import type { SetGet } from "./types.d.ts";
 import type { WithSelectors } from "./withSelector.d.ts";
 export declare class StoreRegistry {
     #private;
+    /** The one store every `st.use` / `st.do` in the process goes through. What an agent bridge drives. */
+    static get instance(): StoreInstance;
     static register<StrCls extends StoreCls>(store: StrCls): StrCls;
     static get(refName: string): StoreCls | undefined;
     static merge<RefName extends string, StoreClses extends (StoreCls | RootStoreCls)[]>(refName: RefName, ...stores: StoreClses): RootStoreCls<RefName, MergeAllKeyOfObjects<StoreClses, typeof STATE_META>, MergeAllTypes<StoreClses, keyof SetGet | "slice">, MergeAllKeyOfTypes<StoreClses, "slice">, MergeAllKeyOfObjects<StoreClses, "_slice">>;

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

@@ -0,0 +1,16 @@
+import { AgentBridge } from "akanjs/store";
+export interface DockProps {
+    className?: string;
+    /** Pass the bridge an agent is already driving so both write into one transcript. Defaults to the app's own. */
+    bridge?: AgentBridge;
+    open?: boolean;
+}
+/**
+ * The in-page surface of the agent bridge: what this page lets an agent do, what it refused, and what it has done.
+ *
+ * It drives the store directly rather than talking to a model, because a model is not the framework's to choose —
+ * there is no provider or key here. An app wires its own agent to `bridge.tools` / `bridge.call` and can render this
+ * beside it; on its own it is the way to see the catalogue a page actually publishes, which is the one thing no
+ * amount of reading the source answers.
+ */
+export declare const Dock: ({ className, bridge, open }: DockProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+interface SectionProps {
+    className?: string;
+    title: string;
+    count: number;
+    children: ReactNode;
+    open?: boolean;
+}
+export default function Section({ className, title, count, children, open }: SectionProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,15 @@
+import type { AgentBridge, SerializedStoreState } from "akanjs/store";
+interface StateKeyProps {
+    className?: string;
+    bridge: AgentBridge;
+    name: string;
+    entry: SerializedStoreState;
+}
+/**
+ * One readable state key, read on demand rather than rendered with the rest.
+ *
+ * Reading is where masking happens, so a key that holds an object no model claims refuses here instead of in the
+ * catalogue — whether it is readable depends on what is in it, which the catalogue cannot know ahead of time.
+ */
+export default function StateKey({ className, bridge, name, entry }: StateKeyProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,15 @@
+import type { AgentBridge, AgentTool } from "akanjs/store";
+interface ToolProps {
+    className?: string;
+    bridge: AgentBridge;
+    tool: AgentTool;
+    onRun: () => void;
+}
+/**
+ * One published action, with the arguments as JSON rather than as a generated form.
+ *
+ * A form per argument is what the API explorer does, and it is the wrong trade here: the point of the dock is to
+ * watch a call land in the running app, and every schema shape the store publishes is already legible as JSON.
+ */
+export default function Tool({ className, bridge, tool, onRun }: ToolProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,13 @@
+import type { AgentCall } from "akanjs/store";
+interface TranscriptProps {
+    className?: string;
+    calls: readonly AgentCall[];
+}
+/**
+ * What the agent did, newest last, so the user can check it against what they saw the page do.
+ *
+ * There is no undo here. Every model removal in this framework is soft, so one is possible in principle, but which
+ * writes are reversible is a per-module judgement and `local/agent-native/PLAN.md` §9-3 leaves it open.
+ */
+export default function Transcript({ className, calls }: TranscriptProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,11 @@
+import Section from "./Section.d.ts";
+import StateKey from "./StateKey.d.ts";
+import Tool from "./Tool.d.ts";
+import Transcript from "./Transcript.d.ts";
+export declare const Agent: {
+    Dock: ({ className, bridge, open }: import("./Dock.d.ts").DockProps) => import("react/jsx-runtime").JSX.Element;
+    Section: typeof Section;
+    StateKey: typeof StateKey;
+    Tool: typeof Tool;
+    Transcript: typeof Transcript;
+};

package/types/ui/Agent.d.ts

@@ -0,0 +1 @@
+export * from "./Agent/index.d.ts";

package/types/ui/agentAttrs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The `data-akan-*` attributes for a handler the caller passed by reference.
+ *
+ * `{}` when the handler is an inline arrow, which is the honest answer: a closure the caller wrote says nothing
+ * about what it does, and a guessed annotation is worse than none. The house form for a model field is the setter
+ * itself (`onChange={st.do.setNameOnUser}`), so the fields that matter are annotated without an app writing anything.
+ *
+ * What it buys, beyond an in-page agent: an accessibility tree and E2E selectors that name the action rather than a
+ * class, and an external browser agent — one this framework has no bridge into — reading the same names.
+ */
+export declare const agentAttrs: (handler: unknown) => {
+    "data-akan-action"?: string;
+    "data-akan-state"?: string;
+} | Record<string, never>;

package/types/ui/index.d.ts

@@ -1,3 +1,5 @@
+export { Agent } from "./Agent.d.ts";
+export { agentAttrs } from "./agentAttrs.d.ts";
 export { animated } from "./animated.d.ts";
 export { Badge } from "./Badge.d.ts";
 export { BottomSheet, type BottomSheetRef } from "./BottomSheet.d.ts";

package/ui/Agent/Dock.tsx

@@ -0,0 +1,61 @@
+"use client";
+import { cn } from "akanjs/client";
+import { AgentBridge } from "akanjs/store";
+import { useRef, useState } from "react";
+import Section from "./Section";
+import StateKey from "./StateKey";
+import Tool from "./Tool";
+import Transcript from "./Transcript";
+
+export interface DockProps {
+  className?: string;
+  /** Pass the bridge an agent is already driving so both write into one transcript. Defaults to the app's own. */
+  bridge?: AgentBridge;
+  open?: boolean;
+}
+
+/**
+ * The in-page surface of the agent bridge: what this page lets an agent do, what it refused, and what it has done.
+ *
+ * It drives the store directly rather than talking to a model, because a model is not the framework's to choose —
+ * there is no provider or key here. An app wires its own agent to `bridge.tools` / `bridge.call` and can render this
+ * beside it; on its own it is the way to see the catalogue a page actually publishes, which is the one thing no
+ * amount of reading the source answers.
+ */
+export const Dock = ({ className, bridge, open = false }: DockProps) => {
+  const held = useRef<AgentBridge | null>(null);
+  held.current ??= bridge ?? AgentBridge.of();
+  const agent = held.current;
+  const [ran, setRan] = useState(0);
+  return (
+    <aside
+      className={cn(
+        "fixed right-4 bottom-4 z-50 flex max-h-[70vh] w-80 flex-col gap-2 overflow-y-auto rounded-box border border-base-content/10 bg-base-100/95 p-3 shadow-lg",
+        className,
+      )}
+    >
+      <h2 className="font-semibold text-sm">Agent</h2>
+      <Section count={agent.tools.length} open={open} title="Actions">
+        {agent.tools.map((tool) => (
+          <Tool bridge={agent} key={tool.name} onRun={() => setRan(ran + 1)} tool={tool} />
+        ))}
+      </Section>
+      <Section count={Object.keys(agent.state).length} title="State">
+        {Object.entries(agent.state).map(([name, entry]) => (
+          <StateKey bridge={agent} entry={entry} key={name} name={name} />
+        ))}
+      </Section>
+      <Section count={agent.refusals.length} title="Refused">
+        {agent.refusals.map((refusal) => (
+          <div className="flex flex-col" key={refusal.key}>
+            <span className="truncate font-mono text-xs">{refusal.key}</span>
+            <span className="text-[10px] text-foreground/50">{refusal.reason}</span>
+          </div>
+        ))}
+      </Section>
+      <Section count={agent.transcript.length} open title="Transcript">
+        <Transcript calls={agent.transcript} />
+      </Section>
+    </aside>
+  );
+};

package/ui/Agent/Section.tsx

@@ -0,0 +1,24 @@
+"use client";
+import { cn } from "akanjs/client";
+import type { ReactNode } from "react";
+
+interface SectionProps {
+  className?: string;
+  title: string;
+  count: number;
+  children: ReactNode;
+  open?: boolean;
+}
+
+export default function Section({ className, title, count, children, open }: SectionProps) {
+  return (
+    <details className={cn("group rounded-box bg-muted", className)} open={open}>
+      <summary className="flex cursor-pointer list-none items-center gap-2 px-3 py-2 [&::-webkit-details-marker]:hidden">
+        <span className="font-semibold text-sm">{title}</span>
+        <span className="text-foreground/50 text-xs">{count}</span>
+        <span className="ml-auto text-foreground/40 transition-transform group-open:rotate-180">▾</span>
+      </summary>
+      <div className="flex flex-col gap-1 px-3 pb-3">{children}</div>
+    </details>
+  );
+}

package/ui/Agent/StateKey.tsx

@@ -0,0 +1,42 @@
+"use client";
+import { cn } from "akanjs/client";
+import type { AgentBridge, SerializedStoreState } from "akanjs/store";
+import { useState } from "react";
+
+interface StateKeyProps {
+  className?: string;
+  bridge: AgentBridge;
+  name: string;
+  entry: SerializedStoreState;
+}
+
+/**
+ * One readable state key, read on demand rather than rendered with the rest.
+ *
+ * Reading is where masking happens, so a key that holds an object no model claims refuses here instead of in the
+ * catalogue — whether it is readable depends on what is in it, which the catalogue cannot know ahead of time.
+ */
+export default function StateKey({ className, bridge, name, entry }: StateKeyProps) {
+  const [shown, setShown] = useState("");
+  const read = () => {
+    try {
+      setShown(JSON.stringify(bridge.read(name), null, 2));
+    } catch (thrown) {
+      setShown(thrown instanceof Error ? thrown.message : String(thrown));
+    }
+  };
+  return (
+    <div className={cn("flex flex-col gap-1", className)}>
+      <button className="flex items-center gap-2 text-left" type="button" onClick={read}>
+        <span className="truncate font-mono text-xs">{name}</span>
+        <span className="ml-auto shrink-0 text-[10px] text-foreground/40">
+          {entry.refName ? `${entry.refName}.${entry.modelType ?? ""}` : entry.type}
+          {entry.derived ? " · derived" : ""}
+        </span>
+      </button>
+      {shown ? (
+        <pre className="max-h-40 overflow-auto rounded-field bg-muted p-2 text-[10px] leading-tight">{shown}</pre>
+      ) : null}
+    </div>
+  );
+}

package/ui/Agent/Tool.tsx

@@ -0,0 +1,66 @@
+"use client";
+import { cn } from "akanjs/client";
+import type { AgentBridge, AgentTool } from "akanjs/store";
+import { useState } from "react";
+import { buttonRecipe } from "../recipe";
+
+const effectClass: { [key in AgentTool["effect"]]: string } = {
+  state: "bg-muted text-foreground/70",
+  query: "bg-info/15 text-info",
+  mutation: "bg-warning/15 text-warning",
+};
+
+interface ToolProps {
+  className?: string;
+  bridge: AgentBridge;
+  tool: AgentTool;
+  onRun: () => void;
+}
+
+/**
+ * One published action, with the arguments as JSON rather than as a generated form.
+ *
+ * A form per argument is what the API explorer does, and it is the wrong trade here: the point of the dock is to
+ * watch a call land in the running app, and every schema shape the store publishes is already legible as JSON.
+ */
+export default function Tool({ className, bridge, tool, onRun }: ToolProps) {
+  const [args, setArgs] = useState("{}");
+  const [error, setError] = useState("");
+  const run = async () => {
+    setError("");
+    try {
+      await bridge.call(tool.name, JSON.parse(args) as Record<string, unknown>);
+    } catch (thrown) {
+      setError(thrown instanceof Error ? thrown.message : String(thrown));
+    }
+    onRun();
+  };
+  return (
+    <details className={cn("rounded-field bg-base-100/60 px-2 py-1", className)}>
+      <summary className="flex cursor-pointer list-none items-center gap-2 [&::-webkit-details-marker]:hidden">
+        <span className={cn("rounded-field px-1.5 py-0.5 text-[10px] uppercase", effectClass[tool.effect])}>
+          {tool.effect}
+        </span>
+        <span className="truncate font-mono text-xs">{tool.name}</span>
+      </summary>
+      <div className="flex flex-col gap-2 py-2">
+        {tool.description ? <p className="text-foreground/70 text-xs">{tool.description}</p> : null}
+        <pre className="overflow-x-auto rounded-field bg-muted p-2 text-[10px] leading-tight">
+          {JSON.stringify(tool.inputSchema.properties, null, 2)}
+        </pre>
+        <textarea
+          className="w-full rounded-field bg-muted p-2 font-mono text-xs"
+          rows={2}
+          value={args}
+          onChange={(event) => setArgs(event.target.value)}
+        />
+        {/* `buttonRecipe` rather than `Button`, which reads the app runtime through `usePage()` for labels this
+            developer surface does not localize anyway — the same English the API explorer uses. */}
+        <button className={buttonRecipe({ size: "xs" })} onClick={run} type="button">
+          Run
+        </button>
+        {error ? <p className="text-error text-xs">{error}</p> : null}
+      </div>
+    </details>
+  );
+}

package/ui/Agent/Transcript.tsx

@@ -0,0 +1,33 @@
+"use client";
+import { cn } from "akanjs/client";
+import type { AgentCall } from "akanjs/store";
+
+interface TranscriptProps {
+  className?: string;
+  calls: readonly AgentCall[];
+}
+
+/**
+ * What the agent did, newest last, so the user can check it against what they saw the page do.
+ *
+ * There is no undo here. Every model removal in this framework is soft, so one is possible in principle, but which
+ * writes are reversible is a per-module judgement and `local/agent-native/PLAN.md` §9-3 leaves it open.
+ */
+export default function Transcript({ className, calls }: TranscriptProps) {
+  return (
+    <div className={cn("flex flex-col gap-1", className)}>
+      {calls.map((call, idx) => (
+        <div className="flex flex-col rounded-field bg-base-100/60 px-2 py-1" key={idx}>
+          <div className="flex items-baseline gap-2">
+            <span className="truncate font-mono text-xs">{call.name}</span>
+            <span className="ml-auto shrink-0 text-[10px] text-foreground/40">
+              {call.at.toISOString().slice(11, 19)}
+            </span>
+          </div>
+          <span className="truncate font-mono text-[10px] text-foreground/50">{JSON.stringify(call.args)}</span>
+          {call.error ? <span className="text-[10px] text-error">{call.error}</span> : null}
+        </div>
+      ))}
+    </div>
+  );
+}

package/ui/Agent/index.ts

@@ -0,0 +1,7 @@
+import { Dock } from "./Dock";
+import Section from "./Section";
+import StateKey from "./StateKey";
+import Tool from "./Tool";
+import Transcript from "./Transcript";
+
+export const Agent = { Dock, Section, StateKey, Tool, Transcript };

package/ui/Button.tsx

@@ -4,6 +4,7 @@ import { isThenable } from "akanjs/common";
 import type React from "react";
 import { type ButtonHTMLAttributes, type ComponentType, createElement, useState } from "react";
 import { AiFillCheckCircle, AiOutlineLoading3Quarters } from "react-icons/ai";
+import { agentAttrs } from "./agentAttrs";
 import { type ButtonVariants, buttonRecipe } from "./recipe";
 import { useUiOverride, useUiRecipe } from "./UiOverride";
 
@@ -91,6 +92,7 @@ const DefaultButton = <Result = unknown>({
           cn(loadingMode === "hold" && "relative", busy && !rest.disabled && "disabled:opacity-100", className),
         )}
         {...rest}
+        {...agentAttrs(onClick)}
         disabled={!!rest.disabled || busy}
         onClick={(e) => {
           if (!onClick) return;