@copilotkit/channels 0.1.0

package/dist/tools.js

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

package/dist/tools.test.d.ts

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

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

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

package/dist/tools.test.js

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

package/dist/transcripts.d.ts

@@ -0,0 +1,52 @@
+import type { StateStore } from "./state/state-store.js";
+import type { PlatformUser, IncomingMessage } from "@copilotkit/channels-ui";
+export interface TranscriptEntry {
+    role: "user" | "assistant";
+    text: string;
+    platform: string;
+    threadId: string;
+    userKey: string;
+    ts: number;
+}
+export type Identity = (ctx: {
+    adapter: string;
+    author: PlatformUser;
+    message: IncomingMessage;
+}) => string | null | Promise<string | null>;
+export interface TranscriptsConfig {
+    retention?: string | number;
+    maxPerUser?: number;
+}
+export declare class Transcripts {
+    private state;
+    private cfg;
+    private readonly retentionMs;
+    constructor(state: StateStore, cfg?: TranscriptsConfig);
+    /**
+     * Append a message to the user's transcript.
+     * No-ops silently when no `userKey` is resolved (from `opts.userKey` or `msg.userKey`).
+     */
+    append(thread: {
+        platform: string;
+        conversationKey: string;
+    }, msg: {
+        role?: "user" | "assistant";
+        text: string;
+        userKey?: string;
+    }, opts?: {
+        userKey?: string;
+    }): Promise<void>;
+    list(q: {
+        userKey: string;
+        limit?: number;
+        platforms?: string[];
+        threadId?: string;
+        roles?: ("user" | "assistant")[];
+    }): Promise<TranscriptEntry[]>;
+    delete(q: {
+        userKey: string;
+    }): Promise<{
+        deleted: number;
+    }>;
+}
+//# sourceMappingURL=transcripts.d.ts.map

package/dist/transcripts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcripts.d.ts","sourceRoot":"","sources":["../src/transcripts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE7E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,eAAe,CAAC;CAC1B,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE7C,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,qBAAa,WAAW;IAIpB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,GAAG;IAJb,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAGvC,KAAK,EAAE,UAAU,EACjB,GAAG,GAAE,iBAAsB;IAMrC;;;OAGG;IACG,MAAM,CACV,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,EACrD,GAAG,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EACpE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1B,OAAO,CAAC,IAAI,CAAC;IA2BV,IAAI,CAAC,CAAC,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC;KAClC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAcxB,MAAM,CAAC,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAKnE"}

package/dist/transcripts.js

@@ -0,0 +1,67 @@
+import { parseDuration } from "./state/duration.js";
+const keyFor = (userKey) => `transcript:user:${userKey}`;
+export class Transcripts {
+    state;
+    cfg;
+    retentionMs;
+    constructor(state, cfg = {}) {
+        this.state = state;
+        this.cfg = cfg;
+        this.retentionMs =
+            cfg.retention !== undefined ? parseDuration(cfg.retention) : undefined;
+    }
+    /**
+     * Append a message to the user's transcript.
+     * No-ops silently when no `userKey` is resolved (from `opts.userKey` or `msg.userKey`).
+     */
+    async append(thread, msg, opts) {
+        const userKey = opts?.userKey ?? msg.userKey;
+        if (!userKey)
+            return; // identity unresolved → no-op
+        const entry = {
+            role: msg.role ?? "user",
+            text: msg.text,
+            platform: thread.platform,
+            threadId: thread.conversationKey,
+            userKey,
+            ts: Date.now(),
+        };
+        await this.state.list.append(keyFor(userKey), entry, {
+            maxLen: this.cfg.maxPerUser,
+            ttlMs: this.retentionMs,
+        });
+        if (this.retentionMs !== undefined) {
+            const cutoff = Date.now() - this.retentionMs;
+            const all = await this.state.list.range(keyFor(userKey));
+            const expired = all.filter((e) => e.ts < cutoff).length;
+            if (expired > 0) {
+                const survivors = all.length - expired;
+                if (survivors <= 0)
+                    await this.state.list.delete(keyFor(userKey));
+                else
+                    await this.state.list.trim(keyFor(userKey), survivors);
+            }
+        }
+    }
+    async list(q) {
+        let items = await this.state.list.range(keyFor(q.userKey));
+        if (this.retentionMs !== undefined) {
+            const cutoff = Date.now() - this.retentionMs;
+            items = items.filter((e) => e.ts >= cutoff);
+        }
+        if (q.platforms)
+            items = items.filter((e) => q.platforms.includes(e.platform));
+        if (q.threadId)
+            items = items.filter((e) => e.threadId === q.threadId);
+        if (q.roles)
+            items = items.filter((e) => q.roles.includes(e.role));
+        if (q.limit !== undefined)
+            items = items.slice(-q.limit);
+        return items; // oldest-first
+    }
+    async delete(q) {
+        const n = (await this.state.list.range(keyFor(q.userKey))).length;
+        await this.state.list.delete(keyFor(q.userKey));
+        return { deleted: n };
+    }
+}

package/dist/transcripts.test.d.ts

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

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

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

package/dist/transcripts.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi } from "vitest";
+import { MemoryStore } from "./state/memory-store.js";
+import { Transcripts } from "./transcripts.js";
+const thread = {
+    platform: "slack",
+    conversationKey: "slack:C1:1",
+};
+describe("Transcripts", () => {
+    it("appends and lists oldest-first, filters compose", async () => {
+        const t = new Transcripts(new MemoryStore(), { maxPerUser: 100 });
+        await t.append(thread, { role: "user", text: "hi" }, { userKey: "u@x.com" });
+        await t.append(thread, { role: "assistant", text: "hello" }, { userKey: "u@x.com" });
+        const all = await t.list({ userKey: "u@x.com" });
+        expect(all.map((e) => e.role)).toEqual(["user", "assistant"]);
+        expect(await t.list({ userKey: "u@x.com", roles: ["user"] })).toHaveLength(1);
+    });
+    it("delete wipes and reports count", async () => {
+        const t = new Transcripts(new MemoryStore());
+        await t.append(thread, { role: "user", text: "x" }, { userKey: "k" });
+        expect(await t.delete({ userKey: "k" })).toEqual({ deleted: 1 });
+        expect(await t.list({ userKey: "k" })).toEqual([]);
+    });
+    it("TTL expiry: entries not visible after retention window", async () => {
+        const t = new Transcripts(new MemoryStore(), { retention: "30ms" });
+        await t.append(thread, { role: "user", text: "hi" }, { userKey: "u" });
+        await new Promise((r) => setTimeout(r, 60));
+        expect(await t.list({ userKey: "u" })).toEqual([]);
+    });
+    it("maxPerUser: only newest N entries are kept", async () => {
+        const t = new Transcripts(new MemoryStore(), { maxPerUser: 2 });
+        await t.append(thread, { role: "user", text: "1" }, { userKey: "u" });
+        await t.append(thread, { role: "user", text: "2" }, { userKey: "u" });
+        await t.append(thread, { role: "user", text: "3" }, { userKey: "u" });
+        const entries = await t.list({ userKey: "u" });
+        expect(entries).toHaveLength(2);
+        expect(entries.map((e) => e.text)).toEqual(["2", "3"]);
+    });
+    it("no userKey resolved: no-op, list returns empty for any key", async () => {
+        const t = new Transcripts(new MemoryStore());
+        // neither opts.userKey nor msg.userKey is set
+        await t.append(thread, { role: "user", text: "ghost" });
+        expect(await t.list({ userKey: "anyone" })).toEqual([]);
+    });
+    it("list with limit: returns only the last N entries", async () => {
+        const t = new Transcripts(new MemoryStore());
+        await t.append(thread, { role: "user", text: "a" }, { userKey: "u" });
+        await t.append(thread, { role: "user", text: "b" }, { userKey: "u" });
+        await t.append(thread, { role: "user", text: "c" }, { userKey: "u" });
+        const last = await t.list({ userKey: "u", limit: 1 });
+        expect(last).toHaveLength(1);
+        expect(last[0].text).toBe("c");
+    });
+    it("bogus retention string throws at construction", () => {
+        expect(() => new Transcripts(new MemoryStore(), { retention: "bogus" })).toThrow();
+    });
+});
+describe("Transcripts retention", () => {
+    it("list() does not return entries older than the retention window", async () => {
+        const store = new MemoryStore();
+        const t = new Transcripts(store, { retention: "1h" });
+        vi.useFakeTimers();
+        try {
+            await t.append(thread, { role: "user", text: "old" }, { userKey: "u" });
+            vi.advanceTimersByTime(2 * 60 * 60 * 1000); // advance 2h
+            expect(await t.list({ userKey: "u" })).toEqual([]);
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+    it("append prunes entries older than retention while the list is kept alive", async () => {
+        // Isolates the prune path from the whole-key sliding TTL: each append
+        // refreshes the 1h key TTL, so the list never expires wholesale. A is
+        // only ever removed by the per-entry age prune — if the prune block were
+        // deleted, the whole-key TTL would keep all three entries alive and this
+        // would read length 3.
+        const store = new MemoryStore();
+        const t = new Transcripts(store, { retention: "1h" });
+        vi.useFakeTimers();
+        try {
+            await t.append(thread, { role: "user", text: "A" }, { userKey: "u" });
+            vi.advanceTimersByTime(50 * 60 * 1000); // +50m: A still within window, key TTL refreshed to +110m
+            await t.append(thread, { role: "user", text: "B" }, { userKey: "u" });
+            vi.advanceTimersByTime(50 * 60 * 1000); // +100m: key still live (expires +110m), but A is now 100m old
+            await t.append(thread, { role: "user", text: "C" }, { userKey: "u" });
+            const raw = await store.list.range("transcript:user:u");
+            expect(raw.map((e) => e.text)).toEqual(["B", "C"]); // A pruned by age, not whole-key expiry
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+    it("recent entries within the window are kept", async () => {
+        const store = new MemoryStore();
+        const t = new Transcripts(store, { retention: "1h" });
+        vi.useFakeTimers();
+        try {
+            await t.append(thread, { role: "user", text: "A" }, { userKey: "u" });
+            vi.advanceTimersByTime(30 * 60 * 1000); // advance 30m — A still within 1h
+            await t.append(thread, { role: "user", text: "B" }, { userKey: "u" });
+            const entries = await t.list({ userKey: "u" });
+            expect(entries).toHaveLength(2);
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+});

package/package.json

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