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

package/dist/create-channel.js

@@ -7,10 +7,12 @@ import { Thread } from "./thread.js";
 import { sanitizeAgentEventStream } from "./sanitize-agent-events.js";
 import { normalizeEmoji, toCanonicalEmoji, renderToIR, } from "@copilotkit/channels-ui";
 import { Transcripts } from "./transcripts.js";
+import { resolveChannelUser } from "./identity.js";
 import { ChannelTelemetry } from "./telemetry/channel-telemetry.js";
 import { errorClass, normalizePlatform } from "./telemetry/sanitize-error.js";
 import { createRequire } from "node:module";
 const pkg = createRequire(import.meta.url)("../package.json");
+const ADAPTER_ROLLBACK_TIMEOUT_MS = 5_000;
 function storeKind(s) {
     const n = s.constructor?.name;
     if (n === "MemoryStore")
@@ -138,8 +140,9 @@ function msgFromTurn(turn) {
     return {
         text: turn.userText,
         contentParts: turn.contentParts,
-        user: turn.user ?? { id: "" },
-        ref: { id: "" },
+        user: null,
+        actor: turn.actor,
+        ref: turn.messageRef ?? { id: "" },
         platform: turn.platform,
         operation: turn.operation,
         eventId: turn.eventId,
@@ -147,21 +150,42 @@ function msgFromTurn(turn) {
         deliveryId: turn.deliveryId,
     };
 }
+function identityContextFromIngress(provider, event, trigger) {
+    const actor = Object.freeze({
+        ...(event.actor ?? { id: "", kind: "unknown" }),
+    });
+    const tenant = Object.freeze({
+        ...(event.identityContext?.tenant ?? { id: "" }),
+    });
+    const installation = Object.freeze({
+        ...(event.identityContext?.installation ?? { id: "" }),
+    });
+    const conversation = Object.freeze({
+        ...(event.identityContext?.conversation ?? {
+            id: event.conversationKey ?? "",
+        }),
+    });
+    const normalizedEvent = Object.freeze({
+        ...event.identityContext?.event,
+    });
+    return Object.freeze({
+        provider,
+        tenant,
+        installation,
+        actor,
+        conversation,
+        trigger: event.identityContext?.trigger ?? trigger,
+        event: normalizedEvent,
+        raw: event.identityContext?.raw,
+        ...(event.identityContext?.lookupProfile
+            ? { lookupProfile: event.identityContext.lookupProfile }
+            : {}),
+    });
+}
 /** Resolve the provider that produced an event without changing adapter identity. */
 function ingressPlatform(adapter, event) {
     return event.platform ?? adapter.platform;
 }
-/**
- * Enforce managed Intelligence Channel exclusivity. Managed and direct
- * delivery are alternative modes on a Channel: Intelligence holds provider
- * credentials, or the runtime does, never both.
- */
-function assertExclusive(adapters) {
-    if (adapters.some((a) => a.__intelligenceChannel) && adapters.length > 1) {
-        throw new Error("The managed Intelligence adapter must be the only adapter on a Channel — " +
-            "managed and direct delivery are alternative modes.");
-    }
-}
 /**
  * Resolve the persistence backend at start(): an explicit `store.adapter` wins
  * (silently); otherwise an adapter-provided `stateStore` is used (warning when
@@ -179,16 +203,15 @@ function resolveBackend(explicit, adapters) {
     return providers[0]?.stateStore ?? new MemoryStore();
 }
 export function createChannel(opts) {
-    const cfg = opts.store ?? {};
-    if ((cfg.identity && !cfg.transcripts) ||
-        (!cfg.identity && cfg.transcripts)) {
-        throw new Error("createChannel: `identity` and `transcripts` must be configured together.");
+    if (opts.identifyUser !== "platform" &&
+        typeof opts.identifyUser !== "function") {
+        throw new Error('createChannel: `identifyUser` must be "platform" or a callback');
     }
+    const cfg = opts.store ?? {};
     // Adapters can be supplied up front or added later via
     // `channel.ɵruntime.addAdapter` (before `channel.ɵruntime.start()`). The
     // runtime uses the latter to attach Channel delivery.
     const adapters = [...(opts.adapters ?? [])];
-    assertExclusive(adapters);
     let started = false;
     // Backend, transcripts, telemetry, the action registry, and component
     // registration are resolved in `ɵruntime.start()` — not at construction —
@@ -238,6 +261,7 @@ export function createChannel(opts) {
     const context = opts.context ?? [];
     const mentionHandlers = [];
     const messageHandlers = [];
+    const welcomeHandlers = [];
     const threadStartedHandlers = [];
     const interactionHandlers = new Map();
     const interruptHandlers = new Map();
@@ -248,6 +272,7 @@ export function createChannel(opts) {
     const modalSubmitHandlers = new Map();
     const modalCloseHandlers = new Map();
     const waiters = new Map();
+    let intelligenceMemoryAvailable = false;
     // Recomputed on start() so tools added via channel.tool() before start are picked up.
     let toolDescriptors = toAgentToolDescriptors([...toolMap.values()]);
     function makeThread(adapter, replyTarget, conversationKey, extras) {
@@ -269,8 +294,13 @@ export function createChannel(opts) {
             state: backend,
             stateSchema: cfg.state,
             transcripts,
-            userKey: extras?.userKey,
             message: extras?.message,
+            user: extras?.user ?? null,
+            actor: extras?.actor ?? { id: "unknown", kind: "unknown" },
+            channelName: opts.name ?? adapter.platform,
+            threadId: adapter.getCanonicalThreadId?.(replyTarget) ?? conversationKey,
+            interactionActionId: extras?.interactionActionId,
+            intelligenceMemoryAvailable,
             telemetry,
         };
         return new Thread(deps);
@@ -312,26 +342,19 @@ export function createChannel(opts) {
                     console.warn(`[channel] dedup check failed for ${platform}; processing without dedup`, err);
                 }
             }
-            // Resolve cross-platform identity key (if configured) and stamp it on
-            // the message so handlers and transcript storage can use it. Done
-            // BEFORE makeThread so the thread carries the userKey + message for
-            // the transcript auto-bridge (runAgent({ transcript: true })).
-            let userKey;
-            if (cfg.identity) {
-                try {
-                    const resolved = await cfg.identity({
-                        adapter: platform,
-                        author: turn.user ?? { id: "" },
-                        message: msgFromTurn(turn),
-                    });
-                    userKey = resolved ?? undefined;
-                }
-                catch (err) {
-                    console.warn(`[channel] identity resolution failed for ${platform}; continuing without userKey`, err);
-                }
-            }
-            const message = { ...msgFromTurn(turn), userKey };
-            const thread = makeThread(adapter, turn.replyTarget, turn.conversationKey, { platform, userKey, message });
+            const identityContext = identityContextFromIngress(platform, turn, "message");
+            const user = await resolveChannelUser(opts.identifyUser, identityContext);
+            const message = {
+                ...msgFromTurn(turn),
+                user,
+                actor: identityContext.actor,
+            };
+            const thread = makeThread(adapter, turn.replyTarget, turn.conversationKey, {
+                platform,
+                message,
+                user,
+                actor: identityContext.actor,
+            });
             const handlers = turn.operation.mentioned
                 ? mentionHandlers.length > 0
                     ? mentionHandlers
@@ -396,19 +419,27 @@ export function createChannel(opts) {
                         console.warn(`[channel] dedup check failed for ${platform}; processing without dedup`, err);
                     }
                 }
-                const thread = makeThread(adapter, evt.replyTarget, evt.conversationKey, { platform });
-                const user = evt.user ?? { id: "" };
+                const identityContext = identityContextFromIngress(platform, evt, "interaction");
+                const canonicalUser = await resolveChannelUser(opts.identifyUser, identityContext);
+                const thread = makeThread(adapter, evt.replyTarget, evt.conversationKey, {
+                    platform,
+                    user: canonicalUser,
+                    actor: identityContext.actor,
+                    interactionActionId: evt.id,
+                });
                 const ctx = {
                     thread,
                     message: {
                         text: "",
-                        user,
+                        user: canonicalUser,
+                        actor: identityContext.actor,
                         ref: evt.messageRef ?? { id: "" },
                         platform,
                     },
                     action: { id: evt.id, value: evt.value },
-                    values: {},
-                    user,
+                    values: evt.values ?? {},
+                    user: canonicalUser,
+                    actor: identityContext.actor,
                     platform,
                 };
                 const openModal = makeOpenModal(adapter, evt.replyTarget, evt.triggerId);
@@ -458,7 +489,13 @@ export function createChannel(opts) {
                 const command = commandHandlers.get(normalizeCommandName(cmd.command));
                 if (!command)
                     return; // unregistered command → skip
-                const thread = makeThread(adapter, cmd.replyTarget, cmd.conversationKey, { platform });
+                const identityContext = identityContextFromIngress(platform, cmd, "command");
+                const user = await resolveChannelUser(opts.identifyUser, identityContext);
+                const thread = makeThread(adapter, cmd.replyTarget, cmd.conversationKey, {
+                    platform,
+                    user,
+                    actor: identityContext.actor,
+                });
                 // Resolve typed options from any structured args the surface supplied
                 // (e.g. Discord); text-only surfaces (Slack) leave `options` empty and
                 // the handler reads `text`.
@@ -473,7 +510,8 @@ export function createChannel(opts) {
                     command: normalizeCommandName(cmd.command),
                     text: cmd.text,
                     options,
-                    user: cmd.user,
+                    user,
+                    actor: identityContext.actor,
                     platform,
                 };
                 const openModal = makeOpenModal(adapter, cmd.replyTarget, cmd.triggerId);
@@ -481,13 +519,35 @@ export function createChannel(opts) {
                     ctx.openModal = openModal;
                 await command.handler(ctx);
             },
+            async onWelcome(evt) {
+                const platform = ingressPlatform(adapter, evt);
+                if (evt.eventId && !adapter.skipIngressDedup) {
+                    const dupKey = `evt:${platform}:${evt.eventId}`;
+                    try {
+                        if (await store.dedup.seen(dupKey, cfg.dedupTtl ?? 300_000))
+                            return;
+                    }
+                    catch (err) {
+                        console.warn(`[channel] dedup check failed for ${platform}; processing welcome without dedup`, err);
+                    }
+                }
+                const identityContext = identityContextFromIngress(platform, evt, "welcome");
+                const user = await resolveChannelUser(opts.identifyUser, identityContext);
+                const thread = makeThread(adapter, evt.replyTarget, evt.conversationKey, { platform, user, actor: identityContext.actor });
+                for (const h of welcomeHandlers) {
+                    await h({ thread, user, actor: identityContext.actor, platform });
+                }
+            },
             async onThreadStarted(evt) {
                 // The adapter has already applied its static defaults (greeting /
                 // prompts) before emitting this, so handlers layer on top and never
                 // race. Zero handlers → no-op.
-                const thread = makeThread(adapter, evt.replyTarget, evt.conversationKey, { platform: ingressPlatform(adapter, evt) });
+                const platform = ingressPlatform(adapter, evt);
+                const identityContext = identityContextFromIngress(platform, evt, "thread-start");
+                const user = await resolveChannelUser(opts.identifyUser, identityContext);
+                const thread = makeThread(adapter, evt.replyTarget, evt.conversationKey, { platform, user, actor: identityContext.actor });
                 for (const h of threadStartedHandlers)
-                    await h({ thread, user: evt.user });
+                    await h({ thread, user, actor: identityContext.actor });
             },
             async onReaction(evt) {
                 // Normalize by source platform, falling back to adapter identity for
@@ -497,14 +557,21 @@ export function createChannel(opts) {
                     ? normalizeEmoji(evt.rawEmoji, sourcePlatform)
                     : undefined;
                 const value = normalized ?? evt.rawEmoji;
-                const thread = makeThread(adapter, evt.replyTarget, evt.conversationKey, { platform: sourcePlatform });
+                const identityContext = identityContextFromIngress(sourcePlatform, evt, "reaction");
+                const user = await resolveChannelUser(opts.identifyUser, identityContext);
+                const thread = makeThread(adapter, evt.replyTarget, evt.conversationKey, {
+                    platform: sourcePlatform,
+                    user,
+                    actor: identityContext.actor,
+                });
                 // Prefer the adapter's update-capable ref; fall back to the bare id.
                 const messageRef = evt.messageRef ?? { id: evt.messageId };
                 const reactionEvt = {
                     emoji: value,
                     rawEmoji: evt.rawEmoji,
                     added: evt.added,
-                    user: evt.user,
+                    user,
+                    actor: identityContext.actor,
                     messageId: evt.messageId,
                     messageRef,
                     threadId: evt.threadId,
@@ -527,7 +594,8 @@ export function createChannel(opts) {
                         emoji: value,
                         rawEmoji: evt.rawEmoji,
                         added: evt.added,
-                        user: evt.user,
+                        user,
+                        actor: identityContext.actor,
                         messageId: evt.messageId,
                         thread,
                         messageRef,
@@ -538,15 +606,20 @@ export function createChannel(opts) {
                 const handler = modalSubmitHandlers.get(evt.callbackId);
                 if (!handler)
                     return; // unregistered → closes
+                const identityContext = identityContextFromIngress(evt.platform, evt, "modal-submit");
+                const user = await resolveChannelUser(opts.identifyUser, identityContext);
                 const thread = evt.conversationKey !== undefined && evt.replyTarget !== undefined
                     ? makeThread(adapter, evt.replyTarget, evt.conversationKey, {
                         platform: evt.platform,
+                        user,
+                        actor: identityContext.actor,
                     })
                     : undefined;
                 const result = await handler({
                     callbackId: evt.callbackId,
                     values: evt.values,
-                    user: evt.user,
+                    user,
+                    actor: identityContext.actor,
                     thread,
                     privateMetadata: evt.privateMetadata,
                     raw: evt.raw,
@@ -557,9 +630,12 @@ export function createChannel(opts) {
                 const handler = modalCloseHandlers.get(evt.callbackId);
                 if (!handler)
                     return;
+                const identityContext = identityContextFromIngress(evt.platform, evt, "modal-close");
+                const user = await resolveChannelUser(opts.identifyUser, identityContext);
                 await handler({
                     callbackId: evt.callbackId,
-                    user: evt.user,
+                    user,
+                    actor: identityContext.actor,
                     privateMetadata: evt.privateMetadata,
                     raw: evt.raw,
                 });
@@ -568,7 +644,6 @@ export function createChannel(opts) {
     }
     const channel = {
         name: opts.name,
-        ...(opts.provider !== undefined ? { provider: opts.provider } : {}),
         ...(opts.showToolStatus !== undefined
             ? { showToolStatus: opts.showToolStatus }
             : {}),
@@ -590,11 +665,13 @@ export function createChannel(opts) {
             return transcripts;
         },
         ɵruntime: {
+            enableIntelligenceMemory() {
+                intelligenceMemoryAvailable = true;
+            },
             addAdapter(adapter) {
                 if (started) {
                     throw new Error("channel.ɵruntime.addAdapter must be called before channel.ɵruntime.start()");
                 }
-                assertExclusive([...adapters, adapter]);
                 adapters.push(adapter);
             },
             async start() {
@@ -610,7 +687,6 @@ export function createChannel(opts) {
                     throw new Error(`channel "${opts.name ?? "(unnamed)"}" must register onMention or onMessage before activation`);
                 }
                 started = true;
-                assertExclusive(adapters);
                 // Resolve persistence now that all adapters (including any attached via
                 // addAdapter) are known, then build the transcript store, action
                 // registry, and register components against it.
@@ -623,7 +699,11 @@ export function createChannel(opts) {
                 });
                 telemetry = tel;
                 const registryInstance = new ActionRegistry({
-                    store: opts.actionStore ?? kvActionStore(backend),
+                    store: opts.actionStore ??
+                        kvActionStore(backend, {
+                            defaultTtlMs: cfg.actionRetentionMs ?? 7 * 24 * 60 * 60 * 1000,
+                        }),
+                    retentionMs: cfg.actionRetentionMs ?? 7 * 24 * 60 * 60 * 1000,
                 });
                 registry = registryInstance;
                 for (const c of opts.components ?? []) {
@@ -644,7 +724,6 @@ export function createChannel(opts) {
                     commandsCount: commandHandlers.size,
                     contextCount: context.length,
                     transcripts: !!cfg.transcripts,
-                    identity: !!cfg.identity,
                 });
                 // Isolate per-adapter startup failures: one adapter rejecting (e.g.
                 // Telegram's setMyCommands rejecting a hyphenated command name, a revoked
@@ -669,6 +748,66 @@ export function createChannel(opts) {
                         startedPlatforms.push(platform);
                     }
                 });
+                const managedFailureIndex = startResults.findIndex((result, index) => adapters[index]?.__intelligenceChannel === true &&
+                    result.status === "rejected");
+                const stopAdapters = async (indexes, reason) => {
+                    const rollbackResults = await Promise.allSettled(indexes.map((index) => new Promise((resolve, reject) => {
+                        let settled = false;
+                        const timeout = setTimeout(() => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            reject(new Error(`stop timed out after ${ADAPTER_ROLLBACK_TIMEOUT_MS}ms`));
+                        }, ADAPTER_ROLLBACK_TIMEOUT_MS);
+                        void Promise.resolve()
+                            .then(() => adapters[index].stop())
+                            .then(() => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            clearTimeout(timeout);
+                            resolve();
+                        }, (error) => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            clearTimeout(timeout);
+                            reject(error);
+                        });
+                    })));
+                    rollbackResults.forEach((result, resultIndex) => {
+                        if (result.status === "rejected") {
+                            const adapterIndex = indexes[resultIndex];
+                            console.error(`[channel] adapter "${adapters[adapterIndex].platform}" failed to stop ${reason}:`, result.reason);
+                        }
+                    });
+                };
+                const allAdapterIndexes = adapters.map((_adapter, index) => index);
+                const rejectedAdapterIndexes = startResults.flatMap((result, index) => result.status === "rejected" ? [index] : []);
+                if (managedFailureIndex >= 0) {
+                    // Managed activation must never report online merely because a
+                    // coexisting direct adapter started. Roll back every attempted
+                    // adapter, including the rejecting managed adapter, because start()
+                    // may have acquired resources before it failed.
+                    await stopAdapters(allAdapterIndexes, "after managed activation failed");
+                    started = false;
+                    throw new Error(`channel "${opts.name ?? "(unnamed)"}" failed to start its managed Intelligence adapter`);
+                }
+                // A channel that has adapters but where NONE started is dead — surface an
+                // error so the runtime reports status "error", not a false "online". A
+                // PARTIAL start (>=1 adapter live) still counts as started. Reset the
+                // `started` guard so a caller can retry after fixing the misconfiguration.
+                if (adapters.length > 0 && startedPlatforms.length === 0) {
+                    await stopAdapters(allAdapterIndexes, "after all adapters failed to start");
+                    started = false;
+                    throw new Error(`channel "${opts.name ?? "(unnamed)"}" failed to start: all ${failedPlatforms.length} adapter(s) failed to connect (${failedPlatforms.join(", ")}) — see the logged errors above`);
+                }
+                if (rejectedAdapterIndexes.length > 0) {
+                    // A rejecting start may still have acquired a listener or provider
+                    // client. Release only those failed adapters while preserving the
+                    // healthy adapters that make this a valid degraded start.
+                    await stopAdapters(rejectedAdapterIndexes, "after its start failed");
+                }
                 if (startedPlatforms.length > 0) {
                     tel.capture("oss.channel.started", {
                         platforms: startedPlatforms,
@@ -681,23 +820,18 @@ export function createChannel(opts) {
                         toolsCount: toolMap.size,
                     });
                 }
-                // A channel that has adapters but where NONE started is dead — surface an
-                // error so the runtime reports status "error", not a false "online". A
-                // PARTIAL start (>=1 adapter live) still counts as started. Reset the
-                // `started` guard so a caller can retry after fixing the misconfiguration.
-                if (adapters.length > 0 && startedPlatforms.length === 0) {
-                    started = false;
-                    throw new Error(`channel "${opts.name ?? "(unnamed)"}" failed to start: all ${failedPlatforms.length} adapter(s) failed to connect (${failedPlatforms.join(", ")}) — see the logged errors above`);
-                }
                 // Hand declared commands to adapters that register them up front (e.g.
-                // Discord); adapters without `registerCommands` are skipped. Per-adapter
-                // failures are isolated the same way as start().
+                // Discord); adapters without `registerCommands` are skipped. Never call
+                // into adapters whose start failed and whose resources were just
+                // cleaned up. Per-adapter failures are isolated the same way as start().
                 const commandSpecs = [...commandHandlers.values()].map(toCommandSpec);
                 if (commandSpecs.length > 0) {
-                    const registerResults = await Promise.allSettled(adapters.map((a) => a.registerCommands?.(commandSpecs)));
-                    registerResults.forEach((r, i) => {
+                    const startedAdapterIndexes = startResults.flatMap((result, index) => result.status === "fulfilled" ? [index] : []);
+                    const registerResults = await Promise.allSettled(startedAdapterIndexes.map((index) => adapters[index].registerCommands?.(commandSpecs)));
+                    registerResults.forEach((r, resultIndex) => {
                         if (r.status === "rejected") {
-                            console.error(`[channel] adapter "${adapters[i].platform}" failed to register commands:`, r.reason);
+                            const adapterIndex = startedAdapterIndexes[resultIndex];
+                            console.error(`[channel] adapter "${adapters[adapterIndex].platform}" failed to register commands:`, r.reason);
                         }
                     });
                 }
@@ -710,7 +844,7 @@ export function createChannel(opts) {
                 started = false;
                 // Isolate per-adapter shutdown failures: one adapter's stop() rejecting
                 // must not prevent the others from being stopped.
-                const stopResults = await Promise.allSettled(adapters.map((a) => a.stop()));
+                const stopResults = await Promise.allSettled(adapters.map((a) => Promise.resolve().then(() => a.stop())));
                 stopResults.forEach((r, i) => {
                     if (r.status === "rejected") {
                         console.error(`[channel] adapter "${adapters[i].platform}" failed to stop:`, r.reason);
@@ -728,6 +862,9 @@ export function createChannel(opts) {
         onMessage(h) {
             messageHandlers.push(h);
         },
+        onWelcome(h) {
+            welcomeHandlers.push(h);
+        },
         onThreadStarted(h) {
             threadStartedHandlers.push(h);
         },