@copilotkit/bot 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Atai Barkai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# @copilotkit/bot
+
+The **platform-agnostic bot engine**. It owns everything between an incoming
+message and a rendered reply — handler registration, the agent
+run/tool/interrupt loop, JSX action binding, and the `PlatformAdapter`
+contract — without knowing anything about Slack (or any other surface). A
+platform adapter plugs in at the boundary; `@copilotkit/bot-slack` is the
+concrete Slack one.
+
+It builds on `@copilotkit/bot-ui` (the JSX runtime + component vocabulary,
+re-exported from here for convenience) and AG-UI (`@ag-ui/client`,
+`@ag-ui/core`).
+
+## Install
+
+```sh
+pnpm add @copilotkit/bot @copilotkit/bot-ui
+# plus a platform adapter, e.g.
+pnpm add @copilotkit/bot-slack
+```
+
+## Quickstart
+
+```ts
+import { createBot } from "@copilotkit/bot";
+import { slack } from "@copilotkit/bot-slack"; // a concrete PlatformAdapter
+
+const bot = createBot({
+  adapters: [slack({ botToken, appToken })],
+  agent: (threadId) => makeAgent(threadId), // AbstractAgent or (threadId) => AbstractAgent
+  tools: [...myTools], // BotTool[] forwarded on every runAgent
+  context: [...myContext], // ContextEntry[] forwarded on every runAgent
+});
+
+bot.onMention(({ thread }) => thread.runAgent());
+bot.onMessage(({ thread }) => thread.runAgent());
+
+await bot.start();
+```
+
+`createBot(opts)` returns a `Bot`:
+
+- `onMention(handler)` / `onMessage(handler)` — turn handlers receiving
+  `{ thread, message }`. (Routing is mention-preferred: if any mention
+  handler is registered, all turns route to it; otherwise message handlers
+  fire.)
+- `onInteraction<TValue>(id, handler)` — explicit escape-hatch handler for a
+  known action id, bypassing the registry; `ctx.action.value` is typed `TValue`.
+- `onInterrupt<TPayload>(eventName, handler)` — handle a captured agent
+  interrupt (LangGraph-style `on_interrupt`); receives `{ payload, thread }`
+  with `payload` typed `TPayload`.
+- `onCommand(command)` / `onCommand(name, handler)` — register a slash command.
+  The handler gets `{ thread, command, text, options, user }`. `text` is the
+  raw args (Slack); `options` is the typed, parsed form (`defineBotCommand`
+  with an `options` Standard Schema) for surfaces with native structured args
+  (e.g. Discord). Forwarded to adapters that support commands and ignored
+  elsewhere — also pass them up front via `commands` in `CreateBotOptions`.
+- `tool(t)` — register a `BotTool` (alternative to `opts.tools`); must be
+  added before `start()`.
+- `start()` / `stop()` — bring adapters up / down.
+
+`agent` is optional. If omitted, calling `thread.runAgent()` throws; supply
+an `AbstractAgent` or a `(threadId) => AbstractAgent` factory.
+
+## `Thread`
+
+A `Thread` is the per-conversation handle handed to your handlers and tool
+contexts. It accepts any `Renderable` (JSX or a string) for posting.
+
+```ts
+interface Thread {
+  readonly platform: string;
+  post(ui: Renderable): Promise<MessageRef>;
+  update(ref: MessageRef, ui: Renderable): Promise<MessageRef>;
+  delete(ref: MessageRef): Promise<void>;
+  stream(src: string | AsyncIterable<string>): Promise<MessageRef>;
+  runAgent(input?: {
+    context?: ContextEntry[];
+    tools?: BotTool[];
+  }): Promise<MessageRef | undefined>;
+  resume(value: unknown): Promise<MessageRef | undefined>;
+  awaitChoice<T = unknown>(ui: Renderable): Promise<T>;
+}
+```
+
+- `post` / `update` render the JSX to IR, **bind** every event-prop handler
+  in the tree (mint a content-stable id, snapshot it, rewrite the prop to
+  `{ id }`), then hand the IR to the adapter.
+- `runAgent` resolves the conversation's agent session, creates the adapter's
+  `RunRenderer`, and drives the run/tool/interrupt loop. Per-run `tools` /
+  `context` are merged on top of the bot-level defaults for that run only.
+- `resume(value)` re-enters a paused interrupt run with
+  `forwardedProps.command`.
+- `awaitChoice<T>(ui)` posts a picker and blocks until an interaction in this
+  conversation resolves it to the clicked control's value (HITL); pass `T` to
+  type the returned value.
+
+## Tools & context
+
+A `BotTool` is forwarded to the agent as a frontend tool; its handler runs in
+the bot when the agent calls it. The handler `ctx` carries the `thread`, so a
+tool can render JSX (`ctx.thread.post(<Card .../>)`) or run the agent further.
+
+```ts
+interface BotTool<Schema extends ObjectSchema = ObjectSchema> {
+  name: string;
+  description: string;
+  parameters: Schema; // any Standard Schema (Zod/Valibot/ArkType/…)
+  handler(args, ctx: BotToolContext): Promise<unknown> | unknown;
+}
+```
+
+Define one with the non-curried `defineBotTool`, which infers the arg types
+from `parameters`:
+
+```ts
+defineBotTool({
+  name: "read_thread",
+  description: "Read the messages in the current conversation.",
+  parameters: z.object({}),
+  async handler(_args, { thread }) {
+    return await thread.getMessages();
+  },
+});
+```
+
+`parameters` (a Standard Schema) is converted to JSON Schema for the LLM and
+validated on the way back. `BotToolContext` is `{ thread, message?, user?,
+signal?, platform }` — a single shared type with no per-adapter generic.
+Platform-specific power is reached only through capability-gated `thread`
+methods (e.g. `thread.getMessages()`, `thread.lookupUser(query)`,
+`thread.postFile(...)`), so a tool stays portable across surfaces.
+
+A `ContextEntry` is `{ description: string; value: string }` — knowledge
+folded into the agent's system context on each `runAgent`.
+
+## ActionStore
+
+Inline JSX handlers are bound by content. Each interactive node gets a
+**content-stable, opaque** minted id — `mintId(componentName, path, props)`
+= `"ck:" + sha1(name | path | stableStringify(props)).slice(0,16)`. Only the
+opaque id (plus any small `bind()` args) is stamped on the native token; no
+props, PII, or secrets go over the wire.
+
+On a click, the `ActionRegistry` resolves the handler from a hot in-memory
+cache; on a miss it **rehydrates** by loading the snapshot from the
+`ActionStore`, re-rendering the named component with the frozen props, and
+re-walking to the handler's path.
+
+The default `ActionStore` is `InMemoryActionStore` (a `Map` with optional
+TTL). It is lost on restart: after a restart an old button click degrades to
+an `ActionExpiredError` ("this action expired"), which `createBot` swallows.
+**Durable actions require an external store (Redis / DB) — not shipped in
+v1.** Implement the `ActionStore` interface (`put` / `get` / `delete`) and
+pass it as `actionStore` to make actions survive restarts.
+
+## Writing a `PlatformAdapter`
+
+To target a new surface, implement `PlatformAdapter` from this package. The
+engine drives ingress through the `IngressSink` you receive in `start(sink)`
+(`sink.onTurn(IncomingTurn)` / `sink.onInteraction(InteractionEvent)`) and
+egress through your `post` / `update` / `stream` / `delete` (which receive
+`BotNode[]` to translate to a native payload via `render`). You also provide
+`createRunRenderer(target)` (an AG-UI `RunRenderer`: the subscriber to stream
+into, plus accessors for captured tool calls and interrupts that the run-loop
+reads after each `runAgent`), `decodeInteraction(raw)` (native event → opaque
+`InteractionEvent`), `lookupUser`, a `conversationStore`
+(`getOrCreate` → `AgentSession`), and the surface `capabilities` /
+`ackDeadlineMs`. Optional capability methods like `getMessages(target)` and
+`postFile(target, args)` back the matching `thread` methods when the surface
+supports them. Slash commands are also capability-gated: an adapter forwards
+invocations via `sink.onCommand(IncomingCommand)`, and may implement
+`registerCommands(specs)` to publish the bot's declared commands up front
+(e.g. Discord's application-command API); adapters that omit it are skipped.
+See `@copilotkit/bot-slack` for a complete implementation.
+
+## Exports
+
+`createBot`, `Bot`, `CreateBotOptions`, `BotHandler`; `Thread`; the
+`PlatformAdapter` boundary types (`RunRenderer`, `IngressSink`,
+`IncomingTurn`, `InteractionEvent`, `IncomingCommand`, `SurfaceCapabilities`,
+`ReplyTarget`, `ConversationStore`, `AgentSession`, `CapturedToolCall`,
+`CapturedInterrupt`, `UserQuery`); `ActionStore` / `InMemoryActionStore` /
+`ActionSnapshot` / `ActionRegistry` / `ActionExpiredError`; `BotTool` /
+`BotToolContext` / `defineBotTool` / `BotCommand` / `CommandContext` /
+`CommandSpec` / `defineBotCommand` / `ContextEntry` /
+`AgentToolDescriptor` / `ObjectSchema` and the tool helpers
+(`toAgentToolDescriptors`, `parseToolArgs`, `stringifyHandlerResult`);
+`mintId` / `stableStringify`; `runAgentLoop`; plus the re-exported
+`@copilotkit/bot-ui` vocabulary.

package/dist/action-registry.d.ts

@@ -0,0 +1,20 @@
+import type { BotNode, InteractionContext, ComponentFn, Renderable } from "@copilotkit/bot-ui";
+import type { ActionStore } from "./action-store.js";
+export declare class ActionExpiredError extends Error {
+    constructor(id: string);
+}
+export declare class ActionRegistry {
+    private store;
+    private components;
+    private hot;
+    constructor(opts: {
+        store: ActionStore;
+    });
+    registerComponent(name: string, fn: ComponentFn): void;
+    clearHotCache(): void;
+    bindTree(componentName: string, props: Record<string, unknown>, conversationKey: string): Promise<BotNode[]>;
+    bindRenderable(ui: Renderable, conversationKey: string): Promise<BotNode[]>;
+    private walk;
+    dispatch(id: string, ctx: InteractionContext): Promise<unknown>;
+}
+//# sourceMappingURL=action-registry.d.ts.map

package/dist/action-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-registry.d.ts","sourceRoot":"","sources":["../src/action-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EAEP,kBAAkB,EAClB,WAAW,EACX,UAAU,EACX,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,EAAE,EAAE,MAAM;CAIvB;AAcD,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,GAAG,CAAmC;gBAElC,IAAI,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE;IAIxC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI;IAItD,aAAa,IAAI,IAAI;IAMf,QAAQ,CACZ,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,OAAO,EAAE,CAAC;IAYf,cAAc,CAClB,EAAE,EAAE,UAAU,EACd,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,OAAO,EAAE,CAAC;YAgBP,IAAI;IAuCZ,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;CAetE"}

package/dist/action-registry.js

@@ -0,0 +1,109 @@
+import { isBound, getBoundArgs, renderToIR } from "@copilotkit/bot-ui";
+import { mintId } from "./mint-id.js";
+export class ActionExpiredError extends Error {
+    constructor(id) {
+        super(`Action "${id}" has expired or is no longer available.`);
+        this.name = "ActionExpiredError";
+    }
+}
+const EVENT_PROPS = ["onClick", "onSelect", "onSubmit"];
+function isComponentElement(ui) {
+    return (typeof ui === "object" &&
+        ui !== null &&
+        typeof ui.type === "function");
+}
+export class ActionRegistry {
+    store;
+    components = new Map();
+    hot = new Map();
+    constructor(opts) {
+        this.store = opts.store;
+    }
+    registerComponent(name, fn) {
+        this.components.set(name, fn);
+    }
+    clearHotCache() {
+        this.hot.clear();
+    }
+    // Renders the named component, binds all event-prop handlers in the tree
+    // (mint id, hot-cache + ActionStore snapshot, rewrite prop to { id }), returns the bound IR.
+    async bindTree(componentName, props, conversationKey) {
+        const fn = this.components.get(componentName);
+        const root = renderToIR((fn ? fn(props) : props));
+        await this.walk(root, [], componentName, props, conversationKey);
+        return root;
+    }
+    // Binds an arbitrary Renderable for posting. If `ui` is a component element
+    // (`{ type: fn, props }`), it is registered + bound by name (cold-path
+    // re-render supported). Otherwise the IR is bound inline with `component:""`,
+    // meaning a cold-cache dispatch throws ActionExpiredError (intended
+    // degradation for inline handlers that can't be re-derived).
+    async bindRenderable(ui, conversationKey) {
+        if (isComponentElement(ui)) {
+            const fn = ui.type;
+            const name = fn.name || "anonymous";
+            this.registerComponent(name, fn);
+            return this.bindTree(name, (ui.props ?? {}), conversationKey);
+        }
+        const root = renderToIR(ui);
+        await this.walk(root, [], "", undefined, conversationKey);
+        return root;
+    }
+    async walk(nodes, base, comp, props, conv) {
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i];
+            const path = [...base, i];
+            for (const ep of EVENT_PROPS) {
+                const handler = node.props[ep];
+                if (typeof handler === "function") {
+                    const fullPath = [...path, ep];
+                    const id = mintId(comp, fullPath, props);
+                    this.hot.set(id, handler);
+                    await this.store.put(id, {
+                        component: comp,
+                        props,
+                        path: fullPath,
+                        conversationKey: conv,
+                        boundArgs: isBound(handler) ? getBoundArgs(handler) : undefined,
+                    });
+                    node.props[ep] = { id };
+                }
+            }
+            const children = node.props.children;
+            if (Array.isArray(children)) {
+                await this.walk(children, [...path, "children"], comp, props, conv);
+            }
+        }
+    }
+    async dispatch(id, ctx) {
+        let handler = this.hot.get(id);
+        if (!handler) {
+            const snap = await this.store.get(id);
+            if (!snap || !snap.component)
+                throw new ActionExpiredError(id);
+            const fn = this.components.get(snap.component);
+            if (!fn)
+                throw new ActionExpiredError(id);
+            const tree = renderToIR(fn(snap.props));
+            handler = pluck(tree, snap.path);
+            if (!handler)
+                throw new ActionExpiredError(id);
+        }
+        return handler({ ...ctx, action: { ...ctx.action, id } });
+    }
+}
+function pluck(tree, path) {
+    let cur = tree;
+    for (const seg of path.slice(0, -1)) {
+        if (Array.isArray(cur))
+            cur = cur[seg];
+        else if (cur && typeof cur === "object")
+            cur = cur.props?.[seg];
+        else
+            return undefined;
+    }
+    const ep = path[path.length - 1];
+    const node = cur;
+    const h = node?.props?.[ep];
+    return typeof h === "function" ? h : undefined;
+}

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

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

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

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

package/dist/action-registry.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { ActionRegistry, ActionExpiredError } from "./action-registry.js";
+import { InMemoryActionStore } from "./action-store.js";
+function Confirm(props) {
+    return {
+        type: "actions",
+        props: {
+            children: [
+                {
+                    type: "button",
+                    props: {
+                        onClick: ({ action }) => `ok:${props.action}:${action.id}`,
+                        children: "Yes",
+                    },
+                },
+            ],
+        },
+    };
+}
+const ctx = {};
+describe("ActionRegistry", () => {
+    it("binds onClick handlers and dispatches via hot cache", async () => {
+        const reg = new ActionRegistry({ store: new InMemoryActionStore() });
+        reg.registerComponent("Confirm", Confirm);
+        const ir = await reg.bindTree("Confirm", { action: "write" }, "conv1");
+        const button = ir[0].props.children[0];
+        const id = button.props.onClick.id;
+        expect(typeof id).toBe("string");
+        const out = await reg.dispatch(id, ctx);
+        expect(out).toContain("ok:write:");
+    });
+    it("cold path re-renders from snapshot when hot cache is cleared", async () => {
+        const reg = new ActionRegistry({ store: new InMemoryActionStore() });
+        reg.registerComponent("Confirm", Confirm);
+        const ir = await reg.bindTree("Confirm", { action: "write" }, "conv1");
+        const id = ir[0].props.children[0].props.onClick.id;
+        reg.clearHotCache();
+        const out = await reg.dispatch(id, ctx);
+        expect(out).toContain("ok:write:");
+    });
+    it("throws ActionExpiredError on full miss", async () => {
+        const reg = new ActionRegistry({ store: new InMemoryActionStore() });
+        await expect(reg.dispatch("ck:missing", ctx)).rejects.toBeInstanceOf(ActionExpiredError);
+    });
+});

package/dist/action-store.d.ts

@@ -0,0 +1,19 @@
+export interface ActionSnapshot {
+    component?: string;
+    props?: unknown;
+    path: (string | number)[];
+    boundArgs?: unknown;
+    conversationKey: string;
+}
+export interface ActionStore {
+    put(id: string, snap: ActionSnapshot, ttlMs?: number): Promise<void>;
+    get(id: string): Promise<ActionSnapshot | undefined>;
+    delete(id: string): Promise<void>;
+}
+export declare class InMemoryActionStore implements ActionStore {
+    private map;
+    put(id: string, snap: ActionSnapshot, ttlMs?: number): Promise<void>;
+    get(id: string): Promise<ActionSnapshot | undefined>;
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=action-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action-store.d.ts","sourceRoot":"","sources":["../src/action-store.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AACD,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AACD,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,GAAG,CAAmE;IACxE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IASpD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}

package/dist/action-store.js

@@ -0,0 +1,22 @@
+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/commands.d.ts

@@ -0,0 +1,68 @@
+import type { InferSchemaOutput, ObjectSchema } from "./standard-schema.js";
+import type { Thread, PlatformUser } from "@copilotkit/bot-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;
+}
+/**
+ * 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,MAAM,oBAAoB,CAAC;AAE/D;;;;;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;CAClB;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,CAEzD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,WAAW,CAM9D"}

package/dist/commands.js

@@ -0,0 +1,30 @@
+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) {
+    return name.trim().replace(/^\//, "").toLowerCase();
+}
+export function toCommandSpec(command) {
+    return {
+        name: normalizeCommandName(command.name),
+        description: command.description ?? "",
+        options: command.options ? toJsonSchema(command.options) : undefined,
+    };
+}

package/dist/create-bot.d.ts

@@ -0,0 +1,44 @@
+import type { PlatformAdapter } from "./platform-adapter.js";
+import { type ActionStore } from "./action-store.js";
+import { type BotTool, type ContextEntry } from "./tools.js";
+import { type BotCommand, type CommandContext } from "./commands.js";
+import { Thread } from "./thread.js";
+import type { AbstractAgent } from "@ag-ui/client";
+import type { InteractionContext, IncomingMessage } from "@copilotkit/bot-ui";
+export type BotHandler = (ctx: {
+    thread: Thread;
+    message: IncomingMessage;
+}) => void | Promise<void>;
+export interface CreateBotOptions {
+    adapters: PlatformAdapter[];
+    agent?: AbstractAgent | ((threadId: string) => AbstractAgent);
+    actionStore?: ActionStore;
+    tools?: BotTool[];
+    context?: ContextEntry[];
+    /** Slash commands. Forwarded to adapters that support them; ignored elsewhere. */
+    commands?: BotCommand[];
+}
+export interface Bot {
+    onMention(h: BotHandler): void;
+    onMessage(h: BotHandler): 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: Thread;
+    }) => 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;
+    tool(t: BotTool): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function createBot(opts: CreateBotOptions): Bot;
+//# 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":"AAAA,OAAO,KAAK,EACV,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAGL,KAAK,OAAO,EACZ,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,MAAM,EAAmB,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE9E,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,CAAC;CAC1B,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3B,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,aAAa,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,aAAa,CAAC,CAAC;IAC9D,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,GAAG;IAClB,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,wFAAwF;IACxF,aAAa,CAAC,MAAM,GAAG,OAAO,EAC5B,EAAE,EAAE,MAAM,EACV,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC3D,IAAI,CAAC;IACR;;;;OAIG;IACH,WAAW,CAAC,QAAQ,GAAG,OAAO,EAC5B,SAAS,EAAE,MAAM,EACjB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACvE,IAAI,CAAC;IACR,8DAA8D;IAC9D,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IACrC,kDAAkD;IAClD,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACrD,IAAI,CAAC;IACR,IAAI,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,GAAG,CA6MrD"}