@copilotkit/channels 0.1.0

package/dist/action-store.js

@@ -0,0 +1,23 @@
+/** @deprecated Configure `createBot({ state })` instead. Action snapshots are stored via `StateStore.kv`. */
+export class InMemoryActionStore {
+    map = new Map();
+    async put(id, snap, ttlMs) {
+        this.map.set(id, {
+            snap,
+            expiresAt: ttlMs ? Date.now() + ttlMs : undefined,
+        });
+    }
+    async get(id) {
+        const e = this.map.get(id);
+        if (!e)
+            return undefined;
+        if (e.expiresAt !== undefined && Date.now() > e.expiresAt) {
+            this.map.delete(id);
+            return undefined;
+        }
+        return e.snap;
+    }
+    async delete(id) {
+        this.map.delete(id);
+    }
+}

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

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

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

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

package/dist/action-store.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect, vi } from "vitest";
+import { InMemoryActionStore } from "./action-store.js";
+describe("InMemoryActionStore", () => {
+    it("puts and gets a snapshot", async () => {
+        const s = new InMemoryActionStore();
+        await s.put("id1", { path: [0], conversationKey: "c" });
+        expect(await s.get("id1")).toMatchObject({ path: [0] });
+    });
+    it("expires entries past ttl", async () => {
+        vi.useFakeTimers();
+        try {
+            const s = new InMemoryActionStore();
+            await s.put("id1", { path: [0], conversationKey: "c" }, 1000);
+            vi.advanceTimersByTime(1500);
+            expect(await s.get("id1")).toBeUndefined();
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+    it("deletes entries", async () => {
+        const s = new InMemoryActionStore();
+        await s.put("id1", { path: [0], conversationKey: "c" });
+        await s.delete("id1");
+        expect(await s.get("id1")).toBeUndefined();
+    });
+});

package/dist/codec.d.ts

@@ -0,0 +1,25 @@
+import type { BotNode } from "@copilotkit/channels-ui";
+/**
+ * A pure, dependency-free, per-platform codec shared by the local adapter and
+ * the Intelligence side. It exists so platform *semantics* (how to render IR to
+ * a native payload, and — later — how to normalize a native event to the
+ * neutral ingress shape) live in ONE place, instead of being duplicated between
+ * a credentialed local adapter (Bolt/discord.js) and the Connector Outbox /
+ * webhook ingress.
+ *
+ * Only the two creds/connection-bound concerns stay per-side: the transport
+ * (who holds the platform connection) and the credentialed send. The codec
+ * excludes both — `renderEgress` is pure (IR → native payload); the actual
+ * send happens in the Connector Outbox with Intelligence-owned credentials.
+ *
+ * TODO(OSS-363): add `normalizeIngress(raw): NeutralEvent` once the pure Slack
+ * ingress mapping (mention stripping, stable event-id derivation, real-user
+ * filtering, field extraction) is extracted from the Bolt listener so both the
+ * local adapter and Intelligence's webhook ingress consume the same logic.
+ */
+export interface PlatformCodec {
+    readonly platform: string;
+    /** IR → native payload. Pure; opaque to bot core. */
+    renderEgress(ir: BotNode[]): unknown;
+}
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;CACtC"}

package/dist/codec.js

@@ -0,0 +1 @@
+export {};

package/dist/commands.d.ts

@@ -0,0 +1,73 @@
+import type { InferSchemaOutput, ObjectSchema } from "./standard-schema.js";
+import type { Thread, PlatformUser, ModalView } from "@copilotkit/channels-ui";
+/**
+ * Context handed to a slash-command handler. `text` is the raw argument string
+ * (the form Slack delivers); `options` is the parsed, typed form, populated by
+ * surfaces that deliver structured args natively (e.g. Discord). On text-only
+ * surfaces `options` is empty — read `text` there.
+ */
+export interface CommandContext<TOptions = Record<string, never>> {
+    /** The conversation the command was invoked in. */
+    thread: Thread;
+    /** The invoked command name, normalized (no leading slash, lower-cased). */
+    command: string;
+    /** Raw argument string after the command name. */
+    text: string;
+    /** Parsed, typed options (empty on surfaces that only deliver `text`). */
+    options: TOptions;
+    /** The invoking user, when the surface provides it. */
+    user?: PlatformUser;
+    platform: string;
+    /** Open a modal in response to this command (requires the surface's trigger; `undefined` when unavailable). */
+    openModal?(view: ModalView): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * A slash command. Defined like a {@link import("./tools.js").BotTool}: a name,
+ * an optional Standard Schema for typed options, and a handler. The `options`
+ * schema maps natively to surfaces with structured args (Discord) and is used
+ * to register/validate there; on text-only surfaces (Slack) args arrive via
+ * `ctx.text`.
+ */
+export interface BotCommand<Schema extends ObjectSchema = ObjectSchema> {
+    /** Command name without the leading slash (e.g. `"triage"`). Matched case-insensitively. */
+    name: string;
+    /** Human description — help text, and the registration label on surfaces like Discord. */
+    description?: string;
+    /** Optional Standard Schema for typed options. */
+    options?: Schema;
+    handler(ctx: CommandContext<InferSchemaOutput<Schema>>): void | Promise<void>;
+}
+/**
+ * Define a {@link BotCommand} with full type inference: `ctx.options` is
+ * inferred from `options`.
+ *
+ * ```ts
+ * const triage = defineBotCommand({
+ *   name: "triage",
+ *   description: "Summarize and file the current thread.",
+ *   options: z.object({ priority: z.enum(["low", "high"]).optional() }),
+ *   async handler({ thread, text, options }) {
+ *     await thread.runAgent({ prompt: `Triage: ${text}`, });
+ *   },
+ * });
+ * ```
+ */
+export declare function defineBotCommand<Schema extends ObjectSchema>(command: BotCommand<Schema>): BotCommand<Schema>;
+/**
+ * Platform-neutral descriptor an adapter may use to register a command with the
+ * surface (e.g. Discord's application-command API). Produced from a
+ * {@link BotCommand} by {@link toCommandSpec}.
+ */
+export interface CommandSpec {
+    name: string;
+    description: string;
+    /** JSON Schema for the options, or `undefined` for a free-text command. */
+    options?: Record<string, unknown>;
+}
+/** Normalize a command name for matching: drop a leading slash, lower-case, trim. */
+export declare function normalizeCommandName(name: string): string;
+export declare function toCommandSpec(command: BotCommand): CommandSpec;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAE5E,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAC9D,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,QAAQ,CAAC;IAClB,uDAAuD;IACvD,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,+GAA+G;IAC/G,SAAS,CAAC,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY;IACpE,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,YAAY,EAC1D,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,GAC1B,UAAU,CAAC,MAAM,CAAC,CAEpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,WAAW,CAU9D"}

package/dist/commands.js

@@ -0,0 +1,38 @@
+import { toJsonSchema } from "./standard-schema.js";
+/**
+ * Define a {@link BotCommand} with full type inference: `ctx.options` is
+ * inferred from `options`.
+ *
+ * ```ts
+ * const triage = defineBotCommand({
+ *   name: "triage",
+ *   description: "Summarize and file the current thread.",
+ *   options: z.object({ priority: z.enum(["low", "high"]).optional() }),
+ *   async handler({ thread, text, options }) {
+ *     await thread.runAgent({ prompt: `Triage: ${text}`, });
+ *   },
+ * });
+ * ```
+ */
+export function defineBotCommand(command) {
+    return command;
+}
+/** Normalize a command name for matching: drop a leading slash, lower-case, trim. */
+export function normalizeCommandName(name) {
+    // Collapse "-"→"_" so a command routes the same whether invoked as
+    // /file-issue (Slack/Discord allow hyphens) or /file_issue (Telegram forbids
+    // them; its adapter converts on registration). This is the ROUTING key only —
+    // per-adapter display names are decided in each adapter / `toCommandSpec`.
+    return name.trim().replace(/^\//, "").toLowerCase().replace(/-/g, "_");
+}
+export function toCommandSpec(command) {
+    return {
+        // Preserve hyphens here (display/registration name): Discord and Slack
+        // accept them, so `/file-issue` stays `/file-issue` there. Telegram's
+        // adapter converts hyphens to underscores itself; routing still matches
+        // because `normalizeCommandName` collapses both forms.
+        name: command.name.trim().replace(/^\//, "").toLowerCase(),
+        description: command.description ?? "",
+        options: command.options ? toJsonSchema(command.options) : undefined,
+    };
+}

package/dist/commands.test.d.ts

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

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

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

package/dist/commands.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect } from "vitest";
+import { normalizeCommandName, toCommandSpec, defineBotCommand, } from "./commands.js";
+describe("normalizeCommandName", () => {
+    it("strips a leading slash, lowercases, and collapses hyphens to underscores", () => {
+        expect(normalizeCommandName("/File-Issue")).toBe("file_issue");
+        expect(normalizeCommandName("file-issue")).toBe("file_issue");
+        expect(normalizeCommandName("file_issue")).toBe("file_issue");
+        expect(normalizeCommandName("agent")).toBe("agent");
+    });
+    it("routes /file-issue and /file_issue to the same key (so Telegram's converted name still matches)", () => {
+        expect(normalizeCommandName("file-issue")).toBe(normalizeCommandName("file_issue"));
+    });
+});
+describe("toCommandSpec", () => {
+    it("preserves hyphens in the display name (Slack/Discord allow them)", () => {
+        const cmd = defineBotCommand({
+            name: "file-issue",
+            description: "File an issue",
+            handler: async () => { },
+        });
+        expect(toCommandSpec(cmd).name).toBe("file-issue");
+    });
+});

package/dist/create-bot.d.ts

@@ -0,0 +1,171 @@
+import type { PlatformAdapter, ModalSubmitResult } from "./platform-adapter.js";
+import type { ActionStore } from "./action-store.js";
+import type { StateStore } from "./state/state-store.js";
+import type { BotTool, ContextEntry } from "./tools.js";
+import type { BotCommand, CommandContext } from "./commands.js";
+import { Thread } from "./thread.js";
+import type { AbstractAgent } from "@ag-ui/client";
+import type { InteractionContext, IncomingMessage, PlatformUser, EmojiValue, ComponentFn, MessageRef } from "@copilotkit/channels-ui";
+import { Transcripts } from "./transcripts.js";
+import type { Identity, TranscriptsConfig } from "./transcripts.js";
+import type { StandardSchemaV1, InferSchemaOutput } from "./standard-schema.js";
+export type LockConflictDecision = "drop" | "force";
+/**
+ * Any `@copilotkit/channels-ui` component function, regardless of its props type.
+ * Accepting `(props: never)` lets a component with required, strongly-typed
+ * props (e.g. `({ title }: { title: string }) => …`) be passed to
+ * `createBot({ components })` without a cast — the registry only ever calls it
+ * with the props persisted in the store, so the specific shape isn't needed here.
+ */
+export type BotComponent = (props: never) => ReturnType<ComponentFn>;
+export type BotHandler<TState = unknown> = (ctx: {
+    thread: StatefulThread<TState>;
+    message: IncomingMessage;
+}) => void | Promise<void>;
+/** Handler for a "conversation opened" lifecycle event (e.g. the Slack assistant pane). */
+export type ThreadStartHandler<TState = unknown> = (ctx: {
+    thread: StatefulThread<TState>;
+    user?: PlatformUser;
+}) => void | Promise<void>;
+/** Event passed to an `onReaction` handler. */
+export interface ReactionEvent {
+    /** Normalized name when recognized, else the raw platform token. */
+    emoji: EmojiValue;
+    /** Platform-native token. */
+    rawEmoji: string;
+    /** true = added, false = removed. */
+    added: boolean;
+    /** The reacting user, when the platform reports one. */
+    user?: PlatformUser;
+    messageId: string;
+    /** Update-capable ref to the reacted message (`thread.update(messageRef, ui)`). */
+    messageRef: MessageRef;
+    threadId?: string;
+    thread: Thread;
+    adapter: PlatformAdapter;
+    raw: unknown;
+}
+export type ReactionHandler = (evt: ReactionEvent) => void | Promise<void>;
+/** Event passed to an `onModalSubmit` handler. */
+export interface ModalSubmitEvent {
+    callbackId: string;
+    values: Record<string, unknown>;
+    user?: PlatformUser;
+    /** Present when the submission carried a conversation context. */
+    thread?: Thread;
+    privateMetadata?: string;
+    raw: unknown;
+}
+export type ModalSubmitHandler = (evt: ModalSubmitEvent) => ModalSubmitResult | void | Promise<ModalSubmitResult | void>;
+/** Event passed to an `onModalClose` handler. */
+export interface ModalCloseEvent {
+    callbackId: string;
+    user?: PlatformUser;
+    privateMetadata?: string;
+    raw: unknown;
+}
+export type ModalCloseHandler = (evt: ModalCloseEvent) => void | Promise<void>;
+/** The per-thread state type implied by the configured `store.state` schema. */
+type ThreadStateOf<TSchema extends StandardSchemaV1 | undefined> = TSchema extends StandardSchemaV1 ? InferSchemaOutput<TSchema> : unknown;
+/** A Thread whose state()/setState() are narrowed to the configured state type. */
+export type StatefulThread<TState> = Omit<Thread, "setState" | "state"> & {
+    setState(value: TState): Promise<void>;
+    state(): Promise<TState | undefined>;
+};
+/**
+ * Persistence and per-thread state configuration. Groups the pluggable
+ * backend, optional state schema, transcript storage, and turn-lock/dedup
+ * tuning under a single `store` option.
+ */
+export interface StoreConfig<TStateSchema extends StandardSchemaV1 | undefined = undefined> {
+    /** Pluggable persistence backend. Defaults to in-memory MemoryStore (lost on restart). */
+    adapter?: StateStore;
+    /** Standard Schema for per-thread state. When set, thread.state()/setState() are typed to its output and setState validates at runtime. */
+    state?: TStateSchema;
+    /** Resolve a stable cross-platform identity key (e.g. email). Paired with `transcripts`. */
+    identity?: Identity;
+    /** Cross-platform transcript storage config. Paired with `identity`. */
+    transcripts?: TranscriptsConfig;
+    /** What to do when a turn arrives while a prior turn on the same conversationKey is processing. */
+    onLockConflict?: LockConflictDecision | ((conversationKey: string, message: IncomingMessage) => LockConflictDecision | Promise<LockConflictDecision>);
+    /** TTL (ms) for the per-conversation turn lock. Default 60_000. */
+    lockTtl?: number;
+    /** TTL (ms) for the inbound event dedup window. Default 300_000. */
+    dedupTtl?: number;
+}
+export interface CreateBotOptions<TStateSchema extends StandardSchemaV1 | undefined = undefined> {
+    /**
+     * Project-unique bot identifier. Required for managed (Intelligence-delivered)
+     * bots — it ties the runtime declaration to the Intelligence setup — and
+     * optional for local/custom adapters. Validated by the managed runtime
+     * (`startManagedBots`), not here.
+     */
+    name?: string;
+    /**
+     * Adapters supplied at construction. Optional — adapters can also be attached
+     * before `start()` via {@link Bot.addAdapter} (the managed runtime uses this).
+     */
+    adapters?: PlatformAdapter[];
+    agent?: AbstractAgent | ((threadId: string) => AbstractAgent);
+    /** @deprecated Pass `store.adapter` instead. */
+    actionStore?: ActionStore;
+    tools?: BotTool[];
+    context?: ContextEntry[];
+    /**
+     * Named JSX components used in interactive messages. Registering them here
+     * lets the bot re-render and re-fire their handlers after a restart (durable
+     * actions); without registration, a click on a message posted before the
+     * restart degrades to "action expired".
+     */
+    components?: BotComponent[];
+    /** Slash commands. Forwarded to adapters that support them; ignored elsewhere. */
+    commands?: BotCommand[];
+    /** Persistence, per-thread state schema, transcripts, and lock/dedup tuning. */
+    store?: StoreConfig<TStateSchema>;
+}
+export interface Bot<TState = unknown> {
+    /** Project-unique identifier from `createBot({ name })`; used by the managed runtime. */
+    readonly name?: string;
+    /** Declared slash-command names (normalized). Surfaced for managed activation metadata. */
+    readonly commandNames: string[];
+    onMention(h: BotHandler<TState>): void;
+    onMessage(h: BotHandler<TState>): void;
+    /**
+     * A conversation surface opened (e.g. the Slack assistant pane). Greet, set
+     * suggested prompts, set a title, or run the agent. Adapters without the
+     * concept never fire this.
+     */
+    onThreadStarted(h: ThreadStartHandler<TState>): void;
+    /** Handle clicks on a specific action `id`. `ctx.action.value` is typed as `TValue`. */
+    onInteraction<TValue = unknown>(id: string, h: (ctx: InteractionContext<TValue>) => void | Promise<void>): void;
+    /**
+     * Handle an agent interrupt (an `on_interrupt` custom event). `payload` is the
+     * event's value; pass `TPayload` to type it, e.g.
+     * `onInterrupt<{ question: string }>("ask", ...)`.
+     */
+    onInterrupt<TPayload = unknown>(eventName: string, h: (args: {
+        payload: TPayload;
+        thread: StatefulThread<TState>;
+    }) => void | Promise<void>): void;
+    /** Register a slash command (with optional typed options). */
+    onCommand(command: BotCommand): void;
+    /** Register a free-text slash command by name. */
+    onCommand(name: string, handler: (ctx: CommandContext) => void | Promise<void>): void;
+    /** React to emoji reactions. Pass emoji name(s) for a specific match, or omit for a catch-all. */
+    onReaction(handler: ReactionHandler): void;
+    onReaction(emoji: EmojiValue | EmojiValue[], handler: ReactionHandler): void;
+    /** Handle a modal submission for `callbackId`. Return `{ errors }` to keep it open. */
+    onModalSubmit(callbackId: string, handler: ModalSubmitHandler): void;
+    /** Handle a modal dismissal for `callbackId` (Slack `view_closed`). */
+    onModalClose(callbackId: string, handler: ModalCloseHandler): void;
+    tool(t: BotTool): void;
+    /** Attach an adapter before `start()`. Throws if called after the bot has started. */
+    addAdapter(adapter: PlatformAdapter): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Cross-platform transcript store. Append, list, and delete entries per user. */
+    transcripts: Transcripts;
+}
+export declare function createBot<TStateSchema extends StandardSchemaV1 | undefined = undefined>(opts: CreateBotOptions<TStateSchema>): Bot<ThreadStateOf<TStateSchema>>;
+export {};
+//# sourceMappingURL=create-bot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-bot.d.ts","sourceRoot":"","sources":["../src/create-bot.ts"],"names":[],"mappings":"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"}

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

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

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

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

package/dist/create-bot.foundations.test.js

@@ -0,0 +1,147 @@
+import { describe, it, expect, vi } from "vitest";
+import { createBot } from "./create-bot.js";
+import { FakeAdapter } from "./testing/fake-adapter.js";
+import { FakeAgent } from "./testing/fake-agent.js";
+import { MemoryStore } from "./state/memory-store.js";
+const tick = () => new Promise((r) => setTimeout(r, 0));
+describe("createBot — optional adapters + addAdapter", () => {
+    it("starts with no adapters and runs one added before start()", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ agent: () => new FakeAgent() });
+        bot.addAdapter(fake);
+        await bot.start();
+        expect(fake.started).toBe(true);
+    });
+    it("throws when addAdapter is called after start()", async () => {
+        const bot = createBot({
+            adapters: [new FakeAdapter()],
+            agent: () => new FakeAgent(),
+        });
+        await bot.start();
+        expect(() => bot.addAdapter(new FakeAdapter())).toThrow(/start/i);
+    });
+    it("is idempotent: a second start() does not re-start adapters or rebuild state", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => new FakeAgent(),
+        });
+        const startSpy = vi.spyOn(fake, "start");
+        await bot.start();
+        const transcriptsAfterFirst = bot.transcripts;
+        await bot.start(); // second call must be a no-op
+        expect(startSpy).toHaveBeenCalledTimes(1);
+        // Same transcript-store instance → state (locks/dedup/actions) not wiped.
+        expect(bot.transcripts).toBe(transcriptsAfterFirst);
+    });
+    it("allows a real restart after stop() (start → stop → start re-inits)", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => new FakeAgent(),
+        });
+        const startSpy = vi.spyOn(fake, "start");
+        await bot.start();
+        await bot.stop();
+        await bot.start(); // stop() cleared `started`, so this is a real restart
+        expect(startSpy).toHaveBeenCalledTimes(2);
+    });
+});
+describe("createBot — transcripts deferred to start()", () => {
+    it("throws if bot.transcripts is accessed before start()", () => {
+        const bot = createBot({
+            adapters: [new FakeAdapter()],
+            agent: () => new FakeAgent(),
+            store: {
+                adapter: new MemoryStore(),
+                identity: () => "u@x.com",
+                transcripts: {},
+            },
+        });
+        expect(() => bot.transcripts).toThrow(/start/i);
+    });
+});
+describe("createBot — store resolution", () => {
+    it("uses an adapter-provided stateStore when no explicit store.adapter", async () => {
+        const adapterStore = new MemoryStore();
+        // Seed the adapter's store via a throwaway bot so we can prove the real
+        // bot reads from that exact instance.
+        const seeder = createBot({
+            adapters: [new FakeAdapter()],
+            agent: () => new FakeAgent(),
+            store: {
+                adapter: adapterStore,
+                identity: () => "u@x.com",
+                transcripts: {},
+            },
+        });
+        await seeder.start();
+        await seeder.transcripts.append({ platform: "fake", conversationKey: "c" }, { role: "user", text: "seeded" }, { userKey: "u@x.com" });
+        const fake = new FakeAdapter();
+        fake.stateStore = adapterStore;
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => new FakeAgent(),
+            store: { identity: () => "u@x.com", transcripts: {} },
+        });
+        await bot.start();
+        const entries = await bot.transcripts.list({ userKey: "u@x.com" });
+        expect(entries.map((e) => e.text)).toContain("seeded");
+    });
+    it("explicit store.adapter wins over an adapter-provided one, silently", async () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const fake = new FakeAdapter();
+        fake.stateStore = new MemoryStore();
+        const explicit = new MemoryStore();
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => new FakeAgent(),
+            store: {
+                adapter: explicit,
+                identity: () => "u@x.com",
+                transcripts: {},
+            },
+        });
+        await bot.start();
+        expect(warn).not.toHaveBeenCalled();
+        warn.mockRestore();
+    });
+    it("warns when ≥2 adapters provide a stateStore", async () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const a = new FakeAdapter({ platform: "a" });
+        a.stateStore = new MemoryStore();
+        const b = new FakeAdapter({ platform: "b" });
+        b.stateStore = new MemoryStore();
+        const bot = createBot({
+            adapters: [a, b],
+            agent: () => new FakeAgent(),
+        });
+        await bot.start();
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("state store"));
+        warn.mockRestore();
+    });
+});
+describe("createBot — id propagation to handler context", () => {
+    it("threads turnId/deliveryId from IncomingTurn onto message", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake], agent: () => new FakeAgent() });
+        let seen = {};
+        bot.onMessage(async ({ message }) => {
+            seen = {
+                turnId: message.turnId,
+                deliveryId: message.deliveryId,
+                eventId: message.eventId,
+            };
+        });
+        await bot.start();
+        fake.emitTurn({
+            userText: "hi",
+            conversationKey: "c1",
+            eventId: "e1",
+            turnId: "t1",
+            deliveryId: "d1",
+        });
+        await tick();
+        expect(seen).toEqual({ turnId: "t1", deliveryId: "d1", eventId: "e1" });
+    });
+});