@copilotkit/channels 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export { createBot } from "./create-bot.js";
+export type { Bot, CreateBotOptions, BotHandler, ThreadStartHandler, ReactionEvent, ReactionHandler, ModalSubmitEvent, ModalSubmitHandler, ModalCloseEvent, ModalCloseHandler, StoreConfig, LockConflictDecision, StatefulThread, BotComponent, } from "./create-bot.js";
+export { Thread } from "./thread.js";
+export type { ThreadDeps } from "./thread.js";
+export type { PlatformAdapter, AdapterStartContext, RunRenderer, IngressSink, IncomingTurn, InteractionEvent, IncomingCommand, IncomingThreadStart, IncomingReaction, IncomingModalSubmit, IncomingModalClose, ModalSubmitResult, SurfaceCapabilities, ReplyTarget, ConversationStore, AgentSession, CapturedToolCall, CapturedInterrupt, UserQuery, NativePayload, } from "./platform-adapter.js";
+export { defineBotCommand, normalizeCommandName, toCommandSpec, } from "./commands.js";
+export type { BotCommand, CommandContext, CommandSpec } from "./commands.js";
+export { InMemoryActionStore } from "./action-store.js";
+export type { ActionStore, ActionSnapshot } from "./action-store.js";
+export { ActionRegistry, ActionExpiredError } from "./action-registry.js";
+export type { StateStore } from "./state/state-store.js";
+export { MemoryStore } from "./state/memory-store.js";
+export { parseDuration } from "./state/duration.js";
+export { createStateBackedConversationStore } from "./state/state-conversation-store.js";
+export { Transcripts } from "./transcripts.js";
+export type { TranscriptEntry, Identity, TranscriptsConfig, } from "./transcripts.js";
+export { toAgentToolDescriptors, parseToolArgs, stringifyHandlerResult, defineBotTool, } from "./tools.js";
+export type { BotTool, ObjectSchema, BotToolContext, ContextEntry, AgentToolDescriptor, } from "./tools.js";
+export { mintId, stableStringify } from "./mint-id.js";
+export { runAgentLoop } from "./run-loop.js";
+export type { RunLoopArgs } from "./run-loop.js";
+export type { PlatformCodec } from "./codec.js";
+export { FakeAdapter, makeFakeRunRenderer } from "./testing/fake-adapter.js";
+export { FakeAgent } from "./testing/fake-agent.js";
+export * from "@copilotkit/channels-ui";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EACV,GAAG,EACH,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,YAAY,GACb,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,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,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAMtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kCAAkC,EAAE,MAAM,qCAAqC,CAAC;AAGzF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EACV,eAAe,EACf,QAAQ,EACR,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,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;AAKjD,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGpD,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,32 @@
+// Public API for @copilotkit/channels.
+// Bot orchestration
+export { createBot } from "./create-bot.js";
+// Thread
+export { Thread } from "./thread.js";
+// Slash commands
+export { defineBotCommand, normalizeCommandName, toCommandSpec, } from "./commands.js";
+// Action store
+export { InMemoryActionStore } from "./action-store.js";
+// Action registry
+export { ActionRegistry, ActionExpiredError } from "./action-registry.js";
+export { MemoryStore } from "./state/memory-store.js";
+// NOTE: `runStateStoreConformance` is intentionally NOT re-exported here. It
+// pulls in `vitest`, so re-exporting it from the package entry would drag a
+// test framework into every consumer's runtime module graph (a bare
+// `import ... from "@copilotkit/channels"` would fail unless vitest is installed).
+// It is published under the `@copilotkit/channels/testing` subpath instead.
+export { parseDuration } from "./state/duration.js";
+export { createStateBackedConversationStore } from "./state/state-conversation-store.js";
+// Transcripts
+export { Transcripts } from "./transcripts.js";
+// Tools & context
+export { toAgentToolDescriptors, parseToolArgs, stringifyHandlerResult, defineBotTool, } from "./tools.js";
+// Id / serialization helpers
+export { mintId, stableStringify } from "./mint-id.js";
+// Run loop
+export { runAgentLoop } from "./run-loop.js";
+// Test utilities (also surfaces them for downstream adapter packages' tests).
+export { FakeAdapter, makeFakeRunRenderer } from "./testing/fake-adapter.js";
+export { FakeAgent } from "./testing/fake-agent.js";
+// Re-export the bot-ui component vocabulary + types for convenience.
+export * from "@copilotkit/channels-ui";

package/dist/mint-id.d.ts

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

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

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

package/dist/mint-id.js

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

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

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

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

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

package/dist/mint-id.test.js

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

package/dist/modal-submit.test.d.ts

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

package/dist/modal-submit.test.d.ts.map

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

package/dist/modal-submit.test.js

@@ -0,0 +1,68 @@
+// packages/channels/src/modal-submit.test.ts
+import { describe, it, expect } from "vitest";
+import { createBot } from "./create-bot.js";
+import { FakeAdapter } from "./testing/fake-adapter.js";
+describe("bot.onModalSubmit / onModalClose", () => {
+    it("routes a submission by callbackId and parses values; thread present when conversation context exists", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        const seen = [];
+        bot.onModalSubmit("triage", (evt) => {
+            seen.push({
+                values: evt.values,
+                user: evt.user?.id,
+                cb: evt.callbackId,
+                hasThread: !!evt.thread,
+            });
+        });
+        await bot.start();
+        const res = await fake.emitModalSubmit({
+            callbackId: "triage",
+            values: { summary: "boom", prio: "high" },
+            user: { id: "U1" },
+            conversationKey: "c",
+            replyTarget: {},
+        });
+        expect(res).toBeUndefined(); // no errors → closes
+        expect(seen).toEqual([
+            {
+                values: { summary: "boom", prio: "high" },
+                user: "U1",
+                cb: "triage",
+                hasThread: true,
+            },
+        ]);
+    });
+    it("returns the handler's field errors so the adapter can keep the modal open", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        bot.onModalSubmit("triage", (evt) => evt.values.summary ? undefined : { errors: { summary: "Required" } });
+        await bot.start();
+        const res = await fake.emitModalSubmit({
+            callbackId: "triage",
+            values: {},
+        });
+        expect(res).toEqual({ errors: { summary: "Required" } });
+    });
+    it("ignores submissions with no registered handler", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        await bot.start();
+        const res = await fake.emitModalSubmit({
+            callbackId: "unknown",
+            values: {},
+        });
+        expect(res).toBeUndefined();
+    });
+    it("routes a close by callbackId", async () => {
+        const fake = new FakeAdapter();
+        const bot = createBot({ adapters: [fake] });
+        const closed = [];
+        bot.onModalClose("triage", (evt) => {
+            closed.push(evt.callbackId);
+        });
+        await bot.start();
+        await fake.emitModalClose({ callbackId: "triage", user: { id: "U2" } });
+        expect(closed).toEqual(["triage"]);
+    });
+});

package/dist/platform-adapter.d.ts

@@ -0,0 +1,312 @@
+import type { AgentSubscriber, AbstractAgent } from "@ag-ui/client";
+import type { AgentContentPart, BotNode, EmojiValue, EphemeralResult, MessageRef, PlatformUser, ThreadMessage } from "@copilotkit/channels-ui";
+import type { CommandSpec } from "./commands.js";
+import type { StateStore } from "./state/state-store.js";
+/** Opaque to the bot core — created by an adapter during ingress and passed back to post/createRunRenderer. */
+export type ReplyTarget = unknown;
+/** Opaque native payload produced by an adapter's render(). */
+export type NativePayload = unknown;
+export interface SurfaceCapabilities {
+    supportsModals: boolean;
+    supportsTyping: boolean;
+    supportsReactions: boolean;
+    supportsStreaming: boolean;
+    maxBlocksPerMessage?: number;
+    /** Pinned prompt chips on a conversation surface (Slack assistant pane). */
+    supportsSuggestedPrompts?: boolean;
+    /** Nameable conversations (Slack assistant-thread titles). */
+    supportsThreadTitle?: boolean;
+    /** Native ephemeral messages (Slack). When false, `postEphemeral` still works via DM fallback. */
+    supportsEphemeral?: boolean;
+    [k: string]: unknown;
+}
+export interface CapturedToolCall {
+    toolCallId: string;
+    toolCallName: string;
+    toolCallArgs: Record<string, unknown>;
+}
+export interface CapturedInterrupt {
+    eventName: string;
+    value: unknown;
+}
+/** A per-run handle: the AG-UI subscriber to stream into, plus capture accessors the run-loop reads after each runAgent. */
+export interface RunRenderer {
+    subscriber: AgentSubscriber;
+    markInterrupted(): Promise<void>;
+    getCapturedToolCalls(): readonly CapturedToolCall[];
+    getPendingInterrupt(): CapturedInterrupt | undefined;
+    clearPendingInterrupt(): void;
+    /**
+     * 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>;
+}
+/**
+ * Fields shared by every ingress event routed through the {@link IngressSink}:
+ * the conversation it belongs to, the opaque target to reply on, and the user
+ * who triggered it (when the platform reports one).
+ */
+export interface IngressEventBase {
+    conversationKey: string;
+    replyTarget: ReplyTarget;
+    user?: PlatformUser;
+}
+/**
+ * Idempotency ids carried by turn/command/interaction ingress. Set on the
+ * managed (Intelligence-delivered) path; local adapters omit them.
+ */
+export interface IngressIds {
+    /** Stable platform event id for idempotency; omit if the platform provides none. */
+    eventId?: string;
+    /** Stable per-turn id (managed/Intelligence path); local adapters omit it. */
+    turnId?: string;
+    /** Lease/delivery id (managed/Intelligence path); local adapters omit it. */
+    deliveryId?: string;
+}
+export interface IncomingTurn extends IngressEventBase, IngressIds {
+    userText: string;
+    /**
+     * Optional multimodal content parts built by the adapter (e.g. inbound
+     * image/file attachments). Carried through to `IncomingMessage.contentParts`.
+     */
+    contentParts?: AgentContentPart[];
+    platform: string;
+}
+export interface InteractionEvent extends IngressEventBase, IngressIds {
+    id: string;
+    value?: unknown;
+    /** The message the interaction occurred on (the picker), so handlers can update it in place. */
+    messageRef?: MessageRef;
+    /** Opaque platform trigger for opening a modal (Slack `trigger_id`; Discord interaction id). */
+    triggerId?: string;
+}
+/** A slash-command invocation normalized by an adapter. */
+export interface IncomingCommand extends IngressEventBase, IngressIds {
+    /** Command name as invoked (a leading slash and case are normalized by the engine). */
+    command: string;
+    /** Raw argument string after the command name (the form text-only surfaces deliver). */
+    text: string;
+    /** Structured, pre-parsed options when the surface delivers them (e.g. Discord). */
+    rawOptions?: Record<string, unknown>;
+    platform: string;
+    /** Opaque platform trigger for opening a modal (Slack `trigger_id`; Discord interaction id). */
+    triggerId?: string;
+}
+/**
+ * A "conversation opened" lifecycle event (Slack: `assistant_thread_started`).
+ * Adapters without the concept never emit it.
+ */
+export interface IncomingThreadStart extends IngressEventBase {
+    platform: string;
+}
+/** A reaction added/removed on a message. Adapters that can't observe reactions never emit it. */
+export interface IncomingReaction extends IngressEventBase {
+    /** Platform-native emoji token (Slack shortcode, Unicode, Discord custom). */
+    rawEmoji: string;
+    /** true = added, false = removed. */
+    added: boolean;
+    /** Id of the reacted-to message. */
+    messageId: string;
+    /**
+     * Update-capable ref to the reacted message (the platform-specific shape the
+     * adapter's `update`/`delete` accept). Lets a `<Message onReaction>` handler
+     * swap the message's UI in place. Adapters that can edit messages should set
+     * this; the engine falls back to `{ id: messageId }` when omitted.
+     */
+    messageRef?: MessageRef;
+    /** Containing thread/conversation id, when distinct from the message. */
+    threadId?: string;
+    /** Native payload. */
+    raw: unknown;
+}
+/** A modal submission. Adapters without modals never emit it. */
+export interface IncomingModalSubmit {
+    callbackId: string;
+    /** Field id → value (text string, selected option value, etc.). */
+    values: Record<string, unknown>;
+    user?: PlatformUser;
+    privateMetadata?: string;
+    /** Present when the submission carries a conversation context (so the engine can build a Thread). */
+    conversationKey?: string;
+    replyTarget?: ReplyTarget;
+    platform: string;
+    raw: unknown;
+}
+/** A modal dismissal (Slack `view_closed`; requires `notifyOnClose`). */
+export interface IncomingModalClose {
+    callbackId: string;
+    user?: PlatformUser;
+    privateMetadata?: string;
+    /** Present when the dismissal carries a conversation context (so the engine can build a Thread). */
+    conversationKey?: string;
+    replyTarget?: ReplyTarget;
+    platform: string;
+    raw: unknown;
+}
+/** What a submit handler may return to keep the modal open with per-field errors. */
+export interface ModalSubmitResult {
+    errors?: Record<string, 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>;
+    /** A reaction was added/removed. Adapters that can't observe reactions never call it. */
+    onReaction(evt: IncomingReaction): void | Promise<void>;
+    /**
+     * A modal was submitted. Returns the handler's result so the adapter can ack
+     * with per-field errors (Slack `response_action: "errors"`). Adapters without
+     * modals never call it.
+     */
+    onModalSubmit(evt: IncomingModalSubmit): Promise<ModalSubmitResult | void>;
+    /** A modal was dismissed. Adapters without `view_closed` never call it. */
+    onModalClose(evt: IncomingModalClose): void | Promise<void>;
+}
+export interface UserQuery {
+    query: string;
+}
+/** A resolved agent session for a conversation (the adapter may build the agent's history from its own state). */
+export interface AgentSession {
+    agent: AbstractAgent;
+}
+/** Adapter-owned conversation state; the adapter resolves (or creates) the agent session for a conversation. */
+export interface ConversationStore {
+    getOrCreate(conversationKey: string, replyTarget: ReplyTarget, makeAgent: (threadId: string) => AbstractAgent): Promise<AgentSession>;
+}
+/**
+ * Optional context bot core passes to {@link PlatformAdapter.start}. Carries
+ * the bot's declared identity so a transport that must announce itself (e.g.
+ * the managed Intelligence adapter's heartbeat) can do so without separate
+ * config. Local adapters ignore it.
+ */
+export interface AdapterStartContext {
+    /** The bot's declared name (`createBot({ name })`), when set. */
+    botName?: string;
+}
+export interface PlatformAdapter {
+    readonly platform: string;
+    readonly capabilities: SurfaceCapabilities;
+    readonly ackDeadlineMs: number;
+    start(sink: IngressSink, ctx?: AdapterStartContext): Promise<void>;
+    stop(): Promise<void>;
+    render(ir: BotNode[]): NativePayload;
+    post(target: ReplyTarget, ir: BotNode[]): Promise<MessageRef>;
+    update(ref: MessageRef, ir: BotNode[]): Promise<void>;
+    stream(target: ReplyTarget, chunks: AsyncIterable<string>): Promise<MessageRef>;
+    delete(ref: MessageRef): Promise<void>;
+    createRunRenderer(target: ReplyTarget): RunRenderer;
+    decodeInteraction(raw: unknown): InteractionEvent | undefined;
+    lookupUser(q: UserQuery): Promise<PlatformUser | undefined>;
+    readonly conversationStore: ConversationStore;
+    /**
+     * Optional persistence backend supplied by the adapter. `createBot` uses it
+     * only when no explicit `store.adapter` is configured; if more than one
+     * adapter provides one, `createBot` warns and uses the first. Distinct from
+     * {@link conversationStore}.
+     */
+    readonly stateStore?: StateStore;
+    /** @internal Marks the managed adapter; bot core uses it for the V1 exclusivity guard. */
+    readonly __managed?: boolean;
+    /**
+     * When true, bot core skips its ingress dedup for events from this adapter.
+     * Set by at-least-once transports (managed delivery) that enforce
+     * idempotency at egress instead — dropping a redelivery at ingress would lose
+     * a legitimate retry.
+     */
+    readonly skipIngressDedup?: boolean;
+    /**
+     * Optional conversation-history read. Backs the capability-gated
+     * `Thread.getMessages()`; adapters that can't read history simply omit this,
+     * and `Thread.getMessages()` returns `[]`.
+     */
+    getMessages?(target: ReplyTarget): Promise<ThreadMessage[]>;
+    /**
+     * Optional platform file upload. Threads expose `postFile` unconditionally;
+     * adapters that can't upload simply omit this, and `Thread.postFile` returns
+     * a capability-gated `{ ok: false, error }`.
+     */
+    postFile?(target: ReplyTarget, args: {
+        bytes: Uint8Array;
+        filename: string;
+        title?: string;
+        altText?: string;
+    }): Promise<{
+        ok: boolean;
+        fileId?: string;
+        error?: string;
+    }>;
+    /**
+     * Optional slash-command support. Called once on `start()` with the bot's
+     * declared commands, so a surface that registers commands up front (e.g.
+     * Discord's application-command API) can publish them. Surfaces that match
+     * commands dynamically (e.g. Slack, which forwards every `/command` to
+     * `sink.onCommand`) need not implement this; adapters that don't support
+     * commands at all simply omit it and command handlers never fire there.
+     */
+    registerCommands?(commands: readonly CommandSpec[]): void | Promise<void>;
+    /**
+     * 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;
+    }>;
+    /**
+     * Optional reactions egress (backs `Thread.react`/`unreact`). Adapters without
+     * reactions omit these; the Thread methods then return `{ ok: false, error }`.
+     */
+    addReaction?(target: ReplyTarget, messageRef: MessageRef, emoji: EmojiValue): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    removeReaction?(target: ReplyTarget, messageRef: MessageRef, emoji: EmojiValue): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /**
+     * Optional ephemeral post (backs `Thread.postEphemeral`). The adapter decides
+     * native vs DM fallback based on `opts.fallbackToDM` and returns
+     * `{ ok, usedFallback }` or `null` (native unsupported and no fallback).
+     */
+    postEphemeral?(target: ReplyTarget, user: PlatformUser | string, ir: BotNode[], opts: {
+        fallbackToDM: boolean;
+    }): Promise<EphemeralResult | null>;
+    /** Optional modal render (pure; backs `openModal`). Throws `ModalRenderError` on unsupported elements. */
+    renderModal?(ir: BotNode[]): NativePayload;
+    /**
+     * Optional modal open (backs context `openModal`). Renders `ir` and opens it
+     * against the platform `triggerId`. Returns `{ ok: false }` on failure
+     * (expired trigger, unsupported elements) — never throws.
+     */
+    openModal?(target: ReplyTarget, triggerId: string, ir: BotNode[]): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=platform-adapter.d.ts.map

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

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

package/dist/platform-adapter.js

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

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

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

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

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

package/dist/platform-adapter.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { FakeAdapter } from "./testing/fake-adapter.js";
+describe("FakeAdapter", () => {
+    it("records posts and drives ingress", async () => {
+        const a = new FakeAdapter();
+        let got;
+        await a.start({
+            onTurn: (t) => {
+                got = t.userText;
+            },
+            onInteraction: () => { },
+            onCommand: () => { },
+            onThreadStarted: () => { },
+            onReaction: () => { },
+            onModalSubmit: async () => { },
+            onModalClose: () => { },
+        });
+        a.emitTurn({ userText: "hi" });
+        expect(got).toBe("hi");
+        await a.post({}, [{ type: "text", props: { value: "x" } }]);
+        expect(a.posted.length).toBe(1);
+    });
+    it("delivers interactions to the sink", async () => {
+        const a = new FakeAdapter();
+        let id;
+        await a.start({
+            onTurn: () => { },
+            onInteraction: (e) => {
+                id = e.id;
+            },
+            onCommand: () => { },
+            onThreadStarted: () => { },
+            onReaction: () => { },
+            onModalSubmit: async () => { },
+            onModalClose: () => { },
+        });
+        a.emitInteraction({ id: "ck:abc" });
+        expect(id).toBe("ck:abc");
+    });
+});

package/dist/reactions.test.d.ts

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

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

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