@copilotkit/channels 0.1.0

package/dist/thread.d.ts

@@ -0,0 +1,152 @@
+import type { PlatformAdapter, ReplyTarget } from "./platform-adapter.js";
+import type { ActionRegistry } from "./action-registry.js";
+import type { AgentContentPart, Renderable, MessageRef, PlatformUser, ThreadMessage, IncomingMessage, Thread as ThreadInterface, EmojiValue, EphemeralResult } from "@copilotkit/channels-ui";
+import type { Transcripts } from "./transcripts.js";
+import type { BotTool, ContextEntry, AgentToolDescriptor } from "./tools.js";
+import type { AbstractAgent } from "@ag-ui/client";
+import type { StateStore } from "./state/state-store.js";
+import type { StandardSchemaV1 } from "./standard-schema.js";
+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>>;
+    /** Pluggable persistence. Injected by createBot; always required. */
+    state: StateStore;
+    /**
+     * Optional Standard Schema for per-thread state. When set, `setState`
+     * validates its argument before persisting and throws on a schema mismatch.
+     */
+    stateSchema?: StandardSchemaV1;
+    /** Cross-platform transcript store. Present only when `store.transcripts` is configured. */
+    transcripts?: Transcripts;
+    /** Resolved cross-platform identity key for this turn (if any). */
+    userKey?: string;
+    /** The inbound message that triggered this turn (for transcript bridging). */
+    message?: IncomingMessage;
+    /**
+     * Optional anonymous telemetry sink. Structural type (not the concrete
+     * BotTelemetry) avoids an import cycle; the real BotTelemetry satisfies it.
+     */
+    telemetry?: {
+        capture(event: string, properties: Record<string, unknown>): 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;
+    /** Stable key identifying this conversation (used by transcript bridging). */
+    readonly conversationKey: string;
+    private readonly store;
+    constructor(deps: ThreadDeps);
+    private bindForPost;
+    /**
+     * Wire a posted message's `onReaction` to its returned id: cache it for this
+     * process and, when it came from a component, persist a durable snapshot so a
+     * reaction after a restart re-derives it (parity with a component `onClick`).
+     */
+    private bindReaction;
+    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;
+    }>;
+    /** 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;
+    }>;
+    /** Add an emoji reaction to a message (capability-gated; `{ ok: false }` on surfaces without support). */
+    react(messageRef: MessageRef, emoji: EmojiValue): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Remove the bot's emoji reaction from a message (capability-gated). */
+    unreact(messageRef: MessageRef, emoji: EmojiValue): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Post a message only `user` can see. `fallbackToDM` is required:
+     * `true` → DM the user when native ephemeral is unsupported; `false` →
+     * resolve to `null` when native ephemeral is unsupported.
+     */
+    postEphemeral(user: PlatformUser | string, ui: Renderable, opts: {
+        fallbackToDM: boolean;
+    }): Promise<EphemeralResult | null>;
+    /** Record this conversation as subscribed (persisted in state). Proactive delivery to subscribed conversations is not yet wired. */
+    subscribe(): Promise<void>;
+    /** Remove the subscription for this conversation. */
+    unsubscribe(): Promise<void>;
+    /** Returns true if this conversation is currently subscribed. */
+    isSubscribed(): Promise<boolean>;
+    /** Persist arbitrary per-thread state (e.g. workflow step). */
+    setState<T>(v: T): Promise<void>;
+    /** Read back per-thread state previously written with `setState`. */
+    state<T>(): Promise<T | undefined>;
+    /** 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. A
+         * `AgentContentPart[]` carries multimodal content (e.g. inbound image/file
+         * attachments) the model can read.
+         */
+        prompt?: string | AgentContentPart[];
+        /**
+         * Auto-bridge cross-platform transcripts for this run. When truthy AND the
+         * thread has a resolved `userKey` AND a `Transcripts` instance, this:
+         *   1. injects prior history (`transcripts.list`, default limit 20) as a
+         *      context entry,
+         *   2. appends the current user turn,
+         *   3. runs the agent,
+         *   4. captures the assistant reply and appends it.
+         * This flag OWNS the bridge — callers using it should NOT also manually
+         * append the same user/assistant turn via `bot.transcripts.append`.
+         * No-ops with a one-time warning when identity/transcripts aren't configured.
+         */
+        transcript?: boolean | {
+            limit?: number;
+        };
+    }): 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,329 @@
+import { runAgentLoop } from "./run-loop.js";
+import { errorClass, normalizePlatform } from "./telemetry/sanitize-error.js";
+import { toAgentToolDescriptors } from "./tools.js";
+import { validateSchema } from "./standard-schema.js";
+/** A concrete conversation thread: posts UI, runs the agent loop, and resolves HITL waiters. */
+export class Thread {
+    deps;
+    platform;
+    /** Stable key identifying this conversation (used by transcript bridging). */
+    conversationKey;
+    store;
+    constructor(deps) {
+        this.deps = deps;
+        this.platform = deps.adapter.platform;
+        this.conversationKey = deps.conversationKey;
+        this.store = deps.state;
+    }
+    async bindForPost(ui) {
+        return this.deps.registry.bindRenderable(ui, this.deps.conversationKey);
+    }
+    /**
+     * Wire a posted message's `onReaction` to its returned id: cache it for this
+     * process and, when it came from a component, persist a durable snapshot so a
+     * reaction after a restart re-derives it (parity with a component `onClick`).
+     */
+    async bindReaction(messageId, bound) {
+        if (bound.onReaction) {
+            this.deps.registry.registerMessageReaction(messageId, bound.onReaction);
+        }
+        if (bound.reactionComponent) {
+            await this.deps.registry.persistMessageReaction(messageId, {
+                ...bound.reactionComponent,
+                conversationKey: this.deps.conversationKey,
+            });
+        }
+    }
+    async post(ui) {
+        const bound = await this.bindForPost(ui);
+        const ref = await this.deps.adapter.post(this.deps.replyTarget, bound.root);
+        await this.bindReaction(ref.id, bound);
+        return ref;
+    }
+    async update(ref, ui) {
+        const bound = await this.bindForPost(ui);
+        await this.deps.adapter.update(ref, bound.root);
+        await this.bindReaction(ref.id, bound);
+        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);
+    }
+    /** 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);
+    }
+    /** Add an emoji reaction to a message (capability-gated; `{ ok: false }` on surfaces without support). */
+    async react(messageRef, emoji) {
+        const adapter = this.deps.adapter;
+        if (!adapter.addReaction) {
+            return {
+                ok: false,
+                error: `${this.platform} does not support reactions`,
+            };
+        }
+        return adapter.addReaction(this.deps.replyTarget, messageRef, emoji);
+    }
+    /** Remove the bot's emoji reaction from a message (capability-gated). */
+    async unreact(messageRef, emoji) {
+        const adapter = this.deps.adapter;
+        if (!adapter.removeReaction) {
+            return {
+                ok: false,
+                error: `${this.platform} does not support reactions`,
+            };
+        }
+        return adapter.removeReaction(this.deps.replyTarget, messageRef, emoji);
+    }
+    /**
+     * Post a message only `user` can see. `fallbackToDM` is required:
+     * `true` → DM the user when native ephemeral is unsupported; `false` →
+     * resolve to `null` when native ephemeral is unsupported.
+     */
+    async postEphemeral(user, ui, opts) {
+        const adapter = this.deps.adapter;
+        if (!adapter.postEphemeral) {
+            return {
+                ok: false,
+                error: `${this.platform} does not support ephemeral messages`,
+            };
+        }
+        // Ephemeral messages can't be reacted to, so any `onReaction` is dropped
+        // (stripped by bindForPost) rather than registered.
+        const { root } = await this.bindForPost(ui);
+        return adapter.postEphemeral(this.deps.replyTarget, user, root, opts);
+    }
+    // Subscription STORAGE lands here; subscription ROUTING (onSubscribedMessage) is deferred.
+    /** Record this conversation as subscribed (persisted in state). Proactive delivery to subscribed conversations is not yet wired. */
+    async subscribe() {
+        await this.store.kv.set(`sub:${this.deps.conversationKey}`, true);
+    }
+    /** Remove the subscription for this conversation. */
+    async unsubscribe() {
+        await this.store.kv.delete(`sub:${this.deps.conversationKey}`);
+    }
+    /** Returns true if this conversation is currently subscribed. */
+    async isSubscribed() {
+        return ((await this.store.kv.get(`sub:${this.deps.conversationKey}`)) ===
+            true);
+    }
+    /** Persist arbitrary per-thread state (e.g. workflow step). */
+    async setState(v) {
+        let value = v;
+        if (this.deps.stateSchema) {
+            const r = await validateSchema(this.deps.stateSchema, v);
+            if (!r.ok)
+                throw new Error(`thread.setState: invalid state — ${r.error}`);
+            value = r.value;
+        }
+        await this.store.kv.set(`threadstate:${this.deps.conversationKey}`, value);
+    }
+    /** Read back per-thread state previously written with `setState`. */
+    async state() {
+        return this.store.kv.get(`threadstate:${this.deps.conversationKey}`);
+    }
+    /** 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, 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,
+            });
+        }
+        const renderer = this.deps.adapter.createRunRenderer(this.deps.replyTarget);
+        // Transcript auto-bridge (step 1 + 2): inject prior cross-platform history
+        // as a context entry, then append the current user turn. This flag owns the
+        // bridge — see `runAgent`'s `transcript` doc. No-ops with one warning when
+        // identity/transcripts aren't configured.
+        const transcripts = this.deps.transcripts;
+        const userKey = this.deps.userKey;
+        let transcriptContext;
+        if (extra?.transcript) {
+            if (transcripts && userKey) {
+                const limit = typeof extra.transcript === "object"
+                    ? (extra.transcript.limit ?? 20)
+                    : 20;
+                // List BEFORE appending the current user turn so the current message
+                // isn't counted as its own "prior history".
+                const prior = await transcripts.list({ userKey, limit });
+                if (prior.length > 0) {
+                    transcriptContext = {
+                        description: `Prior cross-platform conversation history with this user. Current channel: ${this.platform}.`,
+                        value: prior
+                            .map((e) => `[${e.platform}] ${e.role}: ${e.text}`)
+                            .join("\n"),
+                    };
+                }
+                if (this.deps.message) {
+                    await transcripts.append(this, this.deps.message, { userKey });
+                }
+            }
+            else {
+                warnTranscriptIgnored();
+            }
+        }
+        // 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 = [
+            ...this.deps.context,
+            ...(transcriptContext ? [transcriptContext] : []),
+            ...(extra?.context ?? []),
+        ];
+        // Snapshot the message count BEFORE the loop so we can isolate the
+        // assistant messages this run produced (step 4).
+        const messagesBefore = session.agent.messages.length;
+        const startedAt = Date.now();
+        let loopResult;
+        // Telemetry stage: "agent" while the run loop runs, "finalize" for the
+        // transcript-append + renderer.finish() steps below. A throw in either is
+        // reported as agent_run_failed (with the right stage) instead of being
+        // hidden behind an already-sent success event.
+        let stage = "agent";
+        try {
+            loopResult = 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,
+            });
+            stage = "finalize";
+            // Transcript auto-bridge (step 4): capture the assistant text this run
+            // produced and append it. Only when the bridge actually applied (transcripts
+            // + userKey both present and `transcript` was requested).
+            if (extra?.transcript && transcripts && userKey) {
+                const produced = session.agent.messages.slice(messagesBefore);
+                const text = produced
+                    .filter((m) => m.role === "assistant" &&
+                    typeof m.content === "string" &&
+                    m.content.trim().length > 0)
+                    .map((m) => m.content)
+                    .join("\n\n");
+                if (text.length > 0) {
+                    await transcripts.append(this, { role: "assistant", text }, { userKey });
+                }
+            }
+            // 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?.();
+        }
+        catch (err) {
+            // A throw is a run failure — in the agent loop (tool-handler errors are
+            // swallowed inside the loop, so a throw is agent-level) or in finalization.
+            // `stage` distinguishes the two.
+            this.deps.telemetry?.capture("oss.bot.agent_run_failed", {
+                platform: normalizePlatform(this.platform),
+                errorClass: errorClass(err),
+                stage,
+            });
+            throw err;
+        }
+        // Emit success ONLY after the loop AND finalization both completed, so a
+        // late transcript/finish rejection can never follow a success event.
+        this.deps.telemetry?.capture("oss.bot.agent_run", {
+            platform: normalizePlatform(this.platform),
+            durationMs: Date.now() - startedAt,
+            toolCallCount: renderer.getCapturedToolCalls().length,
+            iterations: loopResult.iterations,
+            interrupted: loopResult.interrupted,
+        });
+        return undefined;
+    }
+}
+let transcriptWarned = false;
+/** Warn once when `runAgent({ transcript })` is used without identity/transcripts configured. */
+function warnTranscriptIgnored() {
+    if (transcriptWarned)
+        return;
+    transcriptWarned = true;
+    console.warn("[bot] runAgent({ transcript }) ignored — configure store.identity + store.transcripts so a userKey resolves");
+}

package/dist/thread.test.d.ts

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

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

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

package/dist/thread.test.js

@@ -0,0 +1,83 @@
+import { describe, it, expect } from "vitest";
+import { Thread } from "./thread.js";
+import { MemoryStore } from "./state/memory-store.js";
+import { FakeAdapter } from "./testing/fake-adapter.js";
+import { ActionRegistry } from "./action-registry.js";
+import { InMemoryActionStore } from "./action-store.js";
+function makeTestThread(overrides) {
+    const adapter = new FakeAdapter();
+    const registry = new ActionRegistry({ store: new InMemoryActionStore() });
+    const deps = {
+        adapter,
+        replyTarget: {},
+        conversationKey: overrides.conversationKey ?? "c1",
+        registry,
+        agentFactory: (id) => {
+            throw new Error(`agentFactory not needed in this test: ${id}`);
+        },
+        tools: new Map(),
+        toolDescriptors: [],
+        context: [],
+        registerWaiter: () => { },
+        interruptHandlers: new Map(),
+        state: overrides.state,
+    };
+    return new Thread(deps);
+}
+describe("Thread.subscribe / unsubscribe / isSubscribed", () => {
+    it("subscribe marks the conversation as subscribed", async () => {
+        const state = new MemoryStore();
+        const thread = makeTestThread({ state, conversationKey: "c1" });
+        await thread.subscribe();
+        expect(await thread.isSubscribed()).toBe(true);
+    });
+    it("unsubscribe removes the subscription", async () => {
+        const state = new MemoryStore();
+        const thread = makeTestThread({ state, conversationKey: "c1" });
+        await thread.subscribe();
+        await thread.unsubscribe();
+        expect(await thread.isSubscribed()).toBe(false);
+    });
+    it("isSubscribed returns false before any subscribe call", async () => {
+        const state = new MemoryStore();
+        const thread = makeTestThread({ state, conversationKey: "c1" });
+        expect(await thread.isSubscribed()).toBe(false);
+    });
+    it("subscription state is keyed per conversationKey", async () => {
+        const state = new MemoryStore();
+        const t1 = makeTestThread({ state, conversationKey: "c1" });
+        const t2 = makeTestThread({ state, conversationKey: "c2" });
+        await t1.subscribe();
+        expect(await t1.isSubscribed()).toBe(true);
+        expect(await t2.isSubscribed()).toBe(false);
+    });
+});
+describe("Thread.setState / state", () => {
+    it("round-trips an arbitrary object", async () => {
+        const state = new MemoryStore();
+        const thread = makeTestThread({ state, conversationKey: "c1" });
+        await thread.setState({ step: "ask_name" });
+        expect(await thread.state()).toEqual({
+            step: "ask_name",
+        });
+    });
+    it("returns undefined before any setState call", async () => {
+        const state = new MemoryStore();
+        const thread = makeTestThread({ state, conversationKey: "c1" });
+        expect(await thread.state()).toBeUndefined();
+    });
+    it("overwrites a previous value", async () => {
+        const state = new MemoryStore();
+        const thread = makeTestThread({ state, conversationKey: "c1" });
+        await thread.setState({ step: "ask_name" });
+        await thread.setState({ step: "confirm" });
+        expect(await thread.state()).toEqual({ step: "confirm" });
+    });
+    it("state is keyed per conversationKey", async () => {
+        const state = new MemoryStore();
+        const t1 = makeTestThread({ state, conversationKey: "c1" });
+        const t2 = makeTestThread({ state, conversationKey: "c2" });
+        await t1.setState({ v: 1 });
+        expect(await t2.state()).toBeUndefined();
+    });
+});

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/channels-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,EACV,MAAM,EACN,eAAe,EACf,YAAY,EACb,MAAM,yBAAyB,CAAC;AAEjC,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"}