@copilotkit/runtime 1.57.3 → 1.58.0-canary.thread-id-propagation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/runtime",
-  "version": "1.57.3",
+  "version": "1.58.0-canary.thread-id-propagation",
   "private": false,
   "keywords": [
     "ai",
@@ -12,6 +12,7 @@
     "nextjs",
     "nodejs",
     "react",
+    "tanstack-intent",
     "textarea"
   ],
   "homepage": "https://github.com/CopilotKit/CopilotKit",
@@ -20,6 +21,10 @@
     "type": "git",
     "url": "https://github.com/CopilotKit/CopilotKit.git"
   },
+  "files": [
+    "dist",
+    "skills"
+  ],
   "sideEffects": [
     "./dist/index.mjs",
     "./dist/index.cjs",
@@ -29,22 +34,6 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
-  "typesVersions": {
-    "*": {
-      "v2": [
-        "./dist/v2/index.d.cts"
-      ],
-      "v2/express": [
-        "./dist/v2/express.d.cts"
-      ],
-      "v2/hono": [
-        "./dist/v2/hono.d.cts"
-      ],
-      "v2/node": [
-        "./dist/v2/node.d.cts"
-      ]
-    }
-  },
   "exports": {
     ".": {
       "import": "./dist/index.mjs",
@@ -80,7 +69,7 @@
     "@ag-ui/client": "0.0.53",
     "@ag-ui/core": "0.0.53",
     "@ag-ui/encoder": "0.0.53",
-    "@ag-ui/langgraph": "0.0.31",
+    "@ag-ui/langgraph": "0.0.34",
     "@ag-ui/mcp-apps-middleware": "0.0.3",
     "@ai-sdk/anthropic": "^3.0.49",
     "@ai-sdk/google": "^3.0.33",
@@ -115,11 +104,12 @@
     "uuid": "^10.0.0",
     "ws": "^8.18.0",
     "zod": "^3.23.3",
-    "@copilotkit/shared": "1.57.3"
+    "@copilotkit/shared": "1.58.0-canary.thread-id-propagation"
   },
   "devDependencies": {
     "@copilotkit/aimock": "latest",
     "@swc/core": "1.5.28",
+    "@tanstack/intent": "^0.0.29",
     "@types/cors": "^2.8.17",
     "@types/express": "^4.17.21",
     "@types/node": "^18.11.17",

package/skills/runtime/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: runtime
+description: >
+  @copilotkit/runtime — mount a fetch-native CopilotRuntime on any JS server, wire
+  middleware, pick an AgentRunner, instantiate BuiltInAgent (Factory Mode with TanStack AI
+  is the preferred default) or plug in any of 12 external agent frameworks (Mastra,
+  LangGraph, CrewAI Crews/Flows, PydanticAI, ADK, LlamaIndex, Agno, AWS Strands, MS Agent
+  Framework, AG2, A2A), enable Intelligence mode for durable threads + websocket,
+  register server-side tools via defineTool, and wire voice transcription. Uses the
+  fetch-based createCopilotRuntimeHandler primitive — the Express/Hono adapters are
+  discouraged. Load the reference under references/ that matches your task.
+type: core
+library: copilotkit
+library_version: "1.56.2"
+requires: []
+sources:
+  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/core/fetch-handler.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/core/runtime.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/core/hooks.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/core/middleware.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/runner/agent-runner.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/runner/in-memory.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/runner/intelligence.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/intelligence-platform/client.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/transcription-service/transcription-service.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/v2/runtime/handlers/handle-transcribe.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/agent/index.ts"
+  - "CopilotKit/CopilotKit:packages/runtime/src/agent/converters/tanstack.ts"
+  - "CopilotKit/CopilotKit:packages/sqlite-runner/src/sqlite-runner.ts"
+  - "CopilotKit/CopilotKit:packages/shared/src/transcription-errors.ts"
+---
+
+# CopilotKit Runtime
+
+`@copilotkit/runtime` is the server half of CopilotKit: it accepts AG-UI protocol
+requests, dispatches them to an `AbstractAgent` (built-in or external), runs the
+stream through an `AgentRunner`, and responds as Server-Sent Events.
+
+This SKILL.md is the **index**. Read the reference under `references/` that matches
+your task — do not try to absorb the whole package from this file.
+
+## Mental Model — the three dictionaries you hand to `CopilotRuntime`
+
+```ts
+new CopilotRuntime({
+  agents, // Record<string, AbstractAgent>     — see wiring-external-agents or built-in-agent
+  runner, // AgentRunner (optional)            — see agent-runners
+  intelligence, // CopilotKitIntelligence (optional) — see intelligence-mode (auto-wires runner)
+  mcpApps, // McpAppsConfig (optional)          — see wiring-mcp-apps-middleware
+  a2ui, // A2UIConfig (optional)             — see packages/a2ui-renderer skill
+  hooks, // { onRequest, onBeforeHandler }    — see middleware
+  beforeRequestMiddleware,
+  afterRequestMiddleware, // legacy — see middleware
+  transcription, // TranscriptionService (optional)  — see transcription
+});
+```
+
+You then mount it:
+
+```ts
+import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+export default { fetch: handler };
+```
+
+## When to load which reference
+
+| Task                                                                                                                                                                           | Reference                                                                                                                                                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Mounting on any fetch-native server (Cloudflare Workers, Bun, Deno, Vercel Edge, Next.js App Router, React Router v7, TanStack Start) or delegating from Express/Node          | `references/setup-endpoint.md`                                                                                                                                                                                                                                                                                                                     |
+| Auth / logging / rate-limit / request-scoped guards via `hooks.onRequest` / `hooks.onBeforeHandler` (preferred) or legacy `beforeRequestMiddleware` / `afterRequestMiddleware` | `references/middleware.md`                                                                                                                                                                                                                                                                                                                         |
+| Choosing between `InMemoryAgentRunner`, `SqliteAgentRunner`, or a custom subclass — including thread-locking semantics and the runner/Intelligence mutual exclusion            | `references/agent-runners.md` (+ `-in-memory.md`, `-sqlite.md`, `-custom.md` for backend-specific detail)                                                                                                                                                                                                                                          |
+| Enabling durable threads + realtime websocket via CopilotKit Cloud (Intelligence is **Cloud-only**, not self-hostable)                                                         | `references/intelligence-mode.md`                                                                                                                                                                                                                                                                                                                  |
+| Voice transcription — implementing a `TranscriptionService` subclass for the `/transcribe` endpoint                                                                            | `references/transcription.md`                                                                                                                                                                                                                                                                                                                      |
+| Instantiating `BuiltInAgent` — Simple Mode (classic) or Factory Mode with TanStack AI (preferred AG-UI-compliant default), AI SDK, or custom factory                           | `references/built-in-agent.md` (+ `-factory-modes.md`, `-helper-utilities.md`, `-model-identifiers.md`)                                                                                                                                                                                                                                            |
+| Defining server-side tools via `defineTool` for `BuiltInAgent.config.tools` (Simple Mode only)                                                                                 | `references/server-side-tools.md`                                                                                                                                                                                                                                                                                                                  |
+| Wiring an external agent framework into `CopilotRuntime({ agents })`                                                                                                           | `references/wiring-external-agents.md` (index) + per-framework refs (`wiring-mastra.md`, `wiring-langgraph.md`, `wiring-crewai-crews.md`, `wiring-crewai-flows.md`, `wiring-pydantic-ai.md`, `wiring-adk.md`, `wiring-llamaindex.md`, `wiring-agno.md`, `wiring-aws-strands.md`, `wiring-ms-agent-framework.md`, `wiring-ag2.md`, `wiring-a2a.md`) |
+| Wiring MCP Apps (runtime-level middleware, not an agent)                                                                                                                       | `references/wiring-mcp-apps-middleware.md`                                                                                                                                                                                                                                                                                                         |
+
+## Invariants and gotchas (load-once, before any reference)
+
+- `createCopilotRuntimeHandler` is the canonical primitive. `createCopilotExpressHandler` / `createCopilotHonoHandler` exist but are **avoid at all costs** — delegate from Express/Hono routes to the fetch primitive instead.
+- `publicLicenseKey` is the canonical provider-side field. `publicApiKey` is a **deprecated alias** — expect to see it in legacy code, emit the canonical name in new code.
+- Intelligence mode auto-wires `IntelligenceAgentRunner`. Passing both `runner` and `intelligence` to `CopilotRuntime` is rejected at construction.
+- Intelligence mode targets CopilotKit Cloud (`api.cloud.copilotkit.ai`) and is **not self-hostable**.
+- `hooks.onRequest` runs **before** `beforeRequestMiddleware` (hook-based middleware wins for Response short-circuits). `beforeRequestMiddleware` runs **after** `hooks.onRequest` (see `fetch-handler.ts:136-147`).
+- `identifyUser` (Intelligence) does **not** forward thrown `Response` objects — convert to 500. Gate auth rejection in `hooks.onRequest`, which does forward Responses.
+- `agents__unsafe_dev_only` and `selfManagedAgents` are dev-only aliases of each other; do not reach for them in production. Either signals that the SPA is in dev mode.
+
+## Reading order for a first-time reader
+
+1. `setup-endpoint` — the primitive.
+2. `built-in-agent` **or** pick one from `wiring-external-agents` — the agent.
+3. `agent-runners` — production persistence choice.
+4. Optional: `middleware`, `intelligence-mode`, `server-side-tools`, `transcription`.

package/skills/runtime/references/agent-runners-custom.md

@@ -0,0 +1,161 @@
+Custom AgentRunner — subclass the abstract `AgentRunner` to back thread state with Redis,
+Postgres, Durable Objects, or anything else you own.
+
+## The abstract contract
+
+```typescript
+// packages/runtime/src/v2/runtime/runner/agent-runner.ts
+import {
+  AbstractAgent,
+  BaseEvent,
+  Message,
+  RunAgentInput,
+} from "@ag-ui/client";
+import { Observable } from "rxjs";
+
+export interface AgentRunnerRunRequest {
+  threadId: string;
+  agent: AbstractAgent;
+  input: RunAgentInput;
+  joinCode?: string;
+  persistedInputMessages?: Message[];
+}
+export interface AgentRunnerConnectRequest {
+  threadId: string;
+  headers?: Record<string, string>;
+  joinCode?: string;
+}
+export interface AgentRunnerIsRunningRequest {
+  threadId: string;
+}
+export interface AgentRunnerStopRequest {
+  threadId: string;
+}
+
+export abstract class AgentRunner {
+  abstract run(request: AgentRunnerRunRequest): Observable<BaseEvent>;
+  abstract connect(request: AgentRunnerConnectRequest): Observable<BaseEvent>;
+  abstract isRunning(request: AgentRunnerIsRunningRequest): Promise<boolean>;
+  abstract stop(request: AgentRunnerStopRequest): Promise<boolean | undefined>;
+}
+```
+
+## Redis-backed skeleton (for reference)
+
+```typescript
+import { AgentRunner } from "@copilotkit/runtime/v2";
+import type {
+  AgentRunnerRunRequest,
+  AgentRunnerConnectRequest,
+  AgentRunnerIsRunningRequest,
+  AgentRunnerStopRequest,
+} from "@copilotkit/runtime/v2";
+import { Observable, ReplaySubject } from "rxjs";
+import type { BaseEvent } from "@ag-ui/client";
+import { Redis } from "ioredis";
+
+const RUNNING_KEY = (t: string) => `copilotkit:running:${t}`;
+const STREAM_KEY = (t: string) => `copilotkit:stream:${t}`;
+
+export class RedisAgentRunner extends AgentRunner {
+  constructor(private redis: Redis) {
+    super();
+  }
+
+  run(request: AgentRunnerRunRequest): Observable<BaseEvent> {
+    const { threadId, agent, input } = request;
+    const subject = new ReplaySubject<BaseEvent>();
+
+    (async () => {
+      // NX guard — return 409-equivalent if another instance is running this thread
+      const acquired = await this.redis.set(
+        RUNNING_KEY(threadId),
+        "1",
+        "EX",
+        600,
+        "NX",
+      );
+      if (!acquired) {
+        subject.error(new Error("Thread already running"));
+        return;
+      }
+
+      const sub = agent.run(input).subscribe({
+        next: async (event) => {
+          subject.next(event);
+          await this.redis.xadd(
+            STREAM_KEY(threadId),
+            "*",
+            "event",
+            JSON.stringify(event),
+          );
+        },
+        error: async (err) => {
+          subject.error(err);
+          await this.redis.del(RUNNING_KEY(threadId));
+        },
+        complete: async () => {
+          subject.complete();
+          await this.redis.del(RUNNING_KEY(threadId));
+        },
+      });
+
+      // stop hook
+      this.stopHandlers.set(threadId, () => sub.unsubscribe());
+    })();
+
+    return subject.asObservable();
+  }
+
+  connect(request: AgentRunnerConnectRequest): Observable<BaseEvent> {
+    const subject = new ReplaySubject<BaseEvent>();
+    (async () => {
+      const entries = await this.redis.xrange(
+        STREAM_KEY(request.threadId),
+        "-",
+        "+",
+      );
+      for (const [, fields] of entries) {
+        const eventStr = fields[1];
+        if (eventStr) subject.next(JSON.parse(eventStr));
+      }
+      subject.complete();
+    })();
+    return subject.asObservable();
+  }
+
+  async isRunning(request: AgentRunnerIsRunningRequest): Promise<boolean> {
+    return (await this.redis.exists(RUNNING_KEY(request.threadId))) === 1;
+  }
+
+  async stop(request: AgentRunnerStopRequest): Promise<boolean | undefined> {
+    const stop = this.stopHandlers.get(request.threadId);
+    if (stop) {
+      stop();
+      this.stopHandlers.delete(request.threadId);
+    }
+    await this.redis.del(RUNNING_KEY(request.threadId));
+    return true;
+  }
+
+  private stopHandlers = new Map<string, () => void>();
+}
+```
+
+## Contract gotchas
+
+- `run()` must throw `Error("Thread already running")` (or let a distributed lock return a
+  non-acquired state) when a run is already active. Intelligence mode surfaces the 409 to
+  the client as the typed `agent_thread_locked` error code; SSE mode (direct runner use)
+  only emits a generic 500 response with the error message — so clients cannot depend on
+  the typed code there, and should additionally guard with a busy flag on submit.
+- `connect()` must replay historic events so late clients can catch up on an active run.
+- `stop()` is optional to implement in the sense that returning `undefined` is allowed, but
+  surface cancellations through `abortController.abort()` to the underlying agent if you can.
+- The runner does not persist user messages on its own — that is the Intelligence platform's
+  job. A custom runner that persists only its own event stream is still a drop-in replacement
+  for `InMemoryAgentRunner` / `SqliteAgentRunner`.
+
+Source: `packages/runtime/src/v2/runtime/runner/agent-runner.ts`,
+`packages/runtime/src/v2/runtime/runner/in-memory.ts`,
+`packages/sqlite-runner/src/sqlite-runner.ts`.

package/skills/runtime/references/agent-runners-in-memory.md

@@ -0,0 +1,64 @@
+InMemoryAgentRunner — default ephemeral runner. Keyed on a `globalThis` Symbol so thread state survives hot-module reloads during development.
+
+## Store layout
+
+```typescript
+// packages/runtime/src/v2/runtime/runner/in-memory.ts
+const GLOBAL_STORE_KEY = Symbol.for("@copilotkit/runtime/in-memory-store");
+
+interface GlobalStoreData {
+  stores: Map<string, InMemoryEventStore>; // per-threadId
+  historicRunsBackup: Map<string, HistoricRun[]>; // restored after HMR
+}
+```
+
+One `InMemoryEventStore` per `threadId`. Each store tracks:
+
+- `subject: ReplaySubject<BaseEvent> | null` — current consumers
+- `isRunning: boolean` — gate for the `"Thread already running"` throw
+- `currentRunId: string | null`
+- `historicRuns: HistoricRun[]` — completed runs (backed up across HMR)
+- `agent: AbstractAgent | null` — the instance that owns the active run
+- `runSubject`, `currentEvents`, `stopRequested`
+
+## Lifecycle
+
+1. `run({ threadId, agent, input })` — if `store.isRunning` throw `Error("Thread already running")`. Otherwise create a `ReplaySubject`, subscribe to `agent.run(input)`, push events into the subject, track them in `currentEvents`, mark the store `isRunning`.
+2. On `RunFinishedEvent` / `RunErrorEvent`: finalize the run, push its events into `historicRuns`, clear `isRunning`, `currentRunId`, `agent`.
+3. `connect({ threadId })` — returns a `ReplaySubject` that replays the active run events or (if no active run) the most recent historic run.
+4. `stop({ threadId })` — sets `stopRequested = true`; the active subscription checks the flag on each event and tears down.
+
+## Hot reload (development)
+
+In dev, bundlers replace modules. `GLOBAL_STORE_KEY` uses `Symbol.for(...)` so the same well-known symbol is reused across module instances — `globalThis[KEY]` survives. On module re-evaluation, if the `stores` map is empty but `historicRunsBackup` still has entries, the runner rehydrates historic-only stores from the backup (active runs are lost, historic runs come back).
+
+## When NOT to use
+
+- Multi-instance production deploys — each process has its own store.
+- Long-lived servers — restart wipes active threads (historic runs are only preserved in the HMR-dev backup, not across process exit).
+- Load-balanced serverless with cold starts — new workers see empty stores.
+
+## When it is OK
+
+- Local development.
+- Single-instance preview environments.
+- Tests (each `new InMemoryAgentRunner()` still shares the globalThis store — pass a fresh threadId per test, or clear the captured store in place between tests). Do NOT `delete globalThis[Symbol.for("@copilotkit/runtime/in-memory-store")]`: `in-memory.ts:98` captures `GLOBAL_STORE = getGlobalStore()` as a module-level const referencing the inner `stores` Map, so replacing `globalThis[KEY]` creates a new object that the module no longer consults. Mutate the existing maps in place:
+
+  ```ts
+  // test setup
+  const storeKey = Symbol.for("@copilotkit/runtime/in-memory-store");
+  const data = (globalThis as any)[storeKey] as
+    | {
+        stores: Map<string, unknown>;
+        historicRunsBackup: Map<string, unknown>;
+      }
+    | undefined;
+  if (data) {
+    data.stores.clear();
+    data.historicRunsBackup.clear();
+  }
+  ```
+
+  The runtime does not yet expose an official reset helper — a `__TEST_ONLY_clearGlobalStore` export would be a reasonable follow-up.
+
+Source: `packages/runtime/src/v2/runtime/runner/in-memory.ts`.

package/skills/runtime/references/agent-runners-sqlite.md

@@ -0,0 +1,90 @@
+SqliteAgentRunner — file-backed agent runner in `@copilotkit/sqlite-runner`. Uses `better-sqlite3` as a required peer dep.
+
+## Install
+
+```bash
+pnpm add @copilotkit/sqlite-runner better-sqlite3
+```
+
+If `better-sqlite3` is missing, the `import` of `@copilotkit/sqlite-runner` itself fails
+at module load (`Cannot find module 'better-sqlite3'`). The runner's constructor has a
+friendlier multi-line install hint as a fallback, but you will see the bare resolution
+error first — install the peer before the runner import resolves.
+
+## Configure
+
+```typescript
+import { CopilotRuntime } from "@copilotkit/runtime/v2";
+import { SqliteAgentRunner } from "@copilotkit/sqlite-runner";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    /* ... */
+  } as any,
+  runner: new SqliteAgentRunner({
+    dbPath: "./data/threads.db", // REQUIRED — default is ":memory:"
+  }),
+});
+```
+
+`dbPath: ":memory:"` is the default if omitted — that reverts to an in-memory store and
+loses data at restart. Always set a file path in production.
+
+## Schema
+
+Three tables are created on first use (`packages/sqlite-runner/src/sqlite-runner.ts:75-109`):
+
+```sql
+CREATE TABLE IF NOT EXISTS agent_runs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  thread_id TEXT NOT NULL,
+  run_id TEXT NOT NULL UNIQUE,
+  parent_run_id TEXT,
+  events TEXT NOT NULL,    -- JSON-encoded BaseEvent[]
+  input TEXT NOT NULL,     -- JSON-encoded RunAgentInput
+  created_at INTEGER NOT NULL,
+  version INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS run_state (
+  thread_id TEXT PRIMARY KEY,
+  is_running INTEGER DEFAULT 0,
+  current_run_id TEXT,
+  updated_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS schema_version (
+  version INTEGER PRIMARY KEY,
+  applied_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_thread_id ON agent_runs(thread_id);
+CREATE INDEX IF NOT EXISTS idx_parent_run_id ON agent_runs(parent_run_id);
+```
+
+`agent_runs` is append-only — one row per completed run, full event log in the `events`
+column. `run_state` gates concurrent runs (the `"Thread already running"` check).
+`schema_version` tracks applied migrations so future releases can upgrade existing
+databases in place.
+
+## Retention
+
+There is no automatic retention. If you need bounded history, add a periodic purge:
+
+```typescript
+import Database from "better-sqlite3";
+
+const db = new Database("./data/threads.db");
+setInterval(
+  () => {
+    const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000; // 30 days
+    db.prepare("DELETE FROM agent_runs WHERE created_at < ?").run(cutoff);
+  },
+  60 * 60 * 1000,
+);
+```
+
+## When NOT to use
+
+- Multi-instance deploys without shared storage — each instance would have its own DB file.
+  Either put the DB on a shared volume (EFS, persistent disk) with a single writer, or
+  choose Intelligence mode or a custom Redis/Postgres runner.
+
+Source: `packages/sqlite-runner/src/sqlite-runner.ts`.