@copilotkit/channels-core 0.5.0 → 0.5.1-canary.1785633429

package/README.md

@@ -32,23 +32,28 @@ import { slack } from "@copilotkit/channels-slack";
 `createChannel(opts)` returns a `Channel`:
 
 - `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.)
+  `{ thread, message }`. Bot mentions select `onMention` when registered and
+  otherwise fall back to `onMessage`; other content selects `onMessage`.
 - `onThreadStarted(handler)` — a conversation surface opened (e.g. the Slack
-  assistant pane); receives `{ thread, user? }`. Greet, set suggested prompts
+  assistant pane); receives `{ thread, user, actor }`. Greet, set suggested prompts
   or a title, or run the agent. Adapters without the concept never fire it.
+- `onWelcome(handler)` — a provider installation or conversation activation;
+  receives `{ thread, user?, platform }`. Adapters without a reliable
+  activation event 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 }`
+  interrupt (LangGraph-style `on_interrupt`); receives `{ payload, thread, user, actor }`
   with `payload` typed `TPayload`.
 - `onCommand(command)` / `onCommand(name, handler)` — register a slash command.
-  The handler gets `{ thread, command, text, options, user }`. `text` is the
+  The handler gets `{ thread, command, text, options, user, actor }`. `text` is the
   raw args (Slack); `options` is the typed, parsed form (`defineChannelCommand`
   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 `CreateChannelOptions`.
+  (e.g. Discord). This is a direct-adapter capability: managed Slack and Teams
+  treat leading-slash text as ordinary message content and do not register
+  provider slash commands. Forwarded to direct adapters that support commands
+  and ignored elsewhere — also pass them up front via `commands` in
+  `CreateChannelOptions`.
 - `tool(t)` — register a `ChannelTool` (alternative to `opts.tools`); must be
   added before the runtime activates the channel.
 
@@ -73,6 +78,7 @@ import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";
 
 const channel = createChannel({
   name: "support-bot", // project-unique Intelligence Channel name
+  identifyUser: "platform",
   adapters: [slack({ botToken, appToken })],
 });
 
@@ -82,7 +88,6 @@ const runtime = new CopilotRuntime({
     // both together only for a self-hosted deployment.
     apiKey: process.env.COPILOTKIT_INTELLIGENCE_API_KEY!, // free tier available
   }),
-  identifyUser: async () => ({ id: "support-bot", name: "Support Bot" }),
   channels: [channel],
 });
 
@@ -93,6 +98,12 @@ await listener.channels.ready();
 // await listener.channels.stop(); // tears them down
 ```
 
+The runtime also declares managed Slack and Teams for the same Channel name.
+Developer-owned adapters stay in the adapter array and may run alongside that
+managed adapter. If managed setup is incomplete, configured direct adapters
+still start while `listener.channels.status()` reports `setup_required` for the
+managed path.
+
 ## `Thread`
 
 A `Thread` is the per-conversation handle handed to your handlers and tool
@@ -108,8 +119,15 @@ interface Thread {
   runAgent(input?: {
     context?: ContextEntry[];
     tools?: ChannelTool[];
+    memory?: MemoryGrant;
   }): Promise<MessageRef | undefined>;
-  resume(value: unknown): Promise<MessageRef | undefined>;
+  resume(
+    value: unknown,
+    options?: {
+      memory?: MemoryGrant;
+      subject?: "initiator" | "actor";
+    },
+  ): Promise<MessageRef | undefined>;
   awaitChoice<T = unknown>(ui: Renderable): Promise<T>;
   // Capability-gated (return { ok: false } on surfaces without support):
   setSuggestedPrompts(
@@ -208,8 +226,9 @@ reads after each `runAgent`), `decodeInteraction(raw)` (native event → opaque
 `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
+`thread.setTitle`, `sink.onWelcome(...)` emits a reliable installation or
+activation event, and `sink.onThreadStarted(...)` emits the "conversation
+opened" lifecycle event. Direct-adapter slash commands are also capability-gated: an adapter forwards
 invocations via `sink.onCommand(IncomingCommand)`, and may implement
 `registerCommands(specs)` to publish the channel's declared commands up front
 (e.g. Discord's application-command API); adapters that omit it are skipped.
@@ -217,9 +236,11 @@ See `@copilotkit/channels-slack` for a complete implementation.
 
 ## Exports
 
-`createChannel`, `Channel`, `CreateChannelOptions`, `ChannelHandler`, `ThreadStartHandler`;
+`createChannel`, `Channel`, `CreateChannelOptions`, `ChannelHandler`,
+`WelcomeHandler`, `ThreadStartHandler`;
 `Thread`; the `PlatformAdapter` boundary types (`RunRenderer`, `IngressSink`,
-`IncomingTurn`, `InteractionEvent`, `IncomingCommand`, `IncomingThreadStart`,
+`IncomingTurn`, `InteractionEvent`, `IncomingCommand`, `IncomingWelcome`,
+`IncomingThreadStart`,
 `SurfaceCapabilities`,
 `ReplyTarget`, `ConversationStore`, `AgentSession`, `CapturedToolCall`,
 `CapturedInterrupt`, `UserQuery`); `ActionStore` / `InMemoryActionStore` /

package/dist/action-registry.d.ts

@@ -1,15 +1,23 @@
 import type { ChannelNode, InteractionContext, ComponentFn, Renderable, MessageReactionHandler } from "@copilotkit/channels-ui";
-import type { ActionStore } from "./action-store.js";
+import type { ActionContinuationContext, ActionContinuationBinding, ActionContinuationSnapshot, ActionStore } from "./action-store.js";
 export declare class ActionExpiredError extends Error {
+    readonly code = "channel_action_expired";
     constructor(id: string);
 }
+/** A continuation capability was presented outside its trusted Channel binding. */
+export declare class ActionContinuationMismatchError extends Error {
+    readonly code = "channel_continuation_mismatch";
+    constructor();
+}
 export declare class ActionRegistry {
     private store;
     private components;
     private hot;
     private messageReactions;
+    private readonly retentionMs?;
     constructor(opts: {
         store: ActionStore;
+        retentionMs?: number;
     });
     /** Cache a `<Message onReaction>` handler for the posted message (same-process). */
     registerMessageReaction(messageId: string, handler: MessageReactionHandler): void;
@@ -33,8 +41,8 @@ export declare class ActionRegistry {
     resolveMessageReaction(messageId: string): Promise<MessageReactionHandler | undefined>;
     registerComponent(name: string, fn: ComponentFn): void;
     clearHotCache(): void;
-    bindTree(componentName: string, props: Record<string, unknown>, conversationKey: string): Promise<ChannelNode[]>;
-    bindRenderable(ui: Renderable, conversationKey: string): Promise<{
+    bindTree(componentName: string, props: Record<string, unknown>, conversationKey: string, continuation?: ActionContinuationContext): Promise<ChannelNode[]>;
+    bindRenderable(ui: Renderable, conversationKey: string, continuation?: ActionContinuationContext): Promise<{
         root: ChannelNode[];
         onReaction?: MessageReactionHandler;
         /**
@@ -55,5 +63,9 @@ export declare class ActionRegistry {
      * the element has no `value`.
      */
     dispatch(id: string, ctx: InteractionContext): Promise<unknown>;
+    /** Read and validate one continuation capability without consuming it. */
+    getContinuation(id: string, expected: ActionContinuationBinding): Promise<ActionContinuationSnapshot>;
+    /** Validate and atomically consume one continuation capability. */
+    claimContinuation(id: string, expected: ActionContinuationBinding): Promise<ActionContinuationSnapshot>;
 }
 //# sourceMappingURL=action-registry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"action-registry.d.ts","sourceRoot":"","sources":["../src/action-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,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,WAAW,EAAE,CAAC;IAcnB,cAAc,CAClB,EAAE,EAAE,UAAU,EACd,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC;QACT,IAAI,EAAE,WAAW,EAAE,CAAC;QACpB,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"}
+{"version":3,"file":"action-registry.d.ts","sourceRoot":"","sources":["../src/action-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EACV,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B,EAC1B,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,4BAA4B;gBAE7B,EAAE,EAAE,MAAM;CAIvB;AAED,mFAAmF;AACnF,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,IAAI,mCAAmC;;CAMjD;AAcD,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,UAAU,CAAkC;IAKpD,OAAO,CAAC,GAAG,CAGP;IAIJ,OAAO,CAAC,gBAAgB,CAA6C;IAErE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;gBAE1B,IAAI,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE;IAK9D,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,EACvB,YAAY,CAAC,EAAE,yBAAyB,GACvC,OAAO,CAAC,WAAW,EAAE,CAAC;IAqBnB,cAAc,CAClB,EAAE,EAAE,UAAU,EACd,eAAe,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,yBAAyB,GACvC,OAAO,CAAC;QACT,IAAI,EAAE,WAAW,EAAE,CAAC;QACpB,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;YA4BY,IAAI;IAsDlB;;;;;OAKG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IA2BrE,0EAA0E;IACpE,eAAe,CACnB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,yBAAyB,GAClC,OAAO,CAAC,0BAA0B,CAAC;IAOtC,mEAAmE;IAC7D,iBAAiB,CACrB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,yBAAyB,GAClC,OAAO,CAAC,0BAA0B,CAAC;CASvC"}

package/dist/action-registry.js

@@ -1,11 +1,20 @@
 import { isBound, getBoundArgs, renderToIR } from "@copilotkit/channels-ui";
 import { mintId } from "./mint-id.js";
 export class ActionExpiredError extends Error {
+    code = "channel_action_expired";
     constructor(id) {
         super(`Action "${id}" has expired or is no longer available.`);
         this.name = "ActionExpiredError";
     }
 }
+/** A continuation capability was presented outside its trusted Channel binding. */
+export class ActionContinuationMismatchError extends Error {
+    code = "channel_continuation_mismatch";
+    constructor() {
+        super("The Channel continuation does not match this interaction");
+        this.name = "ActionContinuationMismatchError";
+    }
+}
 const EVENT_PROPS = ["onClick", "onSelect", "onSubmit"];
 function isComponentElement(ui) {
     return (typeof ui === "object" &&
@@ -24,8 +33,10 @@ export class ActionRegistry {
     // posted message's id. Mirrors the `hot` action cache; the durable snapshot
     // (below) is the cross-restart counterpart, exactly like onClick.
     messageReactions = new Map();
+    retentionMs;
     constructor(opts) {
         this.store = opts.store;
+        this.retentionMs = opts.retentionMs;
     }
     /** Cache a `<Message onReaction>` handler for the posted message (same-process). */
     registerMessageReaction(messageId, handler) {
@@ -72,10 +83,10 @@ export class ActionRegistry {
     }
     // 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) {
+    async bindTree(componentName, props, conversationKey, continuation) {
         const fn = this.components.get(componentName);
         const root = renderToIR((fn ? fn(props) : props));
-        await this.walk(root, [], componentName, props, conversationKey);
+        await this.walk(root, [], componentName, props, conversationKey, continuation);
         return root;
     }
     // Binds an arbitrary Renderable for posting. If `ui` is a component element
@@ -85,7 +96,7 @@ export class ActionRegistry {
     // 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) {
+    async bindRenderable(ui, conversationKey, continuation) {
         let root;
         let component;
         let props;
@@ -94,11 +105,11 @@ export class ActionRegistry {
             component = fn.name || "anonymous";
             props = (ui.props ?? {});
             this.registerComponent(component, fn);
-            root = await this.bindTree(component, props, conversationKey);
+            root = await this.bindTree(component, props, conversationKey, continuation);
         }
         else {
             root = renderToIR(ui);
-            await this.walk(root, [], "", undefined, conversationKey);
+            await this.walk(root, [], "", undefined, conversationKey, continuation);
         }
         const onReaction = takeMessageReaction(root);
         return {
@@ -107,7 +118,7 @@ export class ActionRegistry {
             reactionComponent: onReaction && component && props ? { component, props } : undefined,
         };
     }
-    async walk(nodes, base, comp, props, conv) {
+    async walk(nodes, base, comp, props, conv, continuation) {
         for (let i = 0; i < nodes.length; i++) {
             const node = nodes[i];
             const path = [...base, i];
@@ -115,10 +126,13 @@ export class ActionRegistry {
                 const handler = node.props[ep];
                 if (typeof handler === "function") {
                     const fullPath = [...path, ep];
-                    const id = mintId(comp, fullPath, props);
+                    const id = continuation
+                        ? `ck:${globalThis.crypto.randomUUID()}`
+                        : mintId(comp, fullPath, props);
                     this.hot.set(id, {
                         handler: handler,
                         value: node.props.value,
+                        ...(continuation ? { continuation: true } : {}),
                     });
                     await this.store.put(id, {
                         component: comp,
@@ -126,13 +140,16 @@ export class ActionRegistry {
                         path: fullPath,
                         conversationKey: conv,
                         boundArgs: isBound(handler) ? getBoundArgs(handler) : undefined,
-                    });
+                        ...(continuation
+                            ? { continuation: { ...continuation, actionId: id } }
+                            : {}),
+                    }, continuation ? this.retentionMs : undefined);
                     node.props[ep] = { id };
                 }
             }
             const children = node.props.children;
             if (Array.isArray(children)) {
-                await this.walk(children, [...path, "children"], comp, props, conv);
+                await this.walk(children, [...path, "children"], comp, props, conv, continuation);
             }
         }
     }
@@ -147,6 +164,10 @@ export class ActionRegistry {
         let value;
         const hot = this.hot.get(id);
         if (hot) {
+            if (hot.continuation && !(await this.store.get(id))) {
+                this.hot.delete(id);
+                throw new ActionExpiredError(id);
+            }
             handler = hot.handler;
             value = hot.value;
         }
@@ -166,6 +187,37 @@ export class ActionRegistry {
         await handler({ ...ctx, action: { ...ctx.action, id } });
         return value;
     }
+    /** Read and validate one continuation capability without consuming it. */
+    async getContinuation(id, expected) {
+        const available = await this.store.get(id);
+        if (!available?.continuation)
+            throw new ActionExpiredError(id);
+        assertContinuationBinding(available.continuation, id, expected);
+        return available.continuation;
+    }
+    /** Validate and atomically consume one continuation capability. */
+    async claimContinuation(id, expected) {
+        await this.getContinuation(id, expected);
+        const claimed = await this.store.consume(id);
+        if (!claimed?.continuation)
+            throw new ActionExpiredError(id);
+        assertContinuationBinding(claimed.continuation, id, expected);
+        this.hot.delete(id);
+        return claimed.continuation;
+    }
+}
+function assertContinuationBinding(actual, actionId, expected) {
+    if (actual.actionId !== actionId ||
+        actual.channelName !== expected.channelName ||
+        actual.conversationKey !== expected.conversationKey ||
+        actual.threadId !== expected.threadId ||
+        typeof actual.runChainId !== "string" ||
+        actual.runChainId.length === 0 ||
+        typeof actual.initiator?.actor?.id !== "string" ||
+        (actual.initiator.user !== null &&
+            typeof actual.initiator.user?.id !== "string")) {
+        throw new ActionContinuationMismatchError();
+    }
 }
 /** Store key for a message's durable reaction snapshot (distinct from minted action ids). */
 function reactionKey(messageId) {

package/dist/action-registry.test.js

@@ -1,5 +1,5 @@
-import { describe, it, expect, beforeEach } from "vitest";
-import { ActionRegistry, ActionExpiredError } from "./action-registry.js";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { ActionRegistry, ActionContinuationMismatchError, 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";
@@ -112,4 +112,109 @@ describe("ActionRegistry", () => {
             await expect(regBPrime.dispatch(id, ctx)).rejects.toBeInstanceOf(ActionExpiredError);
         });
     });
+    describe("one-use HITL continuations", () => {
+        const continuation = {
+            channelName: "approvals",
+            conversationKey: "conv1",
+            threadId: "thread1",
+            runChainId: "run-chain-1",
+            initiator: {
+                user: { id: "user-1", name: "Alice" },
+                actor: { id: "actor-1", kind: "human" },
+            },
+        };
+        it("mints random capabilities and stores the trusted binding in the action snapshot", async () => {
+            const store = new InMemoryActionStore();
+            const reg = new ActionRegistry({ store, retentionMs: 60_000 });
+            reg.registerComponent("Confirm", Confirm);
+            const first = await reg.bindTree("Confirm", { action: "approve" }, "conv1", continuation);
+            const second = await reg.bindTree("Confirm", { action: "approve" }, "conv1", continuation);
+            const firstId = first[0].props.children[0].props.onClick.id;
+            const secondId = second[0].props.children[0].props.onClick.id;
+            expect(firstId).not.toBe(secondId);
+            expect(await store.get(firstId)).toMatchObject({
+                continuation: { ...continuation, actionId: firstId },
+            });
+        });
+        it("allows exactly one claimant across concurrent resume attempts", async () => {
+            const reg = new ActionRegistry({
+                store: new InMemoryActionStore(),
+                retentionMs: 60_000,
+            });
+            reg.registerComponent("Confirm", Confirm);
+            const tree = await reg.bindTree("Confirm", { action: "approve" }, "conv1", continuation);
+            const id = tree[0].props.children[0].props.onClick.id;
+            const outcomes = await Promise.allSettled([
+                reg.claimContinuation(id, continuation),
+                reg.claimContinuation(id, continuation),
+            ]);
+            expect(outcomes.filter((outcome) => outcome.status === "fulfilled")).toHaveLength(1);
+            expect(outcomes.filter((outcome) => outcome.status === "rejected")).toHaveLength(1);
+            expect(outcomes.find((outcome) => outcome.status === "rejected").reason).toBeInstanceOf(ActionExpiredError);
+        });
+        it.each([
+            ["Channel", { channelName: "wrong" }],
+            ["conversation", { conversationKey: "wrong" }],
+            ["Thread", { threadId: "wrong" }],
+        ])("rejects a wrong %s binding without consuming the valid continuation", async (_label, tampered) => {
+            const reg = new ActionRegistry({
+                store: new InMemoryActionStore(),
+                retentionMs: 60_000,
+            });
+            reg.registerComponent("Confirm", Confirm);
+            const tree = await reg.bindTree("Confirm", { action: "approve" }, "conv1", continuation);
+            const id = tree[0].props.children[0].props.onClick.id;
+            await expect(reg.claimContinuation(id, { ...continuation, ...tampered })).rejects.toBeInstanceOf(ActionContinuationMismatchError);
+            await expect(reg.claimContinuation(id, continuation)).resolves.toMatchObject({
+                actionId: id,
+                runChainId: "run-chain-1",
+            });
+        });
+        it.each([
+            ["run chain", { runChainId: "" }],
+            ["action", { actionId: "ck:other" }],
+            [
+                "initiator actor",
+                { initiator: { ...continuation.initiator, actor: {} } },
+            ],
+        ])("rejects a snapshot with a tampered %s", async (_label, tampered) => {
+            const id = `ck:${globalThis.crypto.randomUUID()}`;
+            const store = new InMemoryActionStore();
+            const reg = new ActionRegistry({ store, retentionMs: 60_000 });
+            await store.put(id, {
+                path: [0, "onClick"],
+                conversationKey: "conv1",
+                continuation: {
+                    ...continuation,
+                    actionId: id,
+                    ...tampered,
+                },
+            });
+            await expect(reg.claimContinuation(id, continuation)).rejects.toBeInstanceOf(ActionContinuationMismatchError);
+        });
+        it("rejects a wrong random capability", async () => {
+            const reg = new ActionRegistry({
+                store: new InMemoryActionStore(),
+                retentionMs: 60_000,
+            });
+            await expect(reg.claimContinuation("ck:wrong-capability", continuation)).rejects.toBeInstanceOf(ActionExpiredError);
+        });
+        it("expires with the action retention window", async () => {
+            vi.useFakeTimers();
+            try {
+                const reg = new ActionRegistry({
+                    store: new InMemoryActionStore(),
+                    retentionMs: 100,
+                });
+                reg.registerComponent("Confirm", Confirm);
+                const tree = await reg.bindTree("Confirm", { action: "approve" }, "conv1", continuation);
+                const id = tree[0].props.children[0].props.onClick.id;
+                vi.advanceTimersByTime(101);
+                await expect(reg.claimContinuation(id, continuation)).rejects.toBeInstanceOf(ActionExpiredError);
+            }
+            finally {
+                vi.useRealTimers();
+            }
+        });
+    });
 });

package/dist/action-store.d.ts

@@ -1,14 +1,36 @@
+import type { ApplicationUser, ProviderActor } from "@copilotkit/channels-ui";
+/** Trusted principal captured when one HITL run chain starts. */
+export interface ActionContinuationInitiator {
+    user: ApplicationUser | null;
+    actor: ProviderActor;
+}
+/** Trusted facts bound to every one-use action rendered by a HITL run chain. */
+export interface ActionContinuationContext {
+    channelName: string;
+    conversationKey: string;
+    threadId: string;
+    runChainId: string;
+    initiator: ActionContinuationInitiator;
+}
+/** Server-derived delivery facts used to validate a presented continuation. */
+export type ActionContinuationBinding = Pick<ActionContinuationContext, "channelName" | "conversationKey" | "threadId">;
+/** Persisted continuation binding, including its random action capability. */
+export interface ActionContinuationSnapshot extends ActionContinuationContext {
+    actionId: string;
+}
 export interface ActionSnapshot {
     component?: string;
     props?: unknown;
     path: (string | number)[];
     boundArgs?: unknown;
     conversationKey: string;
+    continuation?: ActionContinuationSnapshot;
 }
 /** @deprecated Configure `createChannel({ 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>;
+    consume(id: string): Promise<ActionSnapshot | undefined>;
     delete(id: string): Promise<void>;
 }
 /** @deprecated Configure `createChannel({ state })` instead. Action snapshots are stored via `StateStore.kv`. */
@@ -17,5 +39,6 @@ export declare class InMemoryActionStore implements ActionStore {
     put(id: string, snap: ActionSnapshot, ttlMs?: number): Promise<void>;
     get(id: string): Promise<ActionSnapshot | undefined>;
     delete(id: string): Promise<void>;
+    consume(id: string): Promise<ActionSnapshot | undefined>;
 }
 //# sourceMappingURL=action-store.d.ts.map

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

@@ -1 +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,iHAAiH;AACjH,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,iHAAiH;AACjH,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"}
+{"version":3,"file":"action-store.d.ts","sourceRoot":"","sources":["../src/action-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE9E,iEAAiE;AACjE,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,gFAAgF;AAChF,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,2BAA2B,CAAC;CACxC;AAED,+EAA+E;AAC/E,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,yBAAyB,EACzB,aAAa,GAAG,iBAAiB,GAAG,UAAU,CAC/C,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,0BAA2B,SAAQ,yBAAyB;IAC3E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,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;IACxB,YAAY,CAAC,EAAE,0BAA0B,CAAC;CAC3C;AACD,iHAAiH;AACjH,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,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACzD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AACD,iHAAiH;AACjH,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;IAGjC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;CAU/D"}

package/dist/action-store.js

@@ -20,4 +20,15 @@ export class InMemoryActionStore {
     async delete(id) {
         this.map.delete(id);
     }
+    async consume(id) {
+        const entry = this.map.get(id);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
+            this.map.delete(id);
+            return undefined;
+        }
+        this.map.delete(id);
+        return entry.snap;
+    }
 }

package/dist/canonical-run-loop.test.js

@@ -334,7 +334,12 @@ test("terminal delivery tool failure stops the loop and closes renderer fanout",
         tools: new Map([["echo", postFile]]),
         toolDescriptors: [],
         context: [],
-        makeToolCtx: () => ({ thread: {}, platform: "fake" }),
+        makeToolCtx: () => ({
+            thread: {},
+            user: null,
+            actor: { id: "actor", kind: "unknown" },
+            platform: "fake",
+        }),
         subscriber: {
             onEvent: ({ event }) => {
                 ingestedEvents.push(event);

package/dist/channel-identity.test.d.ts

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

package/dist/channel-identity.test.d.ts.map

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