@copilotkit/channels 0.1.0

package/dist/create-bot.js

@@ -0,0 +1,576 @@
+import { ActionRegistry, ActionExpiredError } from "./action-registry.js";
+import { MemoryStore } from "./state/memory-store.js";
+import { kvActionStore } from "./state/kv-action-store.js";
+import { toAgentToolDescriptors, parseToolArgs } from "./tools.js";
+import { normalizeCommandName, toCommandSpec } from "./commands.js";
+import { Thread } from "./thread.js";
+import { normalizeEmoji, toCanonicalEmoji, renderToIR, } from "@copilotkit/channels-ui";
+import { Transcripts } from "./transcripts.js";
+import { BotTelemetry } from "./telemetry/bot-telemetry.js";
+import { errorClass, normalizePlatform } from "./telemetry/sanitize-error.js";
+import { createRequire } from "node:module";
+const pkg = createRequire(import.meta.url)("../package.json");
+function storeKind(s) {
+    const n = s.constructor?.name;
+    if (n === "MemoryStore")
+        return "memory";
+    if (n === "PostgresStore")
+        return "postgres";
+    if (n === "RedisStore")
+        return "redis";
+    return "custom";
+}
+/** Platforms whose tokens the emoji table can normalize. */
+const EMOJI_PLATFORMS = new Set([
+    "slack",
+    "discord",
+    "telegram",
+]);
+function isEmojiPlatform(platform) {
+    return EMOJI_PLATFORMS.has(platform);
+}
+/** Build the IncomingMessage object from an IncomingTurn (shared by lock-conflict callback and handler path). */
+function msgFromTurn(turn) {
+    return {
+        text: turn.userText,
+        contentParts: turn.contentParts,
+        user: turn.user ?? { id: "" },
+        ref: { id: "" },
+        platform: turn.platform,
+        eventId: turn.eventId,
+        turnId: turn.turnId,
+        deliveryId: turn.deliveryId,
+    };
+}
+/**
+ * Enforce V1 managed exclusivity: a managed adapter (`intelligenceAdapter`)
+ * must be the only adapter on a bot. Managed and direct delivery are
+ * alternative modes per platform — Intelligence holds the platform creds, or
+ * the runtime does, never both.
+ */
+function assertExclusive(adapters) {
+    if (adapters.some((a) => a.__managed) && adapters.length > 1) {
+        throw new Error("intelligenceAdapter() must be the only adapter on a bot — managed and " +
+            "direct delivery are alternative modes. Use intelligenceAdapter() OR " +
+            "direct adapters (slack/discord/...), not both.");
+    }
+}
+/**
+ * Resolve the persistence backend at start(): an explicit `store.adapter` wins
+ * (silently); otherwise an adapter-provided `stateStore` is used (warning when
+ * more than one adapter provides one); otherwise an in-memory store.
+ */
+function resolveBackend(explicit, adapters) {
+    if (explicit)
+        return explicit;
+    const providers = adapters.filter((a) => a.stateStore);
+    if (providers.length > 1) {
+        console.warn(`[bot] multiple adapters provide a state store (${providers
+            .map((a) => a.platform)
+            .join(", ")}); using "${providers[0].platform}". Pass store.adapter to choose explicitly.`);
+    }
+    return providers[0]?.stateStore ?? new MemoryStore();
+}
+export function createBot(opts) {
+    const cfg = opts.store ?? {};
+    if ((cfg.identity && !cfg.transcripts) ||
+        (!cfg.identity && cfg.transcripts)) {
+        throw new Error("createBot: `identity` and `transcripts` must be configured together.");
+    }
+    // Adapters can be supplied up front or added later via `bot.addAdapter`
+    // (before `start()`). The runtime uses the latter to attach managed delivery.
+    const adapters = [...(opts.adapters ?? [])];
+    assertExclusive(adapters);
+    let started = false;
+    // Backend, transcripts, telemetry, the action registry, and component
+    // registration are resolved in `start()` — not at construction — so an
+    // adapter added via `addAdapter` after `createBot` can still supply the
+    // persistence backend (see `resolveBackend`). Nothing reads these before the
+    // first event, which can only arrive after `start()`.
+    let backend;
+    let transcripts;
+    let registry;
+    let telemetry;
+    const agentFactory = (() => {
+        const a = opts.agent;
+        if (typeof a === "function")
+            return a;
+        if (a)
+            return () => a;
+        return () => {
+            throw new Error("createBot: no agent configured (pass `agent` to use runAgent)");
+        };
+    })();
+    const toolMap = new Map();
+    for (const t of opts.tools ?? [])
+        toolMap.set(t.name, t);
+    const context = opts.context ?? [];
+    const mentionHandlers = [];
+    const messageHandlers = [];
+    const threadStartedHandlers = [];
+    const interactionHandlers = new Map();
+    const interruptHandlers = new Map();
+    const commandHandlers = new Map();
+    for (const c of opts.commands ?? [])
+        commandHandlers.set(normalizeCommandName(c.name), c);
+    const reactionHandlers = [];
+    const modalSubmitHandlers = new Map();
+    const modalCloseHandlers = new Map();
+    const waiters = new Map();
+    // Recomputed on start() so tools added via bot.tool() before start are picked up.
+    let toolDescriptors = toAgentToolDescriptors([...toolMap.values()]);
+    function makeThread(adapter, replyTarget, conversationKey, extras) {
+        if (!backend || !registry || !telemetry) {
+            throw new Error("bot not started: call bot.start() before handling events");
+        }
+        const deps = {
+            adapter,
+            replyTarget,
+            conversationKey,
+            registry,
+            agentFactory,
+            tools: toolMap,
+            toolDescriptors,
+            context,
+            registerWaiter: (k, r) => waiters.set(k, r),
+            interruptHandlers,
+            state: backend,
+            stateSchema: cfg.state,
+            transcripts,
+            userKey: extras?.userKey,
+            message: extras?.message,
+            telemetry,
+        };
+        return new Thread(deps);
+    }
+    /**
+     * Build the context-level `openModal` closure, or `undefined` when the surface
+     * can't open one. Requires both `adapter.openModal` and a platform `triggerId`;
+     * otherwise the context omits `openModal` (callers guard `ctx.openModal?.(view)`).
+     */
+    function makeOpenModal(adapter, replyTarget, triggerId) {
+        if (!adapter.openModal || !triggerId)
+            return undefined;
+        return (view) => adapter.openModal(replyTarget, triggerId, renderToIR(view));
+    }
+    function makeSink(adapter) {
+        // backend/registry are resolved in start() before any adapter.start() runs,
+        // so they are always set by the time the sink receives an event.
+        const store = backend;
+        return {
+            async onTurn(turn) {
+                const lockKey = `turn:${turn.conversationKey}`;
+                const acquired = await store.lock.acquire(lockKey, {
+                    ttlMs: cfg.lockTtl ?? 60_000,
+                });
+                if (!acquired) {
+                    const decision = typeof cfg.onLockConflict === "function"
+                        ? await cfg.onLockConflict(turn.conversationKey, msgFromTurn(turn))
+                        : (cfg.onLockConflict ?? "drop");
+                    if (decision === "drop")
+                        return; // discard overlapping turn
+                    // "force": proceed WITHOUT a lock token. Does NOT cancel the
+                    // in-flight handler — cooperative cancellation is a future extension.
+                }
+                try {
+                    // Dedup AFTER acquiring the lock: a turn dropped on lock-conflict must NOT burn its
+                    // eventId, so Slack's retry can still be processed once the lock frees. (A handler
+                    // that throws still leaves its event marked seen — dedup drops duplicate DELIVERIES,
+                    // it is not retry-of-failed-turns.)
+                    if (turn.eventId && !adapter.skipIngressDedup) {
+                        const dupKey = `evt:${adapter.platform}:${turn.eventId}`;
+                        try {
+                            if (await store.dedup.seen(dupKey, cfg.dedupTtl ?? 300_000))
+                                return;
+                        }
+                        catch (err) {
+                            console.warn(`[bot] dedup check failed for ${adapter.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: adapter.platform,
+                                author: turn.user ?? { id: "" },
+                                message: msgFromTurn(turn),
+                            });
+                            userKey = resolved ?? undefined;
+                        }
+                        catch (err) {
+                            console.warn(`[bot] identity resolution failed for ${adapter.platform}; continuing without userKey`, err);
+                        }
+                    }
+                    const message = { ...msgFromTurn(turn), userKey };
+                    const thread = makeThread(adapter, turn.replyTarget, turn.conversationKey, { userKey, message });
+                    // v1 routing: there is no turn `kind`, so prefer mention handlers; if
+                    // none are registered, fall back to message handlers. (The reference
+                    // example registers identical handlers on both, so this avoids
+                    // double-firing while still invoking whatever is registered.)
+                    const handlers = mentionHandlers.length > 0 ? mentionHandlers : messageHandlers;
+                    for (const h of handlers)
+                        await h({ thread, message });
+                }
+                finally {
+                    // acquired is null on "force" — naturally skips release.
+                    if (acquired)
+                        await store.lock.release(lockKey, acquired.token);
+                }
+            },
+            async onInteraction(evt) {
+                // Dedup guard: drop duplicate deliveries of the same event within the TTL window.
+                if (evt.eventId && !adapter.skipIngressDedup) {
+                    const dupKey = `evt:${adapter.platform}:${evt.eventId}`;
+                    try {
+                        if (await store.dedup.seen(dupKey, cfg.dedupTtl ?? 300_000))
+                            return;
+                    }
+                    catch (err) {
+                        console.warn(`[bot] dedup check failed for ${adapter.platform}; processing without dedup`, err);
+                    }
+                }
+                const thread = makeThread(adapter, evt.replyTarget, evt.conversationKey);
+                const user = evt.user ?? { id: "" };
+                const ctx = {
+                    thread,
+                    message: {
+                        text: "",
+                        user,
+                        ref: evt.messageRef ?? { id: "" },
+                        platform: adapter.platform,
+                    },
+                    action: { id: evt.id, value: evt.value },
+                    values: {},
+                    user,
+                    platform: adapter.platform,
+                };
+                const openModal = makeOpenModal(adapter, evt.replyTarget, evt.triggerId);
+                if (openModal)
+                    ctx.openModal = openModal;
+                // The clicked element's `value`, recovered by the registry when it
+                // re-renders to find the handler. Used to resolve a HITL waiter on
+                // platforms whose callback payload can't carry the value (Telegram),
+                // where `evt.value` is undefined.
+                let dispatchedValue;
+                try {
+                    const explicit = interactionHandlers.get(evt.id);
+                    if (explicit) {
+                        await explicit(ctx);
+                    }
+                    else {
+                        dispatchedValue = await registry.dispatch(evt.id, ctx);
+                    }
+                }
+                catch (err) {
+                    // v1: swallow expired-action dispatches; surface anything else.
+                    if (!(err instanceof ActionExpiredError))
+                        throw err;
+                }
+                // Resolve any HITL waiter awaiting a choice in this conversation. Prefer
+                // the value carried in the event (Slack), falling back to the value the
+                // registry recovered from the rendered element (Telegram).
+                const w = waiters.get(evt.conversationKey);
+                if (w) {
+                    waiters.delete(evt.conversationKey);
+                    w(evt.value !== undefined ? evt.value : dispatchedValue);
+                }
+            },
+            async onCommand(cmd) {
+                // Dedup guard: drop duplicate deliveries of the same event within the TTL window.
+                if (cmd.eventId && !adapter.skipIngressDedup) {
+                    const dupKey = `evt:${adapter.platform}:${cmd.eventId}`;
+                    try {
+                        if (await store.dedup.seen(dupKey, cfg.dedupTtl ?? 300_000))
+                            return;
+                    }
+                    catch (err) {
+                        console.warn(`[bot] dedup check failed for ${adapter.platform}; processing without dedup`, err);
+                    }
+                }
+                const command = commandHandlers.get(normalizeCommandName(cmd.command));
+                if (!command)
+                    return; // unregistered command → skip
+                const thread = makeThread(adapter, cmd.replyTarget, cmd.conversationKey);
+                // 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`.
+                let options = {};
+                if (command.options && cmd.rawOptions) {
+                    const parsed = await parseToolArgs(command.options, cmd.rawOptions);
+                    if (parsed.ok)
+                        options = parsed.value;
+                }
+                const ctx = {
+                    thread,
+                    command: normalizeCommandName(cmd.command),
+                    text: cmd.text,
+                    options,
+                    user: cmd.user,
+                    platform: cmd.platform,
+                };
+                const openModal = makeOpenModal(adapter, cmd.replyTarget, cmd.triggerId);
+                if (openModal)
+                    ctx.openModal = openModal;
+                await command.handler(ctx);
+            },
+            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);
+                for (const h of threadStartedHandlers)
+                    await h({ thread, user: evt.user });
+            },
+            async onReaction(evt) {
+                // Only normalize when the adapter's platform is one the emoji table
+                // knows; otherwise the raw token passes through unchanged.
+                const normalized = isEmojiPlatform(adapter.platform)
+                    ? normalizeEmoji(evt.rawEmoji, adapter.platform)
+                    : undefined;
+                const value = normalized ?? evt.rawEmoji;
+                const thread = makeThread(adapter, evt.replyTarget, evt.conversationKey);
+                // 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,
+                    messageId: evt.messageId,
+                    messageRef,
+                    threadId: evt.threadId,
+                    thread,
+                    adapter,
+                    raw: evt.raw,
+                };
+                for (const reg of reactionHandlers) {
+                    if (!reg.emojis || reg.emojis.has(value))
+                        await reg.handler(reactionEvt);
+                }
+                // Per-message handler set via `<Message onReaction>` on the posted
+                // message — hot cache, falling back to the durable snapshot after a restart.
+                const perMessage = await registry.resolveMessageReaction(evt.messageId);
+                if (perMessage) {
+                    await perMessage(value, {
+                        emoji: value,
+                        rawEmoji: evt.rawEmoji,
+                        added: evt.added,
+                        user: evt.user,
+                        messageId: evt.messageId,
+                        thread,
+                        messageRef,
+                    });
+                }
+            },
+            async onModalSubmit(evt) {
+                const handler = modalSubmitHandlers.get(evt.callbackId);
+                if (!handler)
+                    return; // unregistered → closes
+                const thread = evt.conversationKey !== undefined && evt.replyTarget !== undefined
+                    ? makeThread(adapter, evt.replyTarget, evt.conversationKey)
+                    : undefined;
+                const result = await handler({
+                    callbackId: evt.callbackId,
+                    values: evt.values,
+                    user: evt.user,
+                    thread,
+                    privateMetadata: evt.privateMetadata,
+                    raw: evt.raw,
+                });
+                return result ?? undefined;
+            },
+            async onModalClose(evt) {
+                const handler = modalCloseHandlers.get(evt.callbackId);
+                if (!handler)
+                    return;
+                await handler({
+                    callbackId: evt.callbackId,
+                    user: evt.user,
+                    privateMetadata: evt.privateMetadata,
+                    raw: evt.raw,
+                });
+            },
+        };
+    }
+    const bot = {
+        name: opts.name,
+        get commandNames() {
+            return [...commandHandlers.keys()];
+        },
+        get transcripts() {
+            if (!transcripts) {
+                throw new Error("bot.transcripts is available after bot.start()");
+            }
+            return transcripts;
+        },
+        addAdapter(adapter) {
+            if (started) {
+                throw new Error("bot.addAdapter must be called before bot.start()");
+            }
+            assertExclusive([...adapters, adapter]);
+            adapters.push(adapter);
+        },
+        onMention(h) {
+            // The public surface narrows `thread` to StatefulThread<TState>; the
+            // internal arrays hold the loose `BotHandler` shape. A real Thread is
+            // assignable to StatefulThread<TState> (its generic setState/state
+            // satisfy the narrowed signatures), so the cast is sound.
+            mentionHandlers.push(h);
+        },
+        onMessage(h) {
+            messageHandlers.push(h);
+        },
+        onThreadStarted(h) {
+            threadStartedHandlers.push(h);
+        },
+        onInteraction(id, h) {
+            interactionHandlers.set(id, h);
+        },
+        onInterrupt(eventName, h) {
+            interruptHandlers.set(eventName, h);
+        },
+        onCommand(commandOrName, handler) {
+            const command = typeof commandOrName === "string"
+                ? { name: commandOrName, handler: handler }
+                : commandOrName;
+            commandHandlers.set(normalizeCommandName(command.name), command);
+        },
+        onReaction(emojiOrHandler, maybeHandler) {
+            if (typeof emojiOrHandler === "function") {
+                reactionHandlers.push({ handler: emojiOrHandler });
+                return;
+            }
+            const list = Array.isArray(emojiOrHandler)
+                ? emojiOrHandler
+                : [emojiOrHandler];
+            // Ingress normalizes inbound reactions to their canonical name, so
+            // normalize the caller's filter tokens too — otherwise a raw unicode
+            // ("👍") or Slack alias ("thumbsup") filter would never match the
+            // canonical "thumbs_up" the engine compares against. Unknown/custom
+            // tokens pass through unchanged.
+            const emojis = new Set(list.map((e) => toCanonicalEmoji(e)));
+            reactionHandlers.push({ emojis, handler: maybeHandler });
+        },
+        onModalSubmit(callbackId, handler) {
+            modalSubmitHandlers.set(callbackId, handler);
+        },
+        onModalClose(callbackId, handler) {
+            modalCloseHandlers.set(callbackId, handler);
+        },
+        tool(t) {
+            toolMap.set(t.name, t);
+        },
+        async start() {
+            // Idempotent: a second start() must not re-resolve the backend and
+            // rebuild Transcripts/Telemetry/ActionRegistry or re-call adapter.start()
+            // — with a MemoryStore that wipes all lock/dedup/transcript/action state,
+            // and real adapters would connect/port-bind twice.
+            if (started)
+                return;
+            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.
+            backend = resolveBackend(cfg.adapter, adapters);
+            transcripts = new Transcripts(backend, cfg.transcripts ?? {});
+            const tel = new BotTelemetry({
+                backend,
+                packageName: pkg.name,
+                packageVersion: pkg.version,
+            });
+            telemetry = tel;
+            const registryInstance = new ActionRegistry({
+                store: opts.actionStore ?? kvActionStore(backend),
+            });
+            registry = registryInstance;
+            for (const c of opts.components ?? []) {
+                if (!c.name) {
+                    console.warn("[bot] createBot: skipping anonymous component — give it a name to enable durable actions after restart.");
+                    continue;
+                }
+                registryInstance.registerComponent(c.name, c);
+            }
+            toolDescriptors = toAgentToolDescriptors([...toolMap.values()]);
+            tel.capture("oss.bot.configured", {
+                platforms: adapters.map((a) => normalizePlatform(a.platform)),
+                adapterCount: adapters.length,
+                store: storeKind(backend),
+                hasComponents: (opts.components?.length ?? 0) > 0,
+                componentsCount: opts.components?.length ?? 0,
+                toolsCount: toolMap.size,
+                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
+            // token, a port already in use) must NOT crash the bot or prevent the
+            // other adapters from starting. Log + degrade, never throw.
+            const startResults = await Promise.allSettled(adapters.map((a) => a.start(makeSink(a), { botName: opts.name })));
+            const startedPlatforms = [];
+            const failedPlatforms = [];
+            startResults.forEach((r, i) => {
+                const rawPlatform = adapters[i].platform;
+                // Raw label for the human-facing log; normalized label for telemetry.
+                const platform = normalizePlatform(rawPlatform);
+                if (r.status === "rejected") {
+                    failedPlatforms.push(platform);
+                    console.error(`[bot] adapter "${rawPlatform}" failed to start:`, r.reason);
+                    tel.capture("oss.bot.start_failed", {
+                        platform,
+                        errorClass: errorClass(r.reason),
+                    });
+                }
+                else {
+                    startedPlatforms.push(platform);
+                }
+            });
+            if (startedPlatforms.length > 0) {
+                tel.capture("oss.bot.started", {
+                    platforms: startedPlatforms,
+                    startedCount: startedPlatforms.length,
+                    failedCount: failedPlatforms.length,
+                    hasMentionHandler: mentionHandlers.length > 0,
+                    hasMessageHandler: messageHandlers.length > 0,
+                    interruptHandlers: interruptHandlers.size,
+                    commandsCount: commandHandlers.size,
+                    toolsCount: toolMap.size,
+                });
+            }
+            // 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().
+            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) => {
+                    if (r.status === "rejected") {
+                        console.error(`[bot] adapter "${adapters[i].platform}" failed to register commands:`, r.reason);
+                    }
+                });
+            }
+        },
+        async stop() {
+            // Clear the started flag so a later start() is a real restart (re-resolve
+            // backend, rebuild components, reconnect adapters) rather than a silent
+            // no-op. The idempotency guard in start() only exists to block a DOUBLE
+            // start() while running — not a legitimate start→stop→start cycle.
+            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()));
+            stopResults.forEach((r, i) => {
+                if (r.status === "rejected") {
+                    console.error(`[bot] adapter "${adapters[i].platform}" failed to stop:`, r.reason);
+                }
+            });
+        },
+    };
+    return bot;
+}

package/dist/create-bot.test.d.ts

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

package/dist/create-bot.test.d.ts.map

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