`CopilotKitIntelligence` performed no validation on `apiKey`. It assigned the
value and sent it verbatim as a Bearer credential, so a blank key produced
`Authorization: Bearer ` and surfaced much later as a 401 that named nothing.
`apiKey: string` is required on the config type, so TypeScript catches a missing
property. It does not catch an empty one, and the shape that actually happens is
a `process.env` read TypeScript is told to trust: `?? ""` in the starter wiring
block, `!` in this file's own JSDoc examples. Both yield a blank key when the
variable is unset.
Throw at construction instead. Every caller builds the client during boot, so the
error lands at startup rather than on a user's first message. The message names
`CPK_INTELLIGENCE_API_KEY` and `copilotkit project select`, and echoes none of the
key value — the rule `parseProjectIdFromApiKey` already follows for a malformed
key.
This mirrors `configuredUrl`, which already treats a blank `apiUrl`/`wsUrl` as
unset for the same `?? ""` reason.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The Headless UI console notice told developers about "premium features" and
pointed at /premium/overview. The tier is called CopilotKit Intelligence now, so
the notice named a product that no longer exists. It now uses the same sentence
the Headless UI docs page uses.
The docs links in react-core, web-inspector and the runtime skill reference move
from /premium/* to /intelligence/*. They worked through the redirects added in
#6818, but each cost a hop and carried the old name.
One of them was broken, not just stale: the "Show me how" button on the missing
public API key error opened /premium/overview#getting-access. That heading was
deleted on 2026-06-16 in 449237af0c, so the button had been landing at the top
of the page for two and a half months. It now points at #plans-and-access, the
section that answers how to get a key.
Tests assert these hrefs, so they move with the strings.
Refs OSS-1085
Moves the published packages from 0.0.57 to the current AG-UI release across
@ag-ui/client, core, encoder and proto — 27 declarations in 18 packages.
0.0.59 is the first release carrying the subagent protocol surface
(SUBAGENT_STARTED/FINISHED/ERROR, subagentRunId) along with the null-omission
cleanup, so this is the dependency CopilotKit's subagent work needs.
Scope is packages/** plus the release script noted below. The examples and
showcases sit on a spread of older pins (0.0.40 through 0.0.58) and are left
alone.
One behavioural change comes with the bump. channels-core ships
sanitizeAgentEventStream because @ag-ui/client used to reject a TOOL_CALL_START
carrying parentMessageId: null — the shape @ag-ui/langgraph emits for an
interrupt-triggering tool call. 0.0.59 accepts that null and treats it as
absent, so the two tests asserting the run dies WITHOUT the sanitizer no longer
hold. They now assert the run survives, and the one at agent level still checks
the tool call actually arrives so it cannot pass vacuously. The sanitizer is
untouched and its coercion tests are unchanged; it is simply no longer the
thing keeping such a run alive.
The bump also broke the packed Angular consumer matrix. That job generates a
smoke app from scripts/release/lib/angular-package.ts, whose manifest restated
"@ag-ui/client": "0.0.57" as a literal while packages/angular moved to 0.0.59.
pnpm then installed both copies and the app failed to compile:
TS2322: Type 'SmokeAgent' is not assignable to type 'AbstractAgent'.
Types have separate declarations of a private property '_debug'.
The smoke app imports AbstractAgent directly, so it has to resolve the identical
copy the library ships against. Read that version off the packed manifest --
which verify-angular-package.ts already parses for the Angular support contract
-- instead of restating it, so no future AG-UI bump can desynchronise it.
The v2 runtime client gated anonymous events at 5% and let identified
callers through at 100%, then sent without recording which branch the
event took. A quarter of runtime volume — 24.4% in August and roughly
doubling each month — arrived carrying no record of its own sampling, so
it could not be weighted from the data alone. Downstream had to hardcode
a x20 assumption, which both understates real volume and overstates
growth as the sampled/unsampled mix drifts.
Extract the v1 client's sampling block into shared/telemetry/sampling so
the two clients cannot drift again, and call it from both. Identified
events weigh 1, anonymous ones 1/sampleRate.
Carry telemetry_identified explicitly rather than letting consumers infer
identity from sampleWeight === 1: under COPILOTKIT_TELEMETRY_SAMPLE_RATE=1
anonymous events also weigh 1 and the two populations stop being
distinguishable.
The v1 client also sends every capture to both Segment and the lambda
sink, so one request produces two rows with nothing marking them as
copies. Stamp telemetry_emitter, telemetry_transport, and a per-capture
telemetry_event_id shared by both copies, making the dedupe explicit
instead of inferred from $lib. Both transports keep flowing.
Refs OSS-1017, OSS-1018, OSS-1019
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The Intelligence connect handler classified a handful of platform rejections and
flattened everything else into HTTP 404 "Connect plan not available", writing the
real cause only to server-side stderr.
That made every unrecognised failure look like a missing thread. A 500 from
app-api, a socket timeout, a connection reset and a bug in our own code all
produced the same misleading answer, and the only way to find out what actually
happened was to read the runtime container's logs.
It cost a customer a day. Their Redis filled, app-api returned 500 on a
join-code write, and their engineer saw a 404 naming a "connect plan" that had
nothing to do with the failure. The platform was up and the request was
retryable; the reported status said neither.
Now:
- a status we already special-case (400, 401, 403, 404, 409) still reports as
a rejection with its message, unchanged;
- any other status from the platform passes through as itself, so a 503 stays
a 503 and the caller knows to retry; and
- an error carrying no status never reached the platform, so it reports 502
rather than 404, which says "the thing behind me is unreachable" instead of
asserting the thread does not exist.
Every branch now returns the underlying message rather than burying it in a log
line the caller cannot see.
The SSE run path in handlers/shared/sse-response.ts has the same shape and is not
addressed here: it returns 200 and text/event-stream before the run starts, so a
later throw closes the stream with no events and no error frame. That needs its
own change to the streaming contract.
DNS is case-insensitive, so a capitalized host in prose would have slipped the
literal match. Env var names stay case-sensitive — `ignoreCase` is opt-in per
rule. The per-host reason moves onto the constant so adding a third host cannot
silently inherit the wrong message.
Also restores the TSDoc's original framing of what an override is for
("non-production or future self-hosted"), matching the runtime skill's wording
rather than diverging from it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The packaged runtime skill up to v1.62.2 prescribed `api.copilotkit.ai` /
`realtime.copilotkit.ai`. The first host is a CNAME onto the legacy Copilot
Cloud ALB, where no listener rule matches it, so every request gets the ALB
default action: a 404 with an empty body. The second has no DNS record at all.
A reader who followed that page converted a working OSS install into a 502.
The hosts themselves were corrected in v1.64.0, but two shipped surfaces still
carried stale claims about the same step, and nothing stopped the hosts from
coming back a third time:
- The debug skill said Intelligence "requires ... `apiUrl`, `wsUrl`, `apiKey`,
`tenantId`". Three errors in one line: `apiUrl`/`wsUrl` have been optional
with managed defaults since v1.64.0, and `tenantId` has never existed on
`CopilotKitIntelligenceConfig` — the API key carries the project (its token
format is `cpk-{projectId}_...`) and the platform resolves the organization
server-side, so there is no org or tenant field for a caller to pass.
- `CopilotKitIntelligence`'s own TSDoc showed only `*.internal` placeholders,
so the class's hover docs never named the pair that actually serves prod.
`validate-intelligence-env-names` — already the unfiltered guard for this same
config surface (OSS-881) — now also fails on either dead host. The
channels-intelligence realtime test is allowlisted: it needs a hostname that
genuinely does not resolve, since `getaddrinfo ENOTFOUND` is the condition
under test.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
## Problem
`runner` and `intelligence` are mutually exclusive by construction, but
the exclusivity was enforced in only one direction and only for object
literals.
`CopilotIntelligenceRuntime` hardcodes `new
IntelligenceAgentRunner(...)` into its `super()` call
(`runtime.ts:582`), and `runner?` is declared only on
`CopilotSseRuntimeOptions` (`runtime.ts:239`). The type system catches a
`runner:` key on an Intelligence-shaped **object literal** via
excess-property checking — but that is the only barrier. A JS caller, an
`as any`, or a non-literal options object routes through
`CopilotRuntimeShim`'s `hasIntelligenceOptions()` dispatch into the
Intelligence constructor and has `runner` **silently dropped**, with no
diagnostic.
The mirror case is already guarded: `CopilotSseRuntime` throws on
`channels`, and the comment there states the exact reasoning that
applies here — "the type forbids it, but a JS / `as any` caller ...
would otherwise land here and have `channels` silently dropped — fail
loud instead." The Intelligence constructor validates `identifyUser`,
`channels`, `memory`, and `ɵlearning`. Same file, same pattern, one case
missing.
### It also made a shipped skill lie
`packages/runtime/skills/runtime/SKILL.md:87` asserted:
> Passing both `runner` and `intelligence` to `CopilotRuntime` is
rejected at construction.
It was not. And that contradicted the skill's own reference page,
`references/agent-runners.md`, which correctly described the silent
drop. Two files in the same shipped skill said opposite things about the
same behaviour.
## Change
- **Guard** (`runtime.ts:512`) — `CopilotIntelligenceRuntime` now throws
when `runner` is present, mirroring the `channels` guard in
`CopilotSseRuntime`. The message names the exclusivity and points out
that an in-memory/SQLite runner is unnecessary in Intelligence mode,
where durability is managed by the service.
- **`SKILL.md:87` unchanged** — the guard makes it accurate.
- **`references/agent-runners.md` updated** — this is *not* optional.
That page was the accurate one before this change; adding the guard
makes its "the auto-wired Intelligence runner wins regardless of what
you pass" false. Leaving it would fix SKILL.md's lie by creating the
same lie in the reference — rotating the contradiction rather than
resolving it. Its stale `:149-173,285-294` source citation is corrected
to the real line numbers too. Root `skills/` mirror regenerated via
`pnpm sync:plugin-skills`.
## Behavior notes
- Explicit `runner: undefined` still constructs. This matches how the
sibling `identifyUser` / `channels` / `memory` guards treat `undefined`,
and avoids breaking callers that spread an options object.
- The v1 deprecated compat path is unaffected:
`copilot-runtime.ts:492-509` already omits `runner` from its
Intelligence branch, so nothing routes a `runner` into this constructor
from v1.
## Tests
Two tests in `channels-option.test.ts`, alongside the existing `sse
runtime rejects channels` mirror:
- `intelligence runtime rejects a caller-supplied runner` — written
first and confirmed **red** against the unpatched constructor
(`AssertionError: expected [Function] to throw an error`), green after.
- `intelligence runtime tolerates an explicitly undefined runner` — pins
the undefined-tolerance above so the guard cannot over-throw.
## Verification
| Gate | Result |
|---|---|
| `nx test @copilotkit/runtime` | 144 files, **2080 passed, 0 failed** |
| `nx check-types @copilotkit/runtime` | Successfully ran (+22 deps) |
| `oxlint` (changed files) | 0 warnings, 0 errors |
| `oxfmt --check` | no issues in changed files |
| lefthook pre-commit + commit-msg | all green |
Closes OSS-933.
Closes the remaining half of OSS-899.
PR #6644 removed the `require("reflect-metadata")` banner from the
published
`.d.cts` files, taking a bare strict-mode `import { CopilotRuntime }`
from 81
errors to 10. This takes it to **1**, and that one is not ours.
## Result
Measured by overlaying the built `dist` onto a real consumer install of
1.69.0
and typechecking a bare import under `strict` + `skipLibCheck: false`:
| entry point | before | after |
| -- | --: | --: |
| `@copilotkit/runtime` | 10 | **1** |
| `/v2` | 1 | **1** |
| `/v2/express` | 1 | **1** |
| `/v2/hono` | 1 | **1** |
| `/v2/node` | 1 | **1** |
| `/langgraph` | 7 | **6** |
The single remaining error on every entry point is the same one, and it
is in a
third-party package — see "Not fixed here" below.
## The gate
`scripts/validate-dts-imports.ts` is the companion to
`validate-dts-ambient.ts`.
That one checks the *shape* of published declarations; this one checks
what they
*reach for*, against a single invariant:
> Every module a published `.d.ts` imports must be resolvable by someone
who
> installed this package and nothing else.
It flags devDependencies, optional peers, dependencies whose types live
in a
devDependency `@types/*`, relative imports of JS-only bundler chunks,
and an
explicit ban on `graphql-yoga`. It started red on 18 violations and is
now clean
on all 175 declaration files. Wired into the existing `check-dts`
target, so it
runs in `check:packages` and `static_quality.yml`.
It caught two problems the typecheck probe missed, because they happened
to
hoist in that particular install: `@whatwg-node/server` and
`@langchain/langgraph-sdk`.
## The fixes
- **`graphql-yoga` (5× TS2416)** — `GraphQLContext` was
`YogaInitialContext & {...}`.
That one reference pulled the Yoga barrel into every consumer program,
and with
it `lru-cache@10`, whose `implements Map` clause is what actually
errors.
Declared locally instead; structurally identical, so a real Yoga context
still
satisfies it. Nothing in this package serves GraphQL any more — every v1
integration entry point delegates to the v2 Hono endpoint.
- **`@copilotkit/channels` (1× TS7016)** — a devDependency and a pure
re-export of
`channels-core`, so tsdown inlined its prebuilt declarations plus a
rolldown
helper chunk that ships JavaScript only. Types now come from
`channels-core`,
which is a real dependency and stays external.
- **`cors` / `express` (1× TS7016)** — public declarations use their
types, but both
`@types` packages were devDependencies. Promoted to dependencies.
- **`@anthropic-ai/sdk` / `groq-sdk` (2× TS2307)** — optional peers
named in exported
signatures. Params and getters now use `SdkClientLike`, a structural
type a real
client satisfies; the SDK types stay at the two call sites that need
them, inside
function bodies where they are never emitted.
- **`@langchain/langgraph-sdk`** — was deep-importing
`dist/types.messages`, an
internal file of an optional peer. Now derived from the base class
signature in
`@ag-ui/langgraph`, a real dependency.
- **`@whatwg-node/server`** — an `export type {}` workaround for
microsoft/TypeScript#42873 whose own comment said it was waiting on
TypeScript
5.5. We are on 5.9.2 and it typechecks without it.
## Not fixed here
**1× TS2694** — `@copilotkit/license-verifier@0.5.0` references zod's
`core`
namespace, which only exists in zod v4; this package pins `zod ^3.23.3`.
It is an
external package (0.5.0 is the latest published), so the fix is either a
license-verifier release or migrating this package to zod v4. Both are
larger than
this PR and deserve their own ticket.
Also unchanged: the 6 remaining `/langgraph` errors, all inside
`@ag-ui/langgraph`,
`@langchain/core`, and `@langchain/langgraph-sdk`. The `TS2416` on `run`
is present
identically in pristine 1.69.0 — it is downstream of
`@ag-ui/langgraph`'s own
unresolvable deep imports, not something this branch introduced.
## Reviewer note
The `SdkClientLike` swap narrows `adapter.anthropic` and `adapter.groq`
for anyone
reaching past `baseURL` and `apiKey`. Both adapters are v1-deprecated,
and the
alternative is a type error for every consumer who does not install
those optional
peers — but it is a public-surface change and worth a second opinion.
## Verification
- `nx test runtime` — 2078 tests, 144 files, all passing
- `nx build runtime` + `npm run check-dts` — both validators clean on
175 files
- `tsc --noEmit` on the package — clean
🤖 Generated with [Claude Code](https://claude.com/claude-code)
@anthropic-ai/sdk and groq-sdk are optional peers, so a consumer who never uses
those adapters does not install them -- yet both were named in exported
signatures, which is a TS2307 on a bare `import { CopilotRuntime }`. The
LangGraph agent had a third case, and a worse one: it deep-imported
@langchain/langgraph-sdk/dist/types.messages, an internal file of an optional
peer.
The adapter params and getters now use SdkClientLike, a structural type a real
Anthropic or Groq instance satisfies. The SDK types stay for the two call sites
that need them, inside function bodies where they are never emitted. The
LangGraph message type is derived from the base class signature in
@ag-ui/langgraph, which is a real dependency.
Narrows adapter.anthropic and adapter.groq for anyone reaching past baseURL and
apiKey. Both adapters are v1-deprecated and the alternative is a type error for
every consumer.
dist/v2/runtime/endpoints/express.d.cts imports types from `cors` and `express`.
Neither ships its own declarations, and both @types packages were devDependencies,
so whether a consumer resolved them came down to whether something else in their
tree happened to hoist them.
Moving them to dependencies makes the published types self-contained.
`export type {} from "@whatwg-node/server"` worked around microsoft/TypeScript#42873
and its own comment says it was waiting on the TypeScript 5.5 stable release.
The repo is on 5.9.2 and typechecks without it.
It was reaching a devDependency, so it emitted an import of a module consumers
never install.
@copilotkit/channels is a devDependency and a pure re-export of
@copilotkit/channels-core, so tsdown treated it as bundleable and inlined its
prebuilt declarations into dist/channels/dist/index.d.cts -- along with a
rolldown helper chunk that ships JavaScript only. Consumers got a TS7016 for a
file they cannot see.
channels-core is a real dependency and stays external, so importing the types
from there drops the inlined copy entirely.
GraphQLContext was defined as `YogaInitialContext & {...}`. That single type
reference pulled the whole graphql-yoga barrel into every consumer's program,
and with it lru-cache@10, whose `implements Map` clause costs five TS2416
errors under strict + skipLibCheck: false.
Nothing in this package serves GraphQL any more -- every v1 integration entry
point delegates to the v2 Hono endpoint -- so the type is declared locally
instead. It is structurally identical, so a real Yoga context still satisfies it.
OSS-899 shipped 81 strict-mode errors to consumers because nothing checked what
the published .d.cts files reach for. validate-dts-ambient.ts checks their shape;
this checks their imports against the one thing that matters -- whether someone
who installed this package and nothing else can resolve them.
Flags devDependencies, optional peers, dependencies whose types live in a
devDependency @types package, relative imports of JS-only bundler chunks, and an
explicit ban on graphql-yoga, whose types drag lru-cache@10 into every consumer
program. Currently red on 18 real violations; the fixes follow.
Twelve quickstarts provisioned a license key in step 1 and then showed a
runtime constructed with `runner: new InMemoryAgentRunner()` — an option
that is mutually exclusive with `intelligence`, so the key was never read.
Threads showed "locked" and nothing indicated a choice had been made.
Each of those pages now constructs the runtime with `intelligence` and
`identifyUser`, names `INTELLIGENCE_API_KEY` where the route reads it, and
links /premium/connect-your-runtime — which had no inbound link from any
quickstart. The in-memory runner stays available as a labelled opt-out;
it was already the default, so passing it explicitly only added the steer.
Also adds the required `name` field to the `identifyUser` snippets in
connect-your-runtime.mdx and the runtime skill's agent-runners reference.
Both omitted it, so copying either was a type error.
Scope is every page that provisions a key and then shows a runtime that
cannot consume it. Pages that legitimately document the in-memory runner
(backend/agent-runner, deploy/agentcore) are unchanged.
Verified: all 15 doctest `component` snippets typecheck against the pinned
@copilotkit/runtime@1.68.3, and the gate goes red when `name` is removed.
`CopilotIntelligenceRuntime` hardcodes `IntelligenceAgentRunner` into its
`super()` call, so a caller-supplied `runner` could never be honored. The type
forbids it — `runner` is declared only on `CopilotSseRuntimeOptions` — but that
is an excess-property check: a JS, `as any`, or non-literal caller passing
`{ intelligence, runner }` reached the constructor and had `runner` silently
dropped with no diagnostic.
Add the runtime guard, mirroring the `channels` guard already in
`CopilotSseRuntime` for exactly this reason. Explicit `runner: undefined` still
constructs, matching how the sibling `identifyUser` / `channels` / `memory`
guards treat undefined.
This also resolves a contradiction inside the shipped runtime skill:
`SKILL.md:87` already asserted the rejection happens at construction, while
`references/agent-runners.md` correctly described the silent drop. The guard
makes SKILL.md true; agent-runners.md is updated to describe the throw and to
cite line numbers that match the current file.
Benjamin Taylor