Pressing Stop mid-stream against a CopilotRuntime + HttpAgent proxy aborts
the upstream agent, which emits a live RUN_ERROR while a text message is
still open. finalizeRunEvents then appended a trailing TEXT_MESSAGE_END
*after* that RUN_ERROR. Because the runners stream finalization events
after everything the agent already emitted, the closer landed past the
terminal and the AG-UI verifier rejected it with "the run has already
errored with 'RUN_ERROR'. No further events can be sent." — crashing the
chat.
finalizeRunEvents (in @copilotkit/shared, consumed by the in-memory,
intelligence, and sqlite runners) now returns early and appends nothing
when the stream already contains a terminal event (RUN_FINISHED or
RUN_ERROR): any message or tool call still open is closed by the terminal
on the client. The abrupt-end path (no terminal -> close open streams +
synthesize a terminal) is unchanged.
Tests:
- finalize-events.test.ts: terminal-present appends nothing (both
RUN_FINISHED and RUN_ERROR) + a named #5812 case.
- in-memory-runner.test.ts: end-to-end mid-stream-stop regression that
asserts no events follow RUN_ERROR and the stream passes AG-UI
verifyEvents (the verifier the browser runs).
- intelligence-runner.test.ts: corrected an assertion that had encoded
the buggy post-terminal TEXT_MESSAGE_END.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Repairs TypeScript check-types across the monorepo and adds a CI gate so
regressions are caught going forward:
- core: bundler module resolution and strict-mode fixes
- sdk-js: bundler module resolution; keep codegen, formatter, packaging working
- react-core: fixes across components, hooks, and tests
- react-native: restore catch binding referenced by TypeError cause
- runtime: repair check-types and bound AI SDK schema inference
- web-inspector: nodenext import extensions, export Anchor
- remaining packages and node example: assorted check-types repairs
- deps: add missing type-only devDependencies
- license context driven from /info licenseStatus
- ci: run check-types in the static quality workflow
Squashed from 12 commits for a single, easily-revertable change.
Follow-up correction. The client publicLicenseKey/publicApiKey prop is the
header→cloud path and is NOT what activates the Intelligence runtime (that's
the server-side COPILOTKIT_LICENSE_TOKEN). So:
- Remove the `npx copilotkit@latest license` guidance from all client-prop
contexts — that CLI yields the server-side license token, not the client
prop value.
- Revert the client-prop docstrings (copilotkit-props, v2 CopilotKitProvider)
to bare one-liners; drop the premium/"requires a license key" framing from
the headless hook, react-ui observability docs, and runtime logging/onError
JSDoc rather than reframing.
- Angular: remove all `licenseKey` mentions from the README — it is no longer
a premium feature (the license watermark is disabled) and the key is not
needed to function.
Server-side license-token documentation remains deferred to the example/runtime
setup pass (Bucket B).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cloud is no longer promoted; the Intelligence license key is its replacement.
Scrub the old Copilot Cloud system from SDK JSDoc / doc-comments / console
messages / README prose so code references reflect how the license key is
obtained and used, mirroring examples/integrations/*:
- publicApiKey/publicLicenseKey docstrings (react-core props + v2 provider,
vue legacy types, copilot-context) describe the CopilotKit public license
key, acquired via `npx copilotkit@latest license` or the dashboard;
publicApiKey framed as the legacy alias of publicLicenseKey.
- Premium-feature docs (headless hook, react-ui Chat/Popup/Sidebar
observability, runtime logging/onError) drop "Copilot Cloud"/"requires a
publicApiKey" wording and the publicApiKey examples in favor of the public
license key + publicLicenseKey.
- console-styling messages and the angular README point at the license key
and the `npx copilotkit@latest license` command.
Defunct features (guardrails_c, authConfig_c, useCopilotAuthenticatedAction_c)
keep their code but lose their JSDoc (marked @internal defunct).
Functional surfaces untouched: api.cloud.copilotkit.ai endpoint, the
X-CopilotCloud-Public-Api-Key header, prop names, gating logic, tests,
CHANGELOGs. Example-app migration (Bucket B) deferred.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
LicenseMode was removed from license-verifier 0.3.0 and has no consumers
anywhere in the repo; the prior re-export was already uncompilable, so no
external consumer could exist either.
@copilotkit/license-verifier dropped LicenseContextValue and
LicenseMode from its public API in 0.3.0, leaving shared re-exporting
two nonexistent members. tsdown's dts rollup never validated the
re-export, so the broken types shipped silently and check-types fails
on main. Define both types here — shared already owns the context
shape via createLicenseContextValue — using the definitions from
license-verifier 0.2.0. Also annotate the merged telemetry properties
record so string indexing typechecks.
New users were still discovering cloud.copilotkit.ai through docs pages,
the README, example READMEs, and in-app banners/console messages. Replace
all user-facing web links with dashboard.operations.copilotkit.ai (the
destination the marketing-site CTAs already use). Functional API endpoints
(api.cloud.copilotkit.ai) are deliberately untouched since existing cloud
customers depend on them.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace docs URLs that currently 301 through the legacy redirect catalog
with their canonical post-cutover destinations so users clicking links
from console warnings, JSDoc, and in-product help land in one hop.
URLs updated:
- /premium#how-do-i-get-access-to-premium-features
-> /premium/overview#getting-access
- /coagents/quickstart/langgraph -> /langgraph-python/quickstart
- /coagents/shared-state/predictive-state-updates
-> /langgraph-python/shared-state/predictive-state-updates
- /reference/v1/hooks/useCopilotChatHeadless_c
-> /reference/v2/hooks/useCopilotChatHeadless_c
- /coagents/troubleshooting/common-issues
-> /langgraph-python/troubleshooting/common-issues
- /quickstart#get-a-copilot-cloud-public-api-key
-> /built-in-agent/quickstart#create-a-free-account
- /premium -> /premium/overview
URLs left as-is because they already resolve 200 with no redirect:
/migration-guides/migrate-attachments, /migration/render-message,
/telemetry.
Hook bypassed: pre-commit test failed in @copilotkit/web-inspector due
to missing jsdom dependency in its package.json (unrelated to this
change; no overlap with edited files or URLs). Tests for the four
affected packages (react-core, react-ui, shared, runtime) pass.
- Rework shared helper: parseAndWarnTelemetryId returns parsed id AND
warns, so both v1 and v2 setLicenseToken call it once without
inlining duplicate code or double-parsing the JWT.
- Fix v1 sampleWeight bug: identified events bypass the sample gate
and ship at effective rate 1.0, so a single global sampleWeight =
1/sampleRate would overweight identified-customer counts by
1/sampleRate (20x at the 0.05 default). Move sample metadata
(sampleRate / sampleRateAdjustmentFactor / sampleWeight) out of
globalProperties and compute per-event using effectiveSampleRate.
- Guard setSampleRate against parseFloat("nonsense") = NaN slipping
past the range check. With the default now 0.05, env-var overrides
are more common and a typo would otherwise produce silent
always-drop.
- Add tests: sampleWeight differs for identified vs anonymous,
malformed JWT stays anonymous, license-token cache is overwritable,
NaN env override is rejected, v2 default sampleRate = 0.05 is pinned.
Cache parsed telemetry_id at setLicenseToken time and use it to branch
in capture():
- Identified callers (token with telemetry_id) always send to both sinks.
- Anonymous callers are sampled at sampleRate (default 0.05); one dice
roll gates both lambda and Segment.
The Lambda no longer needs to bypass-from-sampling for identified
events — that decision moves entirely to the client. Reduces lambda
invocations by ~95% for the anonymous OSS-runtime firehose.
Operators currently get silent attribution loss if a license token is
configured but parses without a telemetry_id field — useful as a smoke
signal during the issuer rollout, when older licenses lack the field
entirely.
Each TelemetryClient setter (v1 shared, v2 singleton) now calls
parseTelemetryIdFromLicense at configuration time and emits a one-shot
console.warn when the result is null. No per-event spam.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Drops the Lambda/Segment specifics in favor of an implementation-neutral
description: these fields aren't used by the telemetry service, so we
strip them at the wire boundary.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The CopilotCloud customer key (`ck_<env>_<id>.<secret>`) is routed to
Segment for downstream user analytics, but has no role in the
telemetry-sink Lambda. Worse, the secret half should never leave the
customer's runtime.
Strips both wire-format variants at the lambda-client boundary:
- `cloud.public_api_key` (v2 event property convention)
- `cloud.publicApiKey` (v1 globalProperties from setCloudConfiguration)
The strip happens at the lambda-client wire layer rather than in each
caller, so any future caller (or accidental property regression) is
covered by default. Boolean indicators like `cloud.api_key_provided`
and unrelated fields like `cloud.baseUrl` continue to ride through.
New unit test (`lambda-client.test.ts`) exercises the strip with a real
fetch spy, plus end-to-end JWT extraction including the
no-`telemetry_id` and not-a-JWT fallback paths.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The CopilotCloud customer API key (`ck_<env>_<id>.<secret>`) is unrelated
to telemetry attribution — it flows into Segment/PostHog only. The
attribution signal lives in the EIP / Intelligence license JWT, whose
payload carries `telemetry_id` (alongside license_id, owner.org_id,
features, etc.).
Rewires the lambda-client to base64url-decode the license JWT payload
and emit X-CopilotKit-Telemetry-Id from `telemetry_id`. No signature
verification — that's license-verifier's job, and the Lambda is
claim-only by design.
Plumbing:
- Shared TelemetryClient (v1) and v2 telemetry singleton each get a
`setLicenseToken` setter; the v1 client drops `apiKey:` from its
lambdaClient.send call, the v2 client drops the
cloud.public_api_key extraction from event properties.
- Both runtime constructors call `telemetry.setLicenseToken(...)` once,
resolving `options.licenseToken ?? process.env.COPILOTKIT_LICENSE_TOKEN`
to match license-verifier's own env-fallback. Without that, customers
who set only the env var would get a working licenseChecker but
anonymous telemetry.
Tests: v2 telemetry test refreshed — old "cloud api key extraction"
assertion replaced with one that confirms cloud.public_api_key rides
in properties (not as licenseToken), and a new test asserts that
setLicenseToken plumbs through to lambdaClient.send.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The HMAC scheme bound identity to "holder of API key X," but since the
secret is shipped inside distributed customer keys it never actually
prevented a determined attacker from impersonating that customer — and
the Lambda still accepted unsigned requests anyway, so the signing path
provided attribution, not abuse control.
Replaces ~85 lines of Web Crypto / HMAC / nonce / canonical-string
machinery with a single `X-CopilotKit-Telemetry-Id: <id>` header. The
SDK now extracts the id from `ck_<env>_<id>.<secret>` keys and ignores
the secret half. Anonymous sends (no/legacy keys) are unchanged.
Drops the implicit Node ≥19 / edge-runtime requirement that the
WebCrypto path imposed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Locks in the production telemetry-sink endpoint (the API Gateway custom
domain backed by the ingest Lambda). Customers can still override with
COPILOTKIT_TELEMETRY_URL.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds @copilotkit/shared/telemetry/lambda-client which posts events to a
CopilotKit-controlled telemetry-sink endpoint, replacing the direct Scarf
calls in both v1 (shared) and v2 (runtime) telemetry clients. When the
configured CopilotCloud API key parses as the new ck_<env>_<id>.<secret>
format, the request is HMAC-signed (CK1, sha256 over ts/nonce/body) so
the sink can verify and enrich with the customer email; otherwise it
falls through to an unsigned send (legacy keys, OSS-only installs). v1
keeps its existing Segment path with 5% client sampling; v2 sends 100%
to the sink and lets the sink sample server-side.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Add telemetryDisabled to RuntimeInfo from COPILOTKIT_TELEMETRY_DISABLED/DO_NOT_TRACK env vars
- Mirror through AgentRegistry and expose via CopilotKitCore getter
- Guard track calls, URL param appending, and console disclosure on core.telemetryDisabled
- Move maybeShowDisclosure() to onRuntimeConnectionStatusChanged (fires after core attaches)
- Update docs to replace localStorage toggle description with env var approach
- Add telemetryDisabled test suite to get-runtime-info tests
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The A2UI React renderer (packages/a2ui-renderer/src/react-renderer/a2ui-react/A2uiSurface.tsx:152)
always begins rendering at the component with id="root":
export const A2uiSurface: React.FC<{...}> = ({ surface }) => {
// The root component always has ID 'root' and base path '/'
return <DeferredChild surface={surface} id="root" basePath="/" />;
};
If no component has that ID, DeferredChild falls through to its loading-
shimmer placeholder, so the surface silently renders as an empty ~30px
rectangle regardless of how many other components are on the surface.
The generation guidelines shipped to the sub-LLM (in @copilotkit/shared
and copilotkit sdk-python) never stated this requirement. Fixed-schema
demos hard-code a component with id="root" in their JSON and work; dynamic
demos relied on the LLM guessing, which it sometimes did and sometimes
didn't. The failure mode is particularly nasty: no error, no warning,
just a loading spinner that never resolves.
Adds the requirement to COMPONENT ID RULES in both the TS and Python
guideline strings. Both strings are injected into the sub-LLM's context
by A2UICatalogContext (packages/react-core) and
copilotkit.a2ui.a2ui_prompt() respectively, so every A2UI-enabled app
picks it up automatically — no per-demo change needed.
Stacked on #4216, which restores the same instruction to the
langgraph-python-threads demo's tool docstring (belt-and-braces until
consumers update their shared package version).
Address review feedback: extract the repeated clipboard availability check +
writeText + error handling pattern into a shared copyToClipboard() utility in
@copilotkit/shared. All 9 call sites across angular, react-core, and react-ui
now use the shared utility instead of duplicating the same code block.
The shared visitedRefs Set was mutated in place, so when two sibling
properties referenced the same $def (e.g. billing and shipping both
referencing Address), the second resolution was incorrectly flagged as
circular. Clone the set before recursing so each branch has its own
ancestry path. Added regression test that fails without this fix.
Recursive JSON schemas that reference themselves via $ref would cause
infinite recursion and stack overflow. This adds a visited set that
tracks which $ref paths have been seen during resolution. When a cycle
is detected, it breaks with z.any() and logs a console.warn so users
get feedback. Also adds console.warn for the generic z.any() fallback
on unsupported schema types.
Adds tests for circular refs, non-circular $ref resolution, anyOf with
$ref variants, integer type, null type, and unsupported type warning.
- Replace custom { name, props } schema format with spec-aligned inline
catalog format (allOf + properties) so the LLM sees the same flat
structure it must produce — eliminates "props" nesting confusion.
- Restructure generation prompts: inline literal values are the default,
path binding is a narrow schema-driven exception for form inputs.
- Export InlineCatalogSchema type from a2ui-renderer.
LLMs sometimes use path bindings (e.g. {"path": "/chartData"}) on
component properties that only accept literal values, causing silent
render failures. The new guideline tells the LLM to check the schema's
anyOf type before using path bindings.
Detect Zod v4 schemas by checking for a toJSONSchema() method on the
schema object. When present, call it directly instead of routing through
zod-to-json-schema (which cannot handle Zod v4 internals).
Priority order:
1. Standard JSON Schema V1 (~standard.jsonSchema.input)
2. Zod v4 native (schema.toJSONSchema())
3. Zod v3 fallback (injected zodToJsonSchema)
Removes the dead vendor === "zod4" check (Zod v4 reports "zod") and
the _def duck-typing fallback (unnecessary with toJSONSchema detection).
Closes#3636
- Mark parameters as optional when null is present in the type union
- Add matching null-union handling to convertJsonSchemaToZodSchema
- Add 7 tests covering null-union edge cases for both converters
When users pass the boolean shorthand `debug: true`, verbose previously
defaulted to true, logging full event payloads including user messages,
tool args, and state snapshots. Now defaults to false — users must
explicitly opt in with `debug: { verbose: true }`.
## Summary
- Handle `anyOf`, `oneOf`, `$ref`, and null type entries when converting
JSON schema to Zod schemas
- Prevents runtime errors when LLM tool parameters use union types or
nullable fields
Closes#2220
---
*Split from #3847*
Tyler Slaton