@copilotkit/runtime 1.71.0 → 1.71.2

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

@@ -1,161 +0,0 @@
-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 CopilotKit Intelligence'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

@@ -1,79 +0,0 @@
-InMemoryAgentRunner — default ephemeral runner. Thread state lives in a bounded, process-global store shared by every runner instance in the process.
-
-## Store layout
-
-```typescript
-// packages/runtime/src/v2/runtime/runner/in-memory.ts
-export const ɵGLOBAL_STORE = new ɵBoundedThreadStore(ɵINMEMORY_DEFAULTS);
-```
-
-`ɵBoundedThreadStore` owns the `Map<threadId, InMemoryEventStore>`, LRU ordering, byte accounting, and eviction. The runner keeps all streaming logic and delegates storage to the store. The `ɵ` prefix marks internal API — exported for tests, not part of the public surface.
-
-One `InMemoryEventStore` per `threadId`. Each store tracks:
-
-- `subject: ReplaySubject<BaseEvent> | null` — current consumers; released on run completion
-- `isRunning: boolean` — gate for the `"Thread already running"` throw
-- `currentRunId: string | null`
-- `historicRuns: HistoricRun[]` — completed runs (events only; see snapshot note below)
-- `messagesSnapshot: Message[]` — the thread's latest non-empty message snapshot, held at the THREAD level so run-cap eviction can never drop it
-- `agent: AbstractAgent | null` — the instance that owns the active run
-- `runSubject`, `currentEvents`, `stopRequested`
-
-## Bounds
-
-Three limits, whichever trips first. Defaults in `ɵINMEMORY_DEFAULTS`:
-
-| Option             | Default | Enforcement                                                    |
-| ------------------ | ------- | -------------------------------------------------------------- |
-| `maxThreads`       | `1000`  | LRU eviction of the least-recently-used thread                 |
-| `maxRunsPerThread` | `100`   | FIFO drop of oldest runs; `Infinity` or `0` disables           |
-| `maxBytes`         | 512 MiB | Approximate total across all threads; evicts OTHER LRU threads |
-
-```typescript
-new InMemoryAgentRunner({
-  maxThreads: 200,
-  maxRunsPerThread: 50,
-  maxBytes: 128 * 1024 ** 2,
-});
-```
-
-Invariants worth knowing before touching this code:
-
-- A thread is never evicted while `isRunning` **or** `stopRequested` is set. `stop()` flips `isRunning` false immediately but the run finalizes asynchronously; evicting in that window would make the pending `appendRun` silently drop history.
-- `maxBytes` only bounds **committed** history. A single in-flight run's buffered events are not counted until the run completes, so it does not bound one runaway run mid-stream.
-- `maxBytes` evicts other threads and never self-evicts the just-appended thread — it is a cross-thread ceiling, not a per-thread cap. A single dominant thread is bounded by `maxRunsPerThread`.
-- Byte accounting is a `JSON.stringify().length` estimate, not exact heap bytes.
-- Two eviction forms, both steering heavy users to an Intelligence backend via one shared warn-once latch. Whole-thread eviction (`maxThreads` count or `maxBytes` ceiling) drops the entire LRU thread — it stops appearing in `GET /threads`. Per-thread `maxRunsPerThread` trimming drops only a thread's oldest runs' events, keeping the thread visible with its original `createdAt` and its thread-level `messagesSnapshot`. The latch fires **once per store** (not once per eviction), reset only by `clearThreads()`/`clear()`, so a hot thread trimming on every append logs a single line and every later eviction is silent until a clear.
-
-## Concurrency
-
-`onConcurrentRun` is per-runner (unlike the limits, which are process-global):
-
-- `"throw"` (default) — a second `run()` on a live thread throws `Error("Thread already running")`.
-- `"supersede"` — aborts the in-flight run (same path as `stop()`) and starts the new one. The superseded run's teardown is guarded on `store.currentRunId === request.input.runId` (so it cannot push history under the new run's id or reset the new run's state) and on `store.subject === nextSubject` (so releasing its ReplaySubject cannot null out the live run's subject).
-
-## Lifecycle
-
-1. `run({ threadId, agent, input })` — `sharedStore.getOrCreate(threadId)` (may evict other threads), then throw or supersede per `onConcurrentRun`. Create `ReplaySubject`s, run the agent, push events into the subjects and `currentEvents`, mark `isRunning`.
-2. On completion or error: finalize, `sharedStore.appendRun(...)` with the compacted events (which enforces the run cap and byte ceiling), clear `isRunning` / `currentRunId` / `agent`, and release `store.subject` so the infinite ReplaySubject buffer becomes collectable. History is rebuilt from `historicRuns` afterwards.
-3. `connect({ threadId })` — replays compacted `historicRuns`, then bridges the live subject while `isRunning || stopRequested`.
-4. `stop({ threadId })` — sets `stopRequested = true`, aborts the agent; teardown runs in the run's `catch`.
-
-## Config scope gotcha
-
-Limits reconfigure the shared store, so the **last-constructed runner wins for all in-memory threads**. A second runner passing limits that differ from an already-customized store logs a one-time clobber warning. Passing only `onConcurrentRun` leaves the limits untouched.
-
-## When NOT to use
-
-- Multi-instance production deploys — each process has its own store.
-- Anywhere history loss is unacceptable — eviction is history loss, same as a restart.
-- Load-balanced serverless with cold starts — new workers see empty stores.
-
-## When it is OK
-
-- Local development.
-- Single-instance preview environments.
-- Production single-instance deploys where scrollback is best-effort — the bounds make this safe against OOM, not durable.
-- Tests. Every `new InMemoryAgentRunner()` shares the same store, so use a fresh `threadId` per test or call `runner.clearThreads()` (which resets the map, byte total, and eviction warn latch) between tests. Tests that customize limits must restore them: `new InMemoryAgentRunner(ɵINMEMORY_DEFAULTS)` in an `afterEach` — a no-arg construction is inert and will NOT restore defaults.
-
-Source: `packages/runtime/src/v2/runtime/runner/in-memory.ts`.

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

@@ -1,90 +0,0 @@
-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`.

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

@@ -1,336 +0,0 @@
-# CopilotKit Agent Runners
-
-`AgentRunner` is the abstraction that owns thread run state — active runs, the event stream
-replay, and stop semantics. Pick one per `CopilotRuntime` instance.
-
-- `InMemoryAgentRunner` — default; process-global in-memory Map; lost on restart.
-- `SqliteAgentRunner` — file-backed; requires `better-sqlite3` peer.
-- `IntelligenceAgentRunner` — auto-wired by `CopilotIntelligenceRuntime`. You do NOT
-  construct this directly and you cannot pass `runner` alongside `intelligence`.
-- Custom — subclass `AgentRunner` for Redis / Postgres / any backend.
-
-## Setup
-
-Default (in-memory, dev only):
-
-```typescript
-import { CopilotRuntime } from "@copilotkit/runtime/v2";
-
-// Equivalent to passing `runner: new InMemoryAgentRunner()`
-const runtime = new CopilotRuntime({
-  agents: {
-    /* ... */
-  } as any,
-});
-```
-
-Production (file-backed SQLite):
-
-```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" }),
-});
-```
-
-Installation for the SQLite runner (the `better-sqlite3` peer is required):
-
-```bash
-pnpm add @copilotkit/sqlite-runner better-sqlite3
-```
-
-## Core Patterns
-
-### The AgentRunner contract
-
-```typescript
-import { AgentRunner } from "@copilotkit/runtime/v2";
-import type {
-  AgentRunnerRunRequest,
-  AgentRunnerConnectRequest,
-  AgentRunnerIsRunningRequest,
-  AgentRunnerStopRequest,
-} from "@copilotkit/runtime/v2";
-import { Observable } from "rxjs";
-import type { BaseEvent } from "@ag-ui/client";
-
-class MyRunner extends AgentRunner {
-  run(request: AgentRunnerRunRequest): Observable<BaseEvent> {
-    // Start a new run for request.threadId. Throw `new Error("Thread already running")`
-    // if a run is in flight. Stream events from agent.run(request.input).
-    return new Observable<BaseEvent>();
-  }
-  connect(request: AgentRunnerConnectRequest): Observable<BaseEvent> {
-    // Replay events for an active run, or historic runs for request.threadId.
-    return new Observable<BaseEvent>();
-  }
-  async isRunning(request: AgentRunnerIsRunningRequest): Promise<boolean> {
-    return false;
-  }
-  async stop(request: AgentRunnerStopRequest): Promise<boolean | undefined> {
-    return true;
-  }
-}
-```
-
-### Handle double-submit on the client
-
-By default, both `InMemoryAgentRunner` and `SqliteAgentRunner` throw
-`"Thread already running"` on concurrent `run()` calls for the same `threadId`.
-`"throw"` is the default, but it is not the only option: constructing
-`InMemoryAgentRunner` with `onConcurrentRun: "supersede"` makes it abort the
-in-flight run (the same path `stop()` takes) and start the new one instead of
-throwing — the superseded run's partial output is discarded rather than persisted
-to history. `SqliteAgentRunner` has no such option and always throws. When the
-throw does happen, how it surfaces to the client depends on the runtime mode:
-
-- **Intelligence mode** — CopilotKit Intelligence returns HTTP `409` when a lock is
-  held. The client core maps this to `CopilotKitCoreErrorCode.AGENT_THREAD_LOCKED`
-  and fires `onError({ code: "agent_thread_locked", ... })`. Handle this in
-  `<CopilotKit onError>` (the `CopilotKit` provider from `@copilotkit/react-core/v2`).
-- **SSE mode** (default, in-memory / SQLite runners) — the runner throws
-  synchronously and the handler returns a plain `500` JSON body like
-  `{ "error": "Failed to run agent", "message": "Thread already running" }`.
-  There is no typed `agent_thread_locked` code — match on the message text or
-  just guard on the client with a busy flag.
-
-```tsx
-// client — Intelligence mode (typed code)
-import { CopilotKit } from "@copilotkit/react-core/v2";
-
-<CopilotKit
-  onError={({ code }) => {
-    if (code === "agent_thread_locked") {
-      alert("Agent is busy — wait for the current response to finish.");
-    }
-  }}
-/>;
-```
-
-```tsx
-// client — any mode: guard with a busy flag so double-submit is impossible
-import { useAgent } from "@copilotkit/react-core/v2";
-import { useState } from "react";
-
-function Composer() {
-  const agent = useAgent({ agentId: "default" });
-  const [busy, setBusy] = useState(false);
-
-  async function send(text: string) {
-    if (busy) return;
-    setBusy(true);
-    try {
-      await agent?.addMessage({ role: "user", content: text });
-    } finally {
-      setBusy(false);
-    }
-  }
-
-  return null;
-}
-```
-
-## Common Mistakes
-
-### HIGH Shipping InMemoryAgentRunner to production
-
-Wrong:
-
-```typescript
-// production:
-new CopilotRuntime({ agents: { default: agent } });
-```
-
-Correct:
-
-```typescript
-import { SqliteAgentRunner } from "@copilotkit/sqlite-runner";
-
-new CopilotRuntime({
-  agents: { default: agent },
-  runner: new SqliteAgentRunner({ dbPath: "./data/threads.db" }),
-});
-// Or upgrade to Intelligence mode for managed durability.
-```
-
-The default runner is `new InMemoryAgentRunner()`. It keeps state in a process-global,
-bounded store — threads are lost on restart, evicted past the memory limits, and
-horizontally-scaled instances see divergent state. See `agent-runners-in-memory.md`
-for the bounds and how to tune them.
-
-Source: `packages/runtime/src/v2/runtime/runner/in-memory.ts`.
-
-### HIGH Setting runner alongside intelligence option
-
-Wrong:
-
-```typescript
-new CopilotRuntime({
-  agents,
-  intelligence,
-  runner: new SqliteAgentRunner({ dbPath: "./data/threads.db" }),
-});
-```
-
-Correct:
-
-```typescript
-new CopilotRuntime({
-  agents,
-  intelligence,
-  identifyUser: (req) => ({
-    id: req.headers.get("x-user-id")!,
-    name: req.headers.get("x-user-name") ?? "Anonymous",
-  }),
-});
-```
-
-`CopilotIntelligenceRuntimeOptions` does not declare a `runner` field — Intelligence mode
-auto-wires `IntelligenceAgentRunner` pointed at the Intelligence service socket. Excess-property checks will
-flag a `runner:` key on an Intelligence-shaped options object as a type error, and a caller who
-evades that check (JS, `as any`, or a non-literal options object) gets a `throw` at construction
-rather than a silently ignored runner.
-
-Source: `packages/runtime/src/v2/runtime/core/runtime.ts` — `runner?` is declared only on
-`CopilotSseRuntimeOptions` (:239); the Intelligence constructor guard is at :512 and the
-auto-wired runner at :582.
-
-### HIGH Forgetting the better-sqlite3 peer
-
-Wrong:
-
-```bash
-pnpm add @copilotkit/sqlite-runner
-```
-
-Correct:
-
-```bash
-pnpm add @copilotkit/sqlite-runner better-sqlite3
-```
-
-`@copilotkit/sqlite-runner` imports `better-sqlite3` at the top of its module, so if the peer
-is missing, `import { SqliteAgentRunner } from "@copilotkit/sqlite-runner"` itself fails at
-module load with `Cannot find module 'better-sqlite3'` — long before the constructor runs.
-(The constructor has a friendlier multi-line install hint as a belt-and-suspenders fallback,
-but in practice you will see the bare module-resolution error first.) It is a peer dependency,
-not a direct dep.
-
-Source: `packages/sqlite-runner/src/sqlite-runner.ts:18`, `:55-66`.
-
-### HIGH Default SqliteAgentRunner with :memory: dbPath
-
-Wrong:
-
-```typescript
-new SqliteAgentRunner();
-```
-
-Correct:
-
-```typescript
-new SqliteAgentRunner({ dbPath: "./data/threads.db" });
-```
-
-The default `dbPath` is `":memory:"` — SQLite's in-memory mode. Data is lost at restart,
-defeating the reason to use the file-backed runner.
-
-Source: `packages/sqlite-runner/src/sqlite-runner.ts:48-54`.
-
-### MEDIUM Concurrent run() on the same threadId
-
-Wrong:
-
-```tsx
-// Double-click send button → two POST /agent/:id/run to the same thread
-<button onClick={() => agent.addMessage({ role: "user", content })}>
-  Send
-</button>
-```
-
-Correct:
-
-```tsx
-const [busy, setBusy] = useState(false);
-<button
-  disabled={busy}
-  onClick={async () => {
-    setBusy(true);
-    try {
-      await agent.addMessage({ role: "user", content });
-    } finally {
-      setBusy(false);
-    }
-  }}
->
-  Send
-</button>;
-```
-
-By default both runners throw `"Thread already running"` on concurrent runs, so
-debouncing on the client is still the right baseline. In Intelligence mode you can
-additionally handle `code === "agent_thread_locked"` in `<CopilotKit onError>`; SSE
-mode surfaces only a generic 500 with that message.
-
-Throwing is the default (`onConcurrentRun: "throw"`), not the only behavior:
-constructing `InMemoryAgentRunner` with `onConcurrentRun: "supersede"` aborts the
-in-flight run (the `stop()` path) and starts the new one instead of throwing,
-discarding the superseded run's partial output rather than persisting it. That
-suits a UX where a fast follow-up should displace a still-running (or wedged) turn.
-Unlike the process-global memory limits, `onConcurrentRun` is per-runner-instance —
-it affects only the runner you pass it to. `SqliteAgentRunner` has no such option
-and always throws.
-
-Source: the `throw new Error("Thread already running")` in `InMemoryAgentRunner.run()`,
-`packages/runtime/src/v2/runtime/runner/in-memory.ts`;
-`packages/core/src/intelligence-agent.ts:368-369`.
-
-### HIGH In-memory runner + horizontal scaling
-
-Wrong:
-
-```typescript
-// 3 Fly.io / Cloud Run instances, each with its own InMemoryAgentRunner
-new CopilotRuntime({ agents });
-```
-
-Correct:
-
-```typescript
-// Sticky-session one instance per thread (so every run for a thread lands on the
-// same process), OR move to Intelligence mode for managed multi-instance durability.
-new CopilotRuntime({ agents }); // + route by threadId at the load balancer
-```
-
-`InMemoryAgentRunner`'s store is a process-global singleton — multi-instance deploys see
-totally different thread state per worker, making reconnects and `GET /connect` non-deterministic.
-
-Source: the exported `ɵGLOBAL_STORE` singleton in `packages/runtime/src/v2/runtime/runner/in-memory.ts`.
-
-A shared `dbPath` on `SqliteAgentRunner` is **not** a horizontal-scaling fix on its own.
-Sharing the file gives you durable, persisted history: runs survive process restarts, and
-completed runs are readable from any instance pointed at the same file. But the live-run
-bookkeeping used by the connect-bridge and by `stop()` lives in a process-local
-`ACTIVE_CONNECTIONS` map. A second instance has **no** entry for a run started elsewhere, so
-it can replay stored history but **cannot** reconnect to — or stop — an in-flight run on
-another instance. Use `SqliteAgentRunner` for restart-resilient single-instance durability;
-for managed multi-instance durability, use Intelligence mode.
-
-Source: `packages/sqlite-runner/src/sqlite-runner.ts:46` (module-level `ACTIVE_CONNECTIONS`).
-
-## References
-
-- [InMemoryAgentRunner — store, bounds, concurrency, and lifecycle](agent-runners-in-memory.md)
-- [SqliteAgentRunner — schema, retention, ops](agent-runners-sqlite.md)
-- [Custom runner — Redis/Postgres skeleton](agent-runners-custom.md)
-
-## See also
-
-- `copilotkit/intelligence-mode` — managed durability alternative (CopilotKit Intelligence managed service, not self-hostable)
-- `copilotkit/setup-endpoint` — runner is passed via the CopilotRuntime constructor
-- `copilotkit/scale-to-multi-agent` — horizontal scaling considerations