@copilotkit/bot 0.0.1

package/dist/thread.d.ts

@@ -0,0 +1,60 @@
+import type { PlatformAdapter, ReplyTarget } from "./platform-adapter.js";
+import type { ActionRegistry } from "./action-registry.js";
+import type { Renderable, MessageRef, PlatformUser, ThreadMessage, Thread as ThreadInterface } from "@copilotkit/bot-ui";
+import type { BotTool, ContextEntry, AgentToolDescriptor } from "./tools.js";
+import type { AbstractAgent } from "@ag-ui/client";
+export interface ThreadDeps {
+    adapter: PlatformAdapter;
+    replyTarget: ReplyTarget;
+    conversationKey: string;
+    registry: ActionRegistry;
+    agentFactory: (threadId: string) => AbstractAgent;
+    tools: Map<string, BotTool>;
+    toolDescriptors: AgentToolDescriptor[];
+    context: ContextEntry[];
+    registerWaiter: (conversationKey: string, resolve: (value: unknown) => void) => void;
+    interruptHandlers: Map<string, (args: {
+        payload: unknown;
+        thread: Thread;
+    }) => void | Promise<void>>;
+}
+/** A concrete conversation thread: posts UI, runs the agent loop, and resolves HITL waiters. */
+export declare class Thread implements ThreadInterface {
+    private deps;
+    readonly platform: string;
+    constructor(deps: ThreadDeps);
+    private bindForPost;
+    post(ui: Renderable): Promise<MessageRef>;
+    update(ref: MessageRef, ui: Renderable): Promise<MessageRef>;
+    delete(ref: MessageRef): Promise<void>;
+    stream(src: string | AsyncIterable<string>): Promise<MessageRef>;
+    postFile(args: {
+        bytes: Uint8Array;
+        filename: string;
+        title?: string;
+        altText?: string;
+    }): Promise<{
+        ok: boolean;
+        fileId?: string;
+        error?: string;
+    }>;
+    /** Read the conversation's messages (returns `[]` when the adapter can't read history). */
+    getMessages(): Promise<ThreadMessage[]>;
+    /** Resolve a platform user by free-form query (returns `undefined` when unsupported). */
+    lookupUser(query: string): Promise<PlatformUser | undefined>;
+    /** Post a picker and wait until an interaction in this conversation resolves it. */
+    awaitChoice<T = unknown>(ui: Renderable): Promise<T>;
+    runAgent(input?: {
+        context?: ContextEntry[];
+        tools?: BotTool[];
+        /**
+         * A user message to inject before running. Needed when the input isn't
+         * already in the conversation history the adapter reconstructs — e.g. a
+         * slash command, whose args are never posted to the channel.
+         */
+        prompt?: string;
+    }): Promise<MessageRef | undefined>;
+    resume(value: unknown): Promise<MessageRef | undefined>;
+    private run;
+}
+//# sourceMappingURL=thread.d.ts.map

package/dist/thread.d.ts.map

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

package/dist/thread.js

@@ -0,0 +1,109 @@
+import { runAgentLoop } from "./run-loop.js";
+import { toAgentToolDescriptors } from "./tools.js";
+/** A concrete conversation thread: posts UI, runs the agent loop, and resolves HITL waiters. */
+export class Thread {
+    deps;
+    platform;
+    constructor(deps) {
+        this.deps = deps;
+        this.platform = deps.adapter.platform;
+    }
+    async bindForPost(ui) {
+        return this.deps.registry.bindRenderable(ui, this.deps.conversationKey);
+    }
+    async post(ui) {
+        return this.deps.adapter.post(this.deps.replyTarget, await this.bindForPost(ui));
+    }
+    async update(ref, ui) {
+        await this.deps.adapter.update(ref, await this.bindForPost(ui));
+        return ref;
+    }
+    async delete(ref) {
+        await this.deps.adapter.delete(ref);
+    }
+    async stream(src) {
+        const iter = typeof src === "string"
+            ? (async function* () {
+                yield src;
+            })()
+            : src;
+        return this.deps.adapter.stream(this.deps.replyTarget, iter);
+    }
+    async postFile(args) {
+        const adapter = this.deps.adapter;
+        if (!adapter.postFile) {
+            return {
+                ok: false,
+                error: `${this.platform} does not support file upload`,
+            };
+        }
+        return adapter.postFile(this.deps.replyTarget, args);
+    }
+    /** Read the conversation's messages (returns `[]` when the adapter can't read history). */
+    async getMessages() {
+        return (await this.deps.adapter.getMessages?.(this.deps.replyTarget)) ?? [];
+    }
+    /** Resolve a platform user by free-form query (returns `undefined` when unsupported). */
+    async lookupUser(query) {
+        return this.deps.adapter.lookupUser?.({ query });
+    }
+    /** Post a picker and wait until an interaction in this conversation resolves it. */
+    async awaitChoice(ui) {
+        const p = new Promise((resolve) => this.deps.registerWaiter(this.deps.conversationKey, resolve));
+        await this.post(ui);
+        return p;
+    }
+    async runAgent(input) {
+        return this.run(undefined, input);
+    }
+    async resume(value) {
+        return this.run({ resume: value });
+    }
+    async run(initialResume, extra) {
+        const session = await this.deps.adapter.conversationStore.getOrCreate(this.deps.conversationKey, this.deps.replyTarget, this.deps.agentFactory);
+        // Inject an explicit user message when the input isn't in the adapter's
+        // reconstructed history (e.g. a slash command's args).
+        if (extra?.prompt) {
+            session.agent.addMessage({
+                id: globalThis.crypto.randomUUID(),
+                role: "user",
+                content: extra.prompt,
+            });
+        }
+        const renderer = this.deps.adapter.createRunRenderer(this.deps.replyTarget);
+        // Merge per-run context/tools (this run only) on top of the bot-level deps.
+        const extraTools = extra?.tools ?? [];
+        let tools = this.deps.tools;
+        let toolDescriptors = this.deps.toolDescriptors;
+        if (extraTools.length > 0) {
+            tools = new Map(this.deps.tools);
+            for (const t of extraTools)
+                tools.set(t.name, t);
+            toolDescriptors = [
+                ...this.deps.toolDescriptors,
+                ...toAgentToolDescriptors(extraTools),
+            ];
+        }
+        const context = extra?.context?.length
+            ? [...this.deps.context, ...extra.context]
+            : this.deps.context;
+        await runAgentLoop({
+            agent: session.agent,
+            renderer,
+            tools,
+            toolDescriptors,
+            context,
+            makeToolCtx: () => ({
+                thread: this,
+                platform: this.platform,
+            }),
+            handleInterrupt: async (interrupt) => {
+                const h = this.deps.interruptHandlers.get(interrupt.eventName);
+                if (h)
+                    await h({ payload: interrupt.value, thread: this });
+            },
+            initialResume,
+        });
+        return undefined;
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,67 @@
+import type { InferSchemaOutput, ObjectSchema } from "./standard-schema.js";
+import { validateSchema } from "./standard-schema.js";
+import type { Thread, IncomingMessage, PlatformUser } from "@copilotkit/bot-ui";
+export type { ObjectSchema } from "./standard-schema.js";
+export interface BotToolContext {
+    thread: Thread;
+    message?: IncomingMessage;
+    user?: PlatformUser;
+    signal?: AbortSignal;
+    platform: string;
+}
+export type BotTool<Schema extends ObjectSchema = ObjectSchema> = {
+    name: string;
+    description: string;
+    parameters: Schema;
+    /**
+     * Run the tool. The returned value is what the **agent (LLM)** reads back as
+     * the tool result — not the end user.
+     *
+     * Return any value: a `string` is sent to the agent as-is; `null`/`undefined`
+     * becomes an empty string; any other value is JSON-stringified automatically
+     * (see {@link stringifyHandlerResult}). Do NOT hand-stringify and do NOT
+     * return boilerplate like `{ ok: true }`.
+     *
+     * Return something MEANINGFUL to the model:
+     * - a render tool (one that posts a card via `thread.post`) → a short
+     *   natural-language confirmation (e.g. `"Displayed the issue card to the
+     *   user."`) so the model gives a brief ack and doesn't restate the card;
+     * - a failure → the actual error text so the model can repair and retry;
+     * - a data tool → the data itself (return the raw object/array — the SDK
+     *   serializes it for you).
+     */
+    handler(args: InferSchemaOutput<Schema>, ctx: BotToolContext): Promise<unknown> | unknown;
+};
+/**
+ * Define a {@link BotTool} with full type inference. The handler's `args` are
+ * inferred from `parameters`, and `ctx` is the generic {@link BotToolContext}
+ * ({@link Thread} + optional message/user/signal + platform). Reach for
+ * platform power via capability-gated `thread` methods (e.g.
+ * `thread.getMessages()`, `thread.lookupUser(query)`).
+ *
+ * ```ts
+ * const tool = defineBotTool({
+ *   name: "show_thing",
+ *   description: "...",
+ *   parameters: z.object({ id: z.string() }),
+ *   async handler({ id }, { thread }) {  // `id` and `ctx` fully typed
+ *     await thread.post(<Thing id={id} />);
+ *     return "Displayed the thing.";
+ *   },
+ * });
+ * ```
+ */
+export declare function defineBotTool<Schema extends ObjectSchema>(tool: BotTool<Schema>): BotTool<Schema>;
+export interface ContextEntry {
+    description: string;
+    value: string;
+}
+export interface AgentToolDescriptor {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export declare function toAgentToolDescriptors(tools: ReadonlyArray<BotTool>): AgentToolDescriptor[];
+export declare const parseToolArgs: typeof validateSchema;
+export declare function stringifyHandlerResult(value: unknown): string;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAgB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEhF,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,MAAM,OAAO,CAAC,MAAM,SAAS,YAAY,GAAG,YAAY,IAAI;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CACL,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAC/B,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS,YAAY,EACvD,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,GACpB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAC5B,mBAAmB,EAAE,CAMvB;AACD,eAAO,MAAM,aAAa,uBAAiB,CAAC;AAC5C,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI7D"}

package/dist/tools.js

@@ -0,0 +1,38 @@
+import { toJsonSchema, validateSchema } from "./standard-schema.js";
+/**
+ * Define a {@link BotTool} with full type inference. The handler's `args` are
+ * inferred from `parameters`, and `ctx` is the generic {@link BotToolContext}
+ * ({@link Thread} + optional message/user/signal + platform). Reach for
+ * platform power via capability-gated `thread` methods (e.g.
+ * `thread.getMessages()`, `thread.lookupUser(query)`).
+ *
+ * ```ts
+ * const tool = defineBotTool({
+ *   name: "show_thing",
+ *   description: "...",
+ *   parameters: z.object({ id: z.string() }),
+ *   async handler({ id }, { thread }) {  // `id` and `ctx` fully typed
+ *     await thread.post(<Thing id={id} />);
+ *     return "Displayed the thing.";
+ *   },
+ * });
+ * ```
+ */
+export function defineBotTool(tool) {
+    return tool;
+}
+export function toAgentToolDescriptors(tools) {
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: toJsonSchema(t.parameters),
+    }));
+}
+export const parseToolArgs = validateSchema;
+export function stringifyHandlerResult(value) {
+    if (value == null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    return JSON.stringify(value);
+}

package/dist/tools.test.d.ts

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

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

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

package/dist/tools.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { toAgentToolDescriptors, parseToolArgs, stringifyHandlerResult, } from "./tools.js";
+describe("tools", () => {
+    const tool = {
+        name: "t",
+        description: "d",
+        parameters: z.object({ q: z.string() }),
+        handler: () => "ok",
+    };
+    it("emits JSON-schema descriptor", () => {
+        const descriptors = toAgentToolDescriptors([tool]);
+        const d = descriptors[0];
+        if (!d)
+            throw new Error("expected a descriptor");
+        expect(d.name).toBe("t");
+        expect(d.parameters.type).toBe("object");
+    });
+    it("parses valid and rejects invalid args", async () => {
+        expect(await parseToolArgs(tool.parameters, { q: "x" })).toEqual({
+            ok: true,
+            value: { q: "x" },
+        });
+        expect((await parseToolArgs(tool.parameters, {})).ok).toBe(false);
+    });
+    it("stringifies handler results", () => {
+        expect(stringifyHandlerResult("s")).toBe("s");
+        expect(stringifyHandlerResult({ a: 1 })).toBe('{"a":1}');
+        expect(stringifyHandlerResult(undefined)).toBe("");
+    });
+});

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@copilotkit/bot",
+  "version": "0.0.1",
+  "description": "Platform-agnostic JSX bot engine for CopilotKit (createBot, Thread, PlatformAdapter, ActionStore).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CopilotKit/CopilotKit.git"
+  },
+  "homepage": "https://github.com/CopilotKit/CopilotKit",
+  "keywords": [
+    "ai",
+    "agent",
+    "bot",
+    "chatbot",
+    "copilotkit",
+    "slack",
+    "teams",
+    "discord",
+    "ag-ui"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@ag-ui/client": "0.0.53",
+    "@ag-ui/core": "0.0.53",
+    "zod-to-json-schema": "^3.24.1",
+    "@copilotkit/bot-ui": "~0.0.1",
+    "@copilotkit/shared": "^1.59.5",
+    "@copilotkit/core": "^1.59.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.3",
+    "zod": "^3.25.76",
+    "@copilotkit/typescript-config": "^1.55.0-next.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.check.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "publint": "publint .",
+    "attw": "attw --pack . --profile esm-only"
+  }
+}