@copilotkit/bot 0.0.1 → 0.0.3

package/README.md

@@ -44,6 +44,9 @@ await bot.start();
   `{ thread, message }`. (Routing is mention-preferred: if any mention
   handler is registered, all turns route to it; otherwise message handlers
   fire.)
+- `onThreadStarted(handler)` — a conversation surface opened (e.g. the Slack
+  assistant pane); receives `{ thread, user? }`. Greet, set suggested prompts
+  or a title, or run the agent. Adapters without the concept never fire it.
 - `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
@@ -80,6 +83,12 @@ interface Thread {
   }): Promise<MessageRef | undefined>;
   resume(value: unknown): Promise<MessageRef | undefined>;
   awaitChoice<T = unknown>(ui: Renderable): Promise<T>;
+  // Capability-gated (return { ok: false } on surfaces without support):
+  setSuggestedPrompts(
+    prompts: ReadonlyArray<{ title: string; message: string }>,
+    opts?: { title?: string },
+  ): Promise<{ ok: boolean; error?: string }>;
+  setTitle(title: string): Promise<{ ok: boolean; error?: string }>;
 }
 ```
 
@@ -158,8 +167,9 @@ pass it as `actionStore` to make actions survive restarts.
 
 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
+(`sink.onTurn(IncomingTurn)` / `sink.onInteraction(InteractionEvent)` /
+`sink.onCommand(IncomingCommand)` / `sink.onThreadStarted(IncomingThreadStart)`)
+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
@@ -168,7 +178,10 @@ reads after each `runAgent`), `decodeInteraction(raw)` (native event → opaque
 (`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
+supports them — likewise `setSuggestedPrompts(target, prompts, opts?)` and
+`setThreadTitle(target, title)` back `thread.setSuggestedPrompts` /
+`thread.setTitle`, and `sink.onThreadStarted(...)` emits the "conversation
+opened" lifecycle event. 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.
@@ -176,9 +189,10 @@ See `@copilotkit/bot-slack` for a complete implementation.
 
 ## Exports
 
-`createBot`, `Bot`, `CreateBotOptions`, `BotHandler`; `Thread`; the
-`PlatformAdapter` boundary types (`RunRenderer`, `IngressSink`,
-`IncomingTurn`, `InteractionEvent`, `IncomingCommand`, `SurfaceCapabilities`,
+`createBot`, `Bot`, `CreateBotOptions`, `BotHandler`, `ThreadStartHandler`;
+`Thread`; the `PlatformAdapter` boundary types (`RunRenderer`, `IngressSink`,
+`IncomingTurn`, `InteractionEvent`, `IncomingCommand`, `IncomingThreadStart`,
+`SurfaceCapabilities`,
 `ReplyTarget`, `ConversationStore`, `AgentSession`, `CapturedToolCall`,
 `CapturedInterrupt`, `UserQuery`); `ActionStore` / `InMemoryActionStore` /
 `ActionSnapshot` / `ActionRegistry` / `ActionExpiredError`; `BotTool` /

package/dist/action-registry.d.ts

@@ -15,6 +15,12 @@ export declare class ActionRegistry {
     bindTree(componentName: string, props: Record<string, unknown>, conversationKey: string): Promise<BotNode[]>;
     bindRenderable(ui: Renderable, conversationKey: string): Promise<BotNode[]>;
     private walk;
+    /**
+     * Run the click handler for `id` and return the clicked element's `value`
+     * (so callers can resolve a HITL `awaitChoice` waiter even when the platform
+     * couldn't carry the value in its callback payload). Returns `undefined` when
+     * the element has no `value`.
+     */
     dispatch(id: string, ctx: InteractionContext): Promise<unknown>;
 }
 //# sourceMappingURL=action-registry.d.ts.map

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

@@ -1 +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"}
+{"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;IAKpD,OAAO,CAAC,GAAG,CAAgE;gBAE/D,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;IA0ClB;;;;;OAKG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;CAsBtE"}

package/dist/action-registry.js

@@ -15,6 +15,10 @@ function isComponentElement(ui) {
 export class ActionRegistry {
     store;
     components = new Map();
+    // Cache the handler AND the element's `value` per minted id. The value is
+    // needed to resolve HITL `awaitChoice` waiters on platforms whose callback
+    // payload can't carry it (e.g. Telegram's 64-byte callback_data only holds
+    // the action id), where `evt.value` arrives undefined.
     hot = new Map();
     constructor(opts) {
         this.store = opts.store;
@@ -58,7 +62,10 @@ export class ActionRegistry {
                 if (typeof handler === "function") {
                     const fullPath = [...path, ep];
                     const id = mintId(comp, fullPath, props);
-                    this.hot.set(id, handler);
+                    this.hot.set(id, {
+                        handler: handler,
+                        value: node.props.value,
+                    });
                     await this.store.put(id, {
                         component: comp,
                         props,
@@ -75,9 +82,21 @@ export class ActionRegistry {
             }
         }
     }
+    /**
+     * Run the click handler for `id` and return the clicked element's `value`
+     * (so callers can resolve a HITL `awaitChoice` waiter even when the platform
+     * couldn't carry the value in its callback payload). Returns `undefined` when
+     * the element has no `value`.
+     */
     async dispatch(id, ctx) {
-        let handler = this.hot.get(id);
-        if (!handler) {
+        let handler;
+        let value;
+        const hot = this.hot.get(id);
+        if (hot) {
+            handler = hot.handler;
+            value = hot.value;
+        }
+        else {
             const snap = await this.store.get(id);
             if (!snap || !snap.component)
                 throw new ActionExpiredError(id);
@@ -86,11 +105,26 @@ export class ActionRegistry {
                 throw new ActionExpiredError(id);
             const tree = renderToIR(fn(snap.props));
             handler = pluck(tree, snap.path);
+            value = pluckValue(tree, snap.path);
             if (!handler)
                 throw new ActionExpiredError(id);
         }
-        return handler({ ...ctx, action: { ...ctx.action, id } });
+        await handler({ ...ctx, action: { ...ctx.action, id } });
+        return value;
+    }
+}
+/** Navigate to the node owning the event-prop at `path` and read its `value`. */
+function pluckValue(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;
     }
+    return cur?.props?.value;
 }
 function pluck(tree, path) {
     let cur = tree;

package/dist/action-registry.test.js

@@ -1,6 +1,10 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, beforeEach } from "vitest";
 import { ActionRegistry, ActionExpiredError } from "./action-registry.js";
 import { InMemoryActionStore } from "./action-store.js";
+// Records each click so a test can assert the handler ran — dispatch() now
+// returns the clicked element's `value` (needed to resolve HITL waiters on
+// platforms whose callback payload can't carry it), not the handler's return.
+const clicks = [];
 function Confirm(props) {
     return {
         type: "actions",
@@ -9,7 +13,10 @@ function Confirm(props) {
                 {
                     type: "button",
                     props: {
-                        onClick: ({ action }) => `ok:${props.action}:${action.id}`,
+                        value: { ok: props.action },
+                        onClick: ({ action }) => {
+                            clicks.push(`ok:${props.action}:${action.id}`);
+                        },
                         children: "Yes",
                     },
                 },
@@ -19,24 +26,29 @@ function Confirm(props) {
 }
 const ctx = {};
 describe("ActionRegistry", () => {
-    it("binds onClick handlers and dispatches via hot cache", async () => {
+    beforeEach(() => {
+        clicks.length = 0;
+    });
+    it("dispatches via hot cache, runs the handler, and returns the element value", 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:");
+        const value = await reg.dispatch(id, ctx);
+        expect(value).toEqual({ ok: "write" });
+        expect(clicks[0]).toContain("ok:write:");
     });
-    it("cold path re-renders from snapshot when hot cache is cleared", async () => {
+    it("cold path re-renders from snapshot when hot cache is cleared, still returning the value", 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:");
+        const value = await reg.dispatch(id, ctx);
+        expect(value).toEqual({ ok: "write" });
+        expect(clicks[0]).toContain("ok:write:");
     });
     it("throws ActionExpiredError on full miss", async () => {
         const reg = new ActionRegistry({ store: new InMemoryActionStore() });

package/dist/create-bot.d.ts

@@ -1,14 +1,19 @@
 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 type { ActionStore } from "./action-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 } from "@copilotkit/bot-ui";
+import type { InteractionContext, IncomingMessage, PlatformUser } from "@copilotkit/bot-ui";
 export type BotHandler = (ctx: {
     thread: Thread;
     message: IncomingMessage;
 }) => void | Promise<void>;
+/** Handler for a "conversation opened" lifecycle event (e.g. the Slack assistant pane). */
+export type ThreadStartHandler = (ctx: {
+    thread: Thread;
+    user?: PlatformUser;
+}) => void | Promise<void>;
 export interface CreateBotOptions {
     adapters: PlatformAdapter[];
     agent?: AbstractAgent | ((threadId: string) => AbstractAgent);
@@ -21,6 +26,12 @@ export interface CreateBotOptions {
 export interface Bot {
     onMention(h: BotHandler): void;
     onMessage(h: BotHandler): 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): 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;
     /**

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

@@ -1 +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"}
+{"version":3,"file":"create-bot.d.ts","sourceRoot":"","sources":["../src/create-bot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EAMhB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,oBAAoB,CAAC;AAE5B,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,2FAA2F;AAC3F,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,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;;;;OAIG;IACH,eAAe,CAAC,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC7C,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,CAqOrD"}

package/dist/create-bot.js

@@ -1,7 +1,7 @@
 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 { toAgentToolDescriptors, parseToolArgs } from "./tools.js";
+import { normalizeCommandName, toCommandSpec } from "./commands.js";
 import { Thread } from "./thread.js";
 export function createBot(opts) {
     const registry = new ActionRegistry({
@@ -23,6 +23,7 @@ export function createBot(opts) {
     const context = opts.context ?? [];
     const mentionHandlers = [];
     const messageHandlers = [];
+    const threadStartedHandlers = [];
     const interactionHandlers = new Map();
     const interruptHandlers = new Map();
     const commandHandlers = new Map();
@@ -52,6 +53,7 @@ export function createBot(opts) {
                 const thread = makeThread(adapter, turn.replyTarget, turn.conversationKey);
                 const message = {
                     text: turn.userText,
+                    contentParts: turn.contentParts,
                     user: turn.user ?? { id: "" },
                     ref: { id: "" },
                     platform: turn.platform,
@@ -80,13 +82,18 @@ export function createBot(opts) {
                     user,
                     platform: adapter.platform,
                 };
+                // The clicked element's `value`, recovered by the registry when it
+                // re-renders to find the handler. Used to resolve a HITL waiter on
+                // platforms whose callback payload can't carry the value (Telegram),
+                // where `evt.value` is undefined.
+                let dispatchedValue;
                 try {
                     const explicit = interactionHandlers.get(evt.id);
                     if (explicit) {
                         await explicit(ctx);
                     }
                     else {
-                        await registry.dispatch(evt.id, ctx);
+                        dispatchedValue = await registry.dispatch(evt.id, ctx);
                     }
                 }
                 catch (err) {
@@ -94,11 +101,13 @@ export function createBot(opts) {
                     if (!(err instanceof ActionExpiredError))
                         throw err;
                 }
-                // Resolve any HITL waiter awaiting a choice in this conversation.
+                // Resolve any HITL waiter awaiting a choice in this conversation. Prefer
+                // the value carried in the event (Slack), falling back to the value the
+                // registry recovered from the rendered element (Telegram).
                 const w = waiters.get(evt.conversationKey);
                 if (w) {
                     waiters.delete(evt.conversationKey);
-                    w(evt.value);
+                    w(evt.value !== undefined ? evt.value : dispatchedValue);
                 }
             },
             async onCommand(cmd) {
@@ -125,6 +134,14 @@ export function createBot(opts) {
                 };
                 await command.handler(ctx);
             },
+            async onThreadStarted(evt) {
+                // The adapter has already applied its static defaults (greeting /
+                // prompts) before emitting this, so handlers layer on top and never
+                // race. Zero handlers → no-op.
+                const thread = makeThread(adapter, evt.replyTarget, evt.conversationKey);
+                for (const h of threadStartedHandlers)
+                    await h({ thread, user: evt.user });
+            },
         };
     }
     return {
@@ -134,6 +151,9 @@ export function createBot(opts) {
         onMessage(h) {
             messageHandlers.push(h);
         },
+        onThreadStarted(h) {
+            threadStartedHandlers.push(h);
+        },
         onInteraction(id, h) {
             interactionHandlers.set(id, h);
         },

package/dist/create-bot.test.js

@@ -67,6 +67,58 @@ describe("createBot", () => {
         expect(findNode(ir, "section")).toBeDefined();
         expect(collectText(ir)).toBe("hi");
     });
+    it("calls renderer.finish() once after a turn's run-loop resolves", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        bot.onMention(async ({ thread }) => {
+            await thread.runAgent();
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "yo", conversationKey: "c1" });
+        await tick();
+        const renderer = fake.lastRunRenderer;
+        expect(renderer.finishCalls).toBe(1);
+    });
+    it("delivers a turn's contentParts as the runAgent prompt to agent.addMessage", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        // Capture what the framework injects as the user message.
+        const added = [];
+        const origAddMessage = agent.addMessage.bind(agent);
+        agent.addMessage = (m) => {
+            added.push(m);
+            return origAddMessage(m);
+        };
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        const parts = [
+            { type: "text", text: "look" },
+            {
+                type: "image",
+                source: { type: "data", value: "QUJD", mimeType: "image/png" },
+            },
+        ];
+        bot.onMention(async ({ thread, message }) => {
+            // The example mirrors this: prefer multimodal parts over plain text.
+            await thread.runAgent({
+                prompt: message.contentParts && message.contentParts.length > 0
+                    ? message.contentParts
+                    : message.text,
+            });
+        });
+        await bot.start();
+        fake.emitTurn({
+            userText: "look",
+            conversationKey: "c1",
+            contentParts: parts,
+        });
+        await tick();
+        expect(added).toHaveLength(1);
+        const msg = added[0];
+        expect(msg.role).toBe("user");
+        // The multimodal parts array survives the string-typed `content` cast.
+        expect(msg.content).toEqual(parts);
+    });
     it("dispatches a bound onClick handler on interaction", async () => {
         const fake = new FakeAdapter();
         const agent = new FakeAgent();
@@ -95,6 +147,34 @@ describe("createBot", () => {
         await tick();
         expect(clicked).toBe(true);
     });
+    it("resolves a HITL awaitChoice with the element value when the event carries none (Telegram)", async () => {
+        const fake = new FakeAdapter();
+        const agent = new FakeAgent();
+        const bot = createBot({ adapters: [fake], agent: () => agent });
+        let chosen;
+        bot.onMention(async ({ thread }) => {
+            chosen = await thread.awaitChoice(Actions({
+                children: [
+                    Button({
+                        value: { confirmed: true },
+                        onClick: () => { },
+                        children: "Create",
+                    }),
+                ],
+            }));
+        });
+        await bot.start();
+        fake.emitTurn({ userText: "create a thing", conversationKey: "c1" });
+        await tick();
+        const button = findNode(fake.posted[0], "button");
+        const id = button.props.onClick.id;
+        // Telegram can't carry the button value in callback_data, so the event has
+        // no `value`. The waiter must still resolve with the button's value, which
+        // the registry recovers from the rendered element.
+        fake.emitInteraction({ id, conversationKey: "c1" });
+        await tick();
+        expect(chosen).toEqual({ confirmed: true });
+    });
     it("merges per-turn runAgent context with the bot-level context", async () => {
         const fake = new FakeAdapter();
         const agent = new FakeAgent();

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { createBot } from "./create-bot.js";
-export type { Bot, CreateBotOptions, BotHandler } from "./create-bot.js";
+export type { Bot, CreateBotOptions, BotHandler, ThreadStartHandler, } 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 type { PlatformAdapter, RunRenderer, IngressSink, IncomingTurn, InteractionEvent, IncomingCommand, IncomingThreadStart, 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";

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EACV,GAAG,EACH,gBAAgB,EAChB,UAAU,EACV,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAGzB,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,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/platform-adapter.d.ts

@@ -1,5 +1,5 @@
 import type { AgentSubscriber, AbstractAgent } from "@ag-ui/client";
-import type { BotNode, MessageRef, PlatformUser, ThreadMessage } from "@copilotkit/bot-ui";
+import type { AgentContentPart, 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;
@@ -11,6 +11,10 @@ export interface SurfaceCapabilities {
     supportsReactions: boolean;
     supportsStreaming: boolean;
     maxBlocksPerMessage?: number;
+    /** Pinned prompt chips on a conversation surface (Slack assistant pane). */
+    supportsSuggestedPrompts?: boolean;
+    /** Nameable conversations (Slack assistant-thread titles). */
+    supportsThreadTitle?: boolean;
     [k: string]: unknown;
 }
 export interface CapturedToolCall {
@@ -29,11 +33,26 @@ export interface RunRenderer {
     getCapturedToolCalls(): readonly CapturedToolCall[];
     getPendingInterrupt(): CapturedInterrupt | undefined;
     clearPendingInterrupt(): void;
+    /**
+     * Optional turn-end hook. Called once after the run-loop resolves normally
+     * (no more tool calls, or an interrupt was acked), so a renderer that keeps a
+     * turn-scoped resource open across `runAgent` iterations — e.g. a single
+     * native streaming message that interleaves text and tool-progress — can
+     * finalize it. Symmetric with {@link markInterrupted}; renderers whose
+     * streams self-terminate per message simply omit it. Must be a no-op if the
+     * run was already interrupted.
+     */
+    finish?(): Promise<void>;
 }
 export interface IncomingTurn {
     conversationKey: string;
     replyTarget: ReplyTarget;
     userText: string;
+    /**
+     * Optional multimodal content parts built by the adapter (e.g. inbound
+     * image/file attachments). Carried through to `IncomingMessage.contentParts`.
+     */
+    contentParts?: AgentContentPart[];
     user?: PlatformUser;
     platform: string;
 }
@@ -59,11 +78,23 @@ export interface IncomingCommand {
     user?: PlatformUser;
     platform: string;
 }
+/**
+ * A "conversation opened" lifecycle event (Slack: `assistant_thread_started`).
+ * Adapters without the concept never emit it.
+ */
+export interface IncomingThreadStart {
+    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>;
+    /** A conversation surface opened. Adapters without the concept never call it. */
+    onThreadStarted(evt: IncomingThreadStart): void | Promise<void>;
 }
 export interface UserQuery {
     query: string;
@@ -121,5 +152,29 @@ export interface PlatformAdapter {
      * commands at all simply omit it and command handlers never fire there.
      */
     registerCommands?(commands: readonly CommandSpec[]): void | Promise<void>;
+    /**
+     * Optional: pin suggested prompts on a conversation surface (backs the
+     * capability-gated `Thread.setSuggestedPrompts`). Adapters without the
+     * concept omit this, and `Thread.setSuggestedPrompts` returns
+     * `{ ok: false, error }` without throwing.
+     */
+    setSuggestedPrompts?(target: ReplyTarget, prompts: ReadonlyArray<{
+        title: string;
+        message: string;
+    }>, opts?: {
+        title?: string;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Optional: set the conversation's display title (backs `Thread.setTitle`).
+     * Adapters without the concept omit this, and `Thread.setTitle` returns
+     * `{ ok: false, error }` without throwing.
+     */
+    setThreadTitle?(target: ReplyTarget, title: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
 }
 //# sourceMappingURL=platform-adapter.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"platform-adapter.d.ts","sourceRoot":"","sources":["../src/platform-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,YAAY,EACZ,aAAa,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,+GAA+G;AAC/G,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC;AAClC,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC;AAEpC,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AACD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,4HAA4H;AAC5H,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,eAAe,CAAC;IAC5B,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,oBAAoB,IAAI,SAAS,gBAAgB,EAAE,CAAC;IACpD,mBAAmB,IAAI,iBAAiB,GAAG,SAAS,CAAC;IACrD,qBAAqB,IAAI,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,gGAAgG;IAChG,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,+FAA+F;IAC/F,SAAS,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kHAAkH;AAClH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,gHAAgH;AAChH,MAAM,WAAW,iBAAiB;IAChC,WAAW,CACT,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,aAAa,GAC7C,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC;IACrC,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9D,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,MAAM,CACJ,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAAC;IACpD,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAC9D,UAAU,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAC5D,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;IAC9C;;;;OAIG;IACH,WAAW,CAAC,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC5D;;;;OAIG;IACH,QAAQ,CAAC,CACP,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE;QACJ,KAAK,EAAE,UAAU,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACA,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D;;;;;;;OAOG;IACH,gBAAgB,CAAC,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3E"}
+{"version":3,"file":"platform-adapter.d.ts","sourceRoot":"","sources":["../src/platform-adapter.ts"],"names":[],"mappings":"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"}

package/dist/platform-adapter.test.js

@@ -10,6 +10,7 @@ describe("FakeAdapter", () => {
             },
             onInteraction: () => { },
             onCommand: () => { },
+            onThreadStarted: () => { },
         });
         a.emitTurn({ userText: "hi" });
         expect(got).toBe("hi");
@@ -25,6 +26,7 @@ describe("FakeAdapter", () => {
                 id = e.id;
             },
             onCommand: () => { },
+            onThreadStarted: () => { },
         });
         a.emitInteraction({ id: "ck:abc" });
         expect(id).toBe("ck:abc");

package/dist/testing/fake-adapter.d.ts

@@ -1,5 +1,5 @@
 import type { BotNode, MessageRef, PlatformUser, ThreadMessage } from "@copilotkit/bot-ui";
-import type { PlatformAdapter, SurfaceCapabilities, IngressSink, IncomingTurn, InteractionEvent, IncomingCommand, RunRenderer, ReplyTarget, NativePayload, UserQuery, ConversationStore } from "../platform-adapter.js";
+import type { PlatformAdapter, SurfaceCapabilities, IngressSink, IncomingTurn, IncomingThreadStart, InteractionEvent, IncomingCommand, RunRenderer, ReplyTarget, NativePayload, UserQuery, ConversationStore } from "../platform-adapter.js";
 import type { CommandSpec } from "../commands.js";
 /** A RunRenderer whose subscriber captures tool-call-end and custom (interrupt) events — used by run-loop tests. */
 export declare function makeFakeRunRenderer(): RunRenderer;
@@ -7,6 +7,15 @@ export declare class FakeAdapter implements PlatformAdapter {
     readonly platform = "fake";
     readonly capabilities: SurfaceCapabilities;
     readonly ackDeadlineMs = 3000;
+    /**
+     * @param fakeOpts.paneMethods When `false`, the optional
+     *   `setSuggestedPrompts`/`setThreadTitle` methods are omitted (and the
+     *   matching capability flags cleared) so tests can exercise the
+     *   capability-gated `{ ok: false }` path. Defaults to present.
+     */
+    constructor(fakeOpts?: {
+        paneMethods?: boolean;
+    });
     readonly conversationStore: ConversationStore;
     posted: BotNode[][];
     updated: {
@@ -32,7 +41,26 @@ export declare class FakeAdapter implements PlatformAdapter {
     decodeInteraction(raw: unknown): InteractionEvent | undefined;
     lookupUser(_q: UserQuery): Promise<PlatformUser | undefined>;
     getMessages(_target: ReplyTarget): Promise<ThreadMessage[]>;
+    /** Suggested-prompt calls recorded by the capability-gated method (when present). */
+    suggestedPromptsCalls: {
+        target: ReplyTarget;
+        prompts: ReadonlyArray<{
+            title: string;
+            message: string;
+        }>;
+        opts?: {
+            title?: string;
+        };
+    }[];
+    setSuggestedPrompts?: PlatformAdapter["setSuggestedPrompts"];
+    /** Thread-title calls recorded by the capability-gated method (when present). */
+    threadTitleCalls: {
+        target: ReplyTarget;
+        title: string;
+    }[];
+    setThreadTitle?: PlatformAdapter["setThreadTitle"];
     emitTurn(partial: Partial<IncomingTurn>): void;
+    emitThreadStarted(partial?: Partial<IncomingThreadStart>): Promise<void> | void;
     emitInteraction(partial: Partial<InteractionEvent>): void;
     emitCommand(partial: Partial<IncomingCommand> & {
         command: string;

package/dist/testing/fake-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-adapter.d.ts","sourceRoot":"","sources":["../../src/testing/fake-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,YAAY,EACZ,aAAa,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,WAAW,EAGX,WAAW,EACX,aAAa,EACb,SAAS,EACT,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,oHAAoH;AACpH,wBAAgB,mBAAmB,IAAI,WAAW,CAyBjD;AAED,qBAAa,WAAY,YAAW,eAAe;IACjD,QAAQ,CAAC,QAAQ,UAAU;IAC3B,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAKxC;IACF,QAAQ,CAAC,aAAa,QAAQ;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAI3C;IAEF,MAAM,EAAE,OAAO,EAAE,EAAE,CAAM;IACzB,OAAO,EAAE;QAAE,GAAG,EAAE,UAAU,CAAC;QAAC,EAAE,EAAE,OAAO,EAAE,CAAA;KAAE,EAAE,CAAM;IACnD,gBAAgB,EAAE,gBAAgB,EAAE,CAAM;IAC1C,eAAe,CAAC,EAAE,WAAW,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,EAAE,aAAa,EAAE,CAAM;IAC/B,wDAAwD;IACxD,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,IAAI,CAAC,CAAc;IAC3B,OAAO,CAAC,OAAO,CAAK;IAEd,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAGvC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAE3B,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,aAAa;IAG9B,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAI9D,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAGrD,MAAM,CACV,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC;IAMhB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAE7C,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW;IAKpD,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS;IAGvD,UAAU,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAG5D,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAKjE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAS9C,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAUzD,WAAW,CACT,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GACtD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAUvB,gGAAgG;IAChG,kBAAkB,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC5C,gBAAgB,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI;CAGzD"}
+{"version":3,"file":"fake-adapter.d.ts","sourceRoot":"","sources":["../../src/testing/fake-adapter.ts"],"names":[],"mappings":"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"}

package/dist/testing/fake-adapter.js

@@ -16,6 +16,7 @@ export function makeFakeRunRenderer() {
                 pending = { eventName: e.name, value: e.value };
         },
     };
+    let finishCalls = 0;
     return {
         subscriber,
         async markInterrupted() { },
@@ -24,17 +25,45 @@ export function makeFakeRunRenderer() {
         clearPendingInterrupt: () => {
             pending = undefined;
         },
+        async finish() {
+            finishCalls++;
+        },
+        get finishCalls() {
+            return finishCalls;
+        },
     };
 }
 export class FakeAdapter {
     platform = "fake";
-    capabilities = {
-        supportsModals: false,
-        supportsTyping: false,
-        supportsReactions: false,
-        supportsStreaming: true,
-    };
+    capabilities;
     ackDeadlineMs = 3000;
+    /**
+     * @param fakeOpts.paneMethods When `false`, the optional
+     *   `setSuggestedPrompts`/`setThreadTitle` methods are omitted (and the
+     *   matching capability flags cleared) so tests can exercise the
+     *   capability-gated `{ ok: false }` path. Defaults to present.
+     */
+    constructor(fakeOpts = {}) {
+        const paneMethods = fakeOpts.paneMethods !== false;
+        this.capabilities = {
+            supportsModals: false,
+            supportsTyping: false,
+            supportsReactions: false,
+            supportsStreaming: true,
+            supportsSuggestedPrompts: paneMethods,
+            supportsThreadTitle: paneMethods,
+        };
+        if (paneMethods) {
+            this.setSuggestedPrompts = async (target, prompts, opts) => {
+                this.suggestedPromptsCalls.push({ target, prompts, opts });
+                return { ok: true };
+            };
+            this.setThreadTitle = async (target, title) => {
+                this.threadTitleCalls.push({ target, title });
+                return { ok: true };
+            };
+        }
+    }
     conversationStore = {
         async getOrCreate(conversationKey, _replyTarget, makeAgent) {
             return { agent: makeAgent(conversationKey) };
@@ -86,6 +115,12 @@ export class FakeAdapter {
     async getMessages(_target) {
         return this.messages;
     }
+    /** Suggested-prompt calls recorded by the capability-gated method (when present). */
+    suggestedPromptsCalls = [];
+    setSuggestedPrompts;
+    /** Thread-title calls recorded by the capability-gated method (when present). */
+    threadTitleCalls = [];
+    setThreadTitle;
     // --- test helpers ---
     emitTurn(partial) {
         void this.sink?.onTurn({
@@ -96,6 +131,14 @@ export class FakeAdapter {
             ...partial,
         });
     }
+    emitThreadStarted(partial) {
+        return this.sink?.onThreadStarted({
+            conversationKey: "c",
+            replyTarget: {},
+            platform: "fake",
+            ...partial,
+        });
+    }
     emitInteraction(partial) {
         const evt = {
             id: "",

package/dist/thread-capabilities.test.d.ts

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

package/dist/thread-capabilities.test.d.ts.map

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

package/dist/thread-capabilities.test.js

@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+import { createBot } from "./create-bot.js";
+import { FakeAdapter } from "./testing/fake-adapter.js";
+describe("onThreadStarted routing", () => {
+    it("invokes registered handlers with the thread and user", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        const seen = [];
+        bot.onThreadStarted(({ thread, user }) => {
+            seen.push({ user: user?.id, platform: thread.platform });
+        });
+        await bot.start();
+        await fake.emitThreadStarted({ user: { id: "U1", name: "Ada" } });
+        expect(seen).toEqual([{ user: "U1", platform: "fake" }]);
+    });
+    it("invokes every registered handler in order", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        const order = [];
+        bot.onThreadStarted(() => {
+            order.push(1);
+        });
+        bot.onThreadStarted(() => {
+            order.push(2);
+        });
+        await bot.start();
+        await fake.emitThreadStarted();
+        expect(order).toEqual([1, 2]);
+    });
+    it("is a no-op when no handler is registered", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        await bot.start();
+        // Should not throw.
+        await expect(Promise.resolve(fake.emitThreadStarted())).resolves.toBeUndefined();
+    });
+});
+describe("Thread.setSuggestedPrompts / setTitle capability gating", () => {
+    it("delegates to the adapter when supported", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        const results = [];
+        bot.onThreadStarted(async ({ thread }) => {
+            results.push(await thread.setSuggestedPrompts([{ title: "Triage", message: "Triage my issues" }], { title: "Try" }));
+            results.push(await thread.setTitle("My conversation"));
+        });
+        await bot.start();
+        await fake.emitThreadStarted({ replyTarget: { channel: "D1" } });
+        expect(results).toEqual([{ ok: true }, { ok: true }]);
+        expect(fake.suggestedPromptsCalls).toHaveLength(1);
+        expect(fake.suggestedPromptsCalls[0]).toMatchObject({
+            target: { channel: "D1" },
+            prompts: [{ title: "Triage", message: "Triage my issues" }],
+            opts: { title: "Try" },
+        });
+        expect(fake.threadTitleCalls).toEqual([
+            { target: { channel: "D1" }, title: "My conversation" },
+        ]);
+    });
+    it("returns { ok: false } without throwing when unsupported", async () => {
+        const fake = new FakeAdapter({ paneMethods: false });
+        const bot = createBot({ adapters: [fake] });
+        const results = [];
+        bot.onThreadStarted(async ({ thread }) => {
+            results.push(await thread.setSuggestedPrompts([]));
+            results.push(await thread.setTitle("nope"));
+        });
+        await bot.start();
+        await fake.emitThreadStarted();
+        expect(results[0].ok).toBe(false);
+        expect(results[0].error).toMatch(/does not support suggested prompts/);
+        expect(results[1].ok).toBe(false);
+        expect(results[1].error).toMatch(/does not support thread titles/);
+        expect(fake.suggestedPromptsCalls).toHaveLength(0);
+        expect(fake.threadTitleCalls).toHaveLength(0);
+    });
+});

package/dist/thread.d.ts

@@ -1,6 +1,6 @@
 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 { AgentContentPart, 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 {
@@ -38,6 +38,21 @@ export declare class Thread implements ThreadInterface {
         fileId?: string;
         error?: string;
     }>;
+    /** Pin suggested prompts (returns `{ ok: false }` on surfaces without support). */
+    setSuggestedPrompts(prompts: ReadonlyArray<{
+        title: string;
+        message: string;
+    }>, opts?: {
+        title?: string;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Name this conversation (returns `{ ok: false }` on surfaces without support). */
+    setTitle(title: string): Promise<{
+        ok: boolean;
+        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). */
@@ -50,9 +65,11 @@ export declare class Thread implements ThreadInterface {
         /**
          * 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.
+         * slash command, whose args are never posted to the channel. A
+         * `AgentContentPart[]` carries multimodal content (e.g. inbound image/file
+         * attachments) the model can read.
          */
-        prompt?: string;
+        prompt?: string | AgentContentPart[];
     }): Promise<MessageRef | undefined>;
     resume(value: unknown): Promise<MessageRef | undefined>;
     private run;

package/dist/thread.d.ts.map

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

package/dist/thread.js

@@ -39,6 +39,28 @@ export class Thread {
         }
         return adapter.postFile(this.deps.replyTarget, args);
     }
+    /** Pin suggested prompts (returns `{ ok: false }` on surfaces without support). */
+    async setSuggestedPrompts(prompts, opts) {
+        const adapter = this.deps.adapter;
+        if (!adapter.setSuggestedPrompts) {
+            return {
+                ok: false,
+                error: `${this.platform} does not support suggested prompts`,
+            };
+        }
+        return adapter.setSuggestedPrompts(this.deps.replyTarget, prompts, opts);
+    }
+    /** Name this conversation (returns `{ ok: false }` on surfaces without support). */
+    async setTitle(title) {
+        const adapter = this.deps.adapter;
+        if (!adapter.setThreadTitle) {
+            return {
+                ok: false,
+                error: `${this.platform} does not support thread titles`,
+            };
+        }
+        return adapter.setThreadTitle(this.deps.replyTarget, title);
+    }
     /** Read the conversation's messages (returns `[]` when the adapter can't read history). */
     async getMessages() {
         return (await this.deps.adapter.getMessages?.(this.deps.replyTarget)) ?? [];
@@ -62,11 +84,18 @@ export class Thread {
     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).
+        // reconstructed history (e.g. a slash command's args, or inbound image/file
+        // attachments built into multimodal content parts). A non-empty array is
+        // truthy, so this guard also admits multimodal prompts.
         if (extra?.prompt) {
             session.agent.addMessage({
                 id: globalThis.crypto.randomUUID(),
                 role: "user",
+                // AG-UI types `content` as `string`, but multimodal works at runtime by
+                // setting it to an `AgentContentPart[]` — the runtime's LLM adapter
+                // converts the parts to the provider's multimodal format. We cast to
+                // satisfy the string-typed field (bot-slack parity — it does the same
+                // when assigning multimodal `content` to its reconstructed messages).
                 content: extra.prompt,
             });
         }
@@ -104,6 +133,11 @@ export class Thread {
             },
             initialResume,
         });
+        // Turn-end hook: lets a renderer finalize any turn-scoped resource it kept
+        // open across runAgent iterations (e.g. a native streaming message). A
+        // no-op for renderers whose per-message streams already self-terminate, and
+        // for runs that were interrupted (the renderer guards that internally).
+        await renderer.finish?.();
         return undefined;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/bot",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Platform-agnostic JSX bot engine for CopilotKit (createBot, Thread, PlatformAdapter, ActionStore).",
   "license": "MIT",
   "repository": {
@@ -35,12 +35,12 @@
     "dist"
   ],
   "dependencies": {
-    "@ag-ui/client": "0.0.53",
-    "@ag-ui/core": "0.0.53",
+    "@ag-ui/client": "0.0.57",
+    "@ag-ui/core": "0.0.57",
     "zod-to-json-schema": "^3.24.1",
-    "@copilotkit/bot-ui": "~0.0.1",
-    "@copilotkit/shared": "^1.59.5",
-    "@copilotkit/core": "^1.59.5"
+    "@copilotkit/bot-ui": "~0.0.3",
+    "@copilotkit/core": "^1.61.0",
+    "@copilotkit/shared": "^1.61.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",