@copilotkit/channels 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Atai Barkai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# @copilotkit/channels
+
+The **platform-agnostic channel engine**. It owns everything between an incoming
+message and a rendered reply — handler registration, the agent
+run/tool/interrupt loop, JSX action binding, and the `PlatformAdapter`
+contract — without knowing anything about Slack (or any other surface). A
+platform adapter plugs in at the boundary; `@copilotkit/channels-slack` is the
+concrete Slack one.
+
+It builds on `@copilotkit/channels-ui` (the JSX runtime + component vocabulary,
+re-exported from here for convenience) and AG-UI (`@ag-ui/client`,
+`@ag-ui/core`).
+
+## Install
+
+```sh
+pnpm add @copilotkit/channels @copilotkit/channels-ui
+# plus a platform adapter, e.g.
+pnpm add @copilotkit/channels-slack
+```
+
+## Quickstart
+
+```ts
+import { createBot } from "@copilotkit/channels";
+import { slack } from "@copilotkit/channels-slack"; // a concrete PlatformAdapter
+
+const bot = createBot({
+  adapters: [slack({ botToken, appToken })],
+  agent: (threadId) => makeAgent(threadId), // AbstractAgent or (threadId) => AbstractAgent
+  tools: [...myTools], // BotTool[] forwarded on every runAgent
+  context: [...myContext], // ContextEntry[] forwarded on every runAgent
+});
+
+bot.onMention(({ thread }) => thread.runAgent());
+bot.onMessage(({ thread }) => thread.runAgent());
+
+await bot.start();
+```
+
+`createBot(opts)` returns a `Bot`:
+
+- `onMention(handler)` / `onMessage(handler)` — turn handlers receiving
+  `{ thread, message }`. (Routing is mention-preferred: if any mention
+  handler is registered, all turns route to it; otherwise message handlers
+  fire.)
+- `onThreadStarted(handler)` — a conversation surface opened (e.g. the Slack
+  assistant pane); receives `{ thread, user? }`. Greet, set suggested prompts
+  or a title, or run the agent. Adapters without the concept never fire it.
+- `onInteraction<TValue>(id, handler)` — explicit escape-hatch handler for a
+  known action id, bypassing the registry; `ctx.action.value` is typed `TValue`.
+- `onInterrupt<TPayload>(eventName, handler)` — handle a captured agent
+  interrupt (LangGraph-style `on_interrupt`); receives `{ payload, thread }`
+  with `payload` typed `TPayload`.
+- `onCommand(command)` / `onCommand(name, handler)` — register a slash command.
+  The handler gets `{ thread, command, text, options, user }`. `text` is the
+  raw args (Slack); `options` is the typed, parsed form (`defineBotCommand`
+  with an `options` Standard Schema) for surfaces with native structured args
+  (e.g. Discord). Forwarded to adapters that support commands and ignored
+  elsewhere — also pass them up front via `commands` in `CreateBotOptions`.
+- `tool(t)` — register a `BotTool` (alternative to `opts.tools`); must be
+  added before `start()`.
+- `start()` / `stop()` — bring adapters up / down.
+
+`agent` is optional. If omitted, calling `thread.runAgent()` throws; supply
+an `AbstractAgent` or a `(threadId) => AbstractAgent` factory.
+
+## `Thread`
+
+A `Thread` is the per-conversation handle handed to your handlers and tool
+contexts. It accepts any `Renderable` (JSX or a string) for posting.
+
+```ts
+interface Thread {
+  readonly platform: string;
+  post(ui: Renderable): Promise<MessageRef>;
+  update(ref: MessageRef, ui: Renderable): Promise<MessageRef>;
+  delete(ref: MessageRef): Promise<void>;
+  stream(src: string | AsyncIterable<string>): Promise<MessageRef>;
+  runAgent(input?: {
+    context?: ContextEntry[];
+    tools?: BotTool[];
+  }): Promise<MessageRef | undefined>;
+  resume(value: unknown): Promise<MessageRef | undefined>;
+  awaitChoice<T = unknown>(ui: Renderable): Promise<T>;
+  // Capability-gated (return { ok: false } on surfaces without support):
+  setSuggestedPrompts(
+    prompts: ReadonlyArray<{ title: string; message: string }>,
+    opts?: { title?: string },
+  ): Promise<{ ok: boolean; error?: string }>;
+  setTitle(title: string): Promise<{ ok: boolean; error?: string }>;
+}
+```
+
+- `post` / `update` render the JSX to IR, **bind** every event-prop handler
+  in the tree (mint a content-stable id, snapshot it, rewrite the prop to
+  `{ id }`), then hand the IR to the adapter.
+- `runAgent` resolves the conversation's agent session, creates the adapter's
+  `RunRenderer`, and drives the run/tool/interrupt loop. Per-run `tools` /
+  `context` are merged on top of the bot-level defaults for that run only.
+- `resume(value)` re-enters a paused interrupt run with
+  `forwardedProps.command`.
+- `awaitChoice<T>(ui)` posts a picker and blocks until an interaction in this
+  conversation resolves it to the clicked control's value (HITL); pass `T` to
+  type the returned value.
+
+## Tools & context
+
+A `BotTool` is forwarded to the agent as a frontend tool; its handler runs in
+the bot when the agent calls it. The handler `ctx` carries the `thread`, so a
+tool can render JSX (`ctx.thread.post(<Card .../>)`) or run the agent further.
+
+```ts
+interface BotTool<Schema extends ObjectSchema = ObjectSchema> {
+  name: string;
+  description: string;
+  parameters: Schema; // any Standard Schema (Zod/Valibot/ArkType/…)
+  handler(args, ctx: BotToolContext): Promise<unknown> | unknown;
+}
+```
+
+Define one with the non-curried `defineBotTool`, which infers the arg types
+from `parameters`:
+
+```ts
+defineBotTool({
+  name: "read_thread",
+  description: "Read the messages in the current conversation.",
+  parameters: z.object({}),
+  async handler(_args, { thread }) {
+    return await thread.getMessages();
+  },
+});
+```
+
+`parameters` (a Standard Schema) is converted to JSON Schema for the LLM and
+validated on the way back. `BotToolContext` is `{ thread, message?, user?,
+signal?, platform }` — a single shared type with no per-adapter generic.
+Platform-specific power is reached only through capability-gated `thread`
+methods (e.g. `thread.getMessages()`, `thread.lookupUser(query)`,
+`thread.postFile(...)`), so a tool stays portable across surfaces.
+
+A `ContextEntry` is `{ description: string; value: string }` — knowledge
+folded into the agent's system context on each `runAgent`.
+
+## ActionStore
+
+Inline JSX handlers are bound by content. Each interactive node gets a
+**content-stable, opaque** minted id — `mintId(componentName, path, props)`
+= `"ck:" + sha1(name | path | stableStringify(props)).slice(0,16)`. Only the
+opaque id (plus any small `bind()` args) is stamped on the native token; no
+props, PII, or secrets go over the wire.
+
+On a click, the `ActionRegistry` resolves the handler from a hot in-memory
+cache; on a miss it **rehydrates** by loading the snapshot from the
+`ActionStore`, re-rendering the named component with the frozen props, and
+re-walking to the handler's path.
+
+The default `ActionStore` is `InMemoryActionStore` (a `Map` with optional
+TTL). It is lost on restart: after a restart an old button click degrades to
+an `ActionExpiredError` ("this action expired"), which `createBot` swallows.
+**Durable actions require an external store (Redis / DB) — not shipped in
+v1.** Implement the `ActionStore` interface (`put` / `get` / `delete`) and
+pass it as `actionStore` to make actions survive restarts.
+
+## Writing a `PlatformAdapter`
+
+To target a new surface, implement `PlatformAdapter` from this package. The
+engine drives ingress through the `IngressSink` you receive in `start(sink)`
+(`sink.onTurn(IncomingTurn)` / `sink.onInteraction(InteractionEvent)` /
+`sink.onCommand(IncomingCommand)` / `sink.onThreadStarted(IncomingThreadStart)`)
+and egress through your `post` / `update` / `stream` / `delete` (which receive
+`BotNode[]` to translate to a native payload via `render`). You also provide
+`createRunRenderer(target)` (an AG-UI `RunRenderer`: the subscriber to stream
+into, plus accessors for captured tool calls and interrupts that the run-loop
+reads after each `runAgent`), `decodeInteraction(raw)` (native event → opaque
+`InteractionEvent`), `lookupUser`, a `conversationStore`
+(`getOrCreate` → `AgentSession`), and the surface `capabilities` /
+`ackDeadlineMs`. Optional capability methods like `getMessages(target)` and
+`postFile(target, args)` back the matching `thread` methods when the surface
+supports them — likewise `setSuggestedPrompts(target, prompts, opts?)` and
+`setThreadTitle(target, title)` back `thread.setSuggestedPrompts` /
+`thread.setTitle`, and `sink.onThreadStarted(...)` emits the "conversation
+opened" lifecycle event. Slash commands are also capability-gated: an adapter forwards
+invocations via `sink.onCommand(IncomingCommand)`, and may implement
+`registerCommands(specs)` to publish the bot's declared commands up front
+(e.g. Discord's application-command API); adapters that omit it are skipped.
+See `@copilotkit/channels-slack` for a complete implementation.
+
+## Exports
+
+`createBot`, `Bot`, `CreateBotOptions`, `BotHandler`, `ThreadStartHandler`;
+`Thread`; the `PlatformAdapter` boundary types (`RunRenderer`, `IngressSink`,
+`IncomingTurn`, `InteractionEvent`, `IncomingCommand`, `IncomingThreadStart`,
+`SurfaceCapabilities`,
+`ReplyTarget`, `ConversationStore`, `AgentSession`, `CapturedToolCall`,
+`CapturedInterrupt`, `UserQuery`); `ActionStore` / `InMemoryActionStore` /
+`ActionSnapshot` / `ActionRegistry` / `ActionExpiredError`; `BotTool` /
+`BotToolContext` / `defineBotTool` / `BotCommand` / `CommandContext` /
+`CommandSpec` / `defineBotCommand` / `ContextEntry` /
+`AgentToolDescriptor` / `ObjectSchema` and the tool helpers
+(`toAgentToolDescriptors`, `parseToolArgs`, `stringifyHandlerResult`);
+`mintId` / `stableStringify`; `runAgentLoop`; plus the re-exported
+`@copilotkit/channels-ui` vocabulary.

package/dist/action-registry.d.ts

@@ -0,0 +1,59 @@
+import type { BotNode, InteractionContext, ComponentFn, Renderable, MessageReactionHandler } from "@copilotkit/channels-ui";
+import type { ActionStore } from "./action-store.js";
+export declare class ActionExpiredError extends Error {
+    constructor(id: string);
+}
+export declare class ActionRegistry {
+    private store;
+    private components;
+    private hot;
+    private messageReactions;
+    constructor(opts: {
+        store: ActionStore;
+    });
+    /** Cache a `<Message onReaction>` handler for the posted message (same-process). */
+    registerMessageReaction(messageId: string, handler: MessageReactionHandler): void;
+    /**
+     * Persist the message's reaction handler as a `{ component, props }` snapshot
+     * keyed by `messageId`, so a reaction after a restart re-renders the component
+     * and re-derives the handler — durable exactly like a registered-component
+     * `onClick` (and degrading the same way for inline/anonymous components).
+     */
+    persistMessageReaction(messageId: string, snap: {
+        component: string;
+        props: Record<string, unknown>;
+        conversationKey: string;
+    }): Promise<void>;
+    /**
+     * Resolve the `onReaction` handler for `messageId`: the hot cache first, then
+     * the durable snapshot (re-rendering the named component and re-plucking the
+     * root's handler). Returns `undefined` when neither resolves — e.g. an inline
+     * handler whose closure can't be re-derived after a restart.
+     */
+    resolveMessageReaction(messageId: string): Promise<MessageReactionHandler | undefined>;
+    registerComponent(name: string, fn: ComponentFn): void;
+    clearHotCache(): void;
+    bindTree(componentName: string, props: Record<string, unknown>, conversationKey: string): Promise<BotNode[]>;
+    bindRenderable(ui: Renderable, conversationKey: string): Promise<{
+        root: BotNode[];
+        onReaction?: MessageReactionHandler;
+        /**
+         * The component + props to persist for durable reaction routing, present
+         * only when `ui` was a component element with an `onReaction` (an inline IR
+         * tree has no component to re-render, so its handler stays in-memory).
+         */
+        reactionComponent?: {
+            component: string;
+            props: Record<string, unknown>;
+        };
+    }>;
+    private walk;
+    /**
+     * Run the click handler for `id` and return the clicked element's `value`
+     * (so callers can resolve a HITL `awaitChoice` waiter even when the platform
+     * couldn't carry the value in its callback payload). Returns `undefined` when
+     * the element has no `value`.
+     */
+    dispatch(id: string, ctx: InteractionContext): Promise<unknown>;
+}
+//# sourceMappingURL=action-registry.d.ts.map

package/dist/action-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-registry.d.ts","sourceRoot":"","sources":["../src/action-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EAEP,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,EAAE,EAAE,MAAM;CAIvB;AAcD,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,UAAU,CAAkC;IAKpD,OAAO,CAAC,GAAG,CAAgE;IAI3E,OAAO,CAAC,gBAAgB,CAA6C;gBAEzD,IAAI,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE;IAIxC,oFAAoF;IACpF,uBAAuB,CACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,sBAAsB,GAC9B,IAAI;IAIP;;;;;OAKG;IACG,sBAAsB,CAC1B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;QACJ,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,eAAe,EAAE,MAAM,CAAC;KACzB,GACA,OAAO,CAAC,IAAI,CAAC;IAShB;;;;;OAKG;IACG,sBAAsB,CAC1B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC;IAa9C,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI;IAItD,aAAa,IAAI,IAAI;IAMf,QAAQ,CACZ,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,OAAO,EAAE,CAAC;IAcf,cAAc,CAClB,EAAE,EAAE,UAAU,EACd,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC;QACT,IAAI,EAAE,OAAO,EAAE,CAAC;QAChB,UAAU,CAAC,EAAE,sBAAsB,CAAC;QACpC;;;;WAIG;QACH,iBAAiB,CAAC,EAAE;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC;KAC3E,CAAC;YAuBY,IAAI;IA0ClB;;;;;OAKG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;CAsBtE"}

package/dist/action-registry.js

@@ -0,0 +1,217 @@
+import { isBound, getBoundArgs, renderToIR } from "@copilotkit/channels-ui";
+import { mintId } from "./mint-id.js";
+export class ActionExpiredError extends Error {
+    constructor(id) {
+        super(`Action "${id}" has expired or is no longer available.`);
+        this.name = "ActionExpiredError";
+    }
+}
+const EVENT_PROPS = ["onClick", "onSelect", "onSubmit"];
+function isComponentElement(ui) {
+    return (typeof ui === "object" &&
+        ui !== null &&
+        typeof ui.type === "function");
+}
+export class ActionRegistry {
+    store;
+    components = new Map();
+    // Cache the handler AND the element's `value` per minted id. The value is
+    // needed to resolve HITL `awaitChoice` waiters on platforms whose callback
+    // payload can't carry it (e.g. Telegram's 64-byte callback_data only holds
+    // the action id), where `evt.value` arrives undefined.
+    hot = new Map();
+    // Same-process fast path for `<Message onReaction>` handlers, keyed by the
+    // posted message's id. Mirrors the `hot` action cache; the durable snapshot
+    // (below) is the cross-restart counterpart, exactly like onClick.
+    messageReactions = new Map();
+    constructor(opts) {
+        this.store = opts.store;
+    }
+    /** Cache a `<Message onReaction>` handler for the posted message (same-process). */
+    registerMessageReaction(messageId, handler) {
+        this.messageReactions.set(messageId, handler);
+    }
+    /**
+     * Persist the message's reaction handler as a `{ component, props }` snapshot
+     * keyed by `messageId`, so a reaction after a restart re-renders the component
+     * and re-derives the handler — durable exactly like a registered-component
+     * `onClick` (and degrading the same way for inline/anonymous components).
+     */
+    async persistMessageReaction(messageId, snap) {
+        await this.store.put(reactionKey(messageId), {
+            component: snap.component,
+            props: snap.props,
+            path: [],
+            conversationKey: snap.conversationKey,
+        });
+    }
+    /**
+     * Resolve the `onReaction` handler for `messageId`: the hot cache first, then
+     * the durable snapshot (re-rendering the named component and re-plucking the
+     * root's handler). Returns `undefined` when neither resolves — e.g. an inline
+     * handler whose closure can't be re-derived after a restart.
+     */
+    async resolveMessageReaction(messageId) {
+        const hot = this.messageReactions.get(messageId);
+        if (hot)
+            return hot;
+        const snap = await this.store.get(reactionKey(messageId));
+        if (!snap?.component)
+            return undefined;
+        const fn = this.components.get(snap.component);
+        if (!fn)
+            return undefined;
+        const root = renderToIR(fn(snap.props));
+        return takeMessageReaction(root);
+    }
+    registerComponent(name, fn) {
+        this.components.set(name, fn);
+    }
+    clearHotCache() {
+        this.hot.clear();
+    }
+    // Renders the named component, binds all event-prop handlers in the tree
+    // (mint id, hot-cache + ActionStore snapshot, rewrite prop to { id }), returns the bound IR.
+    async bindTree(componentName, props, conversationKey) {
+        const fn = this.components.get(componentName);
+        const root = renderToIR((fn ? fn(props) : props));
+        await this.walk(root, [], componentName, props, conversationKey);
+        return root;
+    }
+    // Binds an arbitrary Renderable for posting. If `ui` is a component element
+    // (`{ type: fn, props }`), it is registered + bound by name (cold-path
+    // re-render supported). Otherwise the IR is bound inline with `component:""`,
+    // meaning a cold-cache dispatch throws ActionExpiredError (intended
+    // degradation for inline handlers that can't be re-derived). A top-level
+    // `<Message onReaction>` handler is pulled off the IR (so it never reaches the
+    // adapter) and returned for the caller to associate with the posted message.
+    async bindRenderable(ui, conversationKey) {
+        let root;
+        let component;
+        let props;
+        if (isComponentElement(ui)) {
+            const fn = ui.type;
+            component = fn.name || "anonymous";
+            props = (ui.props ?? {});
+            this.registerComponent(component, fn);
+            root = await this.bindTree(component, props, conversationKey);
+        }
+        else {
+            root = renderToIR(ui);
+            await this.walk(root, [], "", undefined, conversationKey);
+        }
+        const onReaction = takeMessageReaction(root);
+        return {
+            root,
+            onReaction,
+            reactionComponent: onReaction && component && props ? { component, props } : undefined,
+        };
+    }
+    async walk(nodes, base, comp, props, conv) {
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i];
+            const path = [...base, i];
+            for (const ep of EVENT_PROPS) {
+                const handler = node.props[ep];
+                if (typeof handler === "function") {
+                    const fullPath = [...path, ep];
+                    const id = mintId(comp, fullPath, props);
+                    this.hot.set(id, {
+                        handler: handler,
+                        value: node.props.value,
+                    });
+                    await this.store.put(id, {
+                        component: comp,
+                        props,
+                        path: fullPath,
+                        conversationKey: conv,
+                        boundArgs: isBound(handler) ? getBoundArgs(handler) : undefined,
+                    });
+                    node.props[ep] = { id };
+                }
+            }
+            const children = node.props.children;
+            if (Array.isArray(children)) {
+                await this.walk(children, [...path, "children"], comp, props, conv);
+            }
+        }
+    }
+    /**
+     * Run the click handler for `id` and return the clicked element's `value`
+     * (so callers can resolve a HITL `awaitChoice` waiter even when the platform
+     * couldn't carry the value in its callback payload). Returns `undefined` when
+     * the element has no `value`.
+     */
+    async dispatch(id, ctx) {
+        let handler;
+        let value;
+        const hot = this.hot.get(id);
+        if (hot) {
+            handler = hot.handler;
+            value = hot.value;
+        }
+        else {
+            const snap = await this.store.get(id);
+            if (!snap || !snap.component)
+                throw new ActionExpiredError(id);
+            const fn = this.components.get(snap.component);
+            if (!fn)
+                throw new ActionExpiredError(id);
+            const tree = renderToIR(fn(snap.props));
+            handler = pluck(tree, snap.path);
+            value = pluckValue(tree, snap.path);
+            if (!handler)
+                throw new ActionExpiredError(id);
+        }
+        await handler({ ...ctx, action: { ...ctx.action, id } });
+        return value;
+    }
+}
+/** Store key for a message's durable reaction snapshot (distinct from minted action ids). */
+function reactionKey(messageId) {
+    return `reaction:${messageId}`;
+}
+/**
+ * Pull a top-level `<Message onReaction>` handler off the IR, deleting the prop
+ * so it never reaches the adapter (a function can't be serialized to a native
+ * payload). Returns the handler when the single root node is a `message`.
+ */
+function takeMessageReaction(root) {
+    const node = root.length === 1 ? root[0] : undefined;
+    if (!node || node.type !== "message" || !("onReaction" in node.props)) {
+        return undefined;
+    }
+    const handler = node.props.onReaction;
+    delete node.props.onReaction;
+    return typeof handler === "function"
+        ? handler
+        : undefined;
+}
+/** Navigate to the node owning the event-prop at `path` and read its `value`. */
+function pluckValue(tree, path) {
+    let cur = tree;
+    for (const seg of path.slice(0, -1)) {
+        if (Array.isArray(cur))
+            cur = cur[seg];
+        else if (cur && typeof cur === "object")
+            cur = cur.props?.[seg];
+        else
+            return undefined;
+    }
+    return cur?.props?.value;
+}
+function pluck(tree, path) {
+    let cur = tree;
+    for (const seg of path.slice(0, -1)) {
+        if (Array.isArray(cur))
+            cur = cur[seg];
+        else if (cur && typeof cur === "object")
+            cur = cur.props?.[seg];
+        else
+            return undefined;
+    }
+    const ep = path[path.length - 1];
+    const node = cur;
+    const h = node?.props?.[ep];
+    return typeof h === "function" ? h : undefined;
+}

package/dist/action-registry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=action-registry.test.d.ts.map

package/dist/action-registry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-registry.test.d.ts","sourceRoot":"","sources":["../src/action-registry.test.ts"],"names":[],"mappings":""}

package/dist/action-registry.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { ActionRegistry, ActionExpiredError } from "./action-registry.js";
+import { InMemoryActionStore } from "./action-store.js";
+import { MemoryStore } from "./state/memory-store.js";
+import { kvActionStore } from "./state/kv-action-store.js";
+// Records each click so a test can assert the handler ran — dispatch() now
+// returns the clicked element's `value` (needed to resolve HITL waiters on
+// platforms whose callback payload can't carry it), not the handler's return.
+const clicks = [];
+function Confirm(props) {
+    return {
+        type: "actions",
+        props: {
+            children: [
+                {
+                    type: "button",
+                    props: {
+                        value: { ok: props.action },
+                        onClick: ({ action }) => {
+                            clicks.push(`ok:${props.action}:${action.id}`);
+                        },
+                        children: "Yes",
+                    },
+                },
+            ],
+        },
+    };
+}
+const ctx = {};
+describe("ActionRegistry", () => {
+    beforeEach(() => {
+        clicks.length = 0;
+    });
+    it("dispatches via hot cache, runs the handler, and returns the element value", async () => {
+        const reg = new ActionRegistry({ store: new InMemoryActionStore() });
+        reg.registerComponent("Confirm", Confirm);
+        const ir = await reg.bindTree("Confirm", { action: "write" }, "conv1");
+        const button = ir[0].props.children[0];
+        const id = button.props.onClick.id;
+        expect(typeof id).toBe("string");
+        const value = await reg.dispatch(id, ctx);
+        expect(value).toEqual({ ok: "write" });
+        expect(clicks[0]).toContain("ok:write:");
+    });
+    it("cold path re-renders from snapshot when hot cache is cleared, still returning the value", async () => {
+        const reg = new ActionRegistry({ store: new InMemoryActionStore() });
+        reg.registerComponent("Confirm", Confirm);
+        const ir = await reg.bindTree("Confirm", { action: "write" }, "conv1");
+        const id = ir[0].props.children[0].props.onClick.id;
+        reg.clearHotCache();
+        const value = await reg.dispatch(id, ctx);
+        expect(value).toEqual({ ok: "write" });
+        expect(clicks[0]).toContain("ok:write:");
+    });
+    it("throws ActionExpiredError on full miss", async () => {
+        const reg = new ActionRegistry({ store: new InMemoryActionStore() });
+        await expect(reg.dispatch("ck:missing", ctx)).rejects.toBeInstanceOf(ActionExpiredError);
+    });
+    it("dispatches from a cold registry via a shared store (restart survival)", async () => {
+        const state = new MemoryStore();
+        // registryA: bind a tree and persist snapshot to shared state
+        const regA = new ActionRegistry({ store: kvActionStore(state) });
+        regA.registerComponent("Confirm", Confirm);
+        const ir = await regA.bindTree("Confirm", { action: "approve" }, "conv-cold");
+        const id = ir[0].props.children[0].props.onClick.id;
+        // registryB: fresh registry with no hot cache but sharing the same store
+        const regB = new ActionRegistry({ store: kvActionStore(state) });
+        regB.registerComponent("Confirm", Confirm);
+        const value = await regB.dispatch(id, ctx);
+        expect(value).toEqual({ ok: "approve" });
+        expect(clicks[0]).toContain("ok:approve:");
+    });
+    it("throws ActionExpiredError when the snapshot is absent (missing id)", async () => {
+        const reg = new ActionRegistry({
+            store: kvActionStore(new MemoryStore()),
+        });
+        await expect(reg.dispatch("ck:missing", ctx)).rejects.toBeInstanceOf(ActionExpiredError);
+    });
+    describe("components-seeded registry (createBot components option)", () => {
+        it("enables cold dispatch after simulated restart when component is pre-registered", async () => {
+            // Shared store survives the "restart" (like Redis across process restarts).
+            const sharedState = new MemoryStore();
+            // Registry A: bind a named component and persist its snapshot.
+            const regA = new ActionRegistry({ store: kvActionStore(sharedState) });
+            regA.registerComponent("Confirm", Confirm);
+            const ir = await regA.bindTree("Confirm", { action: "restart-test" }, "conv-restart");
+            const id = ir[0].props.children[0].props.onClick.id;
+            // Registry B: fresh process — no hot cache, but component is seeded via
+            // the createBot `components` option equivalent (registerComponent at startup).
+            const regB = new ActionRegistry({ store: kvActionStore(sharedState) });
+            regB.registerComponent("Confirm", Confirm);
+            // Cold dispatch must succeed and fire the handler.
+            const handlerFired = [];
+            // Wrap the existing Confirm component so we can assert the specific call.
+            const value = await regB.dispatch(id, ctx);
+            expect(value).toEqual({ ok: "restart-test" });
+            // The shared `clicks` array is populated by Confirm's onClick.
+            expect(clicks.some((c) => c.includes("ok:restart-test:"))).toBe(true);
+        });
+        it("throws ActionExpiredError when component is NOT pre-registered (no-registration degradation)", async () => {
+            const sharedState = new MemoryStore();
+            // Registry A: bind and persist.
+            const regA = new ActionRegistry({ store: kvActionStore(sharedState) });
+            regA.registerComponent("Confirm", Confirm);
+            const ir = await regA.bindTree("Confirm", { action: "no-reg" }, "conv-no-reg");
+            const id = ir[0].props.children[0].props.onClick.id;
+            // Registry B': fresh process, shared store, but component NOT registered.
+            const regBPrime = new ActionRegistry({
+                store: kvActionStore(sharedState),
+            });
+            // Without registration the cold path cannot re-render → ActionExpiredError.
+            await expect(regBPrime.dispatch(id, ctx)).rejects.toBeInstanceOf(ActionExpiredError);
+        });
+    });
+});

package/dist/action-store.d.ts

@@ -0,0 +1,21 @@
+export interface ActionSnapshot {
+    component?: string;
+    props?: unknown;
+    path: (string | number)[];
+    boundArgs?: unknown;
+    conversationKey: string;
+}
+/** @deprecated Configure `createBot({ state })` instead. Action snapshots are stored via `StateStore.kv`. */
+export interface ActionStore {
+    put(id: string, snap: ActionSnapshot, ttlMs?: number): Promise<void>;
+    get(id: string): Promise<ActionSnapshot | undefined>;
+    delete(id: string): Promise<void>;
+}
+/** @deprecated Configure `createBot({ state })` instead. Action snapshots are stored via `StateStore.kv`. */
+export declare class InMemoryActionStore implements ActionStore {
+    private map;
+    put(id: string, snap: ActionSnapshot, ttlMs?: number): Promise<void>;
+    get(id: string): Promise<ActionSnapshot | undefined>;
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=action-store.d.ts.map

package/dist/action-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-store.d.ts","sourceRoot":"","sources":["../src/action-store.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AACD,6GAA6G;AAC7G,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AACD,6GAA6G;AAC7G,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,GAAG,CAAmE;IACxE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IASpD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}