@copilotkit/bot 0.0.1

package/dist/create-bot.js

@@ -0,0 +1,166 @@
+import { ActionRegistry, ActionExpiredError } from "./action-registry.js";
+import { InMemoryActionStore } from "./action-store.js";
+import { toAgentToolDescriptors, parseToolArgs, } from "./tools.js";
+import { normalizeCommandName, toCommandSpec, } from "./commands.js";
+import { Thread } from "./thread.js";
+export function createBot(opts) {
+    const registry = new ActionRegistry({
+        store: opts.actionStore ?? new InMemoryActionStore(),
+    });
+    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 interactionHandlers = new Map();
+    const interruptHandlers = new Map();
+    const commandHandlers = new Map();
+    for (const c of opts.commands ?? [])
+        commandHandlers.set(normalizeCommandName(c.name), c);
+    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) {
+        const deps = {
+            adapter,
+            replyTarget,
+            conversationKey,
+            registry,
+            agentFactory,
+            tools: toolMap,
+            toolDescriptors,
+            context,
+            registerWaiter: (k, r) => waiters.set(k, r),
+            interruptHandlers,
+        };
+        return new Thread(deps);
+    }
+    function makeSink(adapter) {
+        return {
+            async onTurn(turn) {
+                const thread = makeThread(adapter, turn.replyTarget, turn.conversationKey);
+                const message = {
+                    text: turn.userText,
+                    user: turn.user ?? { id: "" },
+                    ref: { id: "" },
+                    platform: turn.platform,
+                };
+                // 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 });
+            },
+            async onInteraction(evt) {
+                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,
+                };
+                try {
+                    const explicit = interactionHandlers.get(evt.id);
+                    if (explicit) {
+                        await explicit(ctx);
+                    }
+                    else {
+                        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.
+                const w = waiters.get(evt.conversationKey);
+                if (w) {
+                    waiters.delete(evt.conversationKey);
+                    w(evt.value);
+                }
+            },
+            async onCommand(cmd) {
+                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,
+                };
+                await command.handler(ctx);
+            },
+        };
+    }
+    return {
+        onMention(h) {
+            mentionHandlers.push(h);
+        },
+        onMessage(h) {
+            messageHandlers.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);
+        },
+        tool(t) {
+            toolMap.set(t.name, t);
+        },
+        async start() {
+            toolDescriptors = toAgentToolDescriptors([...toolMap.values()]);
+            await Promise.all(opts.adapters.map((a) => a.start(makeSink(a))));
+            // Hand declared commands to adapters that register them up front (e.g.
+            // Discord); adapters without `registerCommands` are skipped.
+            const commandSpecs = [...commandHandlers.values()].map(toCommandSpec);
+            if (commandSpecs.length > 0) {
+                await Promise.all(opts.adapters.map((a) => a.registerCommands?.(commandSpecs)));
+            }
+        },
+        async stop() {
+            await Promise.all(opts.adapters.map((a) => a.stop()));
+        },
+    };
+}

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":""}

package/dist/create-bot.test.js

@@ -0,0 +1,261 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { createBot } from "./create-bot.js";
+import { defineBotCommand } from "./commands.js";
+import { FakeAdapter } from "./testing/fake-adapter.js";
+import { FakeAgent } from "./testing/fake-agent.js";
+import { Section, Actions, Button } from "@copilotkit/bot-ui";
+const tick = () => new Promise((r) => setTimeout(r, 0));
+/**
+ * Compile-time guards for the handler generics (validated by check-types/build,
+ * never executed). `onInterrupt<T>` types `payload`; `onInteraction<T>` types
+ * `ctx.action.value`.
+ */
+const __handlerTypeGuards = () => {
+    const bot = createBot({ adapters: [new FakeAdapter()] });
+    bot.onInterrupt("ask", ({ payload }) => {
+        payload.question.toUpperCase();
+        // @ts-expect-error 'missing' is not on the payload type
+        payload.missing;
+    });
+    bot.onInteraction("next", (ctx) => {
+        ctx.action.value?.page.toFixed(0);
+        // @ts-expect-error 'nope' is not on the action value type
+        ctx.action.value?.nope;
+    });
+};
+void __handlerTypeGuards;
+/** Recursively find the first node of a given type in an IR tree. */
+function findNode(nodes, type) {
+    for (const n of nodes) {
+        if (n.type === type)
+            return n;
+        const children = n.props.children;
+        if (Array.isArray(children)) {
+            const found = findNode(children, type);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+/** Concatenate all text node values in an IR tree. */
+function collectText(nodes) {
+    let out = "";
+    for (const n of nodes) {
+        if (n.type === "text" && typeof n.props.value === "string")
+            out += n.props.value;
+        const children = n.props.children;
+        if (Array.isArray(children))
+            out += collectText(children);
+    }
+    return out;
+}
+describe("createBot", () => {
+    it("routes a mention to a handler that posts UI", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        bot.onMention(async ({ thread }) => {
+            await thread.post(Section({ children: "hi" }));
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "yo", conversationKey: "c1" });
+        await tick();
+        expect(fake.posted.length).toBe(1);
+        const ir = fake.posted[0];
+        expect(findNode(ir, "section")).toBeDefined();
+        expect(collectText(ir)).toBe("hi");
+    });
+    it("dispatches a bound onClick handler on interaction", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        let clicked = false;
+        bot.onMention(async ({ thread }) => {
+            await thread.post(Actions({
+                children: [
+                    Button({
+                        value: { ok: 1 },
+                        onClick: () => {
+                            clicked = true;
+                        },
+                        children: "Go",
+                    }),
+                ],
+            }));
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "yo", conversationKey: "c1" });
+        await tick();
+        const button = findNode(fake.posted[0], "button");
+        const id = button.props.onClick.id;
+        expect(typeof id).toBe("string");
+        fake.emitInteraction({ id, conversationKey: "c1", value: { ok: 1 } });
+        await tick();
+        expect(clicked).toBe(true);
+    });
+    it("merges per-turn runAgent context with the bot-level context", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        // Capture the context/tools passed to the agent's first runAgent call.
+        let seenContext;
+        let seenTools;
+        const origRunAgent = agent.runAgent.bind(agent);
+        agent.runAgent = async (parameters, subscriber) => {
+            if (seenContext === undefined) {
+                seenContext = parameters
+                    ?.context;
+                seenTools = parameters?.tools;
+            }
+            return origRunAgent(parameters, subscriber);
+        };
+        const bot = createBot({
+            adapters: [fake],
+            agent: () => agent,
+            context: [{ description: "bot-level", value: "always here" }],
+        });
+        bot.onMention(async ({ thread }) => {
+            await thread.runAgent({
+                context: [{ description: "who", value: "user U1" }],
+            });
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "go", conversationKey: "c1" });
+        await tick();
+        expect(seenContext).toEqual([
+            { description: "bot-level", value: "always here" },
+            { description: "who", value: "user U1" },
+        ]);
+        expect(seenTools).toEqual([]);
+    });
+    it("thread.postFile returns a capability-gated error when the adapter can't upload", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        let result;
+        bot.onMention(async ({ thread }) => {
+            result = await thread.postFile({
+                bytes: new Uint8Array([1, 2, 3]),
+                filename: "x.png",
+            });
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "hi", conversationKey: "c1" });
+        await tick();
+        expect(result).toEqual({
+            ok: false,
+            error: "fake does not support file upload",
+        });
+    });
+    it("thread.getMessages and thread.lookupUser surface the adapter's data", async () => {
+        const fake = new FakeAdapter();
+        fake.messages = [
+            { user: { id: "u1", name: "Ada" }, text: "hi", ts: "1", isBot: false },
+        ];
+        fake.user = { id: "u1", name: "Ada" };
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        let history;
+        let resolved;
+        bot.onMention(async ({ thread }) => {
+            history = await thread.getMessages();
+            resolved = await thread.lookupUser("Ada");
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "hi", conversationKey: "c1" });
+        await tick();
+        expect(history).toEqual([
+            { user: { id: "u1", name: "Ada" }, text: "hi", ts: "1", isBot: false },
+        ]);
+        expect(resolved).toEqual({ id: "u1", name: "Ada" });
+    });
+    it("resolves awaitChoice when a matching interaction arrives", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        let choicePromise;
+        bot.onMention(async ({ thread }) => {
+            choicePromise = thread.awaitChoice(Actions({
+                children: [
+                    Button({
+                        value: { confirmed: true },
+                        onClick: () => { },
+                        children: "Confirm",
+                    }),
+                ],
+            }));
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "decide", conversationKey: "c1" });
+        await tick();
+        const button = findNode(fake.posted[0], "button");
+        const id = button.props.onClick.id;
+        fake.emitInteraction({
+            id,
+            conversationKey: "c1",
+            value: { confirmed: true },
+        });
+        await tick();
+        expect(choicePromise).toBeDefined();
+        await expect(choicePromise).resolves.toEqual({ confirmed: true });
+    });
+});
+describe("createBot slash commands", () => {
+    it("routes a command to its handler with the raw text", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        let seen;
+        bot.onCommand("triage", ({ command, text }) => {
+            seen = { command, text };
+        });
+        await bot.start();
+        await fake.emitCommand({ command: "/Triage", text: "db is down" });
+        expect(seen).toEqual({ command: "triage", text: "db is down" });
+    });
+    it("ignores a command with no registered handler", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        let fired = false;
+        bot.onCommand("triage", () => {
+            fired = true;
+        });
+        await bot.start();
+        await fake.emitCommand({ command: "unknown", text: "x" });
+        expect(fired).toBe(false);
+    });
+    it("parses rawOptions through the command's schema into ctx.options", async () => {
+        let captured;
+        const fake = new FakeAdapter();
+        const bot = createBot({
+            adapters: [fake],
+            commands: [
+                defineBotCommand({
+                    name: "book",
+                    options: z.object({ seat: z.string() }),
+                    handler: ({ options }) => {
+                        captured = options; // typed { seat: string }
+                    },
+                }),
+            ],
+        });
+        await bot.start();
+        await fake.emitCommand({
+            command: "book",
+            text: "raw",
+            rawOptions: { seat: "12A" },
+        });
+        expect(captured).toEqual({ seat: "12A" });
+    });
+    it("hands declared commands to adapters that implement registerCommands", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        bot.onCommand("triage", () => { });
+        bot.onCommand("status", () => { });
+        await bot.start();
+        expect(fake.registeredCommands?.map((c) => c.name).sort()).toEqual([
+            "status",
+            "triage",
+        ]);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { createBot } from "./create-bot.js";
+export type { Bot, CreateBotOptions, BotHandler } from "./create-bot.js";
+export { Thread } from "./thread.js";
+export type { ThreadDeps } from "./thread.js";
+export type { PlatformAdapter, RunRenderer, IngressSink, IncomingTurn, InteractionEvent, IncomingCommand, SurfaceCapabilities, ReplyTarget, ConversationStore, AgentSession, CapturedToolCall, CapturedInterrupt, UserQuery, NativePayload, } from "./platform-adapter.js";
+export { defineBotCommand, normalizeCommandName, toCommandSpec, } from "./commands.js";
+export type { BotCommand, 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 { toAgentToolDescriptors, parseToolArgs, stringifyHandlerResult, defineBotTool, } from "./tools.js";
+export type { BotTool, ObjectSchema, BotToolContext, 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 * from "@copilotkit/bot-ui";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,GAAG,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGzE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,YAAY,EACV,eAAe,EACf,WAAW,EACX,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,aAAa,GACd,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGrE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1E,OAAO,EACL,sBAAsB,EACtB,aAAa,EACb,sBAAsB,EACtB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,OAAO,EACP,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+// Public API for @copilotkit/bot.
+// Bot orchestration
+export { createBot } from "./create-bot.js";
+// Thread
+export { Thread } from "./thread.js";
+// Slash commands
+export { defineBotCommand, normalizeCommandName, toCommandSpec, } from "./commands.js";
+// Action store
+export { InMemoryActionStore } from "./action-store.js";
+// Action registry
+export { ActionRegistry, ActionExpiredError } from "./action-registry.js";
+// Tools & context
+export { toAgentToolDescriptors, parseToolArgs, stringifyHandlerResult, defineBotTool, } from "./tools.js";
+// Id / serialization helpers
+export { mintId, stableStringify } from "./mint-id.js";
+// Run loop
+export { runAgentLoop } from "./run-loop.js";
+// Re-export the bot-ui component vocabulary + types for convenience.
+export * from "@copilotkit/bot-ui";

package/dist/mint-id.d.ts

@@ -0,0 +1,3 @@
+export declare function stableStringify(v: unknown): string;
+export declare function mintId(componentName: string, path: (string | number)[], props: unknown): string;
+//# sourceMappingURL=mint-id.d.ts.map

package/dist/mint-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mint-id.d.ts","sourceRoot":"","sources":["../src/mint-id.ts"],"names":[],"mappings":"AAEA,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAYlD;AAED,wBAAgB,MAAM,CACpB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACzB,KAAK,EAAE,OAAO,GACb,MAAM,CAKR"}

package/dist/mint-id.js

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto";
+export function stableStringify(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v) ?? "null";
+    if (Array.isArray(v))
+        return "[" + v.map(stableStringify).join(",") + "]";
+    const obj = v;
+    const keys = Object.keys(obj).sort();
+    return ("{" +
+        keys
+            .map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k]))
+            .join(",") +
+        "}");
+}
+export function mintId(componentName, path, props) {
+    const h = createHash("sha1")
+        .update(`${componentName}|${path.join(".")}|${stableStringify(props)}`)
+        .digest("hex");
+    return "ck:" + h.slice(0, 16);
+}

package/dist/mint-id.test.d.ts

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

package/dist/mint-id.test.d.ts.map

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

package/dist/mint-id.test.js

@@ -0,0 +1,16 @@
+import { describe, it, expect } from "vitest";
+import { mintId, stableStringify } from "./mint-id.js";
+describe("mintId", () => {
+    it("is content-stable for same component/path/props", () => {
+        const a = mintId("Flight", [0, "onClick"], { id: "f1" });
+        const b = mintId("Flight", [0, "onClick"], { id: "f1" });
+        expect(a).toBe(b);
+        expect(a.startsWith("ck:")).toBe(true);
+    });
+    it("differs when props differ", () => {
+        expect(mintId("Flight", [0], { id: "f1" })).not.toBe(mintId("Flight", [0], { id: "f2" }));
+    });
+    it("stableStringify sorts keys", () => {
+        expect(stableStringify({ b: 1, a: 2 })).toBe(stableStringify({ a: 2, b: 1 }));
+    });
+});

package/dist/platform-adapter.d.ts

@@ -0,0 +1,125 @@
+import type { AgentSubscriber, AbstractAgent } from "@ag-ui/client";
+import type { BotNode, MessageRef, PlatformUser, ThreadMessage } from "@copilotkit/bot-ui";
+import type { CommandSpec } from "./commands.js";
+/** Opaque to the bot core — created by an adapter during ingress and passed back to post/createRunRenderer. */
+export type ReplyTarget = unknown;
+/** Opaque native payload produced by an adapter's render(). */
+export type NativePayload = unknown;
+export interface SurfaceCapabilities {
+    supportsModals: boolean;
+    supportsTyping: boolean;
+    supportsReactions: boolean;
+    supportsStreaming: boolean;
+    maxBlocksPerMessage?: number;
+    [k: string]: unknown;
+}
+export interface CapturedToolCall {
+    toolCallId: string;
+    toolCallName: string;
+    toolCallArgs: Record<string, unknown>;
+}
+export interface CapturedInterrupt {
+    eventName: string;
+    value: unknown;
+}
+/** A per-run handle: the AG-UI subscriber to stream into, plus capture accessors the run-loop reads after each runAgent. */
+export interface RunRenderer {
+    subscriber: AgentSubscriber;
+    markInterrupted(): Promise<void>;
+    getCapturedToolCalls(): readonly CapturedToolCall[];
+    getPendingInterrupt(): CapturedInterrupt | undefined;
+    clearPendingInterrupt(): void;
+}
+export interface IncomingTurn {
+    conversationKey: string;
+    replyTarget: ReplyTarget;
+    userText: string;
+    user?: PlatformUser;
+    platform: string;
+}
+export interface InteractionEvent {
+    id: string;
+    conversationKey: string;
+    replyTarget: ReplyTarget;
+    value?: unknown;
+    user?: PlatformUser;
+    /** The message the interaction occurred on (the picker), so handlers can update it in place. */
+    messageRef?: MessageRef;
+}
+/** A slash-command invocation normalized by an adapter. */
+export interface IncomingCommand {
+    /** Command name as invoked (a leading slash and case are normalized by the engine). */
+    command: string;
+    /** Raw argument string after the command name (the form text-only surfaces deliver). */
+    text: string;
+    /** Structured, pre-parsed options when the surface delivers them (e.g. Discord). */
+    rawOptions?: Record<string, unknown>;
+    conversationKey: string;
+    replyTarget: ReplyTarget;
+    user?: PlatformUser;
+    platform: string;
+}
+export interface IngressSink {
+    onTurn(turn: IncomingTurn): void | Promise<void>;
+    onInteraction(evt: InteractionEvent): void | Promise<void>;
+    /** A slash command fired. Routed to the matching `bot.onCommand` handler (ignored if none). */
+    onCommand(cmd: IncomingCommand): void | Promise<void>;
+}
+export interface UserQuery {
+    query: string;
+}
+/** A resolved agent session for a conversation (the adapter may build the agent's history from its own state). */
+export interface AgentSession {
+    agent: AbstractAgent;
+}
+/** Adapter-owned conversation state; the adapter resolves (or creates) the agent session for a conversation. */
+export interface ConversationStore {
+    getOrCreate(conversationKey: string, replyTarget: ReplyTarget, makeAgent: (threadId: string) => AbstractAgent): Promise<AgentSession>;
+}
+export interface PlatformAdapter {
+    readonly platform: string;
+    readonly capabilities: SurfaceCapabilities;
+    readonly ackDeadlineMs: number;
+    start(sink: IngressSink): Promise<void>;
+    stop(): Promise<void>;
+    render(ir: BotNode[]): NativePayload;
+    post(target: ReplyTarget, ir: BotNode[]): Promise<MessageRef>;
+    update(ref: MessageRef, ir: BotNode[]): Promise<void>;
+    stream(target: ReplyTarget, chunks: AsyncIterable<string>): Promise<MessageRef>;
+    delete(ref: MessageRef): Promise<void>;
+    createRunRenderer(target: ReplyTarget): RunRenderer;
+    decodeInteraction(raw: unknown): InteractionEvent | undefined;
+    lookupUser(q: UserQuery): Promise<PlatformUser | undefined>;
+    readonly conversationStore: ConversationStore;
+    /**
+     * Optional conversation-history read. Backs the capability-gated
+     * `Thread.getMessages()`; adapters that can't read history simply omit this,
+     * and `Thread.getMessages()` returns `[]`.
+     */
+    getMessages?(target: ReplyTarget): Promise<ThreadMessage[]>;
+    /**
+     * Optional platform file upload. Threads expose `postFile` unconditionally;
+     * adapters that can't upload simply omit this, and `Thread.postFile` returns
+     * a capability-gated `{ ok: false, error }`.
+     */
+    postFile?(target: ReplyTarget, args: {
+        bytes: Uint8Array;
+        filename: string;
+        title?: string;
+        altText?: string;
+    }): Promise<{
+        ok: boolean;
+        fileId?: string;
+        error?: string;
+    }>;
+    /**
+     * Optional slash-command support. Called once on `start()` with the bot's
+     * declared commands, so a surface that registers commands up front (e.g.
+     * Discord's application-command API) can publish them. Surfaces that match
+     * commands dynamically (e.g. Slack, which forwards every `/command` to
+     * `sink.onCommand`) need not implement this; adapters that don't support
+     * commands at all simply omit it and command handlers never fire there.
+     */
+    registerCommands?(commands: readonly CommandSpec[]): void | Promise<void>;
+}
+//# sourceMappingURL=platform-adapter.d.ts.map

package/dist/platform-adapter.d.ts.map

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

package/dist/platform-adapter.js

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