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

package/dist/hitl-continuation.test.d.ts

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

package/dist/hitl-continuation.test.d.ts.map

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

package/dist/hitl-continuation.test.js

@@ -0,0 +1,393 @@
+import { jsx as _jsx } from "@copilotkit/channels-core/jsx-runtime";
+import { Button } from "@copilotkit/channels-ui";
+import { afterEach, expect, test, vi } from "vitest";
+import { createChannel } from "./create-channel.js";
+import { MemoryStore } from "./state/memory-store.js";
+import { FakeAdapter } from "./testing/fake-adapter.js";
+import { FakeAgent } from "./testing/fake-agent.js";
+const activeChannels = [];
+afterEach(async () => {
+    await Promise.all(activeChannels.splice(0).map((channel) => channel.stop()));
+});
+function firstActionId(adapter) {
+    const button = adapter.posted.flat().find((node) => node.type === "button");
+    const action = button?.props.onClick;
+    if (typeof action?.id !== "string")
+        throw new Error("missing action id");
+    return action.id;
+}
+function actionIds(adapter) {
+    return adapter.posted
+        .flat()
+        .filter((node) => node.type === "button")
+        .map((node) => node.props.onClick?.id)
+        .filter((id) => typeof id === "string");
+}
+function interrupt(subscriber) {
+    subscriber.onCustomEvent?.({
+        event: { name: "approval", value: { requestId: "request-1" } },
+    });
+    subscriber.onRunFinishedEvent?.({ event: {} });
+}
+async function setup(subject, memory) {
+    const adapter = new FakeAdapter();
+    adapter.supportsIntelligenceMemory = true;
+    const lifecycleCalls = [];
+    adapter.runAgentLifecycle = vi.fn(async (args) => {
+        lifecycleCalls.push(args);
+        return args.execute(args.renderer.subscriber, undefined);
+    });
+    const state = new MemoryStore();
+    const agent = new FakeAgent([interrupt]);
+    function Approval() {
+        return (_jsx(Button, { value: { approved: true }, onClick: async ({ thread }) => {
+                await thread.resume({ approved: true }, { memory, subject });
+            }, children: "Approve" }));
+    }
+    const channel = createChannel({
+        name: "approvals",
+        identifyUser: ({ actor }) => actor.kind === "human"
+            ? { id: `app:${actor.id}`, name: actor.name ?? actor.id }
+            : null,
+        adapters: [adapter],
+        agent,
+        components: [Approval],
+        store: { adapter: state, actionRetentionMs: 60_000 },
+    });
+    channel.onMessage(async ({ thread }) => {
+        await thread.runAgent();
+    });
+    channel.onInterrupt("approval", async ({ thread }) => {
+        await thread.post(_jsx(Approval, {}));
+    });
+    await channel.ɵruntime.start();
+    activeChannels.push({ stop: () => channel.ɵruntime.stop() });
+    await adapter.getSink().onTurn({
+        conversationKey: "thread-1",
+        replyTarget: {},
+        userText: "start",
+        platform: "slack",
+        actor: { id: "alice", kind: "human", name: "Alice" },
+    });
+    return { adapter, lifecycleCalls, state, actionId: firstActionId(adapter) };
+}
+test("resume with initiator Memory keeps the original user when Bob clicks", async () => {
+    const { adapter, lifecycleCalls, actionId } = await setup("initiator", {
+        user: "read",
+    });
+    await adapter.getSink().onInteraction({
+        id: actionId,
+        conversationKey: "thread-1",
+        replyTarget: {},
+        eventId: "bob-click",
+        actor: { id: "bob", kind: "human", name: "Bob" },
+    });
+    expect(lifecycleCalls).toHaveLength(2);
+    expect(lifecycleCalls[1].memory).toEqual({
+        grant: { user: "read", project: "none" },
+        user: { id: "app:alice", name: "Alice" },
+    });
+});
+test("a managed continuation keeps its initiator across a Runtime restart", async () => {
+    const state = new MemoryStore();
+    const lifecycleCalls = [];
+    function Approval() {
+        return (_jsx(Button, { value: { approved: true }, onClick: async ({ thread }) => {
+                await thread.resume({ approved: true }, { memory: { user: "read" }, subject: "initiator" });
+            }, children: "Approve" }));
+    }
+    const makeRuntime = (agent) => {
+        const adapter = new FakeAdapter();
+        adapter.supportsIntelligenceMemory = true;
+        adapter.runAgentLifecycle = vi.fn(async (args) => {
+            lifecycleCalls.push(args);
+            return args.execute(args.renderer.subscriber, undefined);
+        });
+        const channel = createChannel({
+            name: "approvals",
+            identifyUser: ({ actor }) => actor.kind === "human"
+                ? { id: `app:${actor.id}`, name: actor.name ?? actor.id }
+                : null,
+            adapters: [adapter],
+            agent,
+            components: [Approval],
+            store: { adapter: state, actionRetentionMs: 60_000 },
+        });
+        channel.onMessage(async ({ thread }) => {
+            await thread.runAgent();
+        });
+        channel.onInterrupt("approval", async ({ thread }) => {
+            await thread.post(_jsx(Approval, {}));
+        });
+        return { adapter, channel };
+    };
+    const first = makeRuntime(new FakeAgent([interrupt]));
+    await first.channel.ɵruntime.start();
+    await first.adapter.getSink().onTurn({
+        conversationKey: "thread-1",
+        replyTarget: {},
+        userText: "start",
+        platform: "slack",
+        actor: { id: "alice", kind: "human", name: "Alice" },
+    });
+    const actionId = firstActionId(first.adapter);
+    await first.channel.ɵruntime.stop();
+    const restarted = makeRuntime(new FakeAgent());
+    await restarted.channel.ɵruntime.start();
+    activeChannels.push({ stop: () => restarted.channel.ɵruntime.stop() });
+    await restarted.adapter.getSink().onInteraction({
+        id: actionId,
+        conversationKey: "thread-1",
+        replyTarget: {},
+        eventId: "bob-click-after-restart",
+        actor: { id: "bob", kind: "human", name: "Bob" },
+    });
+    expect(lifecycleCalls).toHaveLength(2);
+    expect(lifecycleCalls[1].memory).toEqual({
+        grant: { user: "read", project: "none" },
+        user: { id: "app:alice", name: "Alice" },
+    });
+    expect(lifecycleCalls[1].isResume).toBe(true);
+});
+test("independent runs on one Thread snapshot new initiators", async () => {
+    const state = new MemoryStore();
+    const adapter = new FakeAdapter();
+    function Approval() {
+        return (_jsx(Button, { value: { approved: true }, onClick: () => undefined, children: "Approve" }));
+    }
+    const channel = createChannel({
+        name: "approvals",
+        identifyUser: ({ actor }) => actor.kind === "human"
+            ? { id: `app:${actor.id}`, name: actor.name ?? actor.id }
+            : null,
+        adapters: [adapter],
+        agent: new FakeAgent([interrupt]),
+        components: [Approval],
+        store: { adapter: state, actionRetentionMs: 60_000 },
+    });
+    channel.onMessage(async ({ thread }) => {
+        await thread.runAgent();
+    });
+    channel.onInterrupt("approval", async ({ thread }) => {
+        await thread.post(_jsx(Approval, {}));
+    });
+    await channel.ɵruntime.start();
+    activeChannels.push({ stop: () => channel.ɵruntime.stop() });
+    for (const actor of [
+        { id: "alice", kind: "human", name: "Alice" },
+        { id: "bob", kind: "human", name: "Bob" },
+    ]) {
+        await adapter.getSink().onTurn({
+            conversationKey: "thread-1",
+            replyTarget: {},
+            userText: "start",
+            platform: "slack",
+            actor,
+        });
+    }
+    const snapshots = await Promise.all(actionIds(adapter).map((id) => state.kv.get(`action:${id}`)));
+    expect(snapshots).toHaveLength(2);
+    expect(snapshots.map((snapshot) => snapshot?.continuation?.initiator.user?.id)).toEqual(["app:alice", "app:bob"]);
+    expect(new Set(snapshots.map((snapshot) => snapshot?.continuation?.runChainId))
+        .size).toBe(2);
+});
+test("concurrent independent runs cannot share a continuation chain", async () => {
+    const state = new MemoryStore();
+    const adapter = new FakeAdapter();
+    function Approval() {
+        return (_jsx(Button, { value: { approved: true }, onClick: () => undefined, children: "Approve" }));
+    }
+    const channel = createChannel({
+        name: "approvals",
+        identifyUser: "platform",
+        adapters: [adapter],
+        agent: () => new FakeAgent([interrupt]),
+        components: [Approval],
+        store: { adapter: state, actionRetentionMs: 60_000 },
+    });
+    let receivedThread;
+    channel.onMessage(({ thread }) => {
+        receivedThread = thread;
+    });
+    channel.onInterrupt("approval", async ({ thread }) => {
+        await thread.post(_jsx(Approval, {}));
+    });
+    await channel.ɵruntime.start();
+    activeChannels.push({ stop: () => channel.ɵruntime.stop() });
+    await adapter.getSink().onTurn({
+        conversationKey: "thread-concurrent",
+        replyTarget: {},
+        userText: "start",
+        platform: "slack",
+        actor: { id: "alice", kind: "human", name: "Alice" },
+        identityContext: {
+            tenant: { id: "T1" },
+            installation: { id: "I1" },
+            conversation: { id: "C1" },
+            trigger: "message",
+            event: { id: "E1" },
+            raw: {},
+        },
+    });
+    if (!receivedThread)
+        throw new Error("message handler did not receive a Thread");
+    await Promise.all([receivedThread.runAgent(), receivedThread.runAgent()]);
+    const snapshots = await Promise.all(actionIds(adapter).map((id) => state.kv.get(`action:${id}`)));
+    expect(snapshots).toHaveLength(2);
+    expect(new Set(snapshots.map((snapshot) => snapshot?.continuation?.runChainId))
+        .size).toBe(2);
+});
+test("resume with actor Memory selects the current interaction user", async () => {
+    const { adapter, lifecycleCalls, actionId } = await setup("actor", {
+        user: "read-write",
+    });
+    await adapter.getSink().onInteraction({
+        id: actionId,
+        conversationKey: "thread-1",
+        replyTarget: {},
+        eventId: "bob-click",
+        actor: { id: "bob", kind: "human", name: "Bob" },
+    });
+    expect(lifecycleCalls[1].memory?.user).toEqual({
+        id: "app:bob",
+        name: "Bob",
+    });
+});
+test("project-only resume needs no personal subject or fabricated user", async () => {
+    const { adapter, lifecycleCalls, actionId } = await setup(undefined, {
+        project: "read",
+    });
+    await adapter.getSink().onInteraction({
+        id: actionId,
+        conversationKey: "thread-1",
+        replyTarget: {},
+        eventId: "system-click",
+        actor: { id: "approval-bot", kind: "bot" },
+    });
+    expect(lifecycleCalls[1].memory).toEqual({
+        grant: { user: "none", project: "read" },
+        user: null,
+    });
+});
+test("personal resume requires an explicit trusted subject selector", async () => {
+    const { adapter, lifecycleCalls, actionId } = await setup(undefined, {
+        user: "read",
+    });
+    await expect(adapter.getSink().onInteraction({
+        id: actionId,
+        conversationKey: "thread-1",
+        replyTarget: {},
+        eventId: "bob-click",
+        actor: { id: "bob", kind: "human", name: "Bob" },
+    })).rejects.toMatchObject({ code: "channel_memory_subject_required" });
+    expect(lifecycleCalls).toHaveLength(1);
+});
+test("personal resume fails before execution when the selected actor has no application user", async () => {
+    const { adapter, lifecycleCalls, actionId } = await setup("actor", {
+        user: "read",
+    });
+    await expect(adapter.getSink().onInteraction({
+        id: actionId,
+        conversationKey: "thread-1",
+        replyTarget: {},
+        eventId: "system-click",
+        actor: { id: "approval-bot", kind: "bot" },
+    })).rejects.toMatchObject({ code: "channel_memory_user_required" });
+    expect(lifecycleCalls).toHaveLength(1);
+});
+test("a continuation starts only one resumed run", async () => {
+    const { adapter, lifecycleCalls, actionId } = await setup("actor", {
+        project: "read",
+    });
+    const click = (eventId) => adapter.getSink().onInteraction({
+        id: actionId,
+        conversationKey: "thread-1",
+        replyTarget: {},
+        eventId,
+        actor: { id: "bob", kind: "human", name: "Bob" },
+    });
+    await Promise.all([click("click-1"), click("click-2")]);
+    expect(lifecycleCalls).toHaveLength(2);
+});
+test("a wrong conversation cannot consume another conversation's continuation", async () => {
+    const { adapter, lifecycleCalls, actionId } = await setup("actor", {
+        project: "read",
+    });
+    await expect(adapter.getSink().onInteraction({
+        id: actionId,
+        conversationKey: "thread-wrong",
+        replyTarget: {},
+        eventId: "wrong-thread-click",
+        actor: { id: "bob", kind: "human", name: "Bob" },
+    })).rejects.toMatchObject({ code: "channel_continuation_mismatch" });
+    expect(lifecycleCalls).toHaveLength(1);
+    await adapter.getSink().onInteraction({
+        id: actionId,
+        conversationKey: "thread-1",
+        replyTarget: {},
+        eventId: "correct-thread-click",
+        actor: { id: "bob", kind: "human", name: "Bob" },
+    });
+    expect(lifecycleCalls).toHaveLength(2);
+});
+test("normal runs write no continuation state and one resume consumes once", async () => {
+    const state = new MemoryStore();
+    const set = vi.spyOn(state.kv, "set");
+    const consume = vi.spyOn(state.kv, "consume");
+    const adapter = new FakeAdapter();
+    adapter.supportsIntelligenceMemory = true;
+    function Approval() {
+        return (_jsx(Button, { value: { approved: true }, onClick: async ({ thread }) => {
+                await thread.resume({ approved: true }, { memory: { project: "read" } });
+            }, children: "Approve" }));
+    }
+    const finish = (subscriber) => {
+        subscriber.onRunFinishedEvent?.({ event: {} });
+    };
+    const agent = new FakeAgent([finish]);
+    const channel = createChannel({
+        name: "approvals",
+        identifyUser: ({ actor }) => actor.kind === "human"
+            ? { id: `app:${actor.id}`, name: actor.name ?? actor.id }
+            : null,
+        adapters: [adapter],
+        agent,
+        components: [Approval],
+        store: { adapter: state, actionRetentionMs: 60_000 },
+    });
+    channel.onMessage(async ({ thread, message }) => {
+        agent.setScript([message.text === "interrupt" ? interrupt : finish]);
+        await thread.runAgent();
+    });
+    channel.onInterrupt("approval", async ({ thread }) => {
+        await thread.post(_jsx(Approval, {}));
+    });
+    await channel.ɵruntime.start();
+    activeChannels.push({ stop: () => channel.ɵruntime.stop() });
+    const turn = (userText) => adapter.getSink().onTurn({
+        conversationKey: "thread-1",
+        replyTarget: {},
+        userText,
+        platform: "slack",
+        actor: { id: "alice", kind: "human", name: "Alice" },
+    });
+    await turn("normal");
+    expect(set).not.toHaveBeenCalled();
+    expect(consume).not.toHaveBeenCalled();
+    await turn("interrupt");
+    const actionId = firstActionId(adapter);
+    expect(set).toHaveBeenCalledTimes(1);
+    expect(set.mock.calls[0]?.[0]).toBe(`action:${actionId}`);
+    expect(consume).not.toHaveBeenCalled();
+    const click = (eventId) => adapter.getSink().onInteraction({
+        id: actionId,
+        conversationKey: "thread-1",
+        replyTarget: {},
+        eventId,
+        actor: { id: "bob", kind: "human", name: "Bob" },
+    });
+    await click("bob-click");
+    await click("bob-click-redelivery");
+    expect(consume).toHaveBeenCalledTimes(1);
+    expect(consume.mock.calls[0]?.[0]).toBe(`action:${actionId}`);
+});

package/dist/identity.d.ts

@@ -0,0 +1,51 @@
+import type { ApplicationUser, ProviderActor } from "@copilotkit/channels-ui";
+/** Provider tenant or workspace facts available at ingress. */
+export interface ChannelTenant {
+    readonly id: string;
+    readonly name?: string;
+}
+/** Provider installation facts available at ingress. */
+export interface ChannelInstallation {
+    readonly id: string;
+}
+/** Provider conversation facts available at ingress. */
+export interface ChannelConversation {
+    readonly id: string;
+    readonly kind?: string;
+}
+/** Normalized provider event facts available at ingress. */
+export interface ChannelEvent {
+    readonly id?: string;
+    readonly occurredAt?: string;
+    readonly [key: string]: unknown;
+}
+/** Adapter-provided facts used to select one canonical application user. */
+export interface ChannelIdentityContext {
+    readonly provider: string;
+    readonly tenant: ChannelTenant;
+    readonly installation: ChannelInstallation;
+    readonly actor: ProviderActor;
+    readonly conversation: ChannelConversation;
+    readonly trigger: string;
+    readonly event: ChannelEvent;
+    readonly raw: unknown;
+    readonly lookupProfile?: () => Promise<ProviderActor | undefined>;
+}
+/** Explicit Channel identity strategy. */
+export type ChannelIdentifyUser = "platform" | ((context: ChannelIdentityContext) => ApplicationUser | null | Promise<ApplicationUser | null>);
+/** Identity facts supplied by an adapter alongside every ingress event. */
+export type IngressIdentityContext = Omit<ChannelIdentityContext, "provider" | "actor">;
+/** Stable public failure for malformed custom identity results. */
+export declare class ChannelIdentityResultError extends Error {
+    readonly code = "channel_identity_invalid";
+    constructor();
+}
+/** Stable public failure for a configured identity callback exception. */
+export declare class ChannelIdentityResolutionError extends Error {
+    readonly code = "channel_identity_failed";
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+/** Resolve one immutable canonical application user for one ingress event. */
+export declare function resolveChannelUser(identifyUser: ChannelIdentifyUser | undefined, context: ChannelIdentityContext): Promise<ApplicationUser | null>;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE9E,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wDAAwD;AACxD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,wDAAwD;AACxD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;CACnE;AAED,0CAA0C;AAC1C,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,CAAC,CACC,OAAO,EAAE,sBAAsB,KAC5B,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC,CAAC;AAEnE,2EAA2E;AAC3E,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,sBAAsB,EACtB,UAAU,GAAG,OAAO,CACrB,CAAC;AAEF,mEAAmE;AACnE,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,8BAA8B;;CAQ5C;AAED,0EAA0E;AAC1E,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,IAAI,6BAA6B;IAC1C,SAAkB,KAAK,EAAE,OAAO,CAAC;gBAErB,KAAK,EAAE,OAAO;CAK3B;AAsBD,8EAA8E;AAC9E,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,mBAAmB,GAAG,SAAS,EAC7C,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAgBjC"}

package/dist/identity.js

@@ -0,0 +1,56 @@
+/** Stable public failure for malformed custom identity results. */
+export class ChannelIdentityResultError extends Error {
+    code = "channel_identity_invalid";
+    constructor() {
+        super("Channel identifyUser must return null or an application user with non-empty id and name");
+        this.name = "ChannelIdentityResultError";
+    }
+}
+/** Stable public failure for a configured identity callback exception. */
+export class ChannelIdentityResolutionError extends Error {
+    code = "channel_identity_failed";
+    cause;
+    constructor(cause) {
+        super("Channel identifyUser failed");
+        this.name = "ChannelIdentityResolutionError";
+        this.cause = cause;
+    }
+}
+function hasText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function validateApplicationUser(value) {
+    if (value === null)
+        return null;
+    if (typeof value !== "object" ||
+        value === undefined ||
+        !hasText(value.id) ||
+        !hasText(value.name)) {
+        throw new ChannelIdentityResultError();
+    }
+    return Object.freeze({
+        id: value.id,
+        name: value.name,
+    });
+}
+/** Resolve one immutable canonical application user for one ingress event. */
+export async function resolveChannelUser(identifyUser, context) {
+    if (identifyUser === undefined)
+        return null;
+    if (identifyUser === "platform") {
+        if (context.actor.kind !== "human")
+            return null;
+        return Object.freeze({
+            id: [context.provider, context.tenant.id, context.actor.id].join(":"),
+            name: context.actor.name ?? context.actor.handle ?? context.actor.id,
+        });
+    }
+    let identified;
+    try {
+        identified = await identifyUser(context);
+    }
+    catch (cause) {
+        throw new ChannelIdentityResolutionError(cause);
+    }
+    return validateApplicationUser(identified);
+}

package/dist/identity.test.d.ts

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

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

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

package/dist/identity.test.js

@@ -0,0 +1,109 @@
+import { expect, test, vi } from "vitest";
+import { ChannelIdentityResolutionError, ChannelIdentityResultError, resolveChannelUser, } from "./identity.js";
+function context(kind = "human") {
+    return {
+        provider: "slack",
+        tenant: { id: "T1", name: "Acme" },
+        installation: { id: "I1" },
+        actor: {
+            id: "U1",
+            kind,
+            name: "Ada Lovelace",
+            handle: "ada",
+        },
+        conversation: { id: "C1", kind: "channel" },
+        trigger: "message",
+        event: { id: "E1" },
+        raw: { type: "app_mention" },
+    };
+}
+test("platform identity maps a human actor to a tenant-namespaced application user", async () => {
+    await expect(resolveChannelUser("platform", context())).resolves.toEqual({
+        id: "slack:T1:U1",
+        name: "Ada Lovelace",
+    });
+});
+test("platform identity keeps provider and tenant namespaces distinct", async () => {
+    const slack = context();
+    const otherTenant = { ...context(), tenant: { id: "T2" } };
+    const teams = { ...context(), provider: "teams" };
+    await expect(resolveChannelUser("platform", slack)).resolves.toMatchObject({
+        id: "slack:T1:U1",
+    });
+    await expect(resolveChannelUser("platform", otherTenant)).resolves.toMatchObject({ id: "slack:T2:U1" });
+    await expect(resolveChannelUser("platform", teams)).resolves.toMatchObject({
+        id: "teams:T1:U1",
+    });
+});
+test.each(["bot", "app", "system", "unknown"])("platform identity maps a %s actor to null", async (kind) => {
+    await expect(resolveChannelUser("platform", context(kind))).resolves.toBeNull();
+});
+test("platform identity falls back from name to handle and provider id", async () => {
+    const withHandle = {
+        ...context(),
+        actor: { id: "U1", kind: "human", handle: "ada" },
+    };
+    await expect(resolveChannelUser("platform", withHandle)).resolves.toMatchObject({
+        name: "ada",
+    });
+    const withId = {
+        ...context(),
+        actor: { id: "U1", kind: "human" },
+    };
+    await expect(resolveChannelUser("platform", withId)).resolves.toMatchObject({
+        name: "U1",
+    });
+});
+test("a custom identity callback may map a bot actor", async () => {
+    const botContext = context("bot");
+    await expect(resolveChannelUser(() => ({ id: "service-1", name: "Build bot" }), botContext)).resolves.toEqual({ id: "service-1", name: "Build bot" });
+});
+test.each([
+    undefined,
+    {},
+    { id: "", name: "Ada" },
+    { id: "person-1", name: "" },
+])("a malformed custom identity result fails with the stable public error", async (result) => {
+    await expect(resolveChannelUser(() => result, context())).rejects.toMatchObject({
+        code: "channel_identity_invalid",
+        name: new ChannelIdentityResultError().name,
+    });
+});
+test("a thrown custom identity error uses a stable public failure without platform fallback", async () => {
+    const failure = new Error("identity service unavailable");
+    const result = resolveChannelUser(() => {
+        throw failure;
+    }, context());
+    await expect(result).rejects.toMatchObject({
+        code: "channel_identity_failed",
+        cause: failure,
+    });
+    await expect(result).rejects.toBeInstanceOf(ChannelIdentityResolutionError);
+});
+test("profile lookup stays lazy unless the custom callback calls it", async () => {
+    const lookupProfile = vi.fn(async () => ({
+        id: "U1",
+        kind: "human",
+        email: "ada@example.com",
+    }));
+    const identityContext = { ...context(), lookupProfile };
+    await resolveChannelUser("platform", identityContext);
+    expect(lookupProfile).not.toHaveBeenCalled();
+    await resolveChannelUser(async (received) => {
+        const profile = await received.lookupProfile?.();
+        return { id: "person-1", name: profile?.email ?? "Ada" };
+    }, identityContext);
+    expect(lookupProfile).toHaveBeenCalledTimes(1);
+});
+test("a failing lazy profile lookup cannot break platform identity", async () => {
+    const lookupProfile = vi.fn(async () => {
+        throw new Error("provider profile unavailable");
+    });
+    const identityContext = {
+        ...context(),
+        actor: { id: "U1", kind: "human" },
+        lookupProfile,
+    };
+    await expect(resolveChannelUser("platform", identityContext)).resolves.toEqual({ id: "slack:T1:U1", name: "U1" });
+    expect(lookupProfile).not.toHaveBeenCalled();
+});

package/dist/index.d.ts

@@ -2,28 +2,33 @@ export { createChannel } from "./create-channel.js";
 export { isolateAgentInstance, resolveChannelConcurrency, } from "./create-channel.js";
 export { sanitizeAgentEventStream } from "./sanitize-agent-events.js";
 export { HttpAgent } from "@ag-ui/client";
-export type { Channel, CreateChannelOptions, ManagedChannelProvider, ReplyContinuationOptions, ChannelHandler, ThreadStartHandler, ReactionEvent, ReactionHandler, ModalSubmitEvent, ModalSubmitHandler, ModalCloseEvent, ModalCloseHandler, StoreConfig, LockConflictDecision, ChannelConcurrency, StatefulThread, ChannelComponent, } from "./create-channel.js";
+export type { Channel, CreateChannelOptions, ReplyContinuationOptions, ChannelHandler, WelcomeHandler, ThreadStartHandler, ReactionEvent, ReactionHandler, ModalSubmitEvent, ModalSubmitHandler, ModalCloseEvent, ModalCloseHandler, StoreConfig, LockConflictDecision, ChannelConcurrency, StatefulThread, ChannelComponent, } from "./create-channel.js";
+export { ChannelIdentityResolutionError, ChannelIdentityResultError, resolveChannelUser, } from "./identity.js";
+export type { ChannelConversation, ChannelEvent, ChannelIdentifyUser, ChannelIdentityContext, ChannelInstallation, ChannelTenant, IngressIdentityContext, } from "./identity.js";
 export { Thread } from "./thread.js";
 export type { ThreadDeps } from "./thread.js";
-export type { PlatformAdapter, AdapterStartContext, RunRenderer, IngressSink, IncomingTurn, InteractionEvent, IncomingCommand, IncomingThreadStart, IncomingReaction, IncomingModalSubmit, IncomingModalClose, ModalSubmitResult, SurfaceCapabilities, ReplyTarget, ConversationStore, AgentSession, CapturedToolCall, CapturedInterrupt, ChannelAgentLifecycleArgs, ChannelAgentLoopResult, CanonicalRunIdentity, UserQuery, NativePayload, } from "./platform-adapter.js";
+export type { PlatformAdapter, AdapterStartContext, RunRenderer, IngressSink, IncomingTurn, InteractionEvent, IncomingCommand, IncomingThreadStart, IncomingWelcome, IncomingReaction, IncomingModalSubmit, IncomingModalClose, ModalSubmitResult, SurfaceCapabilities, ReplyTarget, ConversationStore, AgentSession, CapturedToolCall, CapturedInterrupt, ChannelAgentLifecycleArgs, ChannelAgentLoopResult, CanonicalRunIdentity, UserQuery, NativePayload, } from "./platform-adapter.js";
 export { defineChannelCommand, normalizeCommandName, toCommandSpec, } from "./commands.js";
 export type { ChannelCommand, CommandContext, CommandSpec, } from "./commands.js";
 export { InMemoryActionStore } from "./action-store.js";
-export type { ActionStore, ActionSnapshot } from "./action-store.js";
-export { ActionRegistry, ActionExpiredError } from "./action-registry.js";
+export type { ActionStore, ActionSnapshot, ActionContinuationContext, ActionContinuationBinding, ActionContinuationInitiator, ActionContinuationSnapshot, } from "./action-store.js";
+export { ActionRegistry, ActionContinuationMismatchError, ActionExpiredError, } from "./action-registry.js";
 export type { StateStore } from "./state/state-store.js";
 export { MemoryStore } from "./state/memory-store.js";
 export { parseDuration } from "./state/duration.js";
 export { createStateBackedConversationStore } from "./state/state-conversation-store.js";
 export { Transcripts } from "./transcripts.js";
-export type { TranscriptEntry, Identity, TranscriptsConfig, } from "./transcripts.js";
+export type { TranscriptEntry, TranscriptsConfig } from "./transcripts.js";
 export { toAgentToolDescriptors, parseToolArgs, stringifyHandlerResult, defineChannelTool, } from "./tools.js";
 export type { ChannelTool, ObjectSchema, ChannelToolContext, ContextEntry, AgentToolDescriptor, } from "./tools.js";
 export { mintId, stableStringify } from "./mint-id.js";
 export { runAgentLoop } from "./run-loop.js";
 export type { RunLoopArgs } from "./run-loop.js";
+export { ChannelContinuationRequiredError, ChannelMemorySubjectRequiredError, ChannelMemoryUnavailableError, ChannelMemoryUserRequiredError, } from "./thread.js";
 export { ChannelDeliveryTerminatedError, isChannelDeliveryTerminatedError, } from "./delivery-error.js";
 export type { PlatformCodec } from "./codec.js";
+export { ChannelMemoryGrantInvalidError, hasMemoryAccess, resolveMemoryGrant, } from "./memory.js";
+export type { MemoryAccess, MemoryGrant, ResolvedChannelMemory, } from "./memory.js";
 export { FakeAdapter, makeFakeRunRenderer } from "./testing/fake-adapter.js";
 export { FakeAgent } from "./testing/fake-agent.js";
 export * from "@copilotkit/channels-ui";